openapi: 3.0.0
servers:
  - url: https://{server}/api/public/v4
    variables:
      server:
        description: the server where an OpenTripModel implementation is hosted
        default: api.opentripmodel.org
info:
  title: Open Trip Model
  description: |
    # Introduction

    You are viewing the **API Reference Documentation** of OpenTripModel. This reference documentation is targetted at developers that are writing
    client or server code for an OpenTripModel implementation. For a general introduction to OpenTripModel, please refer to the
    [main website of OpenTripModel](https://www.opentripmodel.org/). This documentation is generated from the OpenTripModel API specification, the
    source of which can be found at [OpenTripModels GitHub repository](https://github.com/opentripmodel/opentripmodel).

    > ## ℹ A word on examples
    > The example requests that are shown in this documentation are automatically generated. This means the _structure_ of the examples is right,
    according to the specification, while the _data_ in the examples is not always correct in a given context. E.g. various event types instruct
    to have certain `involvedObjects` available in the event. The examples do not reflect these requirements, since there is (currently) no way
    to express these in terms of an OpenAPI specification.


    # The model
    <img src="/images/otm-model.svg" width="350" style="border:0px;"/>

    OpenTripModel defines entities, displayed yellow in the image. You can click on the boxes in the image to jump to the corresponding section in
    this API Reference Documentation. For a more conceptual introduction to the entities, please read the
    [Introducing the model](https://www.opentripmodel.org/docs/the-model) section of the documentation. There's also an
    [introduction to lifecycles](https://www.opentripmodel.org/docs/lifecycles) available. (Lifecycles are displayed as green boxes in the image.)

    Apart from these entities, perhaps the most important entity in OpenTripModel is the **[Event](/#tag/Event)**. All dynamic behaviour is modeled
    as (a series of) event(s). Please refer to the sections [Important Concepts](https://www.opentripmodel.org/docs/concepts) and
    [Event entity](https://www.opentripmodel.org/docs/event-entity) of the general documentation for an introduction.


    # Technical notes

    ## Unique identifiers
    This section has been moved to the [Implementation guide](https://www.opentripmodel.org/docs/unique-identifiers) on the main OpenTripModel
    website.

    ## Time values
    This section has been moved to the [Implementation guide](https://www.opentripmodel.org/docs/time-and-date-representation) on the main
    OpenTripModel website.

    ## Bundles
    To create multiple entities and events in one request, use a **[Bundle](/#tag/Bundle)** call. This provides transactional guarantees, preventing
    roll-back scenario's. A typical use case is when the originating system is not event based, and it has to communicate an entire "planning" at
    once. The benefits of using a `Bundle` are that you can save network traffic and that all entities and events are validated at the same time.

    ## Changes since 4.2.0-b4
    - Change `sizeConstraint` in `SizeConstraint` to camelCase formatted enum, to be more consistent with other enums.
    - Added the fields `basisType` and `basisReference` to describe the basis of a [`Constraint`](#tag/Constraint).
    - Added the [`Constraint`](#tag/Constraint)-type `dangerousGoodsConstraint`.
    - Added additional `Location` types.
    - Added additional `Vehicle` types.
    - Added the [`Constraint`](#tag/Constraint)-type `numberOfVehiclesConstraint`.
    - All enums are now camelCase, for consistency. Some snake_case values were changed in the process.

    ## Changes since 4.2.0-b3
    - Added the `name` field to `Constraint`, `Shipment` and `Route`, so that all Entities use it in the same way.
    - Added `externalIds` to `Constraint`, so that all Entities use it in the same way.
    - Updated `trafficWarningEvent` to reflect the fact that it needs at least one Location or Route, it does not require both.
    - The eventGenerationTime now may be set by the recipient if the sender does not set it.
    - `Actor` now supports the same contactDetails field `Location` already had.
    - `Shipment` now has a count field for shipments that are counted in units of packaging.
    - Inline location in an `Event` is now always optional because it's also possible to use an involvedObject Location.
    - Removed linkedTrips array from the `Trip` Entity. Trips should be linked using the `linkTripsEvent`.
    - Removed links array from the `Vehicle` Entity. Vehicles should be linked using the `coupleVehiclesEvent`.

    ## Changes since 4.2.0-b2
    - Added the [`Constraint`](#tag/Constraint)-type `eventOrderConstraint`,  to constrain the order of event if there are no timestamps available.
    - Updated the diagram in the section [The model](#section/The-model) to reflect recent changes.
    - Added the possibility to add a `constraint` directly to a `Sensor` entity.
    - Added a `placement` field to the `loadShipmentEvent`.
    - Numeric values in `valueWithUnit` can now be any numeric type, not just `int32`.
    - More explicit documentation on event ordering in relation to the `cancelAllEntityEvents` event.

    ## Changes since 4.2.0-b1
    - Added [top level `/events` endpoint]/paths/~1events/get)
    - Added `involvedObject` query parameter for filtering events
    - Added `lifecycle` query parameter for filtering events on their lifecycle. This only applies when querying for events via the general `/events`
      endpoint.
    - Added overview documentation about [Event endpoints](#event-endpoints)
    - Added overview documentation about [Involved objects](#involved-objects)
    - Updated the specification definition to [OpenAPI 3.0.0](https://swagger.io/specification/)

    ## Changes since 4.1
    - Rewrite of the [documentation on `Event`s](#tag/Event).
    - Added `groupingId` to `Event`s.
    - Added event types:
        - `cancelAllEntityEvents`;
        - `cancelGroupedEvents`;
        - `dissociateFromActorEvent`.
    - Fixed inconsistent query parameters for `GET` requests on event-endpoints.
    - Sensors are now first class citizens in OpenTripModel:
        - Added the `Sensor` entity and corresponding endpoints
        - Added `coupleSensorEvent` and `decoupleSensorEvent`
        - Updated `sensorValueConstraint`
        - Added `sensorUpdateFrequencyConstraint`

    ## Changes since 4.0
    - The `administrativeReference` member of the `Location` entity is now camelCased, like all other members. In OTM 4.0 it was inconsistently
      called ~~`administrative-reference`~~. Implementors are advised to be a [Tolerant Reader](https://martinfowler.com/bliki/TolerantReader.html),
      that is: to accept both forms, but only write the new form.
    - The `location` member of several types of `Event`s no longer accepts references to pre-defined `Location` entities, now only inline (_ad hoc_)
      entities are allowed inside an event. If you want to refer to a pre-defined `Location` inside an `Event`, either publish the event on the
      `Location`'s `event` endpoint or refer to the `Location` in the `involvedObjects` member of the `Event`.
    - Improved the `constraintReference` documentation and removed the ambiguous `reference` field.
    - Added the field `eventGenerationTime` to `Event`. This can be useful e.g. for events in the `projected` lifecycle phase, that typically are
      calculated.
    - Added speed and heading info to `locationUpdateEvents` for point locations.


    # Licence
    <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">
      <img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-sa/4.0/88x31.png" />
    </a>
    <br />
    All OpenTripModel documentation is licensed under a
    <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International License</a>.
  version: "4.2.0-b5"
  license:
    name: Creative Commons Attribution-ShareAlike 4.0 International License
    url: http://creativecommons.org/licenses/by-sa/4.0/

tags:
  - name: Location
    description: |
      Locations are geometric entities which can have either the shape of a point or an area. These points and areas can be used to model delivery
      zones, store and warehouse coordinates as well as environmental zones within urban areas, areas with access restrictions, etc.
  - name: Event
    description: |
      An event is something occurring at a specific time (whether in the past, present, or past alike) and (optionally) at a specific location. Events
      are the core of this API. Events link all static objects together. There are several different event types defined in OpenTripModel. The
      sections below document the available event types. Events are devided into categories:
      - [Update events](#update-events)
      - [Warning events](#warning-events)
      - [Action events](#action-events)
      - [Time window events](#time-window-events)
      - [Associative events](#associative-events)
      - [Meta events](#meta-events)

      In the tables below, symbols are used to indicate which relations with other entities are possible, given an event type. The choice of symbols
      is loosely based on the checkbox/radio button convention, as explained in the following table:

      | Symbol | Meaning                                                                        |
      | -----: | ------------------------------------------------------------------------------ |
      | ●      | Object relation required                                                       |
      | ○      | Exactly one of the relations marked with a ○ should be present.                |
      | ■      | At least one of the relations marked with a ■ should be present.               |
      | □      | Optional relation. Zero or more of the relations marked with □ may be present. |

      ## Event endpoints

      Since events are related to at least one other entity, events can be accessed both via the related entities as well as via a dedicated `events`
      endpoint. The following table summarizes all available ways to access events via OpenTripModel endpoints:

      | #&#160;events | access          | read/write | &#160;                                                   |
      | ------------- | --------------- | ---------- | -------------------------------------------------------- |
      | list          | directly        | read       | [**GET** `/events`](#/paths/~1events/get)                |
      | list          | directly        | write      | [use a Bundle](#tag/Bundle)                              |
      | list          | via&#160;entity | read       | **GET** `/{entity}/{uuid}/{lifecycle}/events/`           |
      | list          | via&#160;entity | write      | [use a Bundle](#tag/Bundle)                              |
      | single        | directly        | read       | [**GET** `/events/{uuid}`](#/paths/~1events~1{uuid}/get) |
      | single        | directly        | write      | [**PUT** `/events`](#/paths/~1events/put)                |
      | single        | via&#160;entity | read       | N/A                                                      |
      | single        | via&#160;entity | write      | **PUT** `/{entity}/{uuid}/{lifecycle}/events/`           |

      ## Involved objects

      Each event has a list of `involvedObjects`. Each event should have at least one other entity in the list of `involvedObjects`, since entities
      only exist in the context of one or more other entities. (Note that events count as entities too, so it _is_ valid to have an event that only
      has another event as involved object. An example is a `cancelEvent`, that only has the event it cancels as involved object.) Some event types
      impose additional requirements, such as a higher minimal number of `involvedObjects` or a specific type of entity as involved object.

      Note that events can be published on the endpoint of an entity, thus creating
      an involvement implicitly. In other words, when you `PUT` e.g. a `locationUpdateEvent` on the
      `/vehicles/0a254672-fc1d-4639-899f-15c40cbb7c3f/actual/events` endpoint, the `Vehicle` with UUID `0a254672-fc1d-4639-899f-15c40cbb7c3f` will
      be an involved object for the `locationUpdateEvent`, even if you don't add the `Vehicle` to the `involvedObjects` array. It is advisable for OTM
      server implementations to add this `Vehicle` to the `involvedObjects` of the `locationUpdateEvent` as soon as possible, to make sure it is
      returned whenever the event is retreived, e.g. via the general `/events` endpoint.

      ## Update events

      Update events typically send an update to the state of an entity. These kind of events are only sensible in the `actual` and `realized`
      lifecycle phases. This makes sense, because things like location or sensor updates can't be planned nor projected. Update events typically
      involve only one entity at a time.

      _Applicable lifecycle phases for update events:_

      | Planned | Projected | Actual | Realized |
      | :-----: | :-------: | :----: | :------: |
      | &#160;  | &#160;    | ○      | ○        |

      ### locationUpdateEvent

      Updates the location of a `Vehicle`

      _Applicable entities for `locationUpdateEvent`:_

      | Location | Vehicle | Shipment | Trip  | Route | Actor | Constraint | Sensor | Event |
      | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: |
      | □        | ●       | &#160;   | &#160;| &#160;| &#160;| &#160;     | &#160; | &#160;|

      The Location is optional because an inline location reference can be used for this event.

      ### sensorUpdateEvent

      Event to send an updated value of a sensor of the `Vehicle`. Can be used e.g. to monitor temperature inside a trailer.

      _Applicable entities for `sensorUpdateEvent`:_

      | Location | Vehicle | Shipment | Trip  | Route | Actor | Constraint | Sensor | Event |
      | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: |
      | &#160;   | &#160;  | &#160;   | &#160;| &#160;| &#160;| &#160;     | ●      | &#160;|

      ### startEngineEvent, stopEngineEvent

      The engine of a `Vehicle` is started or stopped.

      _Applicable entities for `startEngineEvent` and `stopEngineEvent`:_

      | Location | Vehicle | Shipment | Trip  | Route | Actor | Constraint | Sensor | Event |
      | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: |
      | &#160;   | ●       | &#160;   | &#160;| &#160;| &#160;| &#160;     | &#160; | &#160;|

      ## Warning events

      Warning events warn about violations, possible causes for delay or other things that may have impact on an operation and may need some
      attention. Warning events can exist in all lifecycle phases, since other events might be the cause of a warning.

      _Applicable lifecycle phases for warning events:_

      | Planned | Projected | Actual | Realized |
      | :-----: | :-------: | :----: | :------: |
      |  ○      | ○         | ○      | ○        |

      ### restrictionWarningEvent

      A warning event that may be sent when a restriction is violated. This event can be used for all restrictions that are not modelled as
      OpenTripModel `Constraints`. For violations of `Constraints`, please use the `constraintViolationEvent` instead. Restriction violations you
      can model using this event include, but are not limited to:

      - traffic rule violations
      - exceeding of load capacity
      - routing through environmental zones

      _Applicable entities for `restrictionWarningEvent`:_

      | Location | Vehicle | Shipment | Trip  | Route | Actor | Constraint | Sensor | Event |
      | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: |
      | ○        | ○       | ○        | ○     | ○     | ○     | ○          | ○      | ○     |

      ### constraintViolationEvent

      Can be generated if a constraint is violated. This event type is meant for violations of `Constraints` that are modelled as such in
      OpenTripModel. If there is no `Constraint`, please use the `restrictionWarningEvent` instead. A `constraintViolationEvent` should
      always have the applicable `Constraint` in the `involvedObjects` member and one or more other entities that are involved in the
      violation.

      _Applicable entities for `constraintViolationEvent`:_

      | Location | Vehicle | Shipment | Trip  | Route | Actor | Constraint | Sensor | Event |
      | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: |
      | ○        | &#160;  | ○        | ○     | &#160;| &#160;| ●          | ○      | &#160;|

      ### trafficWarningEvent

      A warning event that may be sent to warn about a traffic condition on a `Location` or a `Route`.

      _Applicable entities for `trafficWarningEvent`:_

      | Location | Vehicle | Shipment | Trip  | Route | Actor | Constraint | Sensor | Event |
      | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: |
      | ■        | &#160;  | &#160;   | &#160;| ■     | &#160;| &#160;     | &#160; | &#160;|


      ## Action events

      Action events describe actions that take place in an operation. Action events can typically be used in any lifecycle phase. This makes sense,
      since you can say an action can be planned, projected, actually happening or be realized. Action events typically involve only one entity at
      a time.

      _Applicable lifecycle phases for Action events:_

      | Planned | Projected | Actual | Realized |
      | :-----: | :-------: | :----: | :------: |
      |  ○      | ○         | ○      | ○        |

      ### startMovingEvent, stopMovingEvent

      Marks the moment a `Vehicle` starts or stops moving after or before standing still for a while.

      _Applicable entities for `startMovingEvent` and `stopMovingEvent`:_

      | Location | Vehicle | Shipment | Trip  | Route | Actor | Constraint | Sensor | Event |
      | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: |
      | &#160;   | ●       | &#160;   | &#160;| &#160;| &#160;| &#160;     | &#160; | &#160;|

      ### startWaitingEvent, stopWaitingEvent

      Marks the moment a `Vehicle` starts or stops waiting.

      _Applicable entities for `startWaitingEvent` and `stopWaitingEvent`:_

      | Location | Vehicle | Shipment | Trip  | Route | Actor | Constraint | Sensor | Event |
      | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: |
      | &#160;   | ●       | &#160;   | &#160;| &#160;| &#160;| &#160;     | &#160; | &#160;|

      ### startLoadingAndUnloadingEvent, stopLoadingAndUnloadingEvent

      Marks the start or end of a time period meant for loading and unloading.

      _Applicable entities for `startLoadingAndUnloadingEvent` and `stopLoadingAndUnloadingEvent`:_

      | Location | Vehicle | Shipment | Trip  | Route | Actor | Constraint | Sensor | Event |
      | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: |
      | &#160;   | ●       | &#160;   | &#160;| &#160;| &#160;| &#160;     | &#160; | &#160;|

      ## Time window events

      Time window events are used to model a time window in a `planned` or `projected` lifecycle phase. The start and end of a time window are
      modelled as separate events. The following time window events are available:

      * `pickupTimeWindowStartEvent`: Marks the start of a time window for the pickup of a `Shipment`.
      * `pickupTimeWindowEndEvent`: Marks the end of a time window for the pickup of a `Shipment`.
      * `deliveryTimeWindowStartEvent`: Marks the start of a time window for the delivery of a `Shipment`.
      * `deliveryTimeWindowEndEvent`: Marks the end of a time window for the delivery of a `Shipment`.

      _Applicable lifecycle phases for time window events:_

      | Planned | Projected | Actual | Realized |
      | :-----: | :-------: | :----: | :------: |
      |  ○      | ○         | &#160; | &#160;   |

      _Applicable entities for `pickupTimeWindowStartEvent`, `pickupTimeWindowEndEvent`, `deliveryTimeWindowStartEvent` and
      `deliveryTimeWindowEndEvent`:_

      | Location | Vehicle | Shipment | Trip  | Route | Actor | Constraint | Sensor | Event |
      | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: |
      | &#160;   | &#160;  | ●        | &#160;| &#160;| &#160;| &#160;     | &#160; | &#160;|

      ## Associative events

      Associative events are used to create or remove associations between entities. These events can take place in all lifecycle phases.
      Associative events typically involve two events.

      _Applicable lifecycle phases for associative events:_

      | Planned | Projected | Actual | Realized |
      | :-----: | :-------: | :----: | :------: |
      |  ○      | ○         | ○      | ○        |

      ### coupleVehiclesEvent, decoupleVehiclesEvent

      Marks the moment two `Vehicle`s are coupled or decoupled. Coupling of `Vehicles` can have several meanings in the real world, including, but
      not limited to:

      - coupling a trailer to a truck
      - coupling two or more trailer/truck combinations to form a platoon
      - coupling a trailer to a ferry

      _Applicable entities for `coupleVehiclesEvent` and `decoupleVehiclesEvent`:_

      | Location | Vehicle | Shipment | Trip  | Route | Actor | Constraint | Sensor | Event |
      | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: |
      | &#160;   | ●  ●    | &#160;   | &#160;| &#160;| &#160;| &#160;     | &#160; | &#160;|

      ### assignToTripEvent, deassignFromTripEvent

      Assigns or deassings a `Vehicle` to/from a `Trip`.

      _Applicable entities for `assignToTripEvent` and `deassignFromTripEvent`:_

      | Location | Vehicle | Shipment | Trip  | Route | Actor | Constraint | Sensor | Event |
      | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: |
      | &#160;   | ●       | &#160;   | ●     | &#160;| &#160;| &#160;     | &#160; | &#160;|


      ### assignDriverEvent, deassignDriverEvent

      (De)assigns an `Actor` as a driver to/from a `Vehicle`.

      _Applicable entities for `assignDriverEvent` and `deassignDriverEvent`:_

      | Location | Vehicle | Shipment | Trip  | Route | Actor | Constraint | Sensor | Event |
      | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: |
      | &#160;   | ●       | &#160;   | &#160;| &#160;| ●     | &#160;     | &#160; | &#160;|

      ### associateWithActorEvent, dissociateFromActorEvent

      Associate an entity with an `Actor` or dissociate an already associated actor and entity. The exact meaning of the association can vary and is
      defined by the `role` parameter of the association event. Note that OpenTripModel implementations may choose to use `Actor` associations as a
      source of authorization information. In that case, one can e.g. only query `Shipment`s that are associated with a certain `Actor`.

      _Applicable entities for `associateWithActorEvent` and `dissociateFromActorEvent`:_

      | Location | Vehicle | Shipment | Trip  | Route | Actor | Constraint | Sensor | Event |
      | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: |
      | ○        | ○       | ○        | ○     | ○     | ●     | ○          | ○      | ○     |

      ### Shipment loading and unloading events

      There are four event types for dealing with shipment loading and unloading. `loadShipmentEvent` and `unloadShipmentEvent` describe the loading
      and unloading of `Shipment`s to or from a `Vehicle`. `receiveShipmentEvent` and `releaseShipmentEvent` describe the reception or release of a
      `Shipment` on or from a `Location`. Typically, a `loadShipmentEvent` could be paired to a `releaseShipmentEvent`, occuring at the same time.
      This would mean that a `Shipment` is loaded into a `Vehicle` and at the same time released by a `Location`. In the same fashion, an
      `unloadShipmentEvent` could be paired to a `receiveShipmentEvent`. OpenTripModel does not _require_ to model both the loading/unloading and
      reception/release. It is up to the implementation parties to decide which level of granularity in events is desired for a specific operation.

      _Applicable entites for loading and unloading events:_

      | event type             | Location | Vehicle | Shipment | Trip  | Route | Actor | Constraint | Sensor | Event | description
      | ---------------------: | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: | -----------
      | `loadShipmentEvent`    | &#160;   | ●       | ●        | &#160;| &#160;| &#160;| &#160;     | &#160; | &#160;| Load a `Shipment` in a `Vehicle`
      | `unloadShipmentEvent`  | &#160;   | ●       | ●        | &#160;| &#160;| &#160;| &#160;     | &#160; | &#160;| Unload a `Shipment` from a `Vehicle`
      | `receiveShipmentEvent` | ●        | &#160;  | ●        | &#160;| &#160;| &#160;| &#160;     | &#160; | &#160;| Receive a `Shipment` on a `Location`
      | `releaseShipmentEvent` | ●        | &#160;  | ●        | &#160;| &#160;| &#160;| &#160;     | &#160; | &#160;| Release a `Shipment` from a `Location`


      ### linkTripsEvent

      Event to be used to link two `Trip`s together. This can be used e.g. if you want to model a larger `Trip` with multiple "legs". While
      OpenTripModel does not have a "leg" object, you can model each "leg" as a `Trip` and then link those `Trip`s together. A `linkTripsEvent`
      should at least link to two trip entities in the `involvedObjects` member; it is also allowed to link more than two trips together in one
      event.

      _Applicable entities for `linkTripsEvent`:_

      | Location | Vehicle | Shipment | Trip       | Route | Actor | Constraint | Sensor | Event |
      | :------: | :-----: | :------: | :--------: | :---: | :---: | :--------: | :----: | :---: |
      | &#160;   | &#160;  | &#160;   | ● ● □ ...  | &#160;| &#160;| &#160;     | &#160; | &#160;|


      ### Sensor coupling

      A `Sensor` can be coupled to another entity. It is also possible to decouple `Sensor`s, to facilitate portable sensors that are temporarily
      used. To couple and decouple sensors, use one of the following event types:
      - `coupleSensorEvent`
      - `decoupleSensorEvent`
      The entity the `Sensor` is coupled to, or decoupled from, should be in the `involvedObjects` list of the event.

      The meaning of a sensor coupling event might be a bit different in different lifecycle phases:
      - In the `planned` and `projected` phases, the event should be interpreted as "it is planned (or projected) that this sensor will be coupled
        to this entity. This might be useful if you want to express a planning in OpenTripModel and you want to explicitely document the action
        of placing a portable sensor in e.g. a trailer.
      - In the `actual` lifecycle phase, the event can represent the moment a sensor is installed. But sometimes a sensor is permanently installed,
        and you just need a way to tell the system that a certain sensor is associated with a certain vehicle or physical location. In any case, a
        system can use the couple events in the `actual` lifecycle phase to know that update events to the sensor also apply to the associated
        entity.
      - In the `realized` lifecycle phase, the couple and decouple events might be important for monitoring and auditing. E.g. once you know a
        temperature sensor is coupled to a trailer, you can use it to create an audit trail of the temperature inside the trailer during a trip.

      _Applicable entities for `coupleSensorEvent` and `decoupleSensorEvent`:_

      | Location | Vehicle | Shipment | Trip  | Route | Actor | Constraint | Sensor | Event |
      | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: |
      | ○        | ○       | ○        | &#160;| &#160;| ○     | &#160;     | ●      | &#160;|

      ## Meta events

      Meta events are events about events. There are two types of meta events: `cancelEvent` and `ignoreEvent`. As a rule of thumb, a `cancelEvent`
      is to be used for events that you created yourself and want to cancel (or replace), while an `ignoreEvent` is meant to notify that an event
      sent by another system or actor is to be ignored. An example of the latter might be an event to ignore a `sensorUpdateEvent`, because the
      sensor is defective.

      _Applicable lifecycle phases for meta events:_

      | Planned | Projected | Actual | Realized |
      | :-----: | :-------: | :----: | :------: |
      |  ○      | ○         | ○      | ○        |

      ### cancelEvent

      Cancels one or more `Event`s. Since events can only be created and not deleted nor updated, a `cancelEvent` is needed when you need to change
      or remove an event. To be canceled events should be set as `involvedObjects`. Note that you can only cancel events in your "own" lifecycle
      phase. You can't cancel a `cancelEvent`.

      In order to preserve idempotence, it is not valid to reuse the UUID of an event that has been cancelled by a CancelEvent. A new event that
      replaces a cancelled Event should always get a new UUID.

      _Applicable entities for `cancelEvent`:_

      | Location | Vehicle | Shipment | Trip  | Route | Actor | Constraint | Sensor | Event     |
      | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :-------: |
      | &#160;   | &#160;  | &#160;   | &#160;| &#160;| &#160;| &#160;     | &#160; | ● □ ...   |

      ### cancelAllEntityEvents

      This event can be used to cancel events that have been associated with a given entity. _All_ applicable events that were
      generated before the time given in the `cancelAllEntityEvents` are cancelled.
      This might be needed e.g. in cases where a `Trip` with lots of `planned` events is published and the planning is changed.
      In such a case, it can be more efficient to just cancel all events and start over. You can only cancel events that are in the
      same lifecycle phase as the `cancelAllEntityEvents` you are sending. If there are any `cancelAllEntityEvents` for the given entity, those will
      not be cancelled.

      #### How to determine which events get cancelled:

      In order to preserve idempotence without making it impossible to insert new events for the given entity, this event follows
      a specific rule about timing.

      This rule is based on the different event timing orders as explained in the main OpenTripModel documentation:
      [Ordering of events](https://www.opentripmodel.org/v4.2.0/docs/ordering-of-events).

      The main rule is:
      > **A `cancelAllEntityEvents` event cancels every associated event of the given entity with an `eventGenerationTime` earlier than
        the `time` given in the `cancelAllEntityEvents` body.**

      As an example, take the two events given in the [Ordering of events](https://www.opentripmodel.org/v4.2.0/docs/ordering-of-events) page:
      * A `planned` `stopMovingEvent` with `time` = _2018-09-05T12:00Z_ and `eventGenerationTime` = _2018-08-30T10:15Z_
      * A `planned` `startMovingEvent` with `time` = _2018-09-05T13:00Z_ and `eventGenerationTime` = _2018-08-30T09:15Z_

      Both events have the same vehicle as an `involvedObject`.

      * A user inserts a `cancelAllEntityEvents` for this vehicle. This event is inserted in the `planned` lifeCycle because cancel Events
        can only cancel events in their own lifeCycle. It is given `time` = _2018-08-30T09:45Z_ and `eventGenerationTime` = _2018-08-30T11:48Z_

      This `eventGenerationTime` is the time the `cancelAllEntityEvents` object was generated and is not relevant beyond that.

      <img src="/images/cancel-all-entity-events-timing.svg" width="800" style="border:0px;"/>

      In this example, the 'cutoff point' for the `cancelAllEntityEvents` is _2018-08-30T09:45Z_. All events associated with the vehicle with an
      `eventGenerationTime` earlier than that are cancelled. Events with an `eventGenerationTime` after the cutoff point are not cancelled, so the
      `stopMovingEvent` stays active.

      A few edge cases have been identified:
      * Events with an `eventGenerationTime` exactly _equal_ to the `time` of the `cancelAllEntityEvents` are _not_ cancelled. This makes it more
        straightforward to use a `cancelAllEntityEvents` as part of a larger update containing new events that should not be cancelled.
      * A `cancelAllEntityEvents` with a `time` after its own `eventGenerationTime` is invalid and should not be used.
      * Events without an explicit `eventGenerationTime` cannot be cancelled by a `cancelAllEntityEvents`. Make sure to use the `eventGenerationTime`
        on all events if you want to make use of the `cancelAllEntityEvents`. Note that if the sender does not set the eventGenerationTime on an event,
        the recipient may set this field to the time of reception of the event.

      _Applicable entities for `cancelAllEntityEvents`:_

      | Location | Vehicle | Shipment | Trip  | Route | Actor | Constraint | Sensor | Event |
      | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: |
      | ○        | ○       | ○        | ○     | ○     | ○     | ○          | ○      | &#160;|

      ### cancelGroupedEvents

      This event can be used to cancel all events that share the same `groupingId`. The grouping IDs to be cancelled must be set in the
      `cancelledGroupingIds` variable, which can contain an array of grouping IDs. _All_ applicable events that were
      generated before the time given in the `cancelGroupedEvents` are cancelled.

      For the `cancelGroupedEvents`, the timing rule works exactly the same as for the `cancelAllEntityEvents`.

      _Applicable entities for `cancelGroupedEvents`:_

      | Location | Vehicle | Shipment | Trip  | Route | Actor | Constraint | Sensor | Event |
      | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: |
      | ○        | ○       | ○        | ○     | ○     | ○     | ○          | ○      | &#160;|

      ### ignoreEvent

      Ignore one or more `Event`. To be ignored event(s) should be set as `involvedObject(s)`. Only use `ignoreEvents` to mark events from other
      systems or actors to be ignored if there is no other way to prevent the events from being sent at all.

      _Applicable entities for `ignoreEvent`:_

      | Location | Vehicle | Shipment | Trip  | Route | Actor | Constraint | Sensor | Event     |
      | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :-------: |
      | &#160;   | &#160;  | &#160;   | &#160;| &#160;| &#160;| &#160;     | &#160; | ● □ ...   |
  - name: Trip
    description: |
      A `Trip` represents a series of events, which optionally may be linked to a route.
  - name: Route
    description: |
      A `Route` describes how to move through space in between two locations.
  - name: Vehicle
    description: |
      A `Vehicle` is any entity which can move through space in between locations. It can be for instance a truck, a trailer, an airplane, a drone, or
      even something which has not been invennted yet.
  - name: Sensor
    description: |
      A `Sensor` is an entity which can measure quantities, typically with a certain frequency. Examples are temperature sensors, weight sensors, etc.
      `Sensor` entities can be coupled to other entities. E.g. to measure the temperature inside a trailer, one could couple a `Sensor` entity
      representing a temperature sensor to a `Vehicle` entity representing a trailer.
  - name: Shipment
    description: |
      A `Shipment` is one (or more) item(s) being transported between locations.
  - name: Actor
    description: |
      An `Actor` represents organisations or persons that participate in a logistic process in OpenTripModel.
  - name: Constraint
    description: |
      A `Constraint` can be used to model `Locations` with limited access or `Trips` or `Shipments` with conditions that have to stay within a given
      range.
  - name: Bundle
    description: |
      A `Bundle` creates multiple entities and events in one request.
x-tagGroups:
  - name: Operations per entity
    tags:
      - Location
      - Trip
      - Route
      - Vehicle
      - Shipment
      - Actor
      - Constraint
      - Sensor
  - name: Event-related operations
    tags:
      - Event
  - name: Bundle operations
    tags:
      - Bundle

paths:
  /locations:
    get:
      summary: Get a list of Locations
      description: Get a list of `Locations`, optionally filtered by query parameters.
      tags:
        - Location
      parameters:
        - $ref: '#/components/parameters/nameParam'
        - $ref: '#/components/parameters/externalIdSchemaParam'
        - $ref: '#/components/parameters/externalIdValueParam'
        - $ref: '#/components/parameters/actorQueryParam'
        - $ref: '#/components/parameters/roleQueryParam'
      responses:
        '200':
          description: |
            A list of all defined `Locations`, optionally filtered by query parameters.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/location'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/location'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      summary: Create a new Location
      description: |
        Create a `Location` object with the given data.
      tags:
        - Location
      responses:
        '201':
          description: |
            The `Location` object as created. The returned object will contain the UUID that can be used to refer to this object in future calls.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/location'
            application/xml:
              schema:
                $ref: '#/components/schemas/location'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '409':
          $ref: '#/components/responses/conflict'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/location'
  '/locations/{uuid}':
    get:
      summary: Get a specific Location by its UUID
      description: Retrieves a single `Location` object by its unique identifier (UUID)
      tags:
        - Location
      parameters:
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '200':
          description: A `Location` object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/location'
            application/xml:
              schema:
                $ref: '#/components/schemas/location'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    post:
      summary: Update a Location
      description: |
        Update a `Location` object with the given data. Note that the UUID-part of the `id` in the entity in the body of the `POST`-request should
        equal the ID part of the endpoint where the entity is posted to, otherwise a `400` (Bad request) error will be returned.
      tags:
        - Location
      parameters:
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '200':
          description: The `Location` object with updated values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/location'
            application/xml:
              schema:
                $ref: '#/components/schemas/location'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/location'
  '/locations/{uuid}/{lifecycle}/events':
    get:
      summary: Get a list of Events for this Location
      description: Retrieves a list of `Events` for the `Location` with the given UUID
      tags:
        - Location
      parameters:
        - $ref: '#/components/parameters/lifecycle'
        - $ref: '#/components/parameters/uuidParam'
        - $ref: '#/components/parameters/startDateTimeParam'
        - $ref: '#/components/parameters/endDateTimeParam'
        - $ref: '#/components/parameters/eventTypeParam'
        - $ref: '#/components/parameters/groupingIdParam'
        - $ref: '#/components/parameters/involvedObjectParam'
      responses:
        '200':
          description: A list of `Events` for the given `Location`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      summary: Publish a new Event for the given Location
      description: Publish a new `Event` for the given `Location`
      tags:
        - Location
      parameters:
        - $ref: '#/components/parameters/lifecycle'
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '201':
          description: |
            The created `Event`. The returned object will contain the generated UUID that can be used to refer to this `Event` in later requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event'
            application/xml:
              schema:
                $ref: '#/components/schemas/event'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/event'
  /trips:
    get:
      summary: Get a list of Trips
      description: |
        Retrieves a list of all `Trips`, optionally filtered by query parameters.
      tags:
        - Trip
      parameters:
        - $ref: '#/components/parameters/nameParam'
        - $ref: '#/components/parameters/actorQueryParam'
        - $ref: '#/components/parameters/externalIdSchemaParam'
        - $ref: '#/components/parameters/externalIdValueParam'
      responses:
        '200':
          description: 'A list of trips, optionally filtered by query parameters.'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/trip'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/trip'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      summary: Create a new Trip
      description: Create a `Trip` object with the given data.
      tags:
        - Trip
      responses:
        '201':
          description: |
            The `Trip` object as created. The returned object will contain the UUID that can be used to refer to this object in future calls.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/trip'
            application/xml:
              schema:
                $ref: '#/components/schemas/trip'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '409':
          $ref: '#/components/responses/conflict'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/trip'
  '/trips/{uuid}':
    get:
      summary: Get a specific Trip by its UUID
      description: Retrieves a `Trip` object by its unique identifier (UUID)
      tags:
        - Trip
      parameters:
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '200':
          description: A `Trip` object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/trip'
            application/xml:
              schema:
                $ref: '#/components/schemas/trip'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    post:
      summary: Update Trip
      description: |
        Update a `Trip` object with the given data. Note that the UUID-part of the `id` in the entity in the body of the `POST`-request should
        equal the ID part of the endpoint where the entity is posted to, otherwise a `400` (Bad request) error will be returned.
      tags:
        - Trip
      parameters:
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '200':
          description: The updated trip object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/trip'
            application/xml:
              schema:
                $ref: '#/components/schemas/trip'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/trip'
  '/trips/{uuid}/{lifecycle}/events':
    get:
      summary: Get Events for this Trip
      description: Retrieves a list of `Events` for the trip with the given UUID.
      tags:
        - Trip
      parameters:
        - $ref: '#/components/parameters/lifecycle'
        - $ref: '#/components/parameters/uuidParam'
        - $ref: '#/components/parameters/startDateTimeParam'
        - $ref: '#/components/parameters/endDateTimeParam'
        - $ref: '#/components/parameters/eventTypeParam'
        - $ref: '#/components/parameters/groupingIdParam'
        - $ref: '#/components/parameters/involvedObjectParam'
      responses:
        '200':
          description: A list of Events for the given trip
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      summary: Publish a new Event for the given trip
      description: |
        Publish a new `Event` for the given trip. Note that a planned `Trip` may consist of a lot of `Events`. Therefore it is possible to create a
        `Trip` with its events at once via a `PUT` to the `trips` endpoint.
      tags:
        - Trip
      parameters:
        - $ref: '#/components/parameters/lifecycle'
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '201':
          description: |
            The created `Event`. The returned object will contain the generated UUID that can be used to refer to this `Event` in later requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event'
            application/xml:
              schema:
                $ref: '#/components/schemas/event'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/event'
  /routes:
    get:
      summary: Get a list of Routes
      description: |
        Retrieves a list of all `Routes`, optionally filtered by query parameters.
      tags:
        - Route
      parameters:
        - $ref: '#/components/parameters/nameParam'
        - $ref: '#/components/parameters/actorQueryParam'
        - $ref: '#/components/parameters/externalIdSchemaParam'
        - $ref: '#/components/parameters/externalIdValueParam'
      responses:
        '200':
          description: |
            A list of `Routes`, optionally filtered by query parameters.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/route'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/route'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      summary: Create a new Route
      description: Create a new `Route` object
      tags:
        - Route
      responses:
        '201':
          description: |
            The created `Route` object. Containes the generated UUID that can be used to refer to this `Route` in later requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/route'
            application/xml:
              schema:
                $ref: '#/components/schemas/route'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '409':
          $ref: '#/components/responses/conflict'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/route'
  '/routes/{uuid}':
    get:
      summary: Get a specific Route by its UUID
      description: Retrieves a `Route` object by its unique identifier (UUID)
      tags:
        - Route
      parameters:
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '200':
          description: A `Route` object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/route'
            application/xml:
              schema:
                $ref: '#/components/schemas/route'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    post:
      summary: Update a Route
      description: |
        Updates a `Route` object with the posted data. Note that the UUID-part of the `id` in the entity in the body of the `POST`-request should
        equal the ID part of the endpoint where the entity is posted to, otherwise a `400` (Bad request) error will be returned.
      tags:
        - Route
      parameters:
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '200':
          description: The updated `Route` object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/route'
            application/xml:
              schema:
                $ref: '#/components/schemas/route'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/route'
  '/routes/{uuid}/{lifecycle}/events':
    get:
      summary: Get Events on a Route
      description: |
        Retrieves a list of `Events` on the `Route`, identified by its UUID. The behaviour of this call is slightly different, depending on the
        `lifecycle` phase:

        - "planned" and "projected": The `endDateTime` query parameter is mandatory. The `startDateTime` query parameter is optional; if it is
          ommitted, the default value is _now_. The returned list is a list of planned or projected `Events` on the `Route` in the given time window,
          that are known at the time of the request.
        - "actual": Both the `endDateTime` and `startDateTime` query parameters are mandatory. The returned list contains actual `Events` on the given
          `Route`, within the given time window.
        - "realized": The `startDateTime` query parameter is mandatory. The `endDateTime` query parameter is optional; when ommitted, the default
          value is "now". The returned list is a list of actual `Events` that took place on the given `Route` in the given time window.
      tags:
        - Route
      parameters:
        - $ref: '#/components/parameters/lifecycle'
        - $ref: '#/components/parameters/uuidParam'
        - $ref: '#/components/parameters/startDateTimeParam'
        - $ref: '#/components/parameters/endDateTimeParam'
        - $ref: '#/components/parameters/eventTypeParam'
        - $ref: '#/components/parameters/groupingIdParam'
        - $ref: '#/components/parameters/involvedObjectParam'
      responses:
        '200':
          description: |
            A list of `Events` for the given `Trip`, optionally filtered according to the request parameters.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      summary: Publish a new Event on a Route
      description: Publish a new `Event` for the given `Route`.
      tags:
        - Route
      parameters:
        - $ref: '#/components/parameters/lifecycle'
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '201':
          description: |
            The created `Event`. The returned object will contain the generated UUID that can be used to refer to this `Event` in later requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event'
            application/xml:
              schema:
                $ref: '#/components/schemas/event'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/event'
  /vehicles:
    get:
      summary: Get a list of Vehicles
      description: |
        Retrieves a list of `Vehicle` objects, optionally filtered by query parameters.
      tags:
        - Vehicle
      parameters:
        - $ref: '#/components/parameters/nameParam'
        - $ref: '#/components/parameters/externalIdSchemaParam'
        - $ref: '#/components/parameters/externalIdValueParam'
        - $ref: '#/components/parameters/actorQueryParam'
        - $ref: '#/components/parameters/roleQueryParam'
      responses:
        '200':
          description: |
            A list of `Vehicles`, optionally filtered by query parameters.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/vehicle'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/vehicle'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      summary: Create a new Vehicle
      description: Create a new `Vehicle` object
      tags:
        - Vehicle
      responses:
        '201':
          description: |
            The created `Vehicle` object. Containes the generated UUID that can be used to refer to this `Vehicle` in later requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/vehicle'
              examples:
                response:
                  value:
                    id: |
                      https://opentripmodel.org/vehicles/5b156b91-8e61-45aa-b5e7-d6d560870c29
                    name: My first trailer
                    type:
                      type: trailer
                    maxLinks: 1
                    externalIds:
                      - schema: 'https://opentripmodel.org/types/licensePlate/nl'
                        value: AB-12-YZ
                    fuelType:
                      type: not-applicable
            application/xml:
              schema:
                $ref: '#/components/schemas/vehicle'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '409':
          $ref: '#/components/responses/conflict'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/vehicle'
  '/vehicles/{uuid}':
    get:
      summary: Get a Vehicle by its UUID
      description: Retrieves a specific `Vehicle` object by its unique identifier (UUID)
      tags:
        - Vehicle
      parameters:
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '200':
          description: A `Vehicle` object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/vehicle'
            application/xml:
              schema:
                $ref: '#/components/schemas/vehicle'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    post:
      summary: Update a Vehicle
      description: |
        Updates the `Vehicle` identified by the UUID with the POSTed data. Note that the UUID-part of the `id` in the entity in the body of the
        `POST`-request should equal the ID part of the endpoint where the entity is posted to, otherwise a `400` (Bad request) error will be returned.
      tags:
        - Vehicle
      parameters:
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '200':
          description: The updated vehicle object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/vehicle'
            application/xml:
              schema:
                $ref: '#/components/schemas/vehicle'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/vehicle'
  '/vehicles/{uuid}/{lifecycle}/events':
    get:
      summary: Get a list of Events for a Vehicle
      description: Retrieves a list of `Events` for the `Vehicle` with the given UUID
      tags:
        - Vehicle
      parameters:
        - $ref: '#/components/parameters/lifecycle'
        - $ref: '#/components/parameters/uuidParam'
        - $ref: '#/components/parameters/startDateTimeParam'
        - $ref: '#/components/parameters/endDateTimeParam'
        - $ref: '#/components/parameters/eventTypeParam'
        - $ref: '#/components/parameters/groupingIdParam'
        - $ref: '#/components/parameters/involvedObjectParam'
      responses:
        '200':
          description: A list of `Events` for the given `Vehicle`
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      summary: Publish an Event for a Vehicle
      description: Publish a new `Event` for the given `Vehicle`.
      tags:
        - Vehicle
      parameters:
        - $ref: '#/components/parameters/lifecycle'
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '201':
          description: |
            The created `Event` object. Containes the generated UUID that can be used to refer to this `Event` in later requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event'
            application/xml:
              schema:
                $ref: '#/components/schemas/event'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/event'
  /sensors:
    get:
      summary: Get a list of Sensors
      description: |
        Retrieves a list of `Sensor` objects, optionally filtered by query parameters.
      tags:
        - Sensor
      parameters:
        - $ref: '#/components/parameters/nameParam'
        - $ref: '#/components/parameters/externalIdSchemaParam'
        - $ref: '#/components/parameters/externalIdValueParam'
        - $ref: '#/components/parameters/actorQueryParam'
        - $ref: '#/components/parameters/roleQueryParam'
      responses:
        '200':
          description: |
            A list of `Sensor`s, optionally filtered by query parameters.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/sensor'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/sensor'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      summary: Create a new Sensor
      description: Create a new `Sensor` object
      tags:
        - Sensor
      responses:
        '201':
          description: |
            The created `Sensor` object. Containes the generated UUID that can be used to refer to this `Sensor` in later requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sensor'
            application/xml:
              schema:
                $ref: '#/components/schemas/sensor'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '409':
          $ref: '#/components/responses/conflict'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/sensor'
  '/sensors/{uuid}':
    get:
      summary: Get a Sensor by its UUID
      description: Retrieves a specific `Sensor` object by its unique identifier (UUID)
      tags:
        - Sensor
      parameters:
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '200':
          description: A `Sensor` object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sensor'
            application/xml:
              schema:
                $ref: '#/components/schemas/sensor'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    post:
      summary: Update a Sensor
      description: |
        Updates the `Sensor` identified by the UUID with the POSTed data. Note that the UUID-part of the `id` in the entity in the body of the
        `POST`-request should equal the ID part of the endpoint where the entity is posted to, otherwise a `400` (Bad request) error will be returned.
      tags:
        - Sensor
      parameters:
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '200':
          description: The updated Sensor object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sensor'
            application/xml:
              schema:
                $ref: '#/components/schemas/sensor'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/sensor'
  '/sensors/{uuid}/{lifecycle}/events':
    get:
      summary: Get a list of Events for a Sensor
      description: Retrieves a list of `Events` for the `Sensor` with the given UUID
      tags:
        - Sensor
      parameters:
        - $ref: '#/components/parameters/lifecycle'
        - $ref: '#/components/parameters/uuidParam'
        - $ref: '#/components/parameters/startDateTimeParam'
        - $ref: '#/components/parameters/endDateTimeParam'
        - $ref: '#/components/parameters/eventTypeParam'
        - $ref: '#/components/parameters/groupingIdParam'
        - $ref: '#/components/parameters/involvedObjectParam'
      responses:
        '200':
          description: A list of `Events` for the given `Sensor`
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      summary: Publish an Event for a Sensor
      description: Publish a new `Event` for the given `Sensor`.
      tags:
        - Sensor
      parameters:
        - $ref: '#/components/parameters/lifecycle'
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '201':
          description: >-
            The created `Event` object. Containes the generated UUID that can be used to refer to this `Event` in later requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event'
            application/xml:
              schema:
                $ref: '#/components/schemas/event'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/event'
  /shipments:
    get:
      summary: Get a list of Shipments
      description: |
        Retrieves a list of `Shipment` objects, optionally filtered by query parameters.
      tags:
        - Shipment
      parameters:
        - $ref: '#/components/parameters/nameParam'
        - $ref: '#/components/parameters/externalIdSchemaParam'
        - $ref: '#/components/parameters/externalIdValueParam'
        - $ref: '#/components/parameters/actorQueryParam'
        - $ref: '#/components/parameters/roleQueryParam'
      responses:
        '200':
          description: 'A list of `Shipments`, optionally filtered by query parameters.'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/shipment'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/shipment'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      summary: Create a new Shipment
      description: Create a new `Shipment` object
      tags:
        - Shipment
      responses:
        '201':
          description: |
            The created `Shipment` object. Containes the generated UUID that can be used to refer to this `Shipment` in later requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment'
            application/xml:
              schema:
                $ref: '#/components/schemas/shipment'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '409':
          $ref: '#/components/responses/conflict'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/shipment'
  '/shipments/{uuid}':
    get:
      summary: Get Shipment by UUID
      description: Retrieves a `Shipment` object by its unique identifier (UUID)
      tags:
        - Shipment
      parameters:
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '200':
          description: A `Shipment` object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment'
            application/xml:
              schema:
                $ref: '#/components/schemas/shipment'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    post:
      summary: Update a Shipment
      description: |
        Updates the `Shipment` identified by the UUID with the POSTed data. Note that the UUID-part of the `id` in the entity in the body of the
        `POST`-request should equal the ID part of the endpoint where the entity is posted to, otherwise a `400` (Bad request) error will be returned.
      tags:
        - Shipment
      parameters:
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '200':
          description: The updated `Shipment` object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment'
            application/xml:
              schema:
                $ref: '#/components/schemas/shipment'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/shipment'
  '/shipments/{uuid}/{lifecycle}/events':
    get:
      summary: Get a list of Events for a Shipment
      description: Retrieves a list of `Events` for the `Shipment` with the given UUID
      tags:
        - Shipment
      parameters:
        - $ref: '#/components/parameters/lifecycle'
        - $ref: '#/components/parameters/uuidParam'
        - $ref: '#/components/parameters/startDateTimeParam'
        - $ref: '#/components/parameters/endDateTimeParam'
        - $ref: '#/components/parameters/eventTypeParam'
        - $ref: '#/components/parameters/groupingIdParam'
        - $ref: '#/components/parameters/involvedObjectParam'
      responses:
        '200':
          description: A list of `Events` for the given `Shipment`
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      summary: Publish a new Event on a Shipment
      description: Publish a new `Event` for the given `Shipment`
      tags:
        - Shipment
      parameters:
        - $ref: '#/components/parameters/lifecycle'
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '201':
          description: |
            The created `Event` object. Containes the generated UUID that can be used to refer to this `Event` in later requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event'
            application/xml:
              schema:
                $ref: '#/components/schemas/event'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/event'
  /actors:
    get:
      summary: Get a list of Actors
      description: |
        Retrieves all known `Actors`, optionally filtered by query parameters.
      tags:
        - Actor
      parameters:
        - $ref: '#/components/parameters/nameParam'
        - $ref: '#/components/parameters/externalIdSchemaParam'
        - $ref: '#/components/parameters/externalIdValueParam'
      responses:
        '200':
          description: |
            A list of `Actors`, optionally filtered by query parameters.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/actor'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/actor'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      summary: Create a new Actor
      description: Create a new `Actor` object
      tags:
        - Actor
      responses:
        '201':
          description: |
            The created `Actor` object. Contains the generated UUID that can be used to refer to this `Actor` in later requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/actor'
            application/xml:
              schema:
                $ref: '#/components/schemas/actor'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '409':
          $ref: '#/components/responses/conflict'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/actor'
  '/actors/{uuid}':
    get:
      summary: Get a specific Actor by its UUID
      description: Retrieves a `Actor` object by its unique identifier (UUID)
      tags:
        - Actor
      parameters:
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '200':
          description: An `Actor` object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/actor'
            application/xml:
              schema:
                $ref: '#/components/schemas/actor'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    post:
      summary: Update an Actor
      description: |
        Updates the `Actor` identified by the UUID with the POSTed data. Note that the UUID-part of the `id` in the entity in the body of the
        `POST`-request should equal the ID part of the endpoint where the entity is posted to, otherwise a `400` (Bad request) error will be returned.
      tags:
        - Actor
      parameters:
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '200':
          description: The updated `Actor` object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/actor'
            application/xml:
              schema:
                $ref: '#/components/schemas/actor'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/actor'
  '/actors/{uuid}/{lifecycle}/events':
    get:
      summary: Get a list of Events for this Actor
      description: Retrieves a list of `Events` for the `Actor` with the given UUID
      tags:
        - Actor
      parameters:
        - $ref: '#/components/parameters/lifecycle'
        - $ref: '#/components/parameters/uuidParam'
        - $ref: '#/components/parameters/startDateTimeParam'
        - $ref: '#/components/parameters/endDateTimeParam'
        - $ref: '#/components/parameters/eventTypeParam'
        - $ref: '#/components/parameters/groupingIdParam'
        - $ref: '#/components/parameters/involvedObjectParam'
      responses:
        '200':
          description: A list of `Events` for the given `Actor`
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      summary: Publish a new Event for the given Actor
      description: Publish a new `Event` for the `Actor` with the given UUID
      tags:
        - Actor
      parameters:
        - $ref: '#/components/parameters/lifecycle'
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '201':
          description: |
            The created `Event` object. Containes the generated UUID that can be used to refer to this `Event` in later requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event'
            application/xml:
              schema:
                $ref: '#/components/schemas/event'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/event'
  /constraints:
    get:
      summary: Get a list of Constraints
      description: |
        Retrieves all known `Constraints`, optionally filtered by query parameters.
      tags:
        - Constraint
      parameters:
        - $ref: '#/components/parameters/nameParam'
        - $ref: '#/components/parameters/externalIdSchemaParam'
        - $ref: '#/components/parameters/externalIdValueParam'
      responses:
        '200':
          description: A list of `Constraints`
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/constraint'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/constraint'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      summary: Create a new Constraint
      description: |
        Create a new pre-defined `Constraint` object, that can be referenced to in objects that have a `constraint` member.
      tags:
        - Constraint
      responses:
        '201':
          description: |
            The created `Constraint` object. Contains the generated UUID that can be used to refer to this `Constraint` in later requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/constraint'
            application/xml:
              schema:
                $ref: '#/components/schemas/constraint'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '409':
          $ref: '#/components/responses/conflict'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/constraint'
  '/constraints/{uuid}':
    get:
      summary: Get a Constraint by its UUID
      description: Retrieves a specific `Constraint` object by its unique identifier (UUID)
      tags:
        - Constraint
      parameters:
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '200':
          description: A `Constraint` object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/constraint'
            application/xml:
              schema:
                $ref: '#/components/schemas/constraint'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    post:
      summary: Update a Constraint
      description: |
        Updates the `Constraint` identified by the UUID with the POSTed data. Note that the UUID-part of the `id` in the entity in the body of the
        `POST`-request should equal the ID part of the endpoint where the entity is posted to, otherwise a `400` (Bad request) error will be returned.
      tags:
        - Constraint
      parameters:
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '200':
          description: The updated `Constraint` object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/constraint'
            application/xml:
              schema:
                $ref: '#/components/schemas/constraint'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/constraint'
  '/constraints/{uuid}/{lifecycle}/events':
    get:
      summary: Get a list of Events for a Constraint
      description: Retrieves a list of `Events` for the `Constraint` with the given UUID
      tags:
        - Constraint
      parameters:
        - $ref: '#/components/parameters/lifecycle'
        - $ref: '#/components/parameters/uuidParam'
        - $ref: '#/components/parameters/startDateTimeParam'
        - $ref: '#/components/parameters/endDateTimeParam'
        - $ref: '#/components/parameters/eventTypeParam'
        - $ref: '#/components/parameters/groupingIdParam'
        - $ref: '#/components/parameters/involvedObjectParam'
      responses:
        '200':
          description: A list of `Events` for the given `Constraint`
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      summary: Publish a new Event on a Constraint
      description: Publish a new `Event` for the `Constraint` with the given UUID
      tags:
        - Constraint
      parameters:
        - $ref: '#/components/parameters/lifecycle'
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '201':
          description: |
            The created `Event` object. Containes the generated UUID that can be used to refer to this `Event` in later requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event'
            application/xml:
              schema:
                $ref: '#/components/schemas/event'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/event'
  /events:
    get:
      summary: Get a list of Events
      description: |
        Get a list of `Events`, optionally filtered by query parameters
      tags:
        - Event
      parameters:
        - $ref: '#/components/parameters/lifecycleQueryParam'
        - $ref: '#/components/parameters/groupingIdParam'
        - $ref: '#/components/parameters/eventTypeParam'
        - $ref: '#/components/parameters/startDateTimeParam'
        - $ref: '#/components/parameters/endDateTimeParam'
        - $ref: '#/components/parameters/involvedObjectParam'
      responses:
        '200':
          description: |
            A list of all defined `Events`, optionally filtered by query parameters.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      summary: Create a new Event
      description: |
        Create an `Event` object with the given data.
      tags:
        - Event
      responses:
        '201':
          description: |
            The `Event` object as created. The returned object will contain the generated UUID that can be used to refer to this `Event` in later
            requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event'
            application/xml:
              schema:
                $ref: '#/components/schemas/event'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '409':
          $ref: '#/components/responses/conflict'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/event'
  '/events/{uuid}':
    get:
      summary: Get a specific Event by its UUID
      description: Retrieves a single `Event` object by its unique identifier (UUID)
      tags:
        - Event
      parameters:
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '200':
          description: An `Event` object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event'
            application/xml:
              schema:
                $ref: '#/components/schemas/event'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
  '/events/{uuid}/{lifecycle}/events':
    get:
      summary: Get a list of Events related to this Event
      description: Retrieves a list of `Events` related to the `Event` with the given UUID
      tags:
        - Event
      parameters:
        - $ref: '#/components/parameters/lifecycle'
        - $ref: '#/components/parameters/uuidParam'
        - $ref: '#/components/parameters/startDateTimeParam'
        - $ref: '#/components/parameters/endDateTimeParam'
        - $ref: '#/components/parameters/eventTypeParam'
        - $ref: '#/components/parameters/groupingIdParam'
        - $ref: '#/components/parameters/involvedObjectParam'
      responses:
        '200':
          description: A list of `Events` related to the given `Event`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/event'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
    put:
      summary: Publish a new Event related to the given Event
      description: Publish a new `Event` related to the given `Event`
      tags:
        - Event
      parameters:
        - $ref: '#/components/parameters/lifecycle'
        - $ref: '#/components/parameters/uuidParam'
      responses:
        '201':
          description: |
            The created `Event`. The returned object will contain the generated UUID that can be used to refer to this `Event` in later requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/event'
            application/xml:
              schema:
                $ref: '#/components/schemas/event'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        $ref: '#/components/requestBodies/event'
  /bundles:
    put:
      summary: Create or update multiple entities
      description: |
        By putting a bundle on the server, a client can create or update multiple entities in one call. This can bring down the number of calls,
        thus reducing network traffic. It also ensures all entities in the bundle are validated at the same time and no entities are created or
        updated if there is an error in the bundle. This can be seen as a simple form of transaction. Bundles are not saved as an entity of their own.
        This means there's no `GET` call on the bundle endpoint.
      tags:
        - Bundle
      responses:
        '201':
          description: |
            The original `Bundle`, with added generated UUIDs that can be used to refer to the generated Entities in later requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bundle'
            application/xml:
              schema:
                $ref: '#/components/schemas/bundle'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '409':
          $ref: '#/components/responses/conflict'
        '500':
          $ref: '#/components/responses/internalServerError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bundle'
          application/xml:
            schema:
              $ref: '#/components/schemas/bundle'
        description: JSON object describing a `Bundle`.
        required: true

components:
  parameters:
    lifecycle:
      name: lifecycle
      in: path
      required: true
      description: The lifecycle phase the request applies to
      schema:
        type: string
        enum:
          - planned
          - projected
          - actual
          - realized
    lifecycleQueryParam:
      name: lifecycle
      in: query
      required: false
      description: Parameter to filter events by lifecycle phase.
      schema:
        type: string
        enum:
          - planned
          - projected
          - actual
          - realized
    uuidParam:
      name: uuid
      in: path
      required: true
      description: A uuid, identifying some pre-defined entity.
      schema:
        type: string
    nameParam:
      name: name
      in: query
      required: false
      description: A name or a part of a name, to search entities by their name.
      schema:
        type: string
    externalIdSchemaParam:
      name: externalIdSchema
      in: query
      required: false
      description: |
        The schema of external ID, to search for entities by their external IDs. This would return all entities that have an external ID reference
        with the given schema. This could still be a lot of entities. Combine with the `externalIdValue` query parameter to limit the number of
        results further.
      schema:
        type: string
    externalIdValueParam:
      name: externalIdValue
      in: query
      required: false
      description: |
        An external ID value, or a part of it, to search for entities by their external IDs. This parameter should be combined with the
        `externalIdSchema` parameter.
      schema:
        type: string
    involvedObjectParam:
      name: involvedObject
      in: query
      required: false
      description: |
        Query parameter to filter events by involved object. With this query parameter, you can filter a list of `Events` to only contain `Events`
        that have a certain entity in their list of `involvedObjects`. You can filter for multiple, different involved objects by chaining the
        parameter, as follows: `involvedObject=385afbeb-4fba-48f3-91da-b5547e8f3365&involvedObject=e49064e9-abe4-404b-9d72-3093380db937`. In that
        case, a logical `OR` will be applied, meaning that all events are returned that have any of the listed involved objects.

        > **NOTE**: The value used in this query parameter is the "bare" UUID, not the URI of an object.
      schema:
        type: string
        format: uuid
    startDateTimeParam:
      name: startDateTime
      in: query
      description: |
        The start date and time to query for. Only events on or after the `start-date-time` will be returned. All date-time values in OpenTripModel
        are UTC times, in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) notation: `YYYY-MM-DDThh:mm:ss.sssZ`. See the
        [Time values](/#section/Technical-notes/Time-values) section for details.
      schema:
        type: string
        format: date-time
    endDateTimeParam:
      name: endDateTime
      in: query
      description: |
        The end date and time to query for. Only events before or on the `end-date-time` will be returned. All date-time values in OpenTripModel
        are UTC times, in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) notation: `YYYY-MM-DDThh:mm:ss.sssZ`. See the
        [Time values](/#section/Technical-notes/Time-values) section for details.
      schema:
        type: string
        format: date-time
    eventTypeParam:
      name: eventType
      in: query
      description: |
        Filter events by event type. The resulting list will only have events of the given type. Multiple `eventType` parameters can be combined to
        get a list of multiple event types, like this: `eventType=loadShipmentEvent&eventType=unloadShipmentEvent`. In that case a logical `OR` will
        be used, meaning all events with any of the given `eventTypes` will be returned.
      required: false
      schema:
        type: string
    groupingIdParam:
      name: groupingId
      in: query
      description: |
        `groupingId` to filter by. Should you want to filter on multiple `groupingId`s, you can repeat this parameter multiple times, like this:
        `groupingId=a&groupingId=b`. In that case a logical `OR` will be used, meaning all events with any of the given `groupingId`s will be
        returned.
      required: false
      schema:
        type: string
    actorQueryParam:
      name: actor
      in: query
      description: |
        Filter the query by Actor. Only objects that are associated to the `Actor` identified by the given UUID will be shown.
      required: false
      schema:
        type: string
        format: uuid
    roleQueryParam:
      name: role
      in: query
      description: |
        Filter the query by role and Actor. Only objects that are associated to the `Actor` identified by the given UUID and are associated by the
        given role will be shown. This parameter is only valid in combination with the `actor` parameter.
      required: false
      schema:
        type: string
  responses:
    badRequest:
      description: |
        The request was invalid or cannot be otherwise served. Possible causes are:
          - invalid JSON objects;
          - missing required parameters;
          - when `POST`-ing an updated entity, the UUID-part of the `id` of the `POST` body is not equal to the UUID-part of the endpoint the body
            is posted to.
          - when `PUT`-ing an event, the `lifecyclePhase` field of that event does not correspond to the endpoint you are `PUT`-ing it to.

        An accompanying error message will explain further.
      content:
        application/json:
          schema:
            type: string
            description: error message
            example: The body of the request could not be parsed.
        application/xml:
          schema:
            type: string
            description: error message
            example: The body of the request could not be parsed.
    unauthorized:
      description: Authentication credentials were missing or incorrect.
      content:
        application/json:
          schema:
            type: string
            description: error message
            example: Authentication credentials were missing or incorrect.
        application/xml:
          schema:
            type: string
            description: error message
            example: Authentication credentials were missing or incorrect.
    forbidden:
      description: |
        The request is understood, but it has been refused or access is not allowed. An accompanying error message will explain why.
      content:
        application/json:
          schema:
            type: string
            description: error message
            example: Access to this resource is not allowed.
        application/xml:
          schema:
            type: string
            description: error message
            example: Access to this resource is not allowed.
    notFound:
      description: |-
        The URI requested is invalid or the resource requested does not exists. Also returned when the requested format is not supported by the
        requested method.
      content:
        application/json:
          schema:
            type: string
            description: error message
            example: The requested resource was not found.
        application/xml:
          schema:
            type: string
            description: error message
            example: The requested resource was not found.
    conflict:
      description: |
        System was not able to create an object as requested, because an object with the same properties already exists.
      content:
        application/json:
          schema:
            type: string
            description: error message
            example: An object with the same properties already exists.
        application/xml:
          schema:
            type: string
            description: error message
            example: An object with the same properties already exists.
    internalServerError:
      description: |
        An unexpected server error has occured, which needs further investigation. Please contact support.
      content:
        application/json:
          schema:
            type: string
            description: error message
            example: An unexpected error occured while processing the request.
        application/xml:
          schema:
            type: string
            description: error message
            example: An unexpected error occured while processing the request.
  requestBodies:
    route:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/route'
        application/xml:
          schema:
            $ref: '#/components/schemas/route'
      description: JSON object describing a `Route`.
      required: true
    shipment:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/shipment'
        application/xml:
          schema:
            $ref: '#/components/schemas/shipment'
      description: JSON object describing a `Shipment`.
      required: true
    event:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/event'
        application/xml:
          schema:
            $ref: '#/components/schemas/event'
      description: JSON object describing an `Event`
      required: true
    sensor:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/sensor'
        application/xml:
          schema:
            $ref: '#/components/schemas/sensor'
      description: JSON object describing a `Sensor`.
      required: true
    location:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/location'
        application/xml:
          schema:
            $ref: '#/components/schemas/location'
      description: |
        JSON object describing a `Location`.

        > **Please note:** The `geoReference` variable is the one and only part of the `Location` entity that exactly describes the geographic
          location. The `administrativeReference` member is just what is says: an administrative reference. An administrative reference is typically
          a street address. It _might_ be the street address corresponding to the location that is defined by the `geoReference`, but that's not
          required. A common case is a shop where the `administrativeReference` is the street address of the main entrance, while the `geoLocation`
          is the location of the loading bay, which is typically on the back side and so in another street.

        > **Please note:** In some cases, a street address is the most accurate known location. In such a case, you should set the address in the
          `geoReference` as `addressGeoReference` type.
      required: true
    trip:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/trip'
        application/xml:
          schema:
            $ref: '#/components/schemas/trip'
      description: JSON object describing a `Trip`
      required: true
    vehicle:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/vehicle'
        application/xml:
          schema:
            $ref: '#/components/schemas/vehicle'
      description: JSON object describing a `Vehicle`.
      required: true
    actor:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/actor'
        application/xml:
          schema:
            $ref: '#/components/schemas/actor'
      description: JSON object describing an `Actor`.
      required: true
    constraint:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/constraint'
        application/xml:
          schema:
            $ref: '#/components/schemas/constraint'
      description: JSON object describing a `Constraint`.
      required: true

  schemas:

    actor:
      type: object
      description: |
        An `Actor` models a legal entity. A legal entity is an individual, company, or organization that has legal rights and obligations. The use of
        `Actors` is optional, and is not necessary to use OpenTripModel. Actors can be used e.g. to group all locations that belong to an organisation,
        or to address an OpenTripModel message to a specific person or organisation.
      properties:
        id:
          type: string
          format: uri
          description: |
            Uniquely identifies this `Actor`. A URI can be assigned by the client or will be generated by the server if the client doesn't provide it.
            Once assigned, the URI can't be changed. See [Unique Identifiers](/#section/Technical-notes/Unique-identifiers) for more information.
          example: |
            https://api.opentripmodel.org/api/public/v4/actors/45db6ed0-28a7-4e4a-baba-3d5f8d171103
        externalIds:
          type: array
          description: |
            An optional array of IDs by which the actor may be known in other systems.
          items:
            $ref: '#/components/schemas/idReference'
        name:
          type: string
          description: Name of the `Actor`. For display purposes and search only.
          example: 'My awesome company, Ltd.'
        contactDetails:
          type: array
          items:
            $ref: '#/components/schemas/contactDetail'

    location:
      type: object
      description: |
        Object describing a geographic location. A location can either be a point or an area.
      properties:
        id:
          type: string
          format: uri
          description: |
            Uniquely identifies this location. A URI can be assigned by the client or will be generated by the server if the client doesn't provide
            it. Once assigned, the URI can't be changed. See [Unique Identifiers](/#section/Technical-notes/Unique-identifiers) for more information.
          example: https://api.opentripmodel.org/api/public/v4/locations/11c11d75-e114-4b5f-9751-b3a4afa23ecf
        name:
          type: string
          description: Name of the `Location`. For display purposes and search only.
          example: Main warehouse
        externalIds:
          type: array
          description: |
            An optional array of IDs by which the location may be known in other systems.
          items:
            $ref: '#/components/schemas/idReference'
        type:
          $ref: '#/components/schemas/locationType'
        geoReference:
          $ref: '#/components/schemas/geoReference'
        administrativeReference:
          $ref: '#/components/schemas/administrativeReference'
        contactDetails:
          type: array
          items:
            $ref: '#/components/schemas/contactDetail'
        constraint:
          allOf:
            - description: |
                In the context of a `Location`, access to the location is only allowed if the given constraint applies.

                > **ℹ Note** that constraints can be nested and combined using the `andConstraint`, `orConstraint` and `notConstraint`.
            - $ref: '#/components/schemas/constraint'
        remarks:
          type: string
          description: |
            Remarks about the location. Please don't misuse this field for external references, use the `externalIds` field instead.
          example: The cafe around the corner has the best coffee in town.
      required:
        - geoReference

    locationType:
      type: object
      description: The type of location
      properties:
        type:
          type: string
          enum:
            - warehouse
            - store
            - environmentalZone
            - restrictedArea
            - customer
            - parkingLot
            - parkingGarage
            - parkingSpot
            - loadingUnloadingArea
            - other
          example: warehouse
        other:
          type: string
          description: |
            Name of the location type if `other` is chosen in the `type` field.
          example: playground
      example:
        type: warehouse
      required:
        - type

    contactDetail:
      type: object
      description: 'Contact details, such as phone numbers and email addresses.'
      properties:
        type:
          type: string
          enum:
            - phone
            - email
            - other
          description: Type of contact detail
          example: email
        value:
          type: string
          description: |
            The contact detail itself. Depending on the `type`, this can be a phone number, email address or some other address to contact a location
            or person.
          example: info@opentripmodel.org
        remarks:
          type: string
          description: Remarks about the contact detail.
          example: Usually doesn't answer his phone the first time
      example:
        type: phone
        value: '+312012345678'
        remarks: private cellphone of the CEO
      required:
        - type
        - value

    geoReference:
      type: object
      description: |
        Describes a geographic reference, which can be part of a location or route.
      properties:
        type:
          type: string
          description: Type of geographic reference
          example: openLRGeoReference
      discriminator:
        propertyName: type
      required:
        - type
      example:
        type: latLongPointGeoReference
        lat: 52.0838333
        lon: 5.8318803

    latLongPoint:
      properties:
        lat:
          type: number
          format: double
          example: 52.192294
        lon:
          type: number
          format: double
          example: 5.410124
      required:
        - lat
        - lon
      example:
        lat: 52.0838333
        lon: 5.8318803

    movingInfo:
      properties:
        speed:
          allOf:
          - description: |
              The speed of a moving `Vehicle`.
          - $ref: '#/components/schemas/valueWithUnit'
        heading:
          allOf:
          - description: |
              The heading of a `Vehicle`, that is: the direction the "nose" of the `Vehicle` is pointing to.
          - $ref: '#/components/schemas/valueWithUnit'
        bearing:
          allOf:
          - description: |
              The bearing of a `Vehicle`, that is: the angle between the `Vehicle` and its destination. Either measured _relative_ or _absolute_. See
              [Wikipedia](https://en.wikipedia.org/wiki/Bearing_(navigation)) for an explanation.
          - $ref: '#/components/schemas/valueWithUnit'
        bearingType:
          description: |
            Denotes how the bearing is measured. See [Wikipedia](https://en.wikipedia.org/wiki/Bearing_(navigation)) for an explanation.
          type: string
          enum:
            - absolute
            - relative
          default: absolute

    latLongPointGeoReference:
      allOf:
        - $ref: '#/components/schemas/geoReference'
        - $ref: '#/components/schemas/latLongPoint'
        - $ref: '#/components/schemas/movingInfo'
      example:
        type: latLongPointGeoReference
        lat: 52.0838333
        lon: 5.8318803
        speed:
          unit: 'km/h'
          value: 76
        heading:
          unit: 'degrees'
          value: '143'

    latLongArrayGeoReference:
      allOf:
        - $ref: '#/components/schemas/geoReference'
        - properties:
            points:
              type: array
              minItems: 1
              items:
                $ref: '#/components/schemas/latLongPoint'
      required:
        - points
      example:
        type: latLongArrayGeoReference
        points:
          - lat: 52.0838333
            lon: 5.8318803
          - lat: 52.192294
            lon: 5.410124
          - lat: 52.188841
            lon: 5.414857

    point2D:
      type: array
      maxItems: 2
      minItems: 2
      items:
        type: number
        format: double
      example:
        - 5.408910512924194
        - 52.19404109179293

    geoJSONPoint:
      type: object
      description: GeoJSon geometry
      externalDocs:
        url: 'http://geojson.org/geojson-spec.html#id2'
      allOf:
        - $ref: '#/components/schemas/geoReference'
        - $ref: '#/components/schemas/movingInfo'
        - properties:
            coordinates:
              $ref: '#/components/schemas/point2D'
      required:
        - coordinates

    geoJSONLineString:
      type: object
      description: GeoJSon geometry
      externalDocs:
        url: 'http://geojson.org/geojson-spec.html#id3'
      allOf:
        - $ref: '#/components/schemas/geoReference'
        - properties:
            coordinates:
              type: array
              minItems: 1
              items:
                $ref: '#/components/schemas/point2D'
      required:
        - coordinates

    geoJSONPolygon:
      type: object
      description: GeoJSon geometry
      externalDocs:
        url: 'http://geojson.org/geojson-spec.html#id4'
      allOf:
        - $ref: '#/components/schemas/geoReference'
        - properties:
            coordinates:
              type: array
              items:
                type: array
                items:
                  $ref: '#/components/schemas/point2D'
      required:
        - coordinates

    geoJSONMultiPoint:
      type: object
      description: GeoJSon geometry
      externalDocs:
        url: 'http://geojson.org/geojson-spec.html#id5'
      allOf:
        - $ref: '#/components/schemas/geoReference'
        - properties:
            coordinates:
              type: array
              items:
                $ref: '#/components/schemas/point2D'
      required:
        - coordinates

    geoJSONMultiLineString:
      type: object
      description: GeoJSon geometry
      externalDocs:
        url: 'http://geojson.org/geojson-spec.html#id6'
      allOf:
        - $ref: '#/components/schemas/geoReference'
        - properties:
            coordinates:
              type: array
              items:
                type: array
                items:
                  $ref: '#/components/schemas/point2D'
      required:
        - coordinates

    geoJSONMultiPolygon:
      type: object
      description: GeoJSon geometry
      externalDocs:
        url: 'http://geojson.org/geojson-spec.html#id6'
      allOf:
        - $ref: '#/components/schemas/geoReference'
        - properties:
            coordinates:
              type: array
              items:
                type: array
                items:
                  type: array
                  items:
                    $ref: '#/components/schemas/point2D'
      required:
        - coordinates

    openLRGeoReference:
      allOf:
        - $ref: '#/components/schemas/geoReference'
        - properties:
            openLRString:
              type: string
              format: openLR
              description: |
                A base64 encoded binary OpenLR string.
                More information about OpenLR: http://openlr.org/documents.html
              example: CgOkbyUN6COJAwEB/8YjGQ==
      required:
        - openLRString
      example:
        type: openLRGeoReference
        openLRString: CgOkbyUN6COJAwEB/8YjGQ==

    tmcPoint:
      properties:
        locationCode:
          description: TMC location code
          type: string
        direction:
          description: TMC direction
          type: string
          default: positive
          enum:
            - positive
            - negative

    tmcLocation:
      properties:
        countryCode:
          description: TMC country code
          type: string
        tableId:
          description: TMC table ID
          type: string
        tableVersionId:
          description: TMC table version ID
          type: string
        locationCode:
          description: TMC location code
          type: string
        direction:
          description: TMC direction
          type: string
          default: positive
          enum:
            - positive
            - negative
        offset:
          description: Offset from the TMC location in meters
          type: number
          format: integer32
          default: 0
      required:
        - countryCode
        - tableId
        - tableVersionId
        - locationCode

    tmcLocationArray:
      properties:
        countryCode:
          description: TMC country code
          type: string
        tableId:
          description: TMC table ID
          type: string
        tableVersionId:
          description: TMC table version ID
          type: string
        points:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/tmcPoint'
        startOffset:
          description: Offset from the first TMC location in meters
          type: number
          format: integer32
          default: 0
        endOffset:
          description: Offset from the last TMC location in meters
          type: number
          format: integer32
          default: 0
      required:
        - countryCode
        - tableId
        - tableVersionId
        - points

    tmcLocationGeoReference:
      allOf:
        - $ref: '#/components/schemas/geoReference'
        - $ref: '#/components/schemas/tmcLocation'
        - $ref: '#/components/schemas/movingInfo'

    tmcArrayGeoReference:
      allOf:
        - $ref: '#/components/schemas/geoReference'
        - $ref: '#/components/schemas/tmcLocationArray'

    addressGeoReference:
      allOf:
        - $ref: '#/components/schemas/geoReference'
        - $ref: '#/components/schemas/address'

    address:
      type: object
      properties:
        street:
          type: string
          description: Street of the address.
        houseNumber:
          type: string
          description: Housenumber
        houseNumberAddition:
          type: string
          description: Addition to the houseNumber.
        postalCode:
          type: string
          description: The postal code of the address.
        city:
          type: string
          description: The city of the address
        country:
          type: string
          description: |
            [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1) country code.
      example:
        street: Langestraat
        houseNumber: "3"
        houseNumberAddition: a
        postalCode: 1234AB
        city: Amersfoort
        country: nl

    administrativeReference:
      description: |
        Administrative references are street addresses, only available for reference and for improved human readability. Administrative references
        are **not** intended to be used for identifying locations; always use a geoReference for that purpose. While this is not advised, you _can_
        use an address as georeference. To do so, add the address as `geoReference` via the `addressGeoReference` type.
      allOf:
        - $ref: '#/components/schemas/address'
        - properties:
            name:
              type: string
              description: |
                The name can be sent to the mobile device of the driver, in order to properly address the client.
              example: Sjaak Trekhaak
      example:
        name: Main entrance of store
        street: Langestraat
        houseNumber: "3"
        houseNumberAddition: a
        postalCode: 1234AB
        city: Amersfoort
        country: nl

    constraint:
      type: object
      description: |
        `Constraints` can do different things, depending on the context they're
        used in:
          - In the context of a `Location`, access to the location is only allowed if the given constraint applies.
          - In the context of a `Trip`, constraints can be used to define constraints that have to be met during the trip, e.g. if the temperature in
            a refrigerated trailer has to stay below a given maximum during the trip.
          - In the context of a `Shipment`, constraints can be used to e.g. define minimum or maximum temperatures for shipments, or date time
            constraints for delivery.

        Note that constraints can be nested and combined using the `andConstraint`, `orConstraint` and `notConstraint`.
      properties:
        id:
          type: string
          format: uri
          description: |
            Uniquely identifies this constraint. A URI can be assigned by the client or will be generated by the server if the client doesn't provide
            it. Once assigned, the URI can't be changed. See [Unique Identifiers](/#section/Technical-notes/Unique-identifiers) for more information.

            > **NOTE** The exact meaning of this `id` field depends on the location where it is used. If used in a top-level `Constraint`, defined via
                       the `constraints` endpoint, it denotes the unique `id` of the `Constraint`. If used inside another entity, such as e.g.
                       `Location`, the `id` field is only used if the `type` is `constraintReference`, to refer to a predefined `Constraint`.
          example: 'https://api.opentripmodel.org/api/public/v4/constraints/6d4b4ac8-0122-457f-89cf-15f6d82ac2ec'
        name:
          type: string
          description: Name of the `Constraint`. For display purposes and search only.
          example: 'Constraint name'
        externalIds:
          type: array
          description: |
            An optional array of IDs by which the constraint may be known in other systems.
          items:
            $ref: '#/components/schemas/idReference'
          example:
        basisType:
          description: |
            The basis for the `Constraint`. Legal and physical constraints can generally not be violated. But a constraint may also be based on an
            advice or request, in which case a party may choose not to stick to the constraint.
          type: string
          enum:
          - legal
          - physical
          - contractual
          - advice
          - request
        basisReference:
          description: |
            Reference to the basis of the `Constraint`. In case the `basisType` is `legal`, this can e.g. be a link to a specific law. For a
            `physical` constraint, it may be a link to a photograph or drawing of the situation, etc.
          type: string
          example: https://wetten.overheid.nl/BWBR0007606/2015-04-01
        type:
          description: |
            The constraint type. Set the type to `constraintReference` to refer to a predefined top-level constraint. In that case, use the `id`
            field to refer to the `id` of that predefined constraint. To define a constraint instead of referring to it, choose any of the other types
            and fill the fields that come with that constraint type.
          type: string
      discriminator:
        propertyName: type
      required:
        - type

    constraintReference:
      allOf:
        - $ref: '#/components/schemas/constraint'
      example:
        type: constraintReference
        id: 'https://api.opentripmodel.org/api/public/v4/constraints/6d4b4ac8-0122-457f-89cf-15f6d82ac2ec'

    andConstraint:
      allOf:
        - $ref: '#/components/schemas/constraint'
        - properties:
            and:
              description: |
                All constraints in the array are combined using a boolean AND relation. This means that the resulting constraint will only apply if
                all constraints in the array would apply.
              type: array
              items:
                $ref: '#/components/schemas/constraint'
          example:
            type: andConstraint
            and:
              - type: startDateTimeConstraint
                startDateTime: '2017-01-01T00:00Z'
              - type: endDateTimeConstraint
                endDateTime: '2018-12-31T23:59:59Z'
              - type: notConstraint
                not:
                  type: fuelTypeConstraint
                  fuelTypes:
                    - type: diesel
                    - type: biodiesel
                    - type: other
                      other: liquidGas

    orConstraint:
      allOf:
        - $ref: '#/components/schemas/constraint'
        - properties:
            or:
              description: |
                All constraints in the array are combined using a boolean OR relation. This means that the resulting constraint will apply if any of
                the constraints in the array would apply.
              type: array
              items:
                $ref: '#/components/schemas/constraint'
          example:
            type: orConstraint
            or:
            - type: fuelTypeConstraint
              fuelTypes:
                - type: battery
            - type: fuelTypeConstraint
              fuelTypes:
                - type: biodiesel

    notConstraint:
      allOf:
        - $ref: '#/components/schemas/constraint'
        - properties:
            not:
              allOf:
                - description: |
                    The `notConstraint` inverts a given constraint, like a boolean NOT operation. This means the resulting constraint will apply if the
                    underlying constraint would not.
                - $ref: '#/components/schemas/constraint'
          example:
            type: notConstraint
            not:
              type: fuelTypeConstraint
              fuelTypes:
                - type: petrol

    startDateTimeConstraint:
      allOf:
        - $ref: '#/components/schemas/constraint'
        - properties:
            startDateTime:
              type: string
              format: date-time
              description: This constraint applies from the given start date/time.
              example: '2012-01-01T00:00Z'

    endDateTimeConstraint:
      allOf:
        - $ref: '#/components/schemas/constraint'
        - properties:
            endDateTime:
              type: string
              format: date-time
              description: This constraint applies until the given end date/time.
              example: '2028-12-31T23:59:59Z'

    timeRangeConstraint:
      allOf:
        - $ref: '#/components/schemas/constraint'
        - $ref: '#/components/schemas/dayOfWeekTimeRange'

    eventOrderConstraint:
      allOf:
        - $ref: '#/components/schemas/constraint'
        - properties:
            eventOrderConstraintType:
              description: |
                The type of event order constraint. Available types are:
                  - `before`: The event this constraint is placed on should occur before the referenced event.
                  - `after`: The event this constraint is placed on should occur after the referenced event.
              type: string
              enum:
                - before
                - after
            eventReference:
              description: The URI of the referenced event.
              type: string
              format: uri
              example: 'https://api.opentripmodel.org/api/public/v4/events/17118916-d6bd-4d5d-8b9a-62db7dd6149d'

    numberOfVehiclesConstraint:
      allOf:
        - $ref: '#/components/schemas/constraint'
        - properties:
            numberConstraintType:
              description: |
                The type of number contraint. Available types are:
                  - `maximum`: the constraint is met as long as the number of vehicles in the associated `Location` stays below or on the maximum.
                  - `minimum`: the constraint is met as long as the number of vehicles in the associated `Location` stays above or on the minimum.
                  - `range`: the constraint is met as long as the number of vehicles in the associated `Location` stays between the minimum and
                    maximum, including maximum and minimum values.
              type: string
              enum:
                - maximum
                - minimum
                - range
            maximum:
              type: number
              format: int64
              description: The maximum number of vehicles, only applies if `numberConstraintType` is `maximum` or `range`.
            minimum:
              type: number
              format: int64
              description: The minimum number of vehicles, only applies if `numberConstraintType` is `minimum` or `range`.
          example:
            numberConstraintType: 'maximum'
            maximum: 300

    sizeConstraint:
      allOf:
        - $ref: '#/components/schemas/constraint'
        - properties:
            sizeConstraintType:
              description: |
                The type of size constraint. Available types are:
                  - `maximum`: All sizes below and including the maximum value are allowed.
                  - `minimum`: All sizes above and including the minimum value are allowed.
                  - `range`: All sizes in between and including the minimum and maximum values are allowed.
              type: string
              enum:
                - maximum
                - minimum
                - range
            sizeConstraint:
              type: string
              enum:
                - vehicleLength
                - vehicleHeight
                - vehicleWidth
            maximum:
              allOf:
                - description: Maximum size allowed
                - $ref: '#/components/schemas/valueWithUnit'
            minimum:
              allOf:
                - description: Minimum size allowed
                - $ref: '#/components/schemas/valueWithUnit'
          example:
            sizeConstraintType: range
            sizeConstraint: vehicle-length
            minimum:
              value: 4
              unit: 'm'
            maximum:
              value: '20'
              unit: 'm'

    weightConstraint:
      allOf:
        - $ref: '#/components/schemas/constraint'
        - properties:
            weightConstraintType:
              description: |
                The type of weight constraint. Available types are:
                  - `maximum`: All weights below and including the maximum value are allowed.
                  - `minimum`: All weights above and including the minimum value are allowed.
                  - `range`: All weights in between and including the minimum and maximum values are allowed.
              type: string
              enum:
                - maximum
                - minimum
                - range
            maximum:
              allOf:
                - description: Maximum weight allowed
                - $ref: '#/components/schemas/valueWithUnit'
            minimum:
              allOf:
                - description: Minimum weight allowed
                - $ref: '#/components/schemas/valueWithUnit'
          example:
            weightConstraintType: maximum
            maximum:
              value: 200
              unit: 'kg'

    speedConstraint:
      allOf:
        - $ref: '#/components/schemas/constraint'
        - properties:
            speedConstraintType:
              description: |
                The type of speed constraint. Available types are:
                  - `maximum`: All speeds below and including the maximum value are allowed.
                  - `minimum`: All speeds above and including the minimum value are allowed.
              type: string
              enum:
                - maximum
                - minimum
            maximum:
              allOf:
                - description: Maximum speed allowed
                - $ref: '#/components/schemas/valueWithUnit'
            minimum:
              allOf:
                - description: Minimum speed allowed
                - $ref: '#/components/schemas/valueWithUnit'
          example:
            speedConstraintType: range
            minimum:
              value: 30
              unit: 'km/h'
            maximum:
              value: 130
              unit: 'km/h'

    sensorValueConstraint:
      allOf:
        - $ref: '#/components/schemas/constraint'
        - properties:
            sensorValueConstraintType:
              description: |
                The type of sensor value constraint. Available types are:
                  - `maximum`: All sensor values below and including the maximum value are allowed.
                  - `minimum`: All sensor values above and including the minimum value are allowed.
              type: string
              enum:
                - maximum
                - minimum
            sensor:
              type: string
              format: uri
              description: OTM URI of the sensor this constraint applies to.
              example: 'https://api.opentripmodel.org/api/public/v4/sensors/6666f00c-1332-472c-aff9-bc11b3d53296'
            maximum:
              allOf:
                - description: Maximum sensor value allowed
                - $ref: '#/components/schemas/valueWithUnit'
            minimum:
              allOf:
                - description: Minimum sensor value allowed
                - $ref: '#/components/schemas/valueWithUnit'
          example:
            sensor: 'https://api.opentripmodel.org/api/public/v4/sensors/6666f00c-1332-472c-aff9-bc11b3d53296'
            sensorValueConstraintType: maximum
            maximum:
              value: 0
              unit: '°C'

    sensorUpdateFrequencyConstraint:
      allOf:
        - $ref: '#/components/schemas/constraint'
        - properties:
            sensorUpdateFrequencyConstraintType:
              description: |
                The type of sensor value constraint. Available types are:
                  - `maximum`: All sensor values below and including the maximum value are allowed.
                  - `minimum`: All sensor values above and including the minimum value are allowed.
              type: string
              enum:
                - maximum
                - minimum
            sensor:
              type: string
              format: uri
              description: OTM URI of the sensor this constraint applies to.
              example: 'https://api.opentripmodel.org/api/public/v4/sensors/6666f00c-1332-472c-aff9-bc11b3d53296'
            maximum:
              allOf:
                - description: Maximum sensor value allowed
                - $ref: '#/components/schemas/valueWithUnit'
            minimum:
              allOf:
                - description: Minimum sensor value allowed
                - $ref: '#/components/schemas/valueWithUnit'
          example:
            sensorUpdateFrequencyConstraintType: range
            minimum:
              value: 2
              unit: 'Hz'

    fuelTypeConstraint:
      allOf:
        - $ref: '#/components/schemas/constraint'
        - properties:
            fuelTypes:
              description: The fuel types to which this constraint apply.
              type: array
              items:
                $ref: '#/components/schemas/fuelType'
          example:
            type: fuelTypeConstraint
            fuelTypes:
              - type: battery
              - type: biodiesel
              - type: other
                other: wind

    vehicleTypeConstraint:
      allOf:
        - $ref: '#/components/schemas/constraint'
        - properties:
            vehicleTypes:
              description: The vehicle types that this constraint apply to.
              type: array
              items:
                $ref: '#/components/schemas/vehicleType'

    dangerousGoodsConstraint:
      allOf:
        - $ref: '#/components/schemas/constraint'
        - properties:
            description:
              description: The description of a dangerous good. The exact meaning of the description depends on the `descriptionType` field.
              type: string
            descriptionType:
              description: The type of description of the dangerous good.
              type: string
              enum:
                - chemicalIdentifier
                - commercialName
                - class
                - other
            descriptionTypeReference:
              description: |
                Reference to a resource where the exact meaning of the description can be found. E.g. in case of a `descriptionType` of `class`,
                this reference can be a document where the classes are described. This can be a law, or a document from international organizations
                like IATA, ICAO, IMO, etc. In case the `descriptionType` is `commercialName`, the reference might be a document describing the
                specific dangerous good, with its properties. In case `descriptionType` is `chemicalIdentifier`, the reference is the standard
                that's used to identify the good. Examples of widely used standards for chemical identifiers are:

                - [InChi](https://en.wikipedia.org/wiki/International_Chemical_Identifier)
                - [CAS Registry Number](https://en.wikipedia.org/wiki/CAS_Registry_Number)
          example:
            type: dangerousGoodsConstraint
            description: 'XLYOFNOQVPJJNP-UHFFFAOYSA-N'
            descriptionType: 'chemicalIdentifier'
            descriptionTypeReference: 'https://en.wikipedia.org/wiki/International_Chemical_Identifier'

    routeConstraint:
      allOf:
        - $ref: '#/components/schemas/constraint'
        - properties:
            route:
              $ref: '#/components/schemas/geoReference'
          example:
            type: routeConstraint
            route:
              type: openLRGeoReference
              openLRString: 'CwPQHiUgVAH58hJ8+cw7fg4B'

    dayOfWeekTimeRange:
      type: object
      description: |
        A time range for a specific day of the week, for which the constraint will be applicable.
      properties:
        dayOfWeek:
          type: integer
          format: int32
          minimum: 1
          maximum: 7
          description: |
            Day of the week, where
            - 1 = Monday
            - 2 = Tuesday
            - 3 = Wednesday
            - 4 = Thursday
            - 5 = Friday
            - 6 = Saturday
            - 7 = Sunday
          example: 1
        ranges:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/timeRange'
      required:
        - dayOfWeek
        - ranges

    timeRange:
      type: object
      description: Time range with start and end time.
      properties:
        range:
          type: string
          format: time-range
          description: |
            Time interval in the format `hh:mm:ss/hh:mm:ss`, where the value before the `/` is the start time and the value after the `/` is the end
            time. This follows the [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) time interval notation. Note that the time values are in the
            local time zone of the `Location`. This is because it would be impractical to convert time intervals related to a location to UTC, given
            that the intervals are linked to a weekday (as opposed to a specific date) and thus the UTC time could change in time zones where
            [Daylight Saving Time(DST)](https://en.wikipedia.org/wiki/Daylight_saving_time) is used. See the
            [Time values](/#section/Technical-notes/Time-values) section for details.
          example: '09:00:00/17:00:00'
      required:
        - range

    vehicle:
      type: object
      description: Vehicle
      properties:
        id:
          type: string
          format: uri
          description: |
            Unique ID for this `Vehicle`. A URI can be assigned by the client or will be generated by the server if the client doesn't provide it.
            Once assigned, the URI can't be changed. See [Unique Identifiers](/#section/Technical-notes/Unique-identifiers) for more information.
          example: 'https://api.opentripmodel.org/api/public/v4/vehicles/b9bb914d-845e-46f2-91ff-31fa4bac2fbe'
        name:
          type: string
          description: |
            Name of the `Vehicle`. For display and search purposes only.
          example: Otto's truck
        externalIds:
          type: array
          description: |
            An optional array of IDs by which the vehicle may be known in other systems.
          items:
            $ref: '#/components/schemas/idReference'
        vehicleType:
          $ref: '#/components/schemas/vehicleType'
        fuel:
          $ref: '#/components/schemas/fuelType'
        maxLinks:
          type: integer
          format: int32
          description: |
            Maximum number of links to other `Vehicle` s. Typical values are 0, 1 or 2.
        loadCapacities:
          description: |
            The load capacities of the `Vehicle`. This can be an array of values, for several reasons:

            - The `Vehicle` might be split up in multiple compartments.
            - You might want to express the load capacities in different quantities. E.g. in square meters or litres as well as in number of pallets.
          type: array
          items:
            $ref: '#/components/schemas/valueWithUnit'
          example:
            - value: 1000
              unit: 'kg'
        length:
          allOf:
            - description: The length of the `Vehicle`.
            - $ref: '#/components/schemas/valueWithUnit'
          example:
            value: 5200
            unit: 'mm'
        height:
          allOf:
            - description: The height of the `Vehicle`.
            - $ref: '#/components/schemas/valueWithUnit'
          example:
            value: 2500
            unit: 'mm'
        width:
          allOf:
            - description: The width of the `Vehicle`.
            - $ref: '#/components/schemas/valueWithUnit'
          example:
            value: 1800
            unit: 'mm'
        emptyWeight:
          allOf:
            - description: The weight of the `Vehicle` when empty.
            - $ref: '#/components/schemas/valueWithUnit'
          example:
            value: 2000
            unit: 'kg'
      required:
        - maxLinks
        - type

    vehicleType:
      type: object
      description: The type of vehicle
      properties:
        type:
          type: string
          enum:
            - boxtruck
            - truck
            - trailer
            - lorry
            - tractor
            - airplane
            - deepSeaVessel
            - barge
            - passengerCar
            - motorBike
            - bike
            - bus
            - coach
            - train
            - tram
            - unknown
            - other
        other:
          type: string
          description: |
            Name of the vehcile type if `other` is chosen in the `type` field.
          example: teletransporter
      example:
        type: tractor
      required:
        - type

    fuelType:
      type: object
      description: |
        The type of fuel the vehicle runs on. For vehicle without an engine of their own, such as a trailer, you may choose `not-applicable`. For
        trailers with cooling capabilities, choose the fuel type of the cooling engine.
      properties:
        type:
          type: string
          enum:
            - battery
            - biodiesel
            - diesel
            - dieselBatteryHybrid
            - ethanol
            - hydrogen
            - liquidGas
            - lpg
            - methane
            - petrol
            - petrolBatteryHybrid
            - notApplicable
            - unknown
            - other
        other:
          type: string
          description: |
            Name of the fuel type if `other` is chosen in the `type` field.
          example: nuclear-fusion
      example:
        type: diesel
      required:
        - type

    sensor:
      type: object
      description: Sensor
      properties:
        id:
          type: string
          format: uri
          description: |
            Unique ID for this `Sensor`. A URI can be assigned by the client or will be generated by the server if the client doesn't provide it.
            Once assigned, the URI can't be changed. See [Unique Identifiers](/#section/Technical-notes/Unique-identifiers) for more information.
          example: https://api.opentripmodel.org/api/public/v4/sensors/6666f00c-1332-472c-aff9-bc11b3d53296
        name:
          type: string
          description: |
            Name of the `Sensor`, for display and search purposes only.
          example: Temperature sensor in trailer x
        externalIds:
          type: array
          description: |
            An optional array of IDs by which the sensor may be known in other systems.
          items:
            $ref: '#/components/schemas/idReference'
        placement:
          type: string
          description: |
            Sometimes more than one sensor can be associated with a single entity. This is the case e.g. in cooled trailers that are divided into
            compartments with different temperatures, where each compartment has its own sensor. The `placement` member can be used to identify where
            a sensor is placed. Parties using OpenTripModel to exchange sensor data may wish to agree on a standardized naming, but this is too
            specific to describe in the standard.
          example: Compartment 1
        sensorType:
          $ref: '#/components/schemas/sensorType'
        constraint:
          allOf:
            - description: |
                In the context of a `Sensor`, only `sensorValueConstraint`s really make sense. You can use such a constraint to model a sensor of\
                which the measured value must be within certain bounds at all times.

                > **ℹ Note** that constraints can be nested and combined using the `andConstraint`, `orConstraint` and `notConstraint`.
            - $ref: '#/components/schemas/constraint'


    sensorType:
      type: object
      description: The type of sensor
      properties:
        type:
          type: string
          enum:
            - temperature
            - pressure
            - speed
            - humidity
            - accelerometer
            - current
            - voltage
            - weight
            - unknown
            - other
        other:
          type: string
          description: |
            Name of the sensor type if `other` is chosen in the `type` field.
          example: smurf sensor
      example:
        type: accelerometer
      required:
        - type

    shipment:
      type: object
      description: |
        A shipment object has at lease a `physicalSender` and `physicalAddressee` location. If no `legalSender` or `legalAddressee` are given, those
        are considered equal to their physical counterparts. All sender/addressee values can be given either as embedded location object or as URI of
        a pre-defined location. In the latter case, you can use the field ending with `Id` instead. A `physicalSender` or `physicalSenderId` is
        required, as is a `physicalAddressee` or `physicalAddresseeId`.
      properties:
        id:
          type: string
          format: uri
          description: |
            Uniquely identifies the `Shipment`. A URI can be assigned by the client or will be generated by the server if the client doesn't provide
            it. Once assigned, the URI can't be changed. See [Unique Identifiers](/#section/Technical-notes/Unique-identifiers) for more information.
          example: https://api.opentripmodel.org/api/public/v4/shipments/ddb488f2-9082-4ec9-bd88-3c4e703a103d
        name:
          type: string
          description: Name of the `Shipment`. For display purposes and search only.
          example: Special delivery for store 3
        externalIds:
          type: array
          description: |
            An optional array of IDs by which the shipment may be known in other systems.
          items:
            $ref: '#/components/schemas/idReference'
        physicalSenderId:
          type: string
          format: uri
          description: |
            The URI of an already defined location for the physical location of the sender.
          example: https://api.opentripmodel.org/api/public/v4/locations/ebf47d6b-b976-438f-bf0a-5161d04bf981
        physicalSender:
          $ref: '#/components/schemas/location'
        legalSenderId:
          type: string
          format: uri
          description: |
            The URI of an already defined location for the legal location of the sender.
          example: https://api.opentripmodel.org/api/public/v4/locations/62da797a-bc58-40c1-a9ee-5e90813144a9
        legalSender:
          $ref: '#/components/schemas/location'
        physicalAddresseeId:
          type: string
          format: uri
          description: |
            The URI of an already defined location for the physical location of the addressee.
          example: https://api.opentripmodel.org/api/public/v4/locations/a1ed8116-94c5-4f00-a17d-7b96998a0795
        physicalAddressee:
          $ref: '#/components/schemas/location'
        legalAddresseeId:
          type: string
          format: uri
          description: |
            The URI of an already defined location for the legal location of the addressee.
          example: https://api.opentripmodel.org/api/public/v4/locations/cef100b7-9867-424d-a9a7-350fa823d609
        legalAddressee:
          $ref: '#/components/schemas/location'
        freightDocument:
          type: string
          format: uri
          description: URI to the official freight document for this shipment.
          example: 'https://partner.transfollow.com/api/freightdocuments/abc001'
        dimensions:
          allOf:
            - description: The dimensions of the shipment.
            - $ref: '#/components/schemas/dimensions'
        weight:
          allOf:
            - description: The weight of the shipment.
            - $ref: '#/components/schemas/valueWithUnit'
        packaging:
          type: string
          description: |
            Description of the packaging (type) of this shipment
          example: pallet
        type:
          type: string
          description: |
            This field can be used to categorize and/or group shipments by type, depending on the needs of a specific logistic process.
          example: fresh goods
        count:
          type: number
          description: |
            Amount of units of packaging. For instance, if this field is '2' and packaging is 'pallet', this indicates the shipment
            contains 2 pallets.
            > Note: This field can be used alongside dimensions and weight, but dimensions and weight always apply
            to the entire shipment, not to a single unit of packaging.
          example: 2
        description:
          type: string
          description: |
            Free format text field that can be used to describe the contents of this shipment.
          example: 50 boxes of bananas
        constraint:
          allOf:
            - description: |
                In the context of a `Shipment`, constraints can be used to e.g. define minimum or maximum temperatures for shipments, or date time
                constraints for delivery.

                > **ℹ Note** that constraints can be nested and combined using the `andConstraint`, `orConstraint` and `notConstraint`.
            - $ref: '#/components/schemas/constraint'

    trip:
      type: object
      description: |
        `Trip` entity. A `Trip` entity consists of a list of `Events` and an optional `Route`. The sequence of `Events` defines the trip. Each `Trip`
        has an associated `events` endpoint that can be used to get the events for this trip or to publish new events on the trip. Once defined, a
        `Trip` entity exists in all single lifecycle phases, just like the other entities. However, the events of the `Trip` differ between the
        different lifecycle phases.
      properties:
        id:
          type: string
          format: uri
          description: |
            Uniquely identifies the `Trip`. A URI can be assigned by the client or will be generated by the server if the client doesn't provide it.
            Once assigned, the URI can't be changed. See [Unique Identifiers](/#section/Technical-notes/Unique-identifiers) for more information.
          example: https://api.opentripmodel.org/api/public/v4/trips/aa38745d-1e90-4774-bf12-05c24a6f8318
        name:
          type: string
          description: |
            Name of the `Trip`, for display and search purposes only.
          example: Warehouse to shop
        externalIds:
          type: array
          description: |
            An optional array of IDs by which the trip may be known in other systems.
          items:
            $ref: '#/components/schemas/idReference'
        route:
          type: string
          format: uri
          description: |
            URI of an endpoint that can be used to retrieve the route of this `Trip`.
          example: https://api.opentripmodel.org/api/public/v4/routes/9df853e4-1291-40de-bfc1-4e5d7b23cc76
        constraint:
          allOf:
            - description: |
                In the context of a `Trip`, constraints can be used to define constraints that have to be met during the trip, e.g. if the temperature
                in a refridgerated trailer has to stay below a given maximum during the trip.

                > **ℹ Note** that constraints can be nested and combined using the `andConstraint`, `orConstraint` and `notConstraint`.
            - $ref: '#/components/schemas/constraint'

    route:
      type: object
      description: Route
      properties:
        id:
          type: string
          format: uri
          description: |
            Uniquely identifies the `Route`. A URI can be assigned by the client or will be generated by the server if the client doesn't provide it.
            Once assigned, the URI can't be changed. See [Unique Identifiers](/#section/Technical-notes/Unique-identifiers) for more information.
          example: https://api.opentripmodel.org/api/public/v4/routes/fcc0828c-591f-4b3c-bc48-7dc8856e7f2a
        name:
          type: string
          description: Name of the `Route`. For display purposes and search only.
          example: Quickest from Amsterdam warehouse to Maastricht store
        externalIds:
          type: array
          description: |
            An optional array of IDs by which the route may be known in other systems.
          items:
            $ref: '#/components/schemas/idReference'
        geoReferences:
          $ref: '#/components/schemas/geoReference'
      required:
        - geoReferences

    bundle:
      type: object
      description: Bundle
      properties:
        meta:
          $ref: '#/components/schemas/bundle_meta'
        entities:
          type: array
          items:
            $ref: '#/components/schemas/bundledEntity'
        events:
          description: |
            An array of events. The order of events is determined by the timestamps as explained on the [Ordering of events](https://www.opentripmodel.org/v4.2.0/docs/ordering-of-events) page.
          type: array
          items:
            $ref: '#/components/schemas/event'

    bundle_meta:
      type: object
      description: Meta-information about this bundle.
      properties:
        generator:
          type: string
          description: Description of the generator of this bundle
          example: XYZ Planning software
        creationTime:
          type: string
          format: date-time
          description: Date and time this bundle was generated

    bundledEntity:
      type: object
      description: Entity that is part of a `Bundle`.
      properties:
        entityType:
          type: string
          description: |
            The type of entity. This is needed, since the type cannot be derived from the endpoint in a `Bundle`.
          enum:
            - vehicleEntity
            - locationEntity
            - tripEntity
            - routeEntity
            - shipmentEntity
            - actorEntity
            - constraintEntity
            - sensorEntity
      discriminator:
        propertyName: entityType
      required:
        - entityType
      example:
        entityType: vehicleEntity
        id: 'https://api.opentripmodel.org/api/public/v4/vehicles/635f6bd2-2568-45d8-b4e0-312f563b87de'
        externalIds:
          - schema: 'https://opentripmodel.org/types/licensePlate/nl'
            value: T-123-AB
        vehicleType:
          type: tractor
        fuel:
          type: diesel
        maxLinks: 1

    sensorEntity:
      type: object
      allOf:
        - $ref: '#/components/schemas/bundledEntity'
        - $ref: '#/components/schemas/sensor'

    vehicleEntity:
      type: object
      allOf:
        - $ref: '#/components/schemas/bundledEntity'
        - $ref: '#/components/schemas/vehicle'

    locationEntity:
      type: object
      allOf:
        - $ref: '#/components/schemas/bundledEntity'
        - $ref: '#/components/schemas/location'

    tripEntity:
      type: object
      allOf:
        - $ref: '#/components/schemas/bundledEntity'
        - $ref: '#/components/schemas/trip'

    routeEntity:
      type: object
      allOf:
        - $ref: '#/components/schemas/bundledEntity'
        - $ref: '#/components/schemas/route'

    shipmentEntity:
      type: object
      allOf:
        - $ref: '#/components/schemas/bundledEntity'
        - $ref: '#/components/schemas/shipment'

    actorEntity:
      type: object
      allOf:
        - $ref: '#/components/schemas/bundledEntity'
        - $ref: '#/components/schemas/actor'

    constraintEntity:
      type: object
      allOf:
        - $ref: '#/components/schemas/bundledEntity'
        - $ref: '#/components/schemas/constraint'

    event:
      type: object
      description: Event
      properties:
        id:
          type: string
          format: uri
          description: |
            Uniquely identifies the `Event`. A URI can be assigned by the client or will be generated by the server if the client doesn't provide it.
            Once assigned, the URI can't be changed. See [Unique Identifiers](/#section/Technical-notes/Unique-identifiers) for more information.
          example: |
            https://api.opentripmodel.org/api/public/v4/vehicles/96b65c0f-9692-4b46-bd08-cac21ecabcec/actual/events/ed592f10-a753-40d9-b015-dfeed7dc0681
        groupingId:
          type: string
          description: |
            When defining interfaces between different systems, sometimes one "event" in one system can lead to multiple OTM events. You might need to
            be able to see which events originate to the same "source" event. Another use case for the `groupingId` is for displaying purposes. In a
            GUI, it might be needed to visually group certain events. In these cases, the `groupingId` can be used.
          example: 1f1aac39-437d-4098-aef7-ec720016b932
        lifecyclePhase:
          $ref: '#/components/schemas/lifecyclePhase'
        involvedObjects:
          type: array
          description: |
            A list of URI's, each one pointing to an endpoint representing an object that is involved in this `Event`. The maximum number of objects
            is defined by the `Event`'s type.
          items:
            type: string
            format: uri
            example: |
              https://api.opentripmodel.org/api/public/v4/locations/c4a788c7-d86a-4efe-95da-1e345bd73d67
        type:
          type: string
          description: |
            The type of the `Event`. Depending on this type, additional fields may be required for this object. See the main
            [Event section](#tag/Event) for comprehensive documentation on the available event types, their meaning and their variables.
          example: loadShipmentEvent
        time:
          type: string
          format: date-time
          description: |
            The date and time this `Event` happens. The exact meaning depends on the `lifecyclePhase`:

            - "planned" and "projected": The date and time this event is planned or projected to happen. This is always in the future.
            - "actual": The date and time this event actually happens. This is always in the near past.
            - "realized": The date and time this event did actually happen. This is always in the past.

            All date-time values in OpenTripModel are UTC times, in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) notation:
            `YYYY-MM-DDThh:mm:ss.sssZ`. See the [Time values](/#section/Technical-notes/Time-values) section for details.
        eventGenerationTime:
          type: string
          format: date-time
          description: |
            This field can optionally contain the date and time this event was generated. This can be useful e.g. for events in the `projected`
            lifecycle phase, that typically are calculated. The generation (calculation) time can be an indicator for the relevance of the event.
            The `eventGenerationTime` should always be in the past.

            If the sender of an OTM event does not set the eventGenerationTime, the recipient may set it to the current time.

            All date-time values in OpenTripModel are UTC times, in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) notation:
            `YYYY-MM-DDThh:mm:ss.sssZ`. See the [Time values](/#section/Technical-notes/Time-values) section for details.
        reason:
          type: string
          description: |
            Reason for or cause of this event.
          example: There was a traffic jam.
        remarks:
          type: string
          description: |
            Remarks for this event.
          example: The traffic lights weren't working
        constraint:
          allOf:
            - description: |
                In the context of an `Event`, a `Constraint` can be used to constrain the order of events. This can be useful if events don't have
                any timestamp but you need to guarantee that a certain event occurs before another event. The only constraint types that are valid in
                the context of an `Event` are:

                - `eventOrderConstraint`;
                - `andConstraint`;
                - `orConstraint`;
                - `constraintReference`.
            - $ref: '#/components/schemas/constraint'

      discriminator:
        propertyName: type
      required:
        - type

    updateEvent_location:
      type: object
      description: |
        The location on which this event is taking place. Note that only inline (_ad hoc_) locations can be used. If you wish to refer to a predefined
        `Location`, either publish the event on the particular `Location`'s endpoint or reference the particular `Location` in the `involvedObjects`
        array. (This is changed since version 4.1. Before 4.1 it was possible to reference a `Location` here, but that turned out to be ambiguous.)

        Note that it might seem superfluous to have a `location` inside a `location`; this structure is kept in place for backward compatibility
        with OTM 4.0.
      properties:
        location:
          $ref: '#/components/schemas/geoReference'

    locationUpdateEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'

    sensorUpdateEvent:
      allOf:
      - $ref: '#/components/schemas/event'
      - properties:
          location:
            $ref: '#/components/schemas/updateEvent_location'
          sensorValue:
            $ref: '#/components/schemas/valueWithUnit'
      required:
        - sensorValue

    startEngineEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'

    stopEngineEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'


    restrictionWarningEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'
        - properties:
            warning:
              type: string
              description: Restriction warning description
      required:
        - warning

    constraintViolationEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'
            violatedConstraint:
              $ref: '#/components/schemas/constraint'

    trafficWarningEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'
        - properties:
            warning:
              type: string
              description: Traffic warning description
      required:
        - warning


    startMovingEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'

    stopMovingEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'

    startWaitingEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'

    stopWaitingEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'

    startLoadingAndUnloadingEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'

    stopLoadingAndUnloadingEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'


    pickupTimeWindowStartEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'

    pickupTimeWindowEndEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'

    deliveryTimeWindowStartEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'

    deliveryTimeWindowEndEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'


    coupleVehiclesEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'

    decoupleVehiclesEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'

    assignToTripEvent:
      allOf:
        - $ref: '#/components/schemas/event'

    deassignFromTripEvent:
      allOf:
        - $ref: '#/components/schemas/event'

    assignDriverEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'

    deassignDriverEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'

    associateWithActorEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            actor:
              type: string
              format: uri
              description: |
                Reference to the `Actor` to which the `involvedObjects` are to be associated
              example: 'https://api.opentripmodel.org/api/public/v4/actors/45db6ed0-28a7-4e4a-baba-3d5f8d171103'
            role:
              type: string
              description: |
                The role of the `Actor` with respect to the `involvedObjects`. There are no pre-defined roles, and the role does not have any
                special meaning in OpenTripModel.
              example: owner

    dissociateFromActorEvent:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            actor:
              type: string
              format: uri
              description: |
                Reference to the `Actor` from which the `involvedObjects` are to be dissociated
              example: |
                https://api.opentripmodel.org/api/public/v4/actors/45db6ed0-28a7-4e4a-baba-3d5f8d171103
            role:
              type: string
              description: |
                The role of the `Actor` with respect to the `involvedObjects`. There are no pre-defined roles, and the role does not have any
                special meaning in OpenTripModel.
              example: owner


    loadShipmentEvent:
      description: |
        This events models the loading of a `Shipment` in a `Vehicle`. This event often takes place at the same time as a `releaseShipmentEvent`.
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'
            placement:
              type: string
              description: |
                Sometimes a `Vehicle` has multiple compartments, e.g. to have refridgerated zones with different temperatures. You can use the
                placement value to specify if a `Shipment` should be loaded into a specific compartment of the `Vehicle`.
              example: Compartment 1

    unloadShipmentEvent:
      description: |
        This events models the unloading of a `Shipment` from a `Vehicle`. This event often takes place at the same time as a `receiveShipmentEvent`.
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'

    receiveShipmentEvent:
      description: |
        This event models the reception of a `Shipment` at a `Location`. This event often takes place at the same time as a `unloadShipmentEvent`.
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'

    releaseShipmentEvent:
      description: |
        This event models the release (for pick up) of a `Shipment` at a `Location`. This event often takes place at the same time as a
        `loadShipmentEvent`.
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            location:
              $ref: '#/components/schemas/updateEvent_location'

    linkTripsEvent:
      allOf:
        - $ref: '#/components/schemas/event'

    coupleSensorEvent:
      allOf:
        - $ref: '#/components/schemas/event'

    decoupleSensorEvent:
      allOf:
        - $ref: '#/components/schemas/event'


    cancelEvent:
      allOf:
        - $ref: '#/components/schemas/event'

    cancelAllEntityEvents:
      allOf:
        - $ref: '#/components/schemas/event'

    cancelGroupedEvents:
      allOf:
        - $ref: '#/components/schemas/event'
        - properties:
            cancelledGroupingIds:
              type: array
              description: |
                All events with the given `groupingId`s will be cancelled.
              items:
                type: string
                example: ceb70302-4379-481c-9591-2c42198a9ac7
              example:
                - a52680d3-18d5-4ad5-baed-ba85bd4ce8dc
                - 6ebdb45e-d82d-41df-9554-0a1166db9a05

    ignoreEvent:
      allOf:
        - $ref: '#/components/schemas/event'


    lifecyclePhase:
      type: object
      description: |
        Lifecycle phase, can be one of "planned", "projected", "actual" or "realized". All entities except `Event` exist in all lifecycle phases.
        The events on an entity differ depending on the lifecycle phase. E.g. a vehicle in the "planned" lifecycle phase has different events compared
        to the same vehicle in the "actual" phase.

        > Note that, when `PUT`-ing a new event, you always `PUT` to an endpoint specific to the lifecycle phase. Thus, the lifecycle phase field
          is not required when `PUT`-ing an event. When `GET`-ing an event, the OTM-server will always add the field, so you can see the lifecycle
          phase in the response. It is allowed to add a redundant `lifecyclePhase` field to an event when `PUT`-ing it. Make sure the contents of that
          field correspond to the endpoint you `PUT` to, otherwise the OTM-server might respond with a `400 - Bad Request` error.
      properties:
        phase:
          type: string
          description: phase in the lifecycle
          enum:
            - planned
            - projected
            - actual
            - realized
      example:
        phase: actual

    valueWithUnit:
      type: object
      description: Value with unit
      properties:
        value:
          type: number
          description: value in the given unit
          example: 42
        unit:
          type: string
          description: measurement unit of this value
          example: kg
      required:
        - unit
        - value

    dimensions:
      type: object
      description: Dimensions of an object.
      properties:
        width:
          $ref: '#/components/schemas/valueWithUnit'
        height:
          $ref: '#/components/schemas/valueWithUnit'
        length:
          $ref: '#/components/schemas/valueWithUnit'
      required:
        - width
        - height
        - length

    idReference:
      type: object
      description: |
        Reference to an ID of an object in another system or according to another standard.
      properties:
        schema:
          type: string
          format: uri
          description: |
            URI, uniquely identifying the scheme of the identifier. Examples:

            - `http://www.gs1.org/gln`, **[Global Location Number](http://en.wikipedia.org/wiki/Global_Location_Number)**: See
              http://en.wikipedia.org/wiki/Global_Location_Number and http://www.gs1.org/gln.

            - `https://opentripmodel.org/types/licensePlate/{countryCode}`, **License plate**: Licence plate identifier. Use the
              [international vehicle registration code](https://en.wikipedia.org/wiki/List_of_international_vehicle_registration_codes) in the URI,

            - `https://opentripmodel.org/types/name`, **Name**: Just a name

            - `https://opentripmodel.org/types/kvknummer`, **Dutch Chamber of Commerce number**: Can be used to identify a company.

            - `http://www.gs1.org/gsin`, **GSIN**, [Global Shipment Identification Number](http://www.gs1.org/gsin) - identifies a shipment, according
              to the [GS1 standard](https://en.wikipedia.org/wiki/GS1).

            - `http://www.gs1.org/sscc`, **SSCC**, [Serial Shipping Container Code](http://www.gs1.org/sscc) - identifies a container within a
              shipment, in case a shipment consists of more than one container, according to the [GS1 standard](https://en.wikipedia.org/wiki/GS1).

            - `http://www.gs1.org/gtin`, **GTIN**, [Global Trade Item Number](http://www.gs1.org/gtin), identifies an item in a container within a
              shipment, according to the [GS1 standard](https://en.wikipedia.org/wiki/GS1).

            > **Note** that the list above is just a list of examples. E.g. in case of shipments, OpenTripModel doesn't define the granularity of a
              `Shipment`, while the GS1-references might suggest otherwise. In GS1 terms, a `Shipment` in OpenTripModel can either be a _Shipment_,
              or a _Shipping Container_ or a _Trade Item_ or neither of those. It all depends on the needs of the logistics operation that is to be
              modeled in OpenTripModel.

            Also note that uniqueness of external ID's should not be enforced by an OpenTripModel server. External ID's are for reference only.
          example: 'https://opentripmodel.org/types/licensePlate/nl'
        value:
          type: string
          description: The unique identifier (ID) in the format defined by the schema.
          example: AB-12-CD
        uri:
          type: string
          format: uri
          description: |
            The (optional) URI that can be used to get additional information about the referenced identifier in an external system.
          example: 'https://www.kvk.nl/zoeken/#!zoeken&q=57084173'
      required:
        - schema
        - value