Transport updates for services, product code and baggage (#13)

proto/cmp/services/transport/v1alpha/trip_types.proto

@@ -7,6 +7,7 @@ import "cmp/types/v1alpha/location.proto";
 import "cmp/types/v1alpha/measurement.proto";
 import "cmp/types/v1alpha/price.proto";
 import "cmp/types/v1alpha/time.proto";
+import "cmp/types/v1alpha/product_code.proto";
 import "google/protobuf/timestamp.proto";
 
 // This message type represents a one way trip, either travelling or returning.
@@ -39,42 +40,57 @@ message TripSegment {
   // Ex: "SEG1234"
   string segment_id = 1;
 
-  // Provider Code
-  // Ex: "AC"
+  // Provider Code Ex: "EW" for Eurowings in case of a flight. DB for Deutsche Bahn
+  // in case of train. HT for Holiday Taxi or MTS for MTS in case of a transfer.
   string provider_code = 2;
 
-  // Retailer Code, replacing Marketing carrier
-  // Ex: "BC"
+  // Retailer Code, replacing Marketing carrier The example would be where Iberia is
+  // selling an Iberia Express flight. So in this example the retailer_code for
+  // Iberia would be "IB" and the provider_code for Iberia Express would be "I2".
+  // Similar "interline" or "code share" operation may exist in rail and transfer.
   string retailer_code = 3;
 
   // Sub Provider Code, replacing Operating carrier or identifying sub contracted
   // services provided by other suppliers.
   //
-  // Ex: "BC"
+  // DB could be selling an intenational train trip operated by the Dutch Nederlands
+  // Spoorwegen (NS) or the French SNCF. Holiday Taxis could be selling a transfer
+  // that is operated by Transunion.
   string sub_provider_code = 4;
 
-  // Service Number
+  // Product Code and Number
   //
-  // Ex: "1234"
+  // For flights we use the IATA or ICAO airline code in the code field and the
+  // flight number in the number field.
   //
-  // FIXME: Should this be an integer? For flights yes, but for trains and
-  // transfers?
-  string service_number = 5;
+  // For train some operators use a combination of a code and a number like
+  // Eurostar, but others just use a code or a number (SNCF). 
+  //
+  // Transfers are often identified by just a product code servicing an area.
+  cmp.types.v1alpha.ProductCode product_code = 5;
+
 
   // Departure
   TransitEvent departure = 6;
 
   // Arrival
   TransitEvent arrival = 7;
 
-  // Service description
+  // Flights, trains and transfers often offer different service types
+  // for a product. Think about economy or business for flights, first and second
+  // class on trains and a shared shuttle or a private transfer.
   //
-  // Ex: "Economy"
-  string service_description = 8;
-
-  // Service code
-  // Ex: "Y"
-  string service_code = 9;
+  // Service type code examples:
+  // flight: "Y", "J", "F".
+  // train: "1st", "2nd" or "S", "C", "P"
+  // transfer: "S", "P", "VIP", "SS"
+  string service_type_code = 8;
+
+  // Service type description examples:
+  // flight: "Economy Class", "Business Class", "First Class"
+  // train: "First Class", "Second Class" or "standard", "comfort", and "premium",..
+  // transfer: "Shuttle", "Private", "VIP Limosine", "Speedy Shuttle",...
+  string service_type_description = 9;
 
   // Trip Time
   //
@@ -105,4 +121,4 @@ message TripSegment {
   //
   // Ex: `Price(net=240, currency=Currency.CURRENCY_EUR)
   cmp.types.v1alpha.Price price = 15;
-}
+}

proto/cmp/types/v1alpha/baggage.proto

@@ -17,11 +17,16 @@ message Baggage {
   // Maximum number of the specified baggage count allowed for this type
   int32 max_count = 2;
 
-  // Maximum weith of each of the specified bagage type allowed
+  // Maximum weight of each of the specified baggage type allowed
   Weight max_weight = 3;
 
   // Maximum length, width and height of the specified bagage type allowed
   Dimension max_dimension = 4;
+
+  // traveller ID to specify the various types of baggage for each of participants
+  // of a trip. If there is just a total of different types of baggage, then it is
+  // the total for the booking and not specific to each participant.
+  int32 traveller_id = 5;
 }
 
 // Baggage type ENUM type

proto/cmp/types/v1alpha/product_code.proto

@@ -9,8 +9,16 @@ package cmp.types.v1alpha;
 // ![Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v1alpha/product_code.proto.dot.xs.svg)
 // [Open Message Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v1alpha/product_code.proto.dot.svg)
 message ProductCode {
+
+  // In most cases like in accommodation, just the field "code" and "type" will be
+  // used. For example in case of a GiataID (for example code=182568), a provider
+  // hotel code (for example MTS hotel code=AESPMI1234), a transfer code, etc.
+  // However, for flight and train it is common to have a code and a number like "EW
+  // 51" or "ICE 2803", which would then be code=EW and number=51 or code=ICE and
+  // number=2803
   string code = 1;
-  ProductCodeType type = 2;
+  int32 number = 2;
+  ProductCodeType type = 3;
 }
 
 // Product Code type
@@ -19,4 +27,6 @@ enum ProductCodeType {
   PRODUCT_CODE_TYPE_PROVIDER = 1;
   PRODUCT_CODE_TYPE_GIATA = 2;
   PRODUCT_CODE_TYPE_GOAL_ID = 3;
+  PRODUCT_CODE_TYPE_IATA = 4;
+  PRODUCT_CODE_TYPE_ICAO = 5;
 }

proto/cmp/types/v1alpha/service_fact.proto

@@ -9,10 +9,37 @@ import "cmp/types/v1alpha/price.proto";
 // ![Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v1alpha/service_fact.proto.dot.xs.svg)
 // [Open Message Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v1alpha/service_fact.proto.dot.svg)
 message ServiceFact {
-  string description = 1;
-  PriceDetail price_detail = 2;
-  ServiceAvailabilityType availability_type = 3;
-  ChargeBasisType charge_basis = 4;
+
+  // A code for the specific service, when a service is optional, this code is
+  // referenced in the booking so that the optional service will be added to the
+  // booking.
+  string code = 1;
+
+  // A description of the service like "business class", "shuttle transfer", "early
+  // check-in" etc.
+  string description = 2;
+
+  // the price and price breakdown of the service
+  PriceDetail price_detail = 3;
+
+  // whether the service is included, optional or compulsory. When a price is
+  // mentioned and the service is included, then the price of the service is already
+  // included in the total price of this option and it is better to omit the
+  // price_detail field. In case of an optional or compulsory service, the service
+  // must be specifically be booked and the price is added to the total price.
+  ServiceAvailabilityType availability_type = 4;
+
+  // The ChargeBasisType specifies whether this service is only charged once for the
+  // whole booking, for each participant, for each room or flight etc, for each day
+  // or for a combination of these concepts like for example "foreign distilleries
+  // per participant per day" or just once in case of a massage, but you would be
+  // able to order 3 of them in the booking.
+  ChargeBasisType charge_basis = 5;
+
+  // We can use a single ServiceFact to express just one service. But many services
+  // actually are actually a combination of several services, like the typical
+  // priority boarding, which also allows for a larger carry-on bag.
+  repeated ServiceFact details = 6;
 }
 
 enum ServiceAvailabilityType {

proto/cmp/types/v1alpha/traveller.proto

@@ -10,8 +10,9 @@ import "cmp/types/v1alpha/date.proto";
 // ![Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v1alpha/traveller.proto.dot.xs.svg)
 // [Open Message Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v1alpha/traveller.proto.dot.svg)
 message Traveller {
-  // Guest number, the lowest number is the lead-pax
-  int32 guest_number = 1;
+  // Guest number, the lowest number is the lead-pax. This ID is also used for
+  // referencing services linked to specific participants, like baggage.
+  int32 traveller_id = 1;
 
   // FIXME: Why we need both traveller type and birthday?