Search offers - the 'Who' part - 20260702

deliverables/1 search offers/Animal.yaml

@@ -0,0 +1,23 @@
+Animal:
+  allOf:
+  - $ref: .\TravellingEntity.yaml
+  - type: object
+    additionalProperties: false
+    description: ANIMAL — an animal travelling alongside its owner.
+    required:
+    - entityType
+    - type
+    properties:
+      entityType:
+        type: string
+        const: animal
+      type:
+        type: string
+        description: Category of animal (operator-defined, e.g. dog, cat, other).
+        x-extensible-enum:
+        - dog
+        - cat
+        - other
+      assistant:
+        type: boolean
+        description: Whether this animal is a registered assistance animal.

deliverables/1 search offers/EntitlementRight.yaml

@@ -0,0 +1,16 @@
+EntitlementRight:
+  type: object
+  additionalProperties: false
+  description: ENTITLEMENT RIGHT — a credential held by a travelling entity that may qualify for reduced fares or additional offers (loyalty card, discount card, company card, concession, etc.).
+  required:
+  - entitlementType
+  properties:
+    issuer:
+      type: string
+      description: Issuing authority or scheme name.
+    entitlementType:
+      type: string
+      description: Type of entitlement (operator-defined lookup value, e.g. loyaltyCard, discountCard, concession).
+    code:
+      type: string
+      description: Instance identifier such as a card number or voucher code.

deliverables/1 search offers/Luggage.yaml

@@ -0,0 +1,41 @@
+Luggage:
+  allOf:
+  - $ref: .\TravellingEntity.yaml
+  - type: object
+    additionalProperties: false
+    description: LUGGAGE — a bulky item a traveller brings that may affect offer availability, space allocation, or price.
+    required:
+    - entityType
+    - type
+    properties:
+      entityType:
+        type: string
+        const: luggage
+      type:
+        type: string
+        description: Category of item.
+        x-extensible-enum:
+        - bicycle
+        - pram
+        - luggage
+        - wheelchair
+        - skis
+        - snowboard
+        - musicalInstrument
+        - other
+      length:
+        type: integer
+        minimum: 0
+        description: Length in centimetres.
+      width:
+        type: integer
+        minimum: 0
+        description: Width in centimetres.
+      height:
+        type: integer
+        minimum: 0
+        description: Height in centimetres.
+      weight:
+        type: integer
+        minimum: 0
+        description: Weight in kilograms.

deliverables/1 search offers/PassengerVehicle.yaml

@@ -0,0 +1,48 @@
+PassengerVehicle:
+  allOf:
+  - $ref: .\TravellingEntity.yaml
+  - type: object
+    additionalProperties: false
+    description: PASSENGER VEHICLE — a traveller-owned vehicle to be transported (e.g. on a ferry or car-train).
+    required:
+    - entityType
+    - type
+    properties:
+      entityType:
+        type: string
+        const: vehicle
+      type:
+        type: string
+        description: Vehicle category.
+        x-extensible-enum:
+        - car
+        - motorhome
+        - caravan
+        - motorbike
+        - bicycle
+        - trailerOnly
+      height:
+        type: integer
+        minimum: 0
+        description: Height of the vehicle in centimetres.
+      width:
+        type: integer
+        minimum: 0
+        description: Width of the vehicle in centimetres.
+      length:
+        type: integer
+        minimum: 0
+        description: Total length of the vehicle in centimetres.
+      weight:
+        type: integer
+        minimum: 0
+        description: Total weight of the vehicle in kilograms.
+      trailer:
+        description: Details of a towed trailer, if applicable.
+        $ref: .\PassengerVehicle.yaml
+      vehicleRacks:
+        type: array
+        maxItems: 2
+        description: Vehicle racks (e.g. bike racks) mounted on the vehicle.
+        items:
+          $ref: .\VehicleRack.yaml

deliverables/1 search offers/Traveller.yaml

