Introduce New Protobuf Definitions for Seat Mapping

proto/cmp/services/book/v1alpha/validate.proto

@@ -4,18 +4,15 @@ package cmp.services.book.v1alpha;
 
 import "cmp/types/v1alpha/common.proto";
 import "cmp/types/v1alpha/price.proto";
+import "cmp/types/v1alpha/search.proto";
+import "cmp/types/v1alpha/seat_map.proto";
 
 message ValidationRequest {
   // Message header
   cmp.types.v1alpha.RequestHeader header = 1;
 
-  // Search ID that is returned in the search response message in the `metadata``
-  // (`SearchResponseMetadata`) field.
-  string search_id = 2;
-
-  // Result ID that is that is returned by `result_id` field of the search result
-  // messages, for example: `AccommodationSearchResult`.
-  int32 result_id = 3;
+  // Validation object
+  ValidationObject validation_object = 2;
 }
 
 message ValidationResponse {
@@ -27,15 +24,24 @@ message ValidationResponse {
 
   // Validation object
   ValidationObject validation_object = 3;
+
+  // Price details for the validated product
+  cmp.types.v1alpha.PriceDetail price_detail = 4;
 }
 
 // Validation message that represents a single `result_id` from the search results
-// message.
-//
-// TODO: Better name?
+// message and also the optional `unit_identifier` for specific services that
+// requires it. For example a seat for a concert.
 message ValidationObject {
-  int32 result_id = 1;
-  cmp.types.v1alpha.PriceDetail price_detail = 2;
+  // Search result identifier with `search_id` & `result_id`
+  cmp.types.v1alpha.SearchIdentifier search_identifier = 1;
+
+  // Unit identifier that is used to describe selected units from the `result_id`.
+  // For example: seats for a concert.
+  oneof unit_identifier {
+    // Selected seat(s) represented as a seat map inventory message type.
+    cmp.types.v1alpha.SeatMapInventory seat_selection = 2;
+  }
 }
 
 // ![Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/services/book/v1alpha/validate.proto.dot.xs.svg)

proto/cmp/services/seat_map/v1alpha/availability.proto

@@ -0,0 +1,59 @@
+syntax = "proto3";
+
+package cmp.services.seat_map.v1alpha;
+
+import "cmp/types/v1alpha/common.proto";
+import "cmp/types/v1alpha/search.proto";
+import "cmp/types/v1alpha/seat_map.proto";
+
+// Request for seat map availability data
+//
+// Requests the seat map availability data for a given map ID
+message SeatMapAvailabilityRequest {
+  // Message header
+  //
+  // Header contains information about the request
+  cmp.types.v1alpha.RequestHeader header = 1;
+
+  // Required. The identifier of the seat map.
+  oneof identifier {
+    // Mint Identifier
+    //
+    // Example: For flights which book before seat selection. In this case, the
+    // buyer already have a `mint_id` because the service is already booked (minted
+    // on-chain).
+    string mint_id = 2;
+
+    // Search result identifier with `search_id` & `result_id`
+    //
+    // Example: For requesting seat availability for search results. In this case,
+    // booking has not happended yet.
+    cmp.types.v1alpha.SearchIdentifier search_identifier = 3;
+  }
+}
+
+// Response for seat map availability request
+//
+// Contains the seat map availability data for a given map ID
+message SeatMapAvailabilityResponse {
+  // Message header
+  //
+  // Header contains information about the response
+  cmp.types.v1alpha.ResponseHeader header = 1;
+
+  // Required. Seat map availability data.
+  cmp.types.v1alpha.SeatMapInventory seat_map = 2;
+}
+
+// Service for requesting seat map availability data
+//
+// Service is used to request the seat map availability data for a given map ID
+//
+// ![Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/services/seat_map/v1alpha/availability.proto.dot.xs.svg)
+// [Open Message Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/services/seat_map/v1alpha/availability.proto.dot.svg)
+service SeatMapAvailabilityService {
+  // Get seat map availability data
+  //
+  // Requests the seat map availability data for a given map ID
+  rpc SeatMapAvailability(SeatMapAvailabilityRequest) returns (SeatMapAvailabilityResponse);
+}

proto/cmp/services/seat_map/v1alpha/seat_map.proto

@@ -0,0 +1,48 @@
+syntax = "proto3";
+
+package cmp.services.seat_map.v1alpha;
+
+import "cmp/types/v1alpha/common.proto";
+import "cmp/types/v1alpha/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.v1alpha.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;
+}
+
+// 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.v1alpha.ResponseHeader header = 1;
+
+  // Seat map data
+  //
+  // Contains the seat map data for the requested map ID
+  cmp.types.v1alpha.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/v1alpha/seat_map.proto.dot.xs.svg)
+// [Open Message Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/services/seat_map/v1alpha/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);
+}

