Documentation rework in message comments & optimize Email type (#32)

--------- Co-authored-by: Mohamed Elmoslemany <[email protected]> Co-authored-by: Noctunus <[email protected]> Co-authored-by: Ekrem Seren <[email protected]>
chain4travel · Sep 24, 2024 · ca03e72 · ca03e72
1 parent e2666f0
commit ca03e72
Show file tree

Hide file tree

Showing 16 changed files with 470 additions and 39 deletions.
diff --git a/README.md b/README.md
@@ -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).
diff --git a/proto/cmp/services/accommodation/v2/property_types.proto b/proto/cmp/services/accommodation/v2/property_types.proto
@@ -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";
@@ -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;
@@ -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;

diff --git a/proto/cmp/services/activity/v2/activity_types.proto b/proto/cmp/services/activity/v2/activity_types.proto
@@ -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";
@@ -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;

diff --git a/proto/cmp/services/book/v2/validate.proto b/proto/cmp/services/book/v2/validate.proto
@@ -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
@@ -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;
   }
 }
 

diff --git a/proto/cmp/services/info/v1/entry_requirements.proto b/proto/cmp/services/info/v1/entry_requirements.proto
@@ -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;
 }
 
@@ -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
@@ -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
@@ -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;

diff --git a/proto/cmp/services/info/v2/entry_requirements.proto b/proto/cmp/services/info/v2/entry_requirements.proto
@@ -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;
 }
 
@@ -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
@@ -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
@@ -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;
 }
diff --git a/proto/cmp/services/insurance/v1/insurance_types.proto b/proto/cmp/services/insurance/v1/insurance_types.proto
@@ -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";
@@ -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;

diff --git a/proto/cmp/services/seat_map/v2/availability.proto b/proto/cmp/services/seat_map/v2/availability.proto
@@ -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
 //
@@ -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

diff --git a/proto/cmp/services/seat_map/v2/seat_map.proto b/proto/cmp/services/seat_map/v2/seat_map.proto
@@ -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);
+}
diff --git a/proto/cmp/types/v1/change_policy.proto b/proto/cmp/types/v1/change_policy.proto
@@ -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

diff --git a/proto/cmp/types/v1/common.proto b/proto/cmp/types/v1/common.proto
@@ -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

diff --git a/proto/cmp/types/v1/credit_card.proto b/proto/cmp/types/v1/credit_card.proto
@@ -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;

diff --git a/proto/cmp/types/v2/contact_info.proto b/proto/cmp/types/v2/contact_info.proto
@@ -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.
 //
@@ -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;