@@ -0,0 +1,34 @@
+Traveller:
+  allOf:
+  - $ref: .\TravellingEntity.yaml
+  - type: object
+    additionalProperties: false
+    description: TRAVELLER — a human traveller for whom offers are sought.
+    required:
+    - entityType
+    properties:
+      entityType:
+        type: string
+        const: traveller
+      age:
+        type: integer
+        minimum: 0
+        description: Age in years at the start time of travel.
+      assistant:
+        type: boolean
+        description: Whether this traveller acts as an assistant to another traveller.
+      dateOfBirth:
+        type: string
+        format: date
+        description: Date of birth. Enables age-band fare calculation. (TBD)
+      externalReference:
+        type: string
+        description: Caller-assigned external reference for this traveller.
+      personalNeeds:
+        type: array
+        description: Accessibility or personal needs types (operator-defined lookup values, see GET /personal-needs or GET /collections/personal-needs/items).
+        items:
+          type: string
+      qualifyingCharacteristics:
+        description: Additional qualifying characteristics used for eligibility determination. Only to specify in the purchase request
+        $ref: .\TravellerQualifyingCharacteristics.yaml

deliverables/1 search offers/TravellerQualifyingCharacteristics.yaml

@@ -0,0 +1,23 @@
+TravellerQualifyingCharacteristics:
+  type: object
+  additionalProperties: false
+  description: TRAVELLER QUALIFYING CHARACTERISTICS — demographic and eligibility data used for fare calculation. May contain GDPR-sensitive personal data; transmit only when required.
+  properties:
+    fullName:
+      type: string
+      description: Full name of the traveller.
+    nationality:
+      type: string
+      description: Nationality (ISO 3166-1 alpha-2 country code).
+    residency:
+      type: string
+      description: Country of residency (ISO 3166-1 alpha-2) for domestic vs. international fare eligibility.
+    dateOfBirth:
+      type: string
+      format: date
+      description: Date of birth. (TBD — final field name pending.)
+    licenseTypes:
+      type: array
+      description: License types held by this traveller that may affect offer availability.
+      items:
+        type: string

deliverables/1 search offers/TravellingEntity.yaml

@@ -0,0 +1,25 @@
+TravellingEntity:
+  type: object
+  description: TRAVELLING ENTITY — base class for all entities taking part in a journey. Use the entityType discriminator to select the concrete sub-type.
+  required:
+  - entityType
+  - travellingEntityId
+  properties:
+    travellingEntityId:
+      type: string
+      description: Stable caller-assigned identifier for this entity. Must be unique within the request.
+    entityType:
+      type: string
+      enum:
+      - traveller
+      - vehicle
+      - animal
+      - luggage
+      description: Discriminator identifying the concrete type of this entity.
+    entitlementRights:
+      type: array
+      description: ENTITLEMENT RIGHTs held by this entity that may qualify for reduced fares or additional offers.
+      items:
+        $ref: .\EntitlementRight.yaml
+  example:
+    { "travellingEntityId": "TE-123", "entityType": "traveller", "entitlementRights": [ { "entitlementRightId": "ER-456", "description": "Senior citizen discount" } ] }

deliverables/1 search offers/VehicleRack.yaml

@@ -0,0 +1,37 @@
+VehicleRack:
+  type: object
+  additionalProperties: false
+  description: VEHICLE RACK — a rack or carrier mounted on a passenger vehicle (e.g. roof rack, bike carrier).
+  properties:
+    type:
+      type: string
+      description: Type of rack.
+      x-extensible-enum:
+      - roofRack
+      - bikeCarrier
+      - skiCarrier
+      - towbarCarrier
+      - other
+    mounting:
+      type: string
+      description: How the rack is mounted on the vehicle.
+      enum:
+      - roof
+      - towbar
+      - rear
+    height:
+      type: integer
+      minimum: 0
+      description: Height of the rack in centimetres.
+    width:
+      type: integer
+      minimum: 0
+      description: Width of the rack in centimetres.
+    length:
+      type: integer
+      minimum: 0
+      description: Length of the rack in centimetres.
+    weight:
+      type: integer
+      minimum: 0
+      description: Weight of the rack (including load) in kilograms.