Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation rework in message comments & optimize Email type #32

Merged
merged 25 commits into from
Sep 24, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@

---

> 🚧 **ALPHA CODE NOTICE** 🚧:
> ⚠️ This protocol definition is in the alpha phase of development. It is important to note that during this stage, breaking changes may occur without advance notice. Users should proceed with caution.
> 🚧 **EARLY DAYS NOTICE** 🚧:
> ⚠️ Although we released our first productive Message Types version, it is still early days and partners make substantial and frequent contributions to the Camino Message Types. Please be aware that the Camino Messenger Protocol is still undergoing active development. The code, guidelines, and instructions may be subject to change.

---

The Camino Messenger protocol is created together with Partners from each vertical (flights, hotels, holiday homes, transfers, car rental, cruise,..). The objective is to create a message standard for the Camino Messenger, that is considered simple, efficient, complete, robust and easy to integrate by all partners. And conclusively it will delightfully be implemented and used by partners. As all other Camino Network components, the Camino Messenger Protocol is open source. Free to be used anywhere, but of course targeted to be used with the Camino Messenger.

Please do not hesitate to communicate your observations on this documentation like uncertainties, mistakes or missing explanations, so that we can continuously improve this documentation. Every Camino Network Partner (Validator) can also participate in official Message Type reviews to help improve the message format. Reach us through the [Discord](https://discord.com/channels/949247897688494150/1182680860797960253).

For more information about the concept please visit: https://docs.camino.network/camino-messenger
For more information about the concept please visit [the Camino Messenger documentation](https://docs.camino.network/camino-messenger).
10 changes: 5 additions & 5 deletions proto/cmp/services/accommodation/v2/property_types.proto
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,10 @@ package cmp.services.accommodation.v2;
import "cmp/types/v1/amenity.proto";
import "cmp/types/v1/bed.proto";
import "cmp/types/v1/description.proto";
import "cmp/types/v1/file.proto";
import "cmp/types/v1/meal_plan.proto";
import "cmp/types/v1/product_status.proto";
import "cmp/types/v2/contact_info.proto";
import "cmp/types/v2/file.proto";
import "cmp/types/v2/location.proto";
import "cmp/types/v2/product_code.proto";
import "cmp/types/v2/service_fact.proto";
Expand Down Expand Up @@ -92,10 +92,10 @@ message PropertyExtendedInfo {
cmp.services.accommodation.v2.Property property = 1;

// Images
repeated cmp.types.v1.Image images = 2;
repeated cmp.types.v2.Image images = 2;

// Videos
repeated cmp.types.v1.Video videos = 3;
repeated cmp.types.v2.Video videos = 3;

// Segmentation classification
repeated string classifications = 4;
Expand Down Expand Up @@ -133,8 +133,8 @@ message Room {
// For holiday homes specific room names if availbale can be given.
string original_name = 3;

repeated cmp.types.v1.Image images = 4;
repeated cmp.types.v1.Video videos = 5;
repeated cmp.types.v2.Image images = 4;
repeated cmp.types.v2.Video videos = 5;

// Room descriptions
repeated cmp.types.v1.LocalizedDescriptionSet descriptions = 6;
Expand Down
6 changes: 3 additions & 3 deletions proto/cmp/services/activity/v2/activity_types.proto
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,11 @@ import "cmp/types/v1/datetime_range.proto";
import "cmp/types/v1/delivery.proto";
import "cmp/types/v1/description.proto";
import "cmp/types/v1/duration.proto";
import "cmp/types/v1/file.proto";
import "cmp/types/v1/language.proto";
import "cmp/types/v1/redemption.proto";
import "cmp/types/v2/address.proto";
import "cmp/types/v2/contact_info.proto";
import "cmp/types/v2/file.proto";
import "cmp/types/v2/location.proto";
import "cmp/types/v2/product_code.proto";
import "google/protobuf/timestamp.proto";
Expand Down Expand Up @@ -129,10 +129,10 @@ message ActivityExtendedInfo {
cmp.types.v2.ContactInfo contact_info = 10;

// Images
repeated cmp.types.v1.Image images = 11;
repeated cmp.types.v2.Image images = 11;

// Videos
repeated cmp.types.v1.Video videos = 12;
repeated cmp.types.v2.Video videos = 12;

// Supplier code from the Inventory System for this activity response.
string supplier_unit_code = 13;
Expand Down
4 changes: 2 additions & 2 deletions proto/cmp/services/book/v2/validate.proto
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,10 @@ syntax = "proto3";
package cmp.services.book.v2;

import "cmp/types/v1/common.proto";
import "cmp/types/v1/seat_map.proto";
import "cmp/types/v1/uuid.proto";
import "cmp/types/v2/price.proto";
import "cmp/types/v2/search.proto";
import "cmp/types/v2/seat_map.proto";

message ValidationRequest {
// Message header
Expand Down Expand Up @@ -41,7 +41,7 @@ message ValidationObject {
// For example: seats for a concert.
oneof unit_identifier {
// Selected seat(s) represented as a seat map inventory message type.
cmp.types.v1.SeatMapInventory seat_selection = 2;
cmp.types.v2.SeatMapInventory seat_selection = 2;
}
}

Expand Down
24 changes: 19 additions & 5 deletions proto/cmp/services/info/v1/entry_requirements.proto
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,9 @@ message CountryEntryRequirementsRequest {

bool include_items = 11;

// There is not yet any categorization standard and conclusively filters are
// supplier specific and the filter type should be "FILTER_TYPE_PROVIDER_CODE"
// Examples:
repeated cmp.types.v1.Filter filters = 12;
}

Expand All @@ -70,7 +73,7 @@ message CountryEntryRequirementsResponse {
// Types

message CountryEntryRequirementCategory {
// Category key. FIXME: Can this field be an enum?
// Category key.
string key = 1;

// List of localized names
Expand All @@ -84,13 +87,20 @@ message CountryEntryRequirementCategory {
}

message CountryEntryRequirementItem {
// Item type key. FIXME: Can this field be an enum?
// Item type key.
string key = 1;

// Language specific names and descriptions
repeated cmp.services.info.v1.LocalizedItemInfo info = 2;

// Status of the item. TODO: Add more explanation, what it means if it's false?
// Status of the item. An item specifies an action or requirement which should be
// done/provided or rather not. This is expressed with "true" and "false".
// Examples:
// Entry generally permitted, status=true
// EU Digital COVID Certificate accepted, status=true
// Visa required for stay, status=false
// Entry forms required, status=false
// Additional information, status=undefined
cmp.services.info.v1.ItemStatus status = 3;

// Significant update date
Expand All @@ -103,8 +113,12 @@ message LocalizedItemInfo {
cmp.types.v1.Language language = 3;
}

// FIXME: We need to clarify what true, false and undefined means for status and
// maybe update this enum accordingly
// Status identifies whether an item should be done/provided or rather not. In case
// of an incident, there might be restrictions.
//
// UNKNOWN is different from UNSPECIFIED. For UNKNOWN information about this topic
// was sought, but it was not possible to find enough information to classify that
// topic
enum ItemStatus {
ITEM_STATUS_UNSPECIFIED = 0;
ITEM_STATUS_TRUE = 1;
Expand Down
26 changes: 22 additions & 4 deletions proto/cmp/services/info/v2/entry_requirements.proto
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,9 @@ message CountryEntryRequirementsRequest {

bool include_items = 11;

// There is not yet any categorization standard and conclusively filters are
// supplier specific and the filter type should be "FILTER_TYPE_PROVIDER_CODE"
// Examples:
repeated cmp.types.v1.Filter filters = 12;
}

Expand All @@ -70,7 +73,7 @@ message CountryEntryRequirementsResponse {
// Types

message CountryEntryRequirementCategory {
// Category key. FIXME: Can this field be an enum?
// Category key.
string key = 1;

// List of localized names
Expand All @@ -90,7 +93,14 @@ message CountryEntryRequirementItem {
// Language specific names and descriptions
repeated cmp.services.info.v2.LocalizedItemInfo info = 2;

// Status of the item. TODO: Add more explanation, what it means if it's false?
// Status of the item. An item specifies an action or requirement which should be
// done/provided or rather not. This is expressed with "true" and "false".
// Examples:
// Entry generally permitted, status=true
// EU Digital COVID Certificate accepted, status=true
// Visa required for stay, status=false
// Entry forms required, status=false
// Additional information, status=undefined
cmp.services.info.v2.ItemStatus status = 3;

// Significant update date
Expand All @@ -103,10 +113,18 @@ message LocalizedItemInfo {
cmp.types.v1.Language language = 3;
}

// FIXME: We need to clarify what true, false and undefined means for status and
// maybe update this enum accordingly
// Status identifies whether an item should be done/provided or rather not. In case
// of an incident, there might be restrictions.
//
// UNKNOWN is different from UNSPECIFIED. For UNKNOWN information about this topic
// was sought, but it was not possible to find enough information to classify that
// topic
enum ItemStatus {
ITEM_STATUS_UNSPECIFIED = 0;
ITEM_STATUS_TRUE = 1;
ITEM_STATUS_FALSE = 2;
ITEM_STATUS_CRISIS = 3;
ITEM_STATUS_RESTRICTIONS = 4;
ITEM_STATUS_NO_RESTRICTIONS = 5;
ITEM_STATUS_UNKNOWN = 6;
}
4 changes: 2 additions & 2 deletions proto/cmp/services/insurance/v1/insurance_types.proto
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@ syntax = "proto3";

package cmp.services.insurance.v1;

import "cmp/types/v1/file.proto";
import "cmp/types/v1/inclusivity.proto";
import "cmp/types/v1/link.proto";
import "cmp/types/v2/contact_info.proto";
import "cmp/types/v2/file.proto";
import "cmp/types/v2/price.proto";
import "cmp/types/v2/product_code.proto";
import "google/protobuf/timestamp.proto";
Expand Down Expand Up @@ -51,7 +51,7 @@ message PolicyExtendedInfo {
string carrier_name = 3;

// URL to logo
cmp.types.v1.Image logo = 4;
cmp.types.v2.Image logo = 4;

// Enum of possible types, to be used for filtering
cmp.services.insurance.v1.PolicyType policy_type = 5;
Expand Down
4 changes: 2 additions & 2 deletions proto/cmp/services/seat_map/v2/availability.proto
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@ syntax = "proto3";
package cmp.services.seat_map.v2;

import "cmp/types/v1/common.proto";
import "cmp/types/v1/seat_map.proto";
import "cmp/types/v2/search.proto";
import "cmp/types/v2/seat_map.proto";

// Request for seat map availability data
//
Expand Down Expand Up @@ -42,7 +42,7 @@ message SeatMapAvailabilityResponse {
cmp.types.v1.ResponseHeader header = 1;

// Required. Seat map availability data.
cmp.types.v1.SeatMapInventory seat_map = 2;
cmp.types.v2.SeatMapInventory seat_map = 2;
}

// Service for requesting seat map availability data
Expand Down
52 changes: 52 additions & 0 deletions proto/cmp/services/seat_map/v2/seat_map.proto
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
syntax = "proto3";

package cmp.services.seat_map.v2;

import "cmp/types/v1/common.proto";
import "cmp/types/v1/language.proto";
import "cmp/types/v2/seat_map.proto";

// Request for seat map data
//
// Requests the seat map data for a given map ID
message SeatMapRequest {
// Request header
//
// Header contains information about the request
cmp.types.v1.RequestHeader header = 1;

// Unique identifier for the seat map
//
// This is the map ID that is received in the search results and also from the
// product info responses.
string map_id = 2;

// Requested Languages
repeated cmp.types.v1.Language languages = 3;
}

// Response for seat map request
//
// Contains the seat map data for a given map ID
message SeatMapResponse {
// Response header
//
// Header contains information about the response
cmp.types.v1.ResponseHeader header = 1;

// Seat map data
//
// Contains the seat map data for the requested map ID
cmp.types.v2.SeatMap seat_map = 2;
}

// Service for requesting seat map data for a given map ID
//
// ![Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/services/seat_map/v1/seat_map.proto.dot.xs.svg)
// [Open Message Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/services/seat_map/v1/seat_map.proto.dot.svg)
service SeatMapService {
// Get seat map data
//
// Requests the seat map data for a given map ID
rpc SeatMap(SeatMapRequest) returns (SeatMapResponse);
}
10 changes: 7 additions & 3 deletions proto/cmp/types/v1/change_policy.proto
Original file line number Diff line number Diff line change
Expand Up @@ -37,10 +37,14 @@ message ChangePolicy {
repeated cmp.types.v1.ChangeType change_types = 3;
}

// ChangeTypes
// TODO: Add documentation
// ChangeTypes Different change types can be defined depending on what part of a
// travel booking requires to be changed (like for example the common "name change",
// "date change" or the change of a service booked to another service). Each of these
// changes can be possible or not in relation to the time until the service is
// delivered or the cost of the change may vary closer to the delivery of the
// service.
message ChangeType {
// Change type code
// Change type code in case the change type has a specific code
string code = 1;

// When this change type and date is valid. Either use the start and end date of
Expand Down
11 changes: 4 additions & 7 deletions proto/cmp/types/v1/common.proto
Original file line number Diff line number Diff line change
Expand Up @@ -35,13 +35,10 @@ package cmp.types.v1;
// ![Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v1/common.proto.dot.xs.svg)
// [Open Message Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v1/common.proto.dot.svg)
message Header {
// Protocol Version
// The request and response should always hold the true version implemented.
// This will help transparency and troubleshooting when issues arise. For example
// in case a new filter is introduced with version 1.3.0 and a response by a supply
// partner is still in version 1.1.0 that does not have the new filter. Obviously the
// supply partner has not processed the new field and the response is not filtered as
// specified in the request.
// Bot Version The request and response should always hold the bot version used
// for messaging. This will help transparency and troubleshooting when issues
// arise. For example in case one partner uses bot v9.0.0 and the other partner
// uses bot v10.0.0, which are incompatible.
cmp.types.v1.Version version = 1;

// End-user wallet ID for personalization purposes
Expand Down
4 changes: 3 additions & 1 deletion proto/cmp/types/v1/credit_card.proto
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,9 @@ package cmp.types.v1;
import "cmp/types/v1/date.proto";

message CreditCard {
// FIXME: Can we use an int64 to represent a credit card number?
// A creditcard should be stored as a string to facilitate cards that have leading
// zeros, but also to allow for spaces or dashes for readability, like for example
// 1234-5678-9876-5432
string number = 1;
cmp.types.v1.Date expiration_date = 2;
int32 cvc = 3;
Expand Down
4 changes: 2 additions & 2 deletions proto/cmp/types/v2/contact_info.proto
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@ syntax = "proto3";

package cmp.types.v2;

import "cmp/types/v1/email.proto";
import "cmp/types/v1/link.proto";
import "cmp/types/v1/phone.proto";
import "cmp/types/v2/address.proto";
import "cmp/types/v2/email.proto";

// Contact Info for general use.
//
Expand All @@ -19,7 +19,7 @@ message ContactInfo {
repeated cmp.types.v1.Phone phones = 2;

// Emails
repeated cmp.types.v1.Email emails = 3;
repeated cmp.types.v2.Email emails = 3;

// Websites
repeated cmp.types.v1.Link links = 4;
Expand Down
Loading
Loading