From 4b3c2853885d229ea50c473ce1c91ec942d3b3d4 Mon Sep 17 00:00:00 2001 From: Kinga Mrugala Date: Wed, 10 Jun 2026 11:32:51 +0200 Subject: [PATCH 1/2] Add Itinerary schema to Tour Mirrors the itinerary schema from public-partner-api so structured itineraries appear in the public PPAPI docs site. Adds a new itinerary.yaml with Itinerary, ItineraryItem, ItineraryItemLocation, and ItineraryItemDuration schemas, and wires a nullable itineraries array into the Tour schema. Co-Authored-By: Claude Opus 4.7 --- spec/components/schema/itinerary.yaml | 124 ++++++++++++++++++++++++++ spec/components/schema/tour.yaml | 6 ++ 2 files changed, 130 insertions(+) create mode 100644 spec/components/schema/itinerary.yaml diff --git a/spec/components/schema/itinerary.yaml b/spec/components/schema/itinerary.yaml new file mode 100644 index 0000000..49cd8a0 --- /dev/null +++ b/spec/components/schema/itinerary.yaml @@ -0,0 +1,124 @@ +openapi: 3.0.2 +info: + title: Itinerary Schema + version: 1.0.0 +paths: {} +components: + schemas: + Itinerary: + description: A single day (or the only day) of a tour's itinerary. Single-day tours have one entry; multi-day tours have N entries ordered by day_number. + type: object + properties: + day_number: + type: integer + nullable: true + description: 1-indexed day number. Null for single-day tours. + example: 1 + title: + type: string + nullable: true + description: Display title for this day, e.g. "Day 1: Arrival in Cusco". + example: "Day 1: Arrival in Cusco" + items: + type: array + description: Ordered list of stops/activities for this day. + items: + $ref: "#/components/schemas/ItineraryItem" + ItineraryItem: + description: A single stop or segment within an itinerary day. + type: object + properties: + type: + type: string + enum: + - meeting_point + - pick_up + - drop_off + - transfer + - visit + - food_stop + - photo_stop + - break + - transfer_stop + - activity + description: The kind of stop. + example: visit + title: + type: string + nullable: true + description: Display title for this stop. + example: "Colosseum" + description: + type: string + nullable: true + description: Detailed description of what happens at this stop. + example: "Explore the ancient amphitheatre with skip-the-line access." + start_time: + type: string + nullable: true + description: Structured start time in HH:MM:SS (24h) format. Null if not scheduled. + example: "09:30:00" + duration: + $ref: "#/components/schemas/ItineraryItemDuration" + location: + $ref: "#/components/schemas/ItineraryItemLocation" + optional: + type: boolean + nullable: true + description: Whether the traveller can skip this stop. + example: false + extra_cost: + type: boolean + nullable: true + description: Whether this stop involves cost not included in the tour price. + example: false + entry_included: + type: boolean + nullable: true + description: Whether admission/entry fee is included in the tour price. + example: true + meal_type: + type: string + nullable: true + enum: + - breakfast + - lunch + - dinner + - snack + description: Type of meal (only present for food_stop items). + example: lunch + transportation_type: + type: string + nullable: true + description: Mode of transport (only present for transfer/transfer_stop items). + example: bus + ItineraryItemLocation: + description: Location of an itinerary stop. + type: object + properties: + name: + type: string + nullable: true + description: Display name of the location. + example: "Colosseum" + coordinates: + $ref: "../commons/objects.yaml#/components/schemas/Coordinates" + ItineraryItemDuration: + description: How long a stop lasts. + type: object + properties: + value: + type: number + format: float + nullable: true + description: Numeric duration value. + example: 1.5 + unit: + type: string + nullable: true + enum: + - day + - hour + - minute + description: Time unit for the duration value. + example: hour diff --git a/spec/components/schema/tour.yaml b/spec/components/schema/tour.yaml index 6b541f6..7f6a4b7 100644 --- a/spec/components/schema/tour.yaml +++ b/spec/components/schema/tour.yaml @@ -169,6 +169,12 @@ components: $ref: "../commons/fields.yaml#/components/schemas/CancellationPolicy" cancellation_policy_text: $ref: "../commons/fields.yaml#/components/schemas/CancellationPolicyText" + itineraries: + type: array + nullable: true + description: Structured itinerary describing the ordered stops/days of the tour. May be null or empty for tours without structured itinerary data. + items: + $ref: "./itinerary.yaml#/components/schemas/Itinerary" TourCategoryMinimal: description: A minimal representation of a tour category. More information about each category can be retrieved from the `/categories` endpoint. type: object From 600e9431fcf45cdcbd537fe210838159d6215796 Mon Sep 17 00:00:00 2001 From: Kinga Mrugala Date: Wed, 10 Jun 2026 11:42:29 +0200 Subject: [PATCH 2/2] Quote itinerary day title example to fix YAML parse The unquoted description ended with "Day 1: Arrival in Cusco", and the inner ": " was being parsed as a YAML mapping by SnakeYAML, failing the openapi-generator step. Co-Authored-By: Claude Opus 4.7 --- spec/components/schema/itinerary.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/components/schema/itinerary.yaml b/spec/components/schema/itinerary.yaml index 49cd8a0..2e6a326 100644 --- a/spec/components/schema/itinerary.yaml +++ b/spec/components/schema/itinerary.yaml @@ -17,7 +17,7 @@ components: title: type: string nullable: true - description: Display title for this day, e.g. "Day 1: Arrival in Cusco". + description: 'Display title for this day, e.g. "Day 1: Arrival in Cusco".' example: "Day 1: Arrival in Cusco" items: type: array