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 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 Creative Commons License
All OpenTripModel documentation is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. version: "{{VERSION}}" 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: | # events | access | read/write |   | | ------------- | --------------- | ---------- | -------------------------------------------------------- | | list | directly | read | [**GET** `/events`](#/paths/~1events/get) | | list | directly | write | [use a Bundle](#tag/Bundle) | | list | via entity | read | **GET** `/{entity}/{uuid}/{lifecycle}/events/` | | list | via 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 entity | read | N/A | | single | via 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 | | :-----: | :-------: | :----: | :------: | |   |   | ○ | ○ | ### locationUpdateEvent Updates the location of a `Vehicle` _Applicable entities for `locationUpdateEvent`:_ | Location | Vehicle | Shipment | Trip | Route | Actor | Constraint | Sensor | Event | | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: | | □ | ● |   |  |  |  |   |   |  | 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 | | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: | |   |   |   |  |  |  |   | ● |  | ### 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 | | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: | |   | ● |   |  |  |  |   |   |  | ## 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 | | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: | | ○ |   | ○ | ○ |  |  | ● | ○ |  | ### 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 | | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: | | ■ |   |   |  | ■ |  |   |   |  | ## 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 | | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: | |   | ● |   |  |  |  |   |   |  | ### 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 | | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: | |   | ● |   |  |  |  |   |   |  | ### 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 | | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: | |   | ● |   |  |  |  |   |   |  | ## 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 | | :-----: | :-------: | :----: | :------: | | ○ | ○ |   |   | _Applicable entities for `pickupTimeWindowStartEvent`, `pickupTimeWindowEndEvent`, `deliveryTimeWindowStartEvent` and `deliveryTimeWindowEndEvent`:_ | Location | Vehicle | Shipment | Trip | Route | Actor | Constraint | Sensor | Event | | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: | |   |   | ● |  |  |  |   |   |  | ## 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 | | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: | |   | ● ● |   |  |  |  |   |   |  | ### 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 | | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: | |   | ● |   | ● |  |  |   |   |  | ### 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 | | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: | |   | ● |   |  |  | ● |   |   |  | ### 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` |   | ● | ● |  |  |  |   |   |  | Load a `Shipment` in a `Vehicle` | `unloadShipmentEvent` |   | ● | ● |  |  |  |   |   |  | Unload a `Shipment` from a `Vehicle` | `receiveShipmentEvent` | ● |   | ● |  |  |  |   |   |  | Receive a `Shipment` on a `Location` | `releaseShipmentEvent` | ● |   | ● |  |  |  |   |   |  | 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 | | :------: | :-----: | :------: | :--------: | :---: | :---: | :--------: | :----: | :---: | |   |   |   | ● ● □ ... |  |  |   |   |  | ### 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 | | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: | | ○ | ○ | ○ |  |  | ○ |   | ● |  | ## 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 | | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :-------: | |   |   |   |  |  |  |   |   | ● □ ... | ### 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. 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 | | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: | | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ |  | ### 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 | | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :---: | | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ |  | ### 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 | | :------: | :-----: | :------: | :---: | :---: | :---: | :--------: | :----: | :-------: | |   |   |   |  |  |  |   |   | ● □ ... | - 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: oneOf: - $ref: '#/components/schemas/locationUpdateEvent' - $ref: '#/components/schemas/sensorUpdateEvent' - $ref: '#/components/schemas/startEngineEvent' - $ref: '#/components/schemas/stopEngineEvent' - $ref: '#/components/schemas/restrictionWarningEvent' - $ref: '#/components/schemas/constraintViolationEvent' - $ref: '#/components/schemas/trafficWarningEvent' - $ref: '#/components/schemas/startMovingEvent' - $ref: '#/components/schemas/stopMovingEvent' - $ref: '#/components/schemas/startWaitingEvent' - $ref: '#/components/schemas/stopWaitingEvent' - $ref: '#/components/schemas/startLoadingAndUnloadingEvent' - $ref: '#/components/schemas/stopLoadingAndUnloadingEvent' - $ref: '#/components/schemas/pickupTimeWindowStartEvent' - $ref: '#/components/schemas/pickupTimeWindowEndEvent' - $ref: '#/components/schemas/deliveryTimeWindowStartEvent' - $ref: '#/components/schemas/deliveryTimeWindowEndEvent' - $ref: '#/components/schemas/coupleVehiclesEvent' - $ref: '#/components/schemas/decoupleVehiclesEvent' - $ref: '#/components/schemas/assignToTripEvent' - $ref: '#/components/schemas/deassignFromTripEvent' - $ref: '#/components/schemas/assignDriverEvent' - $ref: '#/components/schemas/deassignDriverEvent' - $ref: '#/components/schemas/associateWithActorEvent' - $ref: '#/components/schemas/dissociateFromActorEvent' - $ref: '#/components/schemas/loadShipmentEvent' - $ref: '#/components/schemas/unloadShipmentEvent' - $ref: '#/components/schemas/receiveShipmentEvent' - $ref: '#/components/schemas/releaseShipmentEvent' - $ref: '#/components/schemas/linkTripsEvent' - $ref: '#/components/schemas/coupleSensorEvent' - $ref: '#/components/schemas/decoupleSensorEvent' - $ref: '#/components/schemas/cancelEvent' - $ref: '#/components/schemas/cancelAllEntityEvents' - $ref: '#/components/schemas/cancelGroupedEvents' - $ref: '#/components/schemas/ignoreEvent' discriminator: propertyName: type mapping: sensorUpdateEvent: '#/components/schemas/locationUpdateEvent' startEngineEvent: '#/components/schemas/sensorUpdateEvent' stopEngineEvent: '#/components/schemas/startEngineEvent' restrictionWarningEvent: '#/components/schemas/stopEngineEvent' constraintViolationEvent: '#/components/schemas/restrictionWarningEvent' trafficWarningEvent: '#/components/schemas/constraintViolationEvent' startMovingEvent: '#/components/schemas/trafficWarningEvent' stopMovingEvent: '#/components/schemas/startMovingEvent' startWaitingEvent: '#/components/schemas/stopMovingEvent' stopWaitingEvent: '#/components/schemas/startWaitingEvent' startLoadingAndUnloadingEvent: '#/components/schemas/stopWaitingEvent' stopLoadingAndUnloadingEvent: '#/components/schemas/startLoadingAndUnloadingEvent' pickupTimeWindowStartEvent: '#/components/schemas/stopLoadingAndUnloadingEvent' pickupTimeWindowEndEvent: '#/components/schemas/pickupTimeWindowStartEvent' deliveryTimeWindowStartEvent: '#/components/schemas/pickupTimeWindowEndEvent' deliveryTimeWindowEndEvent: '#/components/schemas/deliveryTimeWindowStartEvent' coupleVehiclesEvent: '#/components/schemas/deliveryTimeWindowEndEvent' decoupleVehiclesEvent: '#/components/schemas/coupleVehiclesEvent' assignToTripEvent: '#/components/schemas/decoupleVehiclesEvent' deassignFromTripEvent: '#/components/schemas/assignToTripEvent' assignDriverEvent: '#/components/schemas/deassignFromTripEvent' deassignDriverEvent: '#/components/schemas/assignDriverEvent' associateWithActorEvent: '#/components/schemas/deassignDriverEvent' dissociateFromActorEvent: '#/components/schemas/associateWithActorEvent' loadShipmentEvent: '#/components/schemas/dissociateFromActorEvent' unloadShipmentEvent: '#/components/schemas/loadShipmentEvent' receiveShipmentEvent: '#/components/schemas/unloadShipmentEvent' releaseShipmentEvent: '#/components/schemas/receiveShipmentEvent' linkTripsEvent: '#/components/schemas/releaseShipmentEvent' coupleSensorEvent: '#/components/schemas/linkTripsEvent' decoupleSensorEvent: '#/components/schemas/coupleSensorEvent' cancelEvent: '#/components/schemas/decoupleSensorEvent' cancelAllEntityEvents: '#/components/schemas/cancelEvent' cancelGroupedEvents: '#/components/schemas/cancelAllEntityEvents' ignoreEvent: '#/components/schemas/cancelGroupedEvents' application/xml: schema: oneOf: - $ref: '#/components/schemas/locationUpdateEvent' - $ref: '#/components/schemas/sensorUpdateEvent' - $ref: '#/components/schemas/startEngineEvent' - $ref: '#/components/schemas/stopEngineEvent' - $ref: '#/components/schemas/restrictionWarningEvent' - $ref: '#/components/schemas/constraintViolationEvent' - $ref: '#/components/schemas/trafficWarningEvent' - $ref: '#/components/schemas/startMovingEvent' - $ref: '#/components/schemas/stopMovingEvent' - $ref: '#/components/schemas/startWaitingEvent' - $ref: '#/components/schemas/stopWaitingEvent' - $ref: '#/components/schemas/startLoadingAndUnloadingEvent' - $ref: '#/components/schemas/stopLoadingAndUnloadingEvent' - $ref: '#/components/schemas/pickupTimeWindowStartEvent' - $ref: '#/components/schemas/pickupTimeWindowEndEvent' - $ref: '#/components/schemas/deliveryTimeWindowStartEvent' - $ref: '#/components/schemas/deliveryTimeWindowEndEvent' - $ref: '#/components/schemas/coupleVehiclesEvent' - $ref: '#/components/schemas/decoupleVehiclesEvent' - $ref: '#/components/schemas/assignToTripEvent' - $ref: '#/components/schemas/deassignFromTripEvent' - $ref: '#/components/schemas/assignDriverEvent' - $ref: '#/components/schemas/deassignDriverEvent' - $ref: '#/components/schemas/associateWithActorEvent' - $ref: '#/components/schemas/dissociateFromActorEvent' - $ref: '#/components/schemas/loadShipmentEvent' - $ref: '#/components/schemas/unloadShipmentEvent' - $ref: '#/components/schemas/receiveShipmentEvent' - $ref: '#/components/schemas/releaseShipmentEvent' - $ref: '#/components/schemas/linkTripsEvent' - $ref: '#/components/schemas/coupleSensorEvent' - $ref: '#/components/schemas/decoupleSensorEvent' - $ref: '#/components/schemas/cancelEvent' - $ref: '#/components/schemas/cancelAllEntityEvents' - $ref: '#/components/schemas/cancelGroupedEvents' - $ref: '#/components/schemas/ignoreEvent' discriminator: propertyName: type 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: description: Contact details for this `Actor`. 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: oneOf: - $ref: '#/components/schemas/addressGeoReference' - $ref: '#/components/schemas/openLRGeoReference' - $ref: '#/components/schemas/tmcArrayGeoReference' - $ref: '#/components/schemas/tmcLocationGeoReference' - $ref: '#/components/schemas/latLongArrayGeoReference' - $ref: '#/components/schemas/latLongPointGeoReference' - $ref: '#/components/schemas/geoJSONLineString' - $ref: '#/components/schemas/geoJSONMultiLineString' - $ref: '#/components/schemas/geoJSONMultiPoint' - $ref: '#/components/schemas/geoJSONMultiPolygon' - $ref: '#/components/schemas/geoJSONPoint' - $ref: '#/components/schemas/geoJSONPolygon' discriminator: propertyName: type mapping: addressGeoReference: '#/components/schemas/addressGeoReference' openLRGeoReference: '#/components/schemas/openLRGeoReference' tmcArrayGeoReference: '#/components/schemas/tmcArrayGeoReference' tmcLocationGeoReference: '#/components/schemas/tmcLocationGeoReference' latLongArrayGeoReference: '#/components/schemas/latLongArrayGeoReference' latLongPointGeoReference: '#/components/schemas/latLongPointGeoReference' geoJSONLineString: '#/components/schemas/geoJSONLineString' geoJSONMultiLineString: '#/components/schemas/geoJSONMultiLineString' geoJSONMultiPoint: '#/components/schemas/geoJSONMultiPoint' geoJSONMultiPolygon: '#/components/schemas/geoJSONMultiPolygon' geoJSONPoint: '#/components/schemas/geoJSONPoint' geoJSONPolygon: '#/components/schemas/geoJSONPolygon' administrativeReference: allOf: - description: Administrative reference - $ref: '#/components/schemas/administrativeReference' contactDetails: description: Contact details for this `Location`. type: array items: $ref: '#/components/schemas/contactDetail' constraint: 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`. oneOf: - $ref: '#/components/schemas/constraintReference' - $ref: '#/components/schemas/andConstraint' - $ref: '#/components/schemas/notConstraint' - $ref: '#/components/schemas/orConstraint' - $ref: '#/components/schemas/sizeConstraint' - $ref: '#/components/schemas/speedConstraint' - $ref: '#/components/schemas/weightConstraint' - $ref: '#/components/schemas/fuelTypeConstraint' - $ref: '#/components/schemas/vehicleTypeConstraint' - $ref: '#/components/schemas/routeConstraint' - $ref: '#/components/schemas/dangerousGoodsConstraint' - $ref: '#/components/schemas/numberOfVehiclesConstraint' - $ref: '#/components/schemas/eventOrderConstraint' - $ref: '#/components/schemas/sensorValueConstraint' - $ref: '#/components/schemas/sensorUpdateFrequencyConstraint' - $ref: '#/components/schemas/startDateTimeConstraint' - $ref: '#/components/schemas/endDateTimeConstraint' - $ref: '#/components/schemas/timeRangeConstraint' discriminator: propertyName: type mapping: constraintReference: '#/components/schemas/constraintReference' andConstraint: '#/components/schemas/andConstraint' notConstraint: '#/components/schemas/notConstraint' orConstraint: '#/components/schemas/orConstraint' sizeConstraint: '#/components/schemas/sizeConstraint' speedConstraint: '#/components/schemas/speedConstraint' weightConstraint: '#/components/schemas/weightConstraint' fuelTypeConstraint: '#/components/schemas/fuelTypeConstraint' vehicleTypeConstraint: '#/components/schemas/vehicleTypeConstraint' routeConstraint: '#/components/schemas/routeConstraint' dangerousGoodsConstraint: '#/components/schemas/dangerousGoodsConstraint' numberOfVehiclesConstraint: '#/components/schemas/numberOfVehiclesConstraint' eventOrderConstraint: '#/components/schemas/eventOrderConstraint' sensorValueConstraint: '#/components/schemas/sensorValueConstraint' sensorUpdateFrequencyConstraint: '#/components/schemas/sensorUpdateFrequencyConstraint' startDateTimeConstraint: '#/components/schemas/startDateTimeConstraint' endDateTimeConstraint: '#/components/schemas/endDateTimeConstraint' timeRangeConstraint: '#/components/schemas/timeRangeConstraint' 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: description: The type of the location 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 required: - type example: type: latLongPointGeoReference lat: 52.0838333 lon: 5.8318803 latLongPoint: description: | Describes a point on the earth. See [Wikipedia](https://en.wikipedia.org/wiki/Geographic_coordinate_system#Latitude_and_longitude) for an explanation. properties: lat: description: | [Latitude](https://en.wikipedia.org/wiki/Latitude) type: number format: double example: 52.192294 lon: description: | [Longitude](https://en.wikipedia.org/wiki/Longitude) type: number format: double example: 5.410124 required: - lat - lon example: lat: 52.0838333 lon: 5.8318803 movingInfo: description: Cannot be used on its own, is part of some geoReferences. 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: - description: | Georeference modelling an area or route as a series of lat/lon points. - $ref: '#/components/schemas/geoReference' - properties: points: description: An array of lat/lon 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: description: Is used as part of some GeoJson constructs, not to be used on its own. 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: description: Array of lat/lon pairs. 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: description: A two-dimensional array of lan/lon pairs. type: array items: description: An array of lat/lon pairs. 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: description: An array of lat/lon pairs. 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: description: A two-dimensional array of lat/lon pairs. type: array items: description: An array of lat/lon pairs. 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: description: A three-dimensional array of lat/lon pairs. type: array items: description: A two-dimensional array of lat/lon pairs. type: array items: description: An array of lat/lon pairs. 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: description: A geographic point, described according to the TMC spec. properties: locationCode: description: TMC location code type: string direction: description: TMC direction type: string default: positive enum: - positive - negative tmcLocation: description: A geographic location, described according to the TMC spec. 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: description: An array of TMC points, possibly describing a route. properties: countryCode: description: TMC country code type: string tableId: description: TMC table ID type: string tableVersionId: description: TMC table version ID type: string points: description: An array of TMC 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: description: An 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' 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 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: description: Which size are we contraining here? 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: description: An array of time 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 vehicleType: type: object description: The type of vehicle properties: type: description: The type of the vehicle 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: description: The type of fuel. 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: 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`. oneOf: - $ref: '#/components/schemas/constraintReference' - $ref: '#/components/schemas/andConstraint' - $ref: '#/components/schemas/notConstraint' - $ref: '#/components/schemas/orConstraint' - $ref: '#/components/schemas/sizeConstraint' - $ref: '#/components/schemas/speedConstraint' - $ref: '#/components/schemas/weightConstraint' - $ref: '#/components/schemas/fuelTypeConstraint' - $ref: '#/components/schemas/vehicleTypeConstraint' - $ref: '#/components/schemas/routeConstraint' - $ref: '#/components/schemas/dangerousGoodsConstraint' - $ref: '#/components/schemas/numberOfVehiclesConstraint' - $ref: '#/components/schemas/eventOrderConstraint' - $ref: '#/components/schemas/sensorValueConstraint' - $ref: '#/components/schemas/sensorUpdateFrequencyConstraint' - $ref: '#/components/schemas/startDateTimeConstraint' - $ref: '#/components/schemas/endDateTimeConstraint' - $ref: '#/components/schemas/timeRangeConstraint' discriminator: propertyName: type mapping: constraintReference: '#/components/schemas/constraintReference' andConstraint: '#/components/schemas/andConstraint' notConstraint: '#/components/schemas/notConstraint' orConstraint: '#/components/schemas/orConstraint' sizeConstraint: '#/components/schemas/sizeConstraint' speedConstraint: '#/components/schemas/speedConstraint' weightConstraint: '#/components/schemas/weightConstraint' fuelTypeConstraint: '#/components/schemas/fuelTypeConstraint' vehicleTypeConstraint: '#/components/schemas/vehicleTypeConstraint' routeConstraint: '#/components/schemas/routeConstraint' dangerousGoodsConstraint: '#/components/schemas/dangerousGoodsConstraint' numberOfVehiclesConstraint: '#/components/schemas/numberOfVehiclesConstraint' eventOrderConstraint: '#/components/schemas/eventOrderConstraint' sensorValueConstraint: '#/components/schemas/sensorValueConstraint' sensorUpdateFrequencyConstraint: '#/components/schemas/sensorUpdateFrequencyConstraint' startDateTimeConstraint: '#/components/schemas/startDateTimeConstraint' endDateTimeConstraint: '#/components/schemas/endDateTimeConstraint' timeRangeConstraint: '#/components/schemas/timeRangeConstraint' sensorType: type: object description: The type of sensor properties: type: description: The type of sensor 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: 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`. oneOf: - $ref: '#/components/schemas/constraintReference' - $ref: '#/components/schemas/andConstraint' - $ref: '#/components/schemas/notConstraint' - $ref: '#/components/schemas/orConstraint' - $ref: '#/components/schemas/sizeConstraint' - $ref: '#/components/schemas/speedConstraint' - $ref: '#/components/schemas/weightConstraint' - $ref: '#/components/schemas/fuelTypeConstraint' - $ref: '#/components/schemas/vehicleTypeConstraint' - $ref: '#/components/schemas/routeConstraint' - $ref: '#/components/schemas/dangerousGoodsConstraint' - $ref: '#/components/schemas/numberOfVehiclesConstraint' - $ref: '#/components/schemas/eventOrderConstraint' - $ref: '#/components/schemas/sensorValueConstraint' - $ref: '#/components/schemas/sensorUpdateFrequencyConstraint' - $ref: '#/components/schemas/startDateTimeConstraint' - $ref: '#/components/schemas/endDateTimeConstraint' - $ref: '#/components/schemas/timeRangeConstraint' discriminator: propertyName: type mapping: constraintReference: '#/components/schemas/constraintReference' andConstraint: '#/components/schemas/andConstraint' notConstraint: '#/components/schemas/notConstraint' orConstraint: '#/components/schemas/orConstraint' sizeConstraint: '#/components/schemas/sizeConstraint' speedConstraint: '#/components/schemas/speedConstraint' weightConstraint: '#/components/schemas/weightConstraint' fuelTypeConstraint: '#/components/schemas/fuelTypeConstraint' vehicleTypeConstraint: '#/components/schemas/vehicleTypeConstraint' routeConstraint: '#/components/schemas/routeConstraint' dangerousGoodsConstraint: '#/components/schemas/dangerousGoodsConstraint' numberOfVehiclesConstraint: '#/components/schemas/numberOfVehiclesConstraint' eventOrderConstraint: '#/components/schemas/eventOrderConstraint' sensorValueConstraint: '#/components/schemas/sensorValueConstraint' sensorUpdateFrequencyConstraint: '#/components/schemas/sensorUpdateFrequencyConstraint' startDateTimeConstraint: '#/components/schemas/startDateTimeConstraint' endDateTimeConstraint: '#/components/schemas/endDateTimeConstraint' timeRangeConstraint: '#/components/schemas/timeRangeConstraint' 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: 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`. oneOf: - $ref: '#/components/schemas/constraintReference' - $ref: '#/components/schemas/andConstraint' - $ref: '#/components/schemas/notConstraint' - $ref: '#/components/schemas/orConstraint' - $ref: '#/components/schemas/sizeConstraint' - $ref: '#/components/schemas/speedConstraint' - $ref: '#/components/schemas/weightConstraint' - $ref: '#/components/schemas/fuelTypeConstraint' - $ref: '#/components/schemas/vehicleTypeConstraint' - $ref: '#/components/schemas/routeConstraint' - $ref: '#/components/schemas/dangerousGoodsConstraint' - $ref: '#/components/schemas/numberOfVehiclesConstraint' - $ref: '#/components/schemas/eventOrderConstraint' - $ref: '#/components/schemas/sensorValueConstraint' - $ref: '#/components/schemas/sensorUpdateFrequencyConstraint' - $ref: '#/components/schemas/startDateTimeConstraint' - $ref: '#/components/schemas/endDateTimeConstraint' - $ref: '#/components/schemas/timeRangeConstraint' discriminator: propertyName: type mapping: constraintReference: '#/components/schemas/constraintReference' andConstraint: '#/components/schemas/andConstraint' notConstraint: '#/components/schemas/notConstraint' orConstraint: '#/components/schemas/orConstraint' sizeConstraint: '#/components/schemas/sizeConstraint' speedConstraint: '#/components/schemas/speedConstraint' weightConstraint: '#/components/schemas/weightConstraint' fuelTypeConstraint: '#/components/schemas/fuelTypeConstraint' vehicleTypeConstraint: '#/components/schemas/vehicleTypeConstraint' routeConstraint: '#/components/schemas/routeConstraint' dangerousGoodsConstraint: '#/components/schemas/dangerousGoodsConstraint' numberOfVehiclesConstraint: '#/components/schemas/numberOfVehiclesConstraint' eventOrderConstraint: '#/components/schemas/eventOrderConstraint' sensorValueConstraint: '#/components/schemas/sensorValueConstraint' sensorUpdateFrequencyConstraint: '#/components/schemas/sensorUpdateFrequencyConstraint' startDateTimeConstraint: '#/components/schemas/startDateTimeConstraint' endDateTimeConstraint: '#/components/schemas/endDateTimeConstraint' timeRangeConstraint: '#/components/schemas/timeRangeConstraint' 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: oneOf: - $ref: '#/components/schemas/openLRGeoReference' - $ref: '#/components/schemas/tmcArrayGeoReference' - $ref: '#/components/schemas/latLongArrayGeoReference' - $ref: '#/components/schemas/geoJSONLineString' - $ref: '#/components/schemas/geoJSONMultiLineString' - $ref: '#/components/schemas/geoJSONMultiPoint' discriminator: propertyName: type mapping: openLRGeoReference: '#/components/schemas/openLRGeoReference' tmcArrayGeoReference: '#/components/schemas/tmcArrayGeoReference' latLongArrayGeoReference: '#/components/schemas/latLongArrayGeoReference' geoJSONLineString: '#/components/schemas/geoJSONLineString' geoJSONMultiLineString: '#/components/schemas/geoJSONMultiLineString' geoJSONMultiPoint: '#/components/schemas/geoJSONMultiPoint' required: - geoReferences bundle: type: object description: Bundle properties: meta: $ref: '#/components/schemas/bundle_meta' entities: description: | An array of OTM entities. type: array items: type: object oneOf: - $ref: '#/components/schemas/vehicleEntity' - $ref: '#/components/schemas/locationEntity' - $ref: '#/components/schemas/tripEntity' - $ref: '#/components/schemas/routeEntity' - $ref: '#/components/schemas/shipmentEntity' - $ref: '#/components/schemas/actorEntity' - $ref: '#/components/schemas/constraintEntity' - $ref: '#/components/schemas/sensorEntity' discriminator: propertyName: entityType mapping: vehicle: '#/components/schemas/vehicleEntity' location: '#/components/schemas/locationEntity' trip: '#/components/schemas/tripEntity' route: '#/components/schemas/routeEntity' shipment: '#/components/schemas/shipmentEntity' actor: '#/components/schemas/actorEntity' constraint: '#/components/schemas/constraintEntity' sensor: '#/components/schemas/sensorEntity' 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: type: object oneOf: - $ref: '#/components/schemas/locationUpdateEvent' - $ref: '#/components/schemas/sensorUpdateEvent' - $ref: '#/components/schemas/startEngineEvent' - $ref: '#/components/schemas/stopEngineEvent' - $ref: '#/components/schemas/restrictionWarningEvent' - $ref: '#/components/schemas/constraintViolationEvent' - $ref: '#/components/schemas/trafficWarningEvent' - $ref: '#/components/schemas/startMovingEvent' - $ref: '#/components/schemas/stopMovingEvent' - $ref: '#/components/schemas/startWaitingEvent' - $ref: '#/components/schemas/stopWaitingEvent' - $ref: '#/components/schemas/startLoadingAndUnloadingEvent' - $ref: '#/components/schemas/stopLoadingAndUnloadingEvent' - $ref: '#/components/schemas/pickupTimeWindowStartEvent' - $ref: '#/components/schemas/pickupTimeWindowEndEvent' - $ref: '#/components/schemas/deliveryTimeWindowStartEvent' - $ref: '#/components/schemas/deliveryTimeWindowEndEvent' - $ref: '#/components/schemas/coupleVehiclesEvent' - $ref: '#/components/schemas/decoupleVehiclesEvent' - $ref: '#/components/schemas/assignToTripEvent' - $ref: '#/components/schemas/deassignFromTripEvent' - $ref: '#/components/schemas/assignDriverEvent' - $ref: '#/components/schemas/deassignDriverEvent' - $ref: '#/components/schemas/associateWithActorEvent' - $ref: '#/components/schemas/dissociateFromActorEvent' - $ref: '#/components/schemas/loadShipmentEvent' - $ref: '#/components/schemas/unloadShipmentEvent' - $ref: '#/components/schemas/receiveShipmentEvent' - $ref: '#/components/schemas/releaseShipmentEvent' - $ref: '#/components/schemas/linkTripsEvent' - $ref: '#/components/schemas/coupleSensorEvent' - $ref: '#/components/schemas/decoupleSensorEvent' - $ref: '#/components/schemas/cancelEvent' - $ref: '#/components/schemas/cancelAllEntityEvents' - $ref: '#/components/schemas/cancelGroupedEvents' - $ref: '#/components/schemas/ignoreEvent' discriminator: propertyName: type mapping: sensorUpdateEvent: '#/components/schemas/locationUpdateEvent' startEngineEvent: '#/components/schemas/sensorUpdateEvent' stopEngineEvent: '#/components/schemas/startEngineEvent' restrictionWarningEvent: '#/components/schemas/stopEngineEvent' constraintViolationEvent: '#/components/schemas/restrictionWarningEvent' trafficWarningEvent: '#/components/schemas/constraintViolationEvent' startMovingEvent: '#/components/schemas/trafficWarningEvent' stopMovingEvent: '#/components/schemas/startMovingEvent' startWaitingEvent: '#/components/schemas/stopMovingEvent' stopWaitingEvent: '#/components/schemas/startWaitingEvent' startLoadingAndUnloadingEvent: '#/components/schemas/stopWaitingEvent' stopLoadingAndUnloadingEvent: '#/components/schemas/startLoadingAndUnloadingEvent' pickupTimeWindowStartEvent: '#/components/schemas/stopLoadingAndUnloadingEvent' pickupTimeWindowEndEvent: '#/components/schemas/pickupTimeWindowStartEvent' deliveryTimeWindowStartEvent: '#/components/schemas/pickupTimeWindowEndEvent' deliveryTimeWindowEndEvent: '#/components/schemas/deliveryTimeWindowStartEvent' coupleVehiclesEvent: '#/components/schemas/deliveryTimeWindowEndEvent' decoupleVehiclesEvent: '#/components/schemas/coupleVehiclesEvent' assignToTripEvent: '#/components/schemas/decoupleVehiclesEvent' deassignFromTripEvent: '#/components/schemas/assignToTripEvent' assignDriverEvent: '#/components/schemas/deassignFromTripEvent' deassignDriverEvent: '#/components/schemas/assignDriverEvent' associateWithActorEvent: '#/components/schemas/deassignDriverEvent' dissociateFromActorEvent: '#/components/schemas/associateWithActorEvent' loadShipmentEvent: '#/components/schemas/dissociateFromActorEvent' unloadShipmentEvent: '#/components/schemas/loadShipmentEvent' receiveShipmentEvent: '#/components/schemas/unloadShipmentEvent' releaseShipmentEvent: '#/components/schemas/receiveShipmentEvent' linkTripsEvent: '#/components/schemas/releaseShipmentEvent' coupleSensorEvent: '#/components/schemas/linkTripsEvent' decoupleSensorEvent: '#/components/schemas/coupleSensorEvent' cancelEvent: '#/components/schemas/decoupleSensorEvent' cancelAllEntityEvents: '#/components/schemas/cancelEvent' cancelGroupedEvents: '#/components/schemas/cancelAllEntityEvents' ignoreEvent: '#/components/schemas/cancelGroupedEvents' 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 bundled_entity: 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 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/bundled_entity' - $ref: '#/components/schemas/sensor' vehicleEntity: type: object allOf: - $ref: '#/components/schemas/bundled_entity' - $ref: '#/components/schemas/vehicle' locationEntity: type: object allOf: - $ref: '#/components/schemas/bundled_entity' - $ref: '#/components/schemas/location' tripEntity: type: object allOf: - $ref: '#/components/schemas/bundled_entity' - $ref: '#/components/schemas/trip' routeEntity: type: object allOf: - $ref: '#/components/schemas/bundled_entity' - $ref: '#/components/schemas/route' shipmentEntity: type: object allOf: - $ref: '#/components/schemas/bundled_entity' - $ref: '#/components/schemas/shipment' actorEntity: type: object allOf: - $ref: '#/components/schemas/bundled_entity' - $ref: '#/components/schemas/actor' constraintEntity: type: object allOf: - $ref: '#/components/schemas/bundled_entity' - $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: 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`. oneOf: - $ref: '#/components/schemas/constraintReference' - $ref: '#/components/schemas/andConstraint' - $ref: '#/components/schemas/notConstraint' - $ref: '#/components/schemas/orConstraint' - $ref: '#/components/schemas/sizeConstraint' - $ref: '#/components/schemas/speedConstraint' - $ref: '#/components/schemas/weightConstraint' - $ref: '#/components/schemas/fuelTypeConstraint' - $ref: '#/components/schemas/vehicleTypeConstraint' - $ref: '#/components/schemas/routeConstraint' - $ref: '#/components/schemas/dangerousGoodsConstraint' - $ref: '#/components/schemas/numberOfVehiclesConstraint' - $ref: '#/components/schemas/eventOrderConstraint' - $ref: '#/components/schemas/sensorValueConstraint' - $ref: '#/components/schemas/sensorUpdateFrequencyConstraint' - $ref: '#/components/schemas/startDateTimeConstraint' - $ref: '#/components/schemas/endDateTimeConstraint' - $ref: '#/components/schemas/timeRangeConstraint' discriminator: propertyName: type mapping: constraintReference: '#/components/schemas/constraintReference' andConstraint: '#/components/schemas/andConstraint' notConstraint: '#/components/schemas/notConstraint' orConstraint: '#/components/schemas/orConstraint' sizeConstraint: '#/components/schemas/sizeConstraint' speedConstraint: '#/components/schemas/speedConstraint' weightConstraint: '#/components/schemas/weightConstraint' fuelTypeConstraint: '#/components/schemas/fuelTypeConstraint' vehicleTypeConstraint: '#/components/schemas/vehicleTypeConstraint' routeConstraint: '#/components/schemas/routeConstraint' dangerousGoodsConstraint: '#/components/schemas/dangerousGoodsConstraint' numberOfVehiclesConstraint: '#/components/schemas/numberOfVehiclesConstraint' eventOrderConstraint: '#/components/schemas/eventOrderConstraint' sensorValueConstraint: '#/components/schemas/sensorValueConstraint' sensorUpdateFrequencyConstraint: '#/components/schemas/sensorUpdateFrequencyConstraint' startDateTimeConstraint: '#/components/schemas/startDateTimeConstraint' endDateTimeConstraint: '#/components/schemas/endDateTimeConstraint' timeRangeConstraint: '#/components/schemas/timeRangeConstraint' 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