proto/cmp/types/v1alpha/search.proto

@@ -102,3 +102,14 @@ message SearchResponseMetadata {
   // sessions.
   string external_session_id = 6;
 }
+
+// Search identifier
+message SearchIdentifier {
+  // Search ID that is returned in the search response message in the `metadata``
+  // (`SearchResponseMetadata`) field.
+  UUID search_id = 1;
+
+  // Result ID that is that is returned by `result_id` field of the search result
+  // messages, for example: `AccommodationSearchResult`.
+  int32 result_id = 2;
+}

proto/cmp/types/v1alpha/seat_map.proto

@@ -0,0 +1,203 @@
+syntax = "proto3";
+
+package cmp.types.v1alpha;
+
+import "cmp/types/v1alpha/description.proto";
+import "cmp/types/v1alpha/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.
+  SeatLocation location = 2;
+
+  // Static features associated with the seat, such as type, amenities, etc.
+  repeated SeatAttribute features = 3;
+
+  // Restrictions associated with the seat, such as age limits or accessibility requirements.
+  repeated SeatAttribute restrictions = 4;
+}
+
+// List of seats
+message SeatList {
+  repeated 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;
+
+  // Human readable name of the section
+  string name = 2;
+
+  // Seats in this section.
+  oneof seat_info {
+    // List of seats in this section.
+    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.v1alpha.Image image = 5;
+
+  // A set of localized descriptions for this section, useful for providing
+  // information about features and amenities in multiple languages.
+  cmp.types.v1alpha.LocalizedDescriptionSet localized_description_set = 6;
+
+  // Nested sections within this section, allowing for a hierarchical representation
+  // of the venue's layout.
+  repeated 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/v1alpha/seat_map.proto.dot.xs.svg)
+// [Open Message Diagram](https://storage.googleapis.com/docs-cmp-files/diagrams/proto/cmp/types/v1alpha/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 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.v1alpha.Image image = 3;
+
+  // A set of localized descriptions for the seat map. This can be used to describe
+  // features and amenities of the seating arrangement in multiple languages.
+  cmp.types.v1alpha.LocalizedDescriptionSet localized_description_set = 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.
+    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 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 SectionInventory sections = 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.
+  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: `<area shape="rect" coords="x1,y1,x2,y2"`).
+  repeated int32 coordinates = 2;
+}
+
+// Defines the location of a seat within an SVG (vector) seat map. This is typically
+// used for labeling elements within the SVG.
+message VectorSeatLocation {
+  // Label for the seat location in the SVG, e.g., "section-TERRACE-26-34-2-label".
+  string label = 1;
+}
+
+// Represents the location of a seat within a seat map, which can be defined using
+// either a vector (SVG) or bitmap format. This message encapsulates both types of
+// seat location definitions.
+message SeatLocation {
+  // One of the possible seat location types: vector (SVG) or bitmap.
+  oneof location {
+    // Vector-based seat location, used for SVG maps.
+    VectorSeatLocation vector = 1;
+
+    // Bitmap-based seat location, used for HTML image maps.
+    BitmapSeatLocation bitmap = 2;
+  }
+}