Team 2: Homework - review the Vehicle object

[edwinvandenbelt]

Vehicle:
  type: object
  description: >-
    A personal vehicle co-transported alongside a traveller (car, motorcycle,
    motorhome, etc.). Subtype of Transportable. License plate and contact
    details are booking-stage attributes and must NOT be sent in an offer request.
  allOf:
    - $ref: '#/components/schemas/Transportable'
  x-semantics:
    transmodel: VEHICLE
    osdm: TransportableSpecification (CAR / MOTOCYCLE / SPECIAL_VEHICLE / TRAILER)
    tomp: unmapped
    bob: unmapped
    omsa: travellingAsset
    ferrygateway: VehicleType (Lead + optional Trailer)
  required:
    - vehicleType
    - length
    - height
    - width
  properties:
    vehicleType:
      type: string
      description: Category of the vehicle.
      enum:
        - car
        - motorcycle
        - motorcycleWithSidecar
        - trike
        - quad
        - van
        - motorhome
        - minibus
        - vehicleCombination
        - bicycle
        - freight
        - specialVehicle
      x-todo: enum, x-enum or lookup?
      x-semantics:
        transmodel: VEHICLE
        osdm: TransportableSpecification.TransportableType (CAR, MOTOCYCLE, SPECIAL_VEHICLE, TRAILER)
        tomp: unmapped
        bob: unmapped
        omsa: travellingAsset (opaque)
        ferrygateway: LeadVehicleCodeType (Car, Van, Motorhome, Motorcycle, MotorCycleWithSidecar, VehicleCombination, Minibus, Bicycle, Freight)
    length:
      type: integer
      minimum: 0
      description: Length of the vehicle in centimetres.
      x-semantics:
        transmodel: unmapped
        osdm: AbstractTransportableVehicleSpecification.length
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: VehicleBaseType.@Length
    height:
      type: integer
      minimum: 0
      description: Height of the vehicle in centimetres.
      x-semantics:
        transmodel: unmapped
        osdm: AbstractTransportableVehicleSpecification.height
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: VehicleBaseType.@Height
    width:
      type: integer
      minimum: 0
      description: Width of the vehicle in centimetres.
      x-semantics:
        transmodel: unmapped
        osdm: AbstractTransportableVehicleSpecification.width
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: VehicleBaseType.@Width
    weight:
      type: integer
      minimum: 0
      description: Weight of the vehicle in kilograms. Required for booking.
      x-semantics:
        transmodel: unmapped
        osdm: AbstractTransportableVehicleSpecification.weight
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: unmapped
    roofWidth:
      type: integer
      minimum: 0
      description: >-
        Width of the roof in centimetres. Required for cars; used to
        determine rack and overhead clearance constraints.
      x-todo: isn't this covered by the 'width'?
      x-semantics:
        transmodel: unmapped
        osdm: CarSpecification.roofWidth
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: unmapped
    textileRoof:
      type: boolean
      description: Indicates the vehicle has a textile (soft/convertible) roof.
      x-todo: why is this relevant?
      x-semantics:
        transmodel: unmapped
        osdm: CarSpecification.textileRoof
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: unmapped
    make:
      type: string
      description: Manufacturer name, e.g. "Audi", "BMW".
      x-todo: why is this relevant?
      x-semantics:
        transmodel: unmapped
        osdm: AbstractTransportableVehicleSpecification.brand
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: LeadVehicleType.@Make
    model:
      type: string
      description: Model name, e.g. "X5", "Golf".
      x-todo: why is this relevant?
      x-semantics:
        transmodel: unmapped
        osdm: AbstractTransportableVehicleSpecification.model
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: LeadVehicleType.@Model
    fuelType:
      type: string
      description: Fuel type of the vehicle.
      enum:
        - electricOrHybrid
        - liquid
        - liquified
        - compressedGas
        - other
      x-todo: enum, x-enum or lookup?
      x-semantics:
        transmodel: unmapped
        osdm: unmapped
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: LeadVehicleType.@FuelType
    isHireCar:
      type: boolean
      description: Indicates the vehicle is a rental/hire car.
      x-todo: why is this relevant?
      x-semantics:
        transmodel: unmapped
        osdm: unmapped
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: LeadVehicleType.@IsHireCar
    bikeOnBack:
      type: boolean
      description: Indicates a bicycle is mounted on the rear of the vehicle.
      x-todo: integrate in 'rack'?
      x-semantics:
        transmodel: unmapped
        osdm: CarSpecification.attachedItems (BICYCLE_STAND)
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: LeadVehicleType.@BikeOnBack
    roofLoad:
      type: boolean
      description: Indicates the vehicle carries a roof load (roof rack or box).
      x-todo: integrate into 'rack'?
      x-semantics:
        transmodel: unmapped
        osdm: CarSpecification.rack
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: LeadVehicleType.@RoofLoad
    rack:
      $ref: '#/components/schemas/VehicleRack'
    trailer:
      $ref: '#/components/schemas/VehicleTrailer'
    registration:
      type: string
      description: >-
        Vehicle registration / licence plate number.
        Personal data — must NOT be included in offer requests;
        only submitted at booking stage.
      x-semantics:
        transmodel: unmapped
        osdm: Car.licensePlate / MotorCycle.licensePlate
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: VehicleBaseType.@Registration

VehicleRack:
  type: object
  description: Roof or rear rack attached to the vehicle.
  required:
    - mounting
  properties:
    mounting:
      type: string
      enum: [roof, rear]
      x-semantics:
        transmodel: unmapped
        osdm: CarRack.mounting (TOP, REAR)
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: unmapped
    type:
      type: string
      enum: [luggageRack, roofRailing]
      x-todo: overlapping with 'mounting'? enum, x-enum or lookup?
      x-semantics:
        transmodel: unmapped
        osdm: CarRack.type (LUGGAGE_RACK, ROOF_RAILING)
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: unmapped
    additionalHeightCm:
      type: integer
      minimum: 0
      x-todo: consistency: height, and specify in the spec it is in cm.
      x-semantics:
        transmodel: unmapped
        osdm: CarRack.additionalHeight
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: unmapped
    additionalLengthCm:
      type: integer
      minimum: 0
      x-todo: consistency: length, and specify in the spec it is in cm. Why isn't there a 'width'?
      x-semantics:
        transmodel: unmapped
        osdm: CarRack.additionalLength
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: unmapped
    numberOfBicycles:
      type: integer
      minimum: 0
      description: Number of bicycles on a rear rack.
      x-todo: why is this relevant?
      x-semantics:
        transmodel: unmapped
        osdm: CarRack.numberOfBicycles
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: unmapped
        
VehicleTrailer:
  type: object
  description: Trailer or caravan towed by the vehicle.
  x-todo: isn't this just a recursive reference to vehicle, with specific types?
  required:
    - length
    - height
  properties:
    trailerType:
      type: string
      enum: [trailer, caravan]
      x-semantics:
        transmodel: unmapped
        osdm: TransportableSpecification.trailer (CarSpecification)
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: TrailerCodeType (Trailer, Caravan)
    length:
      type: integer
      minimum: 0
      description: Length of the trailer in centimetres.
      x-semantics:
        transmodel: unmapped
        osdm: CarSpecification.length (on trailer object)
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: TrailerType → VehicleBaseType.@Length
    height:
      type: integer
      minimum: 0
      description: Height of the trailer in centimetres.
      x-semantics:
        transmodel: unmapped
        osdm: CarSpecification.height (on trailer object)
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: TrailerType → VehicleBaseType.@Height
    width:
      type: integer
      minimum: 0
      description: Width of the trailer in centimetres.
      x-semantics:
        transmodel: unmapped
        osdm: CarSpecification.width (on trailer object)
        tomp: unmapped
        bob: unmapped
        omsa: unmapped
        ferrygateway: TrailerType → VehicleBaseType.@Width

[joachse]

Ugh, this would be better done in a pull request. Its hard to comment on specific lines here.

I just wanted to point out vehicle could be used in many contexts. Querying for a list of available spots on a ferry, or looking for specific cars for rental, or having a car come pick you up. So the x-todo: why is this relevant? might not be relevant for searching but maybe at a later stage when a more specific car have been presented.

Do we want to reuse the object in every context or have specific structures for every context?

[joachse]

Having specific structures for every context could explode the schema, but we would have clean separation of what is relevant in the specific context. For example a VehicleQuery or a PickupVehicle.

I'm torn to what I want, but wanted to hear your thoughts.

[edwinvandenbelt]

That's a great idea! Using PRs. And I tried here to add ALL properties required for operational usage, in other words, combine the 5 standards at stake, based on the search-offer endpoints we selected in the meeting 2 weeks ago.

[edwinvandenbelt]

This is of course already better readable:

Vehicle:
  allOf:
    - $ref: '#/components/schemas/Transportable'
  required: [vehicleType, length, height, width]
  properties:
    vehicleType:
      type: string
      enum: [car, motorcycle, motorcycleWithSidecar, trike, quad, van, motorhome,
             minibus, vehicleCombination, bicycle, freight, specialVehicle]
    length:        { type: integer, minimum: 0 }
    height:        { type: integer, minimum: 0 }
    width:         { type: integer, minimum: 0 }
    weight:        { type: integer, minimum: 0 }
    roofWidth:     { type: integer, minimum: 0 }
    textileRoof:   { type: boolean }
    make:          { type: string }
    model:         { type: string }
    fuelType:
      type: string
      enum: [electricOrHybrid, liquid, liquified, compressedGas, other]
    isHireCar:     { type: boolean }
    bikeOnBack:    { type: boolean }
    roofLoad:      { type: boolean }
    rack:          { $ref: '#/components/schemas/VehicleRack' }
    trailer:       { $ref: '#/components/schemas/VehicleTrailer' }
    registration:  { type: string }
VehicleRack:
  required: [mounting]
  properties:
    mounting:          { type: string, enum: [roof, rear] }
    type:              { type: string, enum: [luggageRack, roofRailing] }
    additionalHeightCm: { type: integer, minimum: 0 }
    additionalLengthCm: { type: integer, minimum: 0 }
    numberOfBicycles:  { type: integer, minimum: 0 }
VehicleTrailer:
  required: [length, height]
  properties:
    trailerType: { type: string, enum: [trailer, caravan] }
    length:      { type: integer, minimum: 0 }
    height:      { type: integer, minimum: 0 }
    width:       { type: integer, minimum: 0 }

[Ulf9]

Transmodel has a different definition of VEHICLE:

VEHICLE:
A public transport vehicle used for carrying passengers.

I suggest we use PASSENGER VEHICLE as the term to relate to the passengers own, brought along vehicle. This avoids clashing with the current Transmodel concept.

[edwinvandenbelt]

worthwile considering!