diff --git a/README.md b/README.md index 05f6e74f..a8c65e71 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,8 @@ --- -> 🚧 **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. --- @@ -13,4 +13,4 @@ The Camino Messenger protocol is created together with Partners from each vertic 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 index 837e2981..257c2810 100644 --- 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 index 300463a4..0d3719c4 100644 --- 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 index aaa6283d..4ac7220f 100644 --- 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 index 6c1743d8..dcb67156 100644 --- 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 index ee2a86ff..e299f6e0 100644 --- 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 index c8ba406e..20d0e3a6 100644 --- 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 index 036df60a..070d92e3 100644 --- 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 new file mode 100644 index 00000000..7e106d9a --- /dev/null +++ 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 index 519370f1..6052afa9 100644 --- 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 index cd2ae7b5..71c6988e 100644 --- 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 index cea29c01..cbb120ba 100644 --- 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 index 5af89e01..e9136b50 100644 --- 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; diff --git a/proto/cmp/types/v2/email.proto b/proto/cmp/types/v2/email.proto new file mode 100644 index 00000000..0a9c236a --- /dev/null +++ b/proto/cmp/types/v2/email.proto @@ -0,0 +1,33 @@ +syntax = "proto3"; + +package cmp.types.v2; + +// Email type for general use. +// +// ![Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v1/email.proto.dot.xs.svg) +// [Open Message Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v1/email.proto.dot.svg) +message Email { + string address = 1; + + cmp.types.v2.EmailType type = 2; +} + +// Email Types +enum EmailType { + EMAIL_TYPE_UNSPECIFIED = 0; + EMAIL_TYPE_OTHER = 1; // For emails that don't fit into other categories. + EMAIL_TYPE_RECEPTION = 2; // For services that require a reception like hotels, hostels, car rental. + EMAIL_TYPE_BOOKING = 3; // For booking confirmations. + EMAIL_TYPE_SUPPORT = 4; // General customer support. + EMAIL_TYPE_INQUIRY_RESPONSE = 5; // Responses to customer inquiries. + EMAIL_TYPE_TRANSPORT_INFO = 6; // Information regarding transport services. + EMAIL_TYPE_CONFIRMATION = 7; // Confirmation email for on-request bookings. + EMAIL_TYPE_FEEDBACK_REQUEST = 8; // Requests for customer feedback. + EMAIL_TYPE_BILLING = 9; // Billing and payment related emails. + EMAIL_TYPE_CANCELLATION = 10; // Cancellation notices. + EMAIL_TYPE_REMINDER = 11; // Reminders for reservations or activities. + EMAIL_TYPE_PROMOTIONAL = 12; // Promotional emails, offers, discounts. + EMAIL_TYPE_UPDATES = 13; // Updates about services or policy changes. + EMAIL_TYPE_ALERTS = 14; // Alerts or important notices. + EMAIL_TYPE_NEWSLETTER = 15; // Regular newsletters. +} diff --git a/proto/cmp/types/v2/file.proto b/proto/cmp/types/v2/file.proto new file mode 100644 index 00000000..666149cf --- /dev/null +++ b/proto/cmp/types/v2/file.proto @@ -0,0 +1,101 @@ +syntax = "proto3"; + +package cmp.types.v2; + +import "google/protobuf/timestamp.proto"; + +// ![Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v1/file.proto.dot.xs.svg) +// [Open Message Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v1/file.proto.dot.svg) +message File { + // file name + string name = 1; + + // URL + string url = 2; + + // Last modification time + google.protobuf.Timestamp last_modified = 3; +} + +message Image { + // file + cmp.types.v2.File file = 1; + + // Width + int32 width = 2; + + // Height + int32 height = 3; + + // Category + string category = 6; + + // Image type + cmp.types.v2.ImageFormat format = 7; +} + +message Video { + // File + cmp.types.v2.File file = 1; + + // Codec of video + cmp.types.v2.Codec codec = 2; + + // Bitrate in kbps + int32 bitrate = 3; + + // Framerate + int32 framerate = 4; + + // Width and height are specified in pixels. Aspect ratio can be derived from that + // Ex: "16:9" + int32 width = 5; + int32 height = 6; + + // Container format. Ex: "MP4" + cmp.types.v2.VideoFormat format = 7; + + // Category + string category = 8; +} + +// Image formats +enum ImageFormat { + IMAGE_FORMAT_UNSPECIFIED = 0; + IMAGE_FORMAT_JPEG = 1; // JPEG or JPG + IMAGE_FORMAT_PNG = 2; + IMAGE_FORMAT_GIF = 3; + IMAGE_FORMAT_BMP = 4; + IMAGE_FORMAT_TIFF = 5; + IMAGE_FORMAT_SVG = 6; + IMAGE_FORMAT_EPS = 7; + IMAGE_FORMAT_PDF = 8; + IMAGE_FORMAT_PSD = 9; + IMAGE_FORMAT_AI = 10; // Adobe Illustrator’s native format + IMAGE_FORMAT_WEBP = 11; + IMAGE_FORMAT_HEIF = 12; // heif or heic +} + +// Video formats +enum VideoFormat { + VIDEO_FORMAT_UNSPECIFIED = 0; + VIDEO_FORMAT_MP4 = 1; // MPEG-4 + VIDEO_FORMAT_MKV = 2; // Matroska + VIDEO_FORMAT_MOV = 3; // QuickTime + VIDEO_FORMAT_AVI = 4; // Audio Video Interleave + VIDEO_FORMAT_FLV = 5; // Flash Video + VIDEO_FORMAT_WEBM = 6; // WebM + VIDEO_FORMAT_WMV = 7; // Windows Media Video + VIDEO_FORMAT_M4V = 8; // iTunes Video + VIDEO_FORMAT_MPEG = 9; // MPEG Video (sometimes also expressed as mpg) +} + +// Codec formats +enum Codec { + CODEC_UNSPECIFIED = 0; + CODEC_H264 = 1; // H.264 (Advanced Video Coding) + CODEC_HEVC = 2; // HEVC (H.265, High-Efficiency Video Coding) + CODEC_VP9 = 3; // VP9 + CODEC_AV1 = 4; // AV1 + CODEC_MPEG2 = 5; // MPEG-2 (codec used for video on DVDs) +} diff --git a/proto/cmp/types/v2/seat_map.proto b/proto/cmp/types/v2/seat_map.proto new file mode 100644 index 00000000..ef014768 --- /dev/null +++ b/proto/cmp/types/v2/seat_map.proto @@ -0,0 +1,210 @@ +syntax = "proto3"; + +package cmp.types.v2; + +import "cmp/types/v1/description.proto"; +import "cmp/types/v1/language.proto"; +import "cmp/types/v1/localized.proto"; +import "cmp/types/v2/file.proto"; +import "google/protobuf/wrappers.proto"; + +// Represents a basic seat with optional features and restrictions. Each seat has a +// unique identifier, a location within the seat map, and can have various static +// features and restrictions associated with it. +message Seat { + // Unique identifier for the seat, such as "12B" or "A26". This identifier must be + // unique within the section to which this seat belongs. + string id = 1; + + // The location of the seat within the seat map. This can be defined using either + // a vector (SVG) or bitmap format. + cmp.types.v2.SeatLocation location = 2; + + // Static features associated with the seat, such as type, amenities, etc. + repeated cmp.types.v2.LocalizedSeatAttributeSet features = 3; + + // Restrictions associated with the seat, such as age limits or accessibility requirements. + repeated cmp.types.v2.LocalizedSeatAttributeSet restrictions = 4; +} + +// List of seats +message SeatList { + repeated cmp.types.v2.Seat seats = 1; +} + +// A Section represents a distinct area within a venue, which can be defined by +// various attributes. It can be a block of rows in a theater, a specific area in a +// concert venue such as the stage or standing area, a section of seating in a +// stadium, or a section in an airplane. Each Section is uniquely identified and can +// contain information about its seats, layout, and additional properties. +message Section { + // Level, section or row identifier, e.g., "Upper", "Balcony" or "Section 101", + // "Orchestra" or "A", "12". Must be unique for each section. + string id = 1; + + // List of localized names Human readable names of the section + repeated cmp.types.v1.LocalizedString names = 2; + + // Seats in this section. + oneof seat_info { + // List of seats in this section. + cmp.types.v2.SeatList seat_list = 3; + + // Total number of seats in this section as an integer. + google.protobuf.Int32Value total_seats = 4; + } + + // Image that provides a visual representation of the section's layout, which can + // be either a vector (SVG) or bitmap image. + // + // If set, it is assumed that this image is used for locating seats within the + // section. (the `SeatLocation` message type in the `Seat` message above is + // used to represent seat location inside this image). + cmp.types.v2.Image image = 5; + + // A list of localized descriptions for this section, useful for providing + // information about features and amenities in multiple languages. + repeated cmp.types.v1.LocalizedDescriptionSet localized_descriptions = 6; + + // Nested sections within this section, allowing for a hierarchical representation + // of the venue's layout. + repeated cmp.types.v2.Section sections = 7; +} + +// High-level representation of a seat map, which defines the layout and structure +// of seating within a venue. This message provides a comprehensive overview of the +// seating arrangement, including sections, images, and localized descriptions. +// +// ![Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v1/seat_map.proto.dot.xs.svg) +// [Open Message Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v1/seat_map.proto.dot.svg) +message SeatMap { + // Unique identifier for the seat map + string id = 1; + + // A list of sections within the seat map. Each section represents a distinct area + // within the venue, such as rows, sections, levels, or blocks of seats. This + // field is recursive, allowing for hierarchical structuring of the seating + // layout. + repeated cmp.types.v2.Section sections = 2; + + // Image that provides a visual representation of the seat map, illustrating the + // location and arrangement of seats. The image can be in vector format (SVG) or + // bitmap format. + cmp.types.v2.Image image = 3; + + // A list of localized descriptions for the seat map. This can be used to describe + // features and amenities of the seating arrangement in multiple languages. + // The languages should match those requested in SeatMapRequest + repeated cmp.types.v1.LocalizedDescriptionSet localized_descriptions = 4; +} + +// List of _only_ seat IDs to be used for seat selection or seat availability. +message SeatInventory { + // List of seat IDs + repeated string ids = 1; +} + +// Represents the inventory of seats for a specific section and all its inner +// sections. This message is used for both seat availability and seat selection +// purposes, providing information about either the remaining or selected seats +// within the section. +message SectionInventory { + // Unique identifier for the section. Must be unique within the seat map. + string id = 1; + + oneof seat_info { + // List of individual seat IDs within this section. + cmp.types.v2.SeatInventory seat_list = 2; + + // Seat count in this section, representing either the remaining seats for + // availability purposes or the selected seats for seat selection messages. + // + // This field is intended for sections without individual seat details, such as + // standing areas at a concert or an arena. + google.protobuf.Int32Value seat_count = 3; + } + + // Nested inner sections within this section, allowing for a hierarchical + // representation of seat inventory. Each inner section can have its own seat + // information and further nested sections. + repeated cmp.types.v2.SectionInventory sections = 4; +} + +// Represents the inventory of seats for a specific seat map, used for both seat +// selection and seat availability purposes. This message provides a comprehensive +// overview of the seating inventory, including detailed information about each +// section and its inner sections. +message SeatMapInventory { + // Unique identifier for the seat map that this Inventory refers to. + string id = 1; + + // A list of seat inventories for each section within the seat map. This field + // includes detailed seat information and supports nested sections, allowing for a + // hierarchical representation of the seating arrangement. + repeated cmp.types.v2.SectionInventory sections = 2; +} + +message LocalizedSeatAttributeSet { + cmp.types.v1.Language language = 1; + repeated cmp.types.v2.SeatAttribute seat_attributes = 2; +} +/* Helper messages */ + +// Defines a static attribute for a seat, which can be used for specifying features +// and restrictions. Attributes include a name, a human-readable description, and a +// value that can be used for various conditions or restrictions. +// +// FIXME: Can we make this a big enum? +message SeatAttribute { + // Name of the attribute, used to identify the feature or restriction. + string name = 1; + + // Human-readable description of the attribute, providing more details about its purpose. + string description = 2; + + // Integer value associated with the attribute, which can be used for conditions + // or restrictions, such as "min_age". + int32 value = 3; +} + +// Enumerates the types of areas that can be defined within a seat map. This is used +// for specifying the shape of regions in bitmap images. +enum AreaType { + AREA_TYPE_UNSPECIFIED = 0; + AREA_TYPE_RECTANGLE = 1; + AREA_TYPE_CIRCLE = 2; + AREA_TYPE_POLYGON = 3; +} + +// Defines the location of a seat within a bitmap image seat map. This information +// is generally used with the HTML `area` tag to specify clickable regions. +message BitmapSeatLocation { + // The type of area defining the seat location, such as rectangle, circle, or polygon. + cmp.types.v2.AreaType type = 1; + + // Coordinates defining the area. The format of the coordinates depends on the + // area type (e.g., top-left (x1,y1) and bottom-right (x2,y2) corners for a + // rectangle: `