Update ProductCode/SupplierProductCode et al. (#14)

* breaking change in field order adding "Brand" in types/search.proto
* added ProviderProductCode to Accommodation, Activity and Transport messages. Fields reordered.
* unifying room_code and room_name, adding original_room_name
* improved multi room and multi home explanations. Improved filer explanations

proto/cmp/services/accommodation/v1alpha/info.proto

@@ -6,6 +6,7 @@ import "cmp/services/accommodation/v1alpha/property_types.proto";
 import "cmp/types/v1alpha/common.proto";
 import "cmp/types/v1alpha/language.proto";
 import "google/protobuf/timestamp.proto";
+import "cmp/types/v1alpha/product_code.proto";
 
 message AccommodationProductInfoRequest {
   // Message header
@@ -18,7 +19,7 @@ message AccommodationProductInfoRequest {
   repeated cmp.types.v1alpha.Language languages = 3;
 
   // Property codes
-  repeated string property_codes = 4;
+  repeated cmp.types.v1alpha.SupplierProductCode supplier_codes = 4;
 }
 
 message AccommodationProductInfoResponse {

proto/cmp/services/accommodation/v1alpha/property_types.proto

@@ -14,6 +14,7 @@ import "cmp/types/v1alpha/phone.proto";
 import "cmp/types/v1alpha/service_fact.proto";
 import "cmp/types/v1alpha/traveller.proto";
 import "google/protobuf/timestamp.proto";
+import "cmp/types/v1alpha/product_code.proto";
 
 // ### Property message type
 //
@@ -26,48 +27,44 @@ message Property {
   google.protobuf.Timestamp last_modified = 1;
 
   // Ex: "AESPMI1234"
-  string property_code = 2;
+  cmp.types.v1alpha.SupplierProductCode supplier_code = 2;
+
+  // Product code which can be of different types
+  repeated cmp.types.v1alpha.ProductCode product_code = 3;
 
   // Ex: "Beach Hotel Alanya"
-  string name = 3;
+  string name = 4;
 
   // Ex: "Hilton"
-  string chain = 4;
+  string chain = 5;
 
   // Ex: CategoryRating.CATEGORY_RATING_4_5
-  CategoryRating category_rating = 5;
+  CategoryRating category_rating = 6;
 
   // Ex: CategoryUnit.CATEGORY_UNIT_PALMS
-  CategoryUnit category_unit = 6;
+  CategoryUnit category_unit = 7;
 
   // Ex: Address type
-  cmp.types.v1alpha.Address address = 7;
+  cmp.types.v1alpha.Address address = 8;
 
   // Emails
-  repeated cmp.types.v1alpha.Email emails = 8;
+  repeated cmp.types.v1alpha.Email emails = 9;
 
   // Phones
-  repeated cmp.types.v1alpha.Phone phones = 9;
+  repeated cmp.types.v1alpha.Phone phones = 10;
 
   // Location coordinate
-  cmp.types.v1alpha.Coordinate coordinate = 10;
+  cmp.types.v1alpha.Coordinate coordinate = 11;
 
   // Ex: "www.hotel.com"
-  string website = 11;
+  string website = 12;
 
   // Status of the property
-  // FIXME: Changed "deactivated" to "status". But we should still make this an enum. ??
-  string status = 12;
-
-  // GIATA ID
-  string giata_id = 13;
-
-  // Goal ID
-  int32 goal_id = 14;
+    PropertyStatus status = 13;
 
   // Airports
   // Ex: ["PMI", "ZRH", "AYT"]
-  repeated string airports = 15;
+  repeated string airports = 14;
 }
 
 enum CategoryRating {
@@ -100,6 +97,13 @@ enum CategoryUnit {
   CATEGORY_UNIT_PALMS = 2;
 }
 
+enum PropertyStatus {
+  PROPERTY_STATUS_UNSPECIFIED = 0;
+  PROPERTY_STATUS_DRAFT = 1;
+  PROPERTY_STATUS_CONFIRMED = 2;
+  PROPERTY_STATUS_EXPIRED = 3;
+}
+
 // This message type contains extended info about a property
 message PropertyExtendedInfo {
   // Property
@@ -123,43 +127,50 @@ message PropertyExtendedInfo {
   // Payment type. Ex: "MERCHANT"
   string payment_type = 7;
 
-  // Status
-  PropertyStatus status = 8;
-
   // Rooms
-  repeated Room rooms = 9;
-}
-
-enum PropertyStatus {
-  PROPERTY_STATUS_UNSPECIFIED = 0;
-  PROPERTY_STATUS_DRAFT = 1;
-  PROPERTY_STATUS_CONFIRMED = 2;
-  PROPERTY_STATUS_EXPIRED = 3;
+  repeated Room rooms = 8;
 }
 
 message Room {
-  string code = 1;
-  string name = 2;
-  repeated cmp.types.v1alpha.Image images = 3;
-  repeated cmp.types.v1alpha.Video videos = 4;
+  // Room code of the unit in case of hotel. Ex: "RMSDDB0000". For holiday homes
+  // often no room codes are used. This code must explicitly match the supplier_room_code
+  // in the ProductList and the ProductInfo messages, so that the static data like room
+  // amenities, descriptions, images etc. can be married to the dynamic price and
+  // availability data for display to the end user.
+  string supplier_room_code = 1;
+
+   // Room name. In case of hotel a standardized room name is often derrived from
+   // room code structures. Exmple: "superior seaview room".
+   // For holiday homes we expect names like "Master Bedroom", "Second Bedroom" or
+   // "Bathroom" when specific descriptions for each room are available.
+  string supplier_room_name = 2;
+
+  // Original room name as assigned by the hotel. In case of spefifically designated room
+  // names by chains and both the chain and the customer wants to adhere to them.
+  // Ex: "CEIBA CLUB", "CEIBA GOVERNORS SUITE", "GOVERNORS SUITE" or "ENCLAVE NATURE VIEW"
+  // For holiday homes specific room names if availbale can be given.
+  string original_room_name =3;
+
+  repeated cmp.types.v1alpha.Image images = 4;
+  repeated cmp.types.v1alpha.Video videos = 5;
 
   // Room descriptions
-  repeated cmp.types.v1alpha.LocalizedDescriptionSet descriptions = 5;
+  repeated cmp.types.v1alpha.LocalizedDescriptionSet descriptions = 6;
 
   // Meal plan (Board code)
-  repeated cmp.types.v1alpha.MealPlan meal_plan = 6;
+  repeated cmp.types.v1alpha.MealPlan meal_plan = 7;
 
   // Beds
-  repeated cmp.types.v1alpha.Bed beds = 7;
+  repeated cmp.types.v1alpha.Bed beds = 8;
 
   // Occupancy
-  Occupancy total_occupancy = 8;
+  Occupancy total_occupancy = 9;
 
   // Services
-  repeated cmp.types.v1alpha.ServiceFact services = 9;
+  repeated cmp.types.v1alpha.ServiceFact services = 10;
 
   // Amenities
-  repeated cmp.types.v1alpha.Amenity amenities = 10;
+  repeated cmp.types.v1alpha.Amenity amenities = 11;
 }
 
 message Occupancy {

proto/cmp/services/accommodation/v1alpha/search.proto

@@ -21,21 +21,56 @@ import "cmp/types/v1alpha/search.proto";
 // accommodations like hotel and holiday home searches within the platform. In the
 // request the market, language and currency are specified at the top-level.
 //
-// In the Unit we specify the details of the trip like dates, properties or
+// In "queries" we specify the details of the trip like dates, properties or
 // locations or filters. The purpose of such a structure is to allow for multi-room
-// and multi-property searches. This means that there is no grouping of different
+// and multi-property search requests. 
+//
+// For the response this means that there is no grouping of different
 // room, mealplan or rateplan options in single room or single property searches.
-// Each AccommodationSearchResult is one bookable option.
+// Each AccommodationSearchResult is one bookable option as a "result_id".
+//
+// Simple example:
+// a search for 1 room for 2 adults would be just 1 query, with one travel period and
+// one set of search parameters. The response has one query_id with many result_ids
+// for various rooms, mealplans and rateplans in one hotel and depending on the search
+// parameters, again for other hotels. Each property+room+rateplan+mealplan is one 
+// result_id with just one unit.
+//
+// The simple example is also applicable for holiday homes where one or multiple
+// result_ids will be returned for various homes matching the query. The results will
+// probably not include a mealplan and in general no room information as all rooms in
+// the home are included. Flexible and non-refundable as well as packaging rateplans
+// are already surfacing in some distribution channels.
+//
+// Multi room example:
+// a search for 1 room for 2 adults in one query and another room for two adults and a
+// child of 8 in another room in the same hotel or destination for the same dates in
+// another query in the search request. This will lead to a search response with just
+// one unit for eavery possible option available for each query_id, with many result_ids.
+//
+// The same concept is valid for multiple homes for more than one family travelling
+// together to one park or destination.
 //
-// Several rooms or houses can be requested for the same dates and location or for
-// the purpose of a tour or roadtrip, several accommodations or properties for
-// sequential dates and different locations. This is done by specifying multiple
-// Units for the same or different periods, the same or different accommodations or
-// properties, specifying which travellers sleep in which unit.
+// Road-trip or circuit example:
+// a search for one or multiple rooms or homes in queries that have sequential dates
+// and destinations. For example a trip to Las Vegas, a flight to New York and decending
+// the atlantic coastline to New Orleans or Orlando by car with stops in various places.
 //
-// Developers leveraging this message type should ensure proper validation and
-// handling, especially considering fields that are still under review, like
-// `speech_request`.
+// The hostel, convention or groups example:
+// Often just 5 rooms for 10 peopleare requested or specific bed combinations like 5
+// single-use rooms (for 5 travellers) and 5 double rooms (10 travellers) are requested.
+// In this case the number of rooms is specified and the total amount of travellers,
+// but no distribution of travellers per room is detailed in the request. The reponse
+// then hold multiple units for one search_id and result_id, so that if 5 rooms are
+// requested, but only 2 standard rooms are available, the requested amount can be 
+// completed with a different room type (superior, seaview,..)
+//
+// In general, the number of available rooms should be considered to ensure that for
+// requests with multiple rooms or homes, the same room or home is not offered twice
+// to different travellers.
+//
+//
+
 message AccommodationSearchRequest {
   // Message header. Contains API version, message info string and end-user wallet
   // address
@@ -46,6 +81,9 @@ message AccommodationSearchRequest {
 
   // Generic search parameters Ex: Inclusion of OnRequest options and inclusion of
   // only the cheapest or all options.
+  // In the search parameters multiple filters can be applied for upfront filtering
+  // of the search results to for example to only include hotels that are less than
+  // one kilometer from the beach, have a kids club and offer an a la carte restaurant
   cmp.types.v1alpha.SearchParameters search_parameters_generic = 3;
 
   // This field represents a list of search queries that can be used to create

proto/cmp/services/accommodation/v1alpha/search_parameters_types.proto

@@ -45,6 +45,9 @@ message AccommodationSearchParameters {
   repeated cmp.types.v1alpha.RateRule rate_rules = 8;
 
   // Product code list
-  // Here a list of property codes would be used
+  // Here a list of property codes would be used that could be of different types
   repeated cmp.types.v1alpha.ProductCode product_codes = 9;
+
+  // Or a list of provider codes would be used
+  repeated cmp.types.v1alpha.SupplierProductCode supplier_codes = 10;
 }

proto/cmp/services/accommodation/v1alpha/unit_types.proto

@@ -25,52 +25,66 @@ message Unit {
   // Ex: `UnitType.UNIT_TYPE_ROOM`
   UnitType type = 1;
 
-  // Unit code. Room code of the unit in case of hotel. Ex: "RMSDDB0000"
-  string unit_code = 2;
-
-  // Unit name. In case of enrichment additional name of the unit code.
-  // Ex: "Double Standard Room"
-  string unit_name = 3;
+  // Room code of the unit in case of hotel. Ex: "RMSDDB0000". This code must explicitly
+  // match the supplier_room_code in the ProductList and the ProductInfo messages, so that
+  // the static data like room amenities, descriptions, images etc. can be married to the
+  // dynamic price and availability data for display to the end user.
+  string supplier_room_code = 2;
+
+  // Room name. In case of enrichment additional name of the unit code.
+  // In theory, this field should never be included as it is already available in
+  // the static data. However, some providers prefer to be specific to avoid room
+  // mapping issues. Ex: "Double Standard Room"
+  string supplier_room_name = 3;
+
+  // Original room name as assigned by the hotel. In case of spefifically designated room
+  // names by chains and both the chain and the customer wants to adhere to them.
+  // Ex: "CEIBA CLUB", "CEIBA GOVERNORS SUITE", "GOVERNORS SUITE" or "ENCLAVE NATURE VIEW"
+  string original_room_name = 4;
 
   // Travel period
-  cmp.types.v1alpha.TravelPeriod travel_period = 4;
+  cmp.types.v1alpha.TravelPeriod travel_period = 5;
 
   // Travellers
-  repeated cmp.types.v1alpha.Traveller travellers = 5;
+  repeated cmp.types.v1alpha.Traveller travellers = 6;
 
   // Beds
-  repeated cmp.types.v1alpha.Bed beds = 6;
+  repeated cmp.types.v1alpha.Bed beds = 7;
 
   // Price in detail with breakdowns
-  cmp.types.v1alpha.PriceDetail price_detail = 7;
+  cmp.types.v1alpha.PriceDetail price_detail = 8;
 
-  // Services
-  repeated cmp.types.v1alpha.ServiceFact services = 8;
+  // Included, compulsory and optional services available
+  repeated cmp.types.v1alpha.ServiceFact services = 9;
 
   // Mealplan code
-  cmp.types.v1alpha.MealPlan meal_plan_code = 9;
+  cmp.types.v1alpha.MealPlan meal_plan_code = 10;
 
   // Rate plan
-  cmp.types.v1alpha.RatePlan rate_plan = 10;
+  cmp.types.v1alpha.RatePlan rate_plan = 11;
 
   // Rate Rule
-  cmp.types.v1alpha.RateRule rate_rule = 11;
+  cmp.types.v1alpha.RateRule rate_rule = 12;
 
   // This is a list so that various policies can be expressed.
   //
   // Ex: 10-5 days before arrival x€, 4-1 days before arrival y€ and 0 days before
   // arrival z€
-  repeated cmp.types.v1alpha.CancelPolicy cancel_policies = 12;
+  repeated cmp.types.v1alpha.CancelPolicy cancel_policies = 13;
 
-  // Remaining units
-  int32 remaining_units = 13;
+  // Number of remaining units at the time of calculation
+  int32 remaining_units = 14;
 
-  // Property code
-  cmp.types.v1alpha.ProductCode property_code = 14;
+  // Property code which can be of different types
+  cmp.types.v1alpha.ProductCode property_code = 15;
+
+  // Supplier Property code, consistent in ProductList, ProductInfo and Search
+  cmp.types.v1alpha.SupplierProductCode supplier_code = 16;
 
   // Remarks
-  // FIXME: Is this field "per Unit" or should it be "per search request"?
-  string remarks = 15;
+  // Non structural aspects related to the unit a supplier wants to include in the search
+  // response
+  string remarks = 17;
 }
 
 enum UnitType {