swagger: "2.0" 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). # 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.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` life cycle 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: "4.1.2" # the domain of the service # host: api.opentripmodel.org #commented out so we can deploy to other hosts. # array of all schemes that your API supports schemes: - http - https basePath: /api/public/v4 produces: - application/json - application/xml consumes: - application/json - application/xml 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. The table below shows which event types are applicable to which entities in the OpenTripModel. | event type | Location | Vehicle | Shipment | Trip | Route | Actor | life cycle | description | ------------------------------: | :------: | :-----: | :------: | :---: | :---: | :---: | --------------- | ----------- | updateEvent | ● | ● | ● | ● | ● | ● | `PPAR` |   | locationUpdateEvent | | ● | | | | | `__AR` | Updates the location of a `Vehicle` | startMovingEvent | | ● | | | | | `PPAR` | Marks the moment a `Vehicle` starts moving after standing still for a while. | stopMovingEvent | | ● | | | | | `PPAR` | Marks the moment a `Vehicle` starts standing still after moving for a while. | startWaitingEvent | | ● | | | | | `PPAR` |   | stopWaitingEvent | | ● | | | | | `PPAR` |   | startLoadingAndUnloadingEvent | | ● | | | | | `PPAR` | Marks the start of a time period meant for loading and unloading. Mainly useful in `planned` and `projected` life cycle phases. | stopLoadingAndUnloadingEvent | | ● | | | | | `PPAR` | Marks the end of a time period meant for loading and unloading. Mainly useful in `planned` and `projected` life cycle phases. | startEngineEvent | | ● | | | | | `__AR` | The engine of a `Vehicle` is started. | stopEngineEvent | | ● | | | | | `__AR` | The engine of a `Vehicle` is stopped. | coupleVehiclesEvent | | ● | | | | | `PPAR` | Marks the moment two `Vehicle`s are coupled. | decoupleVehiclesEvent | | ● | | | | | `PPAR` | Marks the moment two `Vehicle`s are decoupled. | assignToTripEvent | | ● | | ● | | | `PPAR` | Assigns a `Vehicle` to a `Trip`. | deassignFromTripEvent | | ● | | ● | | | `PPAR` | Deassigns a `Vehicle` from a `Trip`. | assignDriverEvent | | ● | | | | ● | `PPAR` | Assigns an `Actor` as a driver to a `Trip`. | deassignDriverEvent | | ● | | | | ● | `PPAR` | Deassigns an `Actor` as a driver from a `Trip`. | sensorUpdateEvent | | ● | | | | | `__AR` | Event to send an updated value of a sensor of the `Vehicle`. Can be used e.g. to monitor temperature inside a trailer. | loadShipmentEvent | | ● | ● | | | | `PPAR` | Load a `Shipment` in a `Vehicle` | unloadShipmentEvent | | ● | ● | | | | `PPAR` | Unload a `Shipment` from a `Vehicle` | receiveShipmentEvent | ● | | ● | | | | `PPAR` | Receive a `Shipment` on a `Location` | releaseShipmentEvent | ● | | ● | | | | `PPAR` | Release a `Shipment` from a `Location` | restrictionWarningEvent | ● | | | ● | ● | | `PPAR` | A warning event that may be sent when a restriction is violated. | trafficWarningEvent | ● | | | | ● | | `PPAR` | A warning event that may be sent to warn about a traffic condition on a `Location` or a `Route`. | linkTripsEvent | | | | ● | | | `PPAR` | Event to be used to link two `Trip`s together. | pickupTimeWindowStartEvent | | | ● | | | | `PP__` | Marks the start of a time window for the pickup of a `Shipment`. Only applicable in `planned` or `projected` life cycle phases. | pickupTimeWindowEndEvent | | | ● | | | | `PP__` | Marks the end of a time window for the pickup of a `Shipment`. Only applicable in `planned` or `projected` life cycle phases. | deliveryTimeWindowStartEvent | | | ● | | | | `PP__` | Marks the start of a time window for the delivery of a `Shipment`. Only applicable in `planned` or `projected` life cycle phases. | deliveryTimeWindowEndEvent | | | ● | | | | `PP__` | Marks the end of a time window for the delivery of a `Shipment`. Only applicable in `planned` or `projected` life cycle phases. | constraintViolationEvent | ● | | ● | ● | | | `PPAR` | Can be generated if a constraint is violated. | cancelEvent | ● | ● | ● | ● | ● | ● | `__AR` | Cancel one or more `Event`. To be canceled event(s) should be set as `involvedObject(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. | ignoreEvent | ● | ● | ● | ● | ● | ● | `__AR` | Ignore one or more `Event`. To be ignored event(s) should be set as `involvedObject(s)`. | associateWithActorEvent | ● | ● | ● | ● | ● | ● | `_PAR` | Associate an entity with an `Actor`. - 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: 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 - name: Bundle operations tags: - Bundle - name: Event-related operations tags: - Event paths: /locations: get: summary: Get a list of Locations description: Get a list of `Locations`, optionally filtered by query parameters tags: - Location produces: - application/json - application/xml parameters: - $ref: "#/parameters/nameParam" - $ref: "#/parameters/externalIdSchemaParam" - $ref: "#/parameters/externalIdValueParam" - $ref: "#/parameters/actorQueryParam" - $ref: "#/parameters/roleQueryParam" responses: 200: description: | A list of all defined `Locations`, optionally filtered by query parameters. schema: type: array items: $ref: "#/definitions/location" 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } put: summary: Create a new Location description: Create a `Location` object with the given data. tags: - Location consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/locationParam" 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. schema: { $ref: "#/definitions/location" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 409: { $ref: "#/responses/conflict" } 500: { $ref: "#/responses/internalServerError" } /locations/{uuid}: get: summary: Get a specific Location by its UUID description: Retrieves a single `Location` object by its unique identifier (UUID) tags: - Location produces: - application/json - application/xml parameters: - $ref: "#/parameters/uuidParam" responses: 200: description: A `Location` object schema: { $ref: "#/definitions/location" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/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 consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/uuidParam" - $ref: "#/parameters/locationParam" responses: 200: description: The `Location` object with updated values. schema: { $ref: "#/definitions/location" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } /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 - Event produces: - application/json - application/xml parameters: - $ref: "#/parameters/lifecycle" - $ref: "#/parameters/uuidParam" responses: 200: description: A list of `Events` for the given `Location`. schema: type: array items: $ref: "#/definitions/event" 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } put: summary: Publish a new Event for the given Location description: Publish a new `Event` for the given `Location` tags: - Event - Location consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/lifecycle" - $ref: "#/parameters/uuidParam" - $ref: "#/parameters/eventParam" 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. schema: { $ref: "#/definitions/event" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } /trips: get: summary: Get a list of Trips description: Retrieves a list of all `Trips`, optionally filtered by query parameters. tags: - Trip produces: - application/json - application/xml parameters: - $ref: "#/parameters/nameParam" - $ref: "#/parameters/actorQueryParam" - $ref: "#/parameters/externalIdSchemaParam" - $ref: "#/parameters/externalIdValueParam" responses: 200: description: A list of trips, optionally filtered by query parameters. schema: type: array items: $ref: "#/definitions/trip" 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } put: summary: Create a new Trip description: Create a `Trip` object with the given data. tags: - Trip consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/tripParam" 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. schema: { $ref: "#/definitions/trip" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 409: { $ref: "#/responses/conflict" } 500: { $ref: "#/responses/internalServerError" } /trips/{uuid}: get: summary: Get a specific Trip by its UUID description: Retrieves a `Trip` object by its unique identifier (UUID) tags: - Trip produces: - application/json - application/xml parameters: - $ref: "#/parameters/uuidParam" responses: 200: description: A `Trip` object schema: { $ref: "#/definitions/trip" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/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 consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/uuidParam" - $ref: "#/parameters/tripParam" responses: 200: description: The updated trip object. schema: { $ref: "#/definitions/trip" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } /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 - Event produces: - application/json - application/xml parameters: - $ref: "#/parameters/lifecycle" - $ref: "#/parameters/uuidParam" - $ref: "#/parameters/eventTypeParam" responses: 200: description: A list of Events for the given trip schema: type: array items: $ref: "#/definitions/event" 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/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: - Event - Trip consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/lifecycle" - $ref: "#/parameters/uuidParam" - $ref: "#/parameters/eventParam" 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. schema: { $ref: "#/definitions/event" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } /routes: get: summary: Get a list of Routes description: Retrieves a list of all `Routes`, optionally filtered by query parameters. tags: - Route parameters: - $ref: "#/parameters/actorQueryParam" - $ref: "#/parameters/externalIdSchemaParam" - $ref: "#/parameters/externalIdValueParam" produces: - application/json - application/xml responses: 200: description: A list of `Routes`, optionally filtered by query parameters. schema: type: array items: $ref: "#/definitions/route" 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } put: summary: Create a new Route description: Create a new `Route` object tags: - Route consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/routeParam" responses: 201: description: The created `Route` object. Containes the generated UUID that can be used to refer to this `Route` in later requests. schema: { $ref: "#/definitions/route" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 409: { $ref: "#/responses/conflict" } 500: { $ref: "#/responses/internalServerError" } /routes/{uuid}: get: summary: Get a specific Route by its UUID description: Retrieves a `Route` object by its unique identifier (UUID) tags: - Route produces: - application/json - application/xml parameters: - $ref: "#/parameters/uuidParam" responses: 200: description: A `Route` object schema: { $ref: "#/definitions/route" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/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 consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/uuidParam" - $ref: "#/parameters/routeParam" responses: 200: description: The updated `Route` object schema: { $ref: "#/definitions/route" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } /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 - Event produces: - application/json - application/xml parameters: - $ref: "#/parameters/lifecycle" - $ref: "#/parameters/uuidParam" - $ref: "#/parameters/startDateTimeParam" - $ref: "#/parameters/endDateTimeParam" - $ref: "#/parameters/eventTypeParam" responses: 200: description: A list of `Events` for the given `Trip`, optionally filtered according to the request parameters. schema: type: array items: $ref: "#/definitions/event" 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } put: summary: Publish a new Event on a Route description: Publish a new `Event` for the given `Route`. tags: - Event - Route consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/lifecycle" - $ref: "#/parameters/uuidParam" - $ref: "#/parameters/eventParam" 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. schema: { $ref: "#/definitions/event" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } /vehicles: get: summary: Get a list of Vehicles description: Retrieves a list of `Vehicle` objects, optionally filtered by query parameters. tags: - Vehicle produces: - application/json - application/xml parameters: - $ref: "#/parameters/nameParam" - $ref: "#/parameters/externalIdSchemaParam" - $ref: "#/parameters/externalIdValueParam" - $ref: "#/parameters/actorQueryParam" - $ref: "#/parameters/roleQueryParam" responses: 200: description: A list of `Vehicles`, optionally filtered by query parameters. schema: type: array items: $ref: "#/definitions/vehicle" 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } put: summary: Create a new Vehicle description: Create a new `Vehicle` object tags: - Vehicle consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/vehicleParam" responses: 201: description: The created `Vehicle` object. Containes the generated UUID that can be used to refer to this `Vehicle` in later requests. schema: { $ref: "#/definitions/vehicle" } examples: application/json: { "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" } } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 409: { $ref: "#/responses/conflict" } 500: { $ref: "#/responses/internalServerError" } /vehicles/{uuid}: get: summary: Get a Vehicle by its UUID description: Retrieves a specific `Vehicle` object by its unique identifier (UUID) tags: - Vehicle produces: - application/json - application/xml parameters: - $ref: "#/parameters/uuidParam" responses: 200: description: A `Vehicle` object schema: { $ref: "#/definitions/vehicle" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/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 consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/uuidParam" - $ref: "#/parameters/vehicleParam" responses: 200: description: The updated vehicle object. schema: { $ref: "#/definitions/vehicle" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } /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 - Event produces: - application/json - application/xml parameters: - $ref: "#/parameters/lifecycle" - $ref: "#/parameters/uuidParam" responses: 200: description: A list of `Events` for the given `Vehicle` schema: type: array items: $ref: "#/definitions/event" 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } put: summary: Publish an Event for a Vehicle description: Publish a new `Event` for the given `Vehicle`. tags: - Event - Vehicle consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/lifecycle" - $ref: "#/parameters/uuidParam" - $ref: "#/parameters/eventParam" responses: 201: description: The created `Event` object. Containes the generated UUID that can be used to refer to this `Event` in later requests. schema: { $ref: "#/definitions/event" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } /shipments: get: summary: Get a list of Shipments description: Retrieves a list of `Shipment` objects, optionally filtered by query parameters. tags: - Shipment produces: - application/json - application/xml parameters: - $ref: "#/parameters/nameParam" - $ref: "#/parameters/externalIdSchemaParam" - $ref: "#/parameters/externalIdValueParam" - $ref: "#/parameters/actorQueryParam" - $ref: "#/parameters/roleQueryParam" responses: 200: description: A list of `Shipments`, optionally filtered by query parameters. schema: type: array items: $ref: "#/definitions/shipment" 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } put: summary: Create a new Shipment description: Create a new `Shipment` object tags: - Shipment consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/shipmentParam" responses: 201: description: The created `Shipment` object. Containes the generated UUID that can be used to refer to this `Shipment` in later requests. schema: { $ref: "#/definitions/shipment" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 409: { $ref: "#/responses/conflict" } 500: { $ref: "#/responses/internalServerError" } /shipments/{uuid}: get: summary: Get Shipment by UUID description: Retrieves a `Shipment` object by its unique identifier (UUID) tags: - Shipment produces: - application/json - application/xml parameters: - $ref: "#/parameters/uuidParam" responses: 200: description: A `Shipment` object schema: { $ref: "#/definitions/shipment" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/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 consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/uuidParam" - $ref: "#/parameters/shipmentParam" responses: 200: description: The updated `Shipment` object. schema: { $ref: "#/definitions/shipment" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } /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 - Event produces: - application/json - application/xml parameters: - $ref: "#/parameters/lifecycle" - $ref: "#/parameters/uuidParam" responses: 200: description: A list of `Events` for the given `Shipment` schema: type: array items: $ref: "#/definitions/event" 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } put: summary: Publish a new Event on a Shipment description: Publish a new `Event` for the given `Shipment` tags: - Event - Shipment consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/lifecycle" - $ref: "#/parameters/uuidParam" - $ref: "#/parameters/eventParam" responses: 201: description: The created `Event` object. Containes the generated UUID that can be used to refer to this `Event` in later requests. schema: { $ref: "#/definitions/event" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } /actors: get: summary: Get a list of Actors description: Retrieves all known `Actors`, optionally filtered by query parameters. tags: - Actor produces: - application/json - application/xml parameters: - $ref: "#/parameters/nameParam" - $ref: "#/parameters/externalIdSchemaParam" - $ref: "#/parameters/externalIdValueParam" responses: 200: description: A list of `Actors`, optionally filtered by query parameters. schema: type: array items: $ref: "#/definitions/actor" 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } put: summary: Create a new Actor description: Create a new `Actor` object tags: - Actor consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/actorParam" responses: 201: description: | The created `Actor` object. Contains the generated UUID that can be used to refer to this `Actor` in later requests. schema: { $ref: "#/definitions/actor" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 409: { $ref: "#/responses/conflict" } 500: { $ref: "#/responses/internalServerError" } /actors/{uuid}: get: summary: Get a specific Actor by its UUID description: Retrieves a `Actor` object by its unique identifier (UUID) tags: - Actor produces: - application/json - application/xml parameters: - $ref: "#/parameters/uuidParam" responses: 200: description: An `Actor` object schema: { $ref: "#/definitions/actor" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/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 consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/uuidParam" - $ref: "#/parameters/actorParam" responses: 200: description: The updated `Actor` object. schema: { $ref: "#/definitions/actor" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } /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 - Event produces: - application/json - application/xml parameters: - $ref: "#/parameters/lifecycle" - $ref: "#/parameters/uuidParam" responses: 200: description: A list of `Events` for the given `Actor` schema: type: array items: $ref: "#/definitions/event" 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/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: - Event - Actor consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/lifecycle" - $ref: "#/parameters/uuidParam" - $ref: "#/parameters/eventParam" responses: 201: description: The created `Event` object. Containes the generated UUID that can be used to refer to this `Event` in later requests. schema: { $ref: "#/definitions/event" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } /constraints: get: summary: Get a list of Constraints description: Retrieves all known `Constraints`, optionally filtered by (part of the) name. tags: - Constraint produces: - application/json - application/xml parameters: - $ref: "#/parameters/nameParam" responses: 200: description: A list of `Constraints` schema: type: array items: $ref: "#/definitions/constraint" 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } put: summary: Create a new Constraint description: Create a new per-defined `Constraint` object, that can be referenced to in objects that have a `constraint` member. tags: - Constraint consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/constraintParam" responses: 201: description: | The created `Constraint` object. Contains the generated UUID that can be used to refer to this `Constraint` in later requests. schema: { $ref: "#/definitions/constraint" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 409: { $ref: "#/responses/conflict" } 500: { $ref: "#/responses/internalServerError" } /constraints/{uuid}: get: summary: Get a Constraint by its UUID description: Retrieves a specific `Constraint` object by its unique identifier (UUID) tags: - Constraint produces: - application/json - application/xml parameters: - $ref: "#/parameters/uuidParam" responses: 200: description: A `Constraint` object schema: { $ref: "#/definitions/constraint" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/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 consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/uuidParam" - $ref: "#/parameters/constraintParam" responses: 200: description: The updated `Constraint` object. schema: { $ref: "#/definitions/constraint" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } /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 - Event produces: - application/json - application/xml parameters: - $ref: "#/parameters/lifecycle" - $ref: "#/parameters/uuidParam" responses: 200: description: A list of `Events` for the given `Constraint` schema: type: array items: $ref: "#/definitions/event" 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } put: summary: Publish a new Event on a Constraint description: Publish a new `Event` for the `Constraint` with the given UUID tags: - Event - Constraint consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/lifecycle" - $ref: "#/parameters/uuidParam" - $ref: "#/parameters/eventParam" responses: 201: description: The created `Event` object. Containes the generated UUID that can be used to refer to this `Event` in later requests. schema: { $ref: "#/definitions/event" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 500: { $ref: "#/responses/internalServerError" } /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 sees 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 consumes: - application/json - application/xml produces: - application/json - application/xml parameters: - $ref: "#/parameters/bundleParam" responses: 201: description: | The original `Bundle`, with added generated UUIDs that can be used to refer to the generated Entities in later requests. schema: { $ref: "#/definitions/bundle" } 400: { $ref: "#/responses/badRequest" } 401: { $ref: "#/responses/unauthorized" } 403: { $ref: "#/responses/forbidden" } 404: { $ref: "#/responses/notFound" } 409: { $ref: "#/responses/conflict" } 500: { $ref: "#/responses/internalServerError" } parameters: lifecycle: name: lifecycle in: path type: string enum: - planned - projected - actual - realized required: true description: The lifecycle phase the request applies to eventParam: name: eventParam in: body schema: { $ref: "#/definitions/event" } required: true description: JSON object describing an `Event` tripParam: name: tripParam in: body schema: { $ref: "#/definitions/trip" } required: true description: JSON object describing a `Trip` locationParam: name: locationParam in: body schema: { $ref: "#/definitions/location" } required: true description: JSON object describing a `Location`. routeParam: name: routeParam in: body schema: { $ref: "#/definitions/route" } required: true description: JSON object describing a `Route`. vehicleParam: name: vehicleParam in: body schema: { $ref: "#/definitions/vehicle" } required: true description: JSON object describing a `Vehicle`. shipmentParam: name: shipmentParam in: body schema: { $ref: "#/definitions/shipment" } required: true description: JSON object describing a `Shipment`. actorParam: name: actorParam in: body schema: { $ref: "#/definitions/actor" } required: true description: JSON object describing an `Actor`. constraintParam: name: constraintParam in: body schema: { $ref: "#/definitions/constraint" } required: true description: JSON object describing a `Constraint`. bundleParam: name: bundleParam in: body schema: { $ref: "#/definitions/bundle" } required: true description: JSON object describing a `Bundle`. uuidParam: name: uuid in: path type: string required: true description: A uuid, identifying some pre-defined entity. nameParam: name: name in: query type: string required: false description: A name or a part of a name, to search entities by their name. externalIdSchemaParam: name: externalIdSchema in: query type: string 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 `externalIdSchema` query parameter to limit the number of results further. externalIdValueParam: name: externalIdValue in: query type: string required: false description: | An external ID value, a part of it, to search for entities by their external IDs. This parameter should be combined with the `externalIdSchema` parameter. startDateTimeParam: name: startDateTime in: query type: string format: date-time 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. endDateTimeParam: name: endDateTime in: query type: string format: date-time 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. eventTypeParam: name: eventType in: query type: string format: comma-separated description: | Comma-separated list of event types. The resulting list will only have events of the given types, events of other types will be ommitted. required: false actorQueryParam: name: actor in: query type: string format: uuid description: | Filter the query by Actor. Only objects that are associated to the `Actor` identified by the given UUID will be shown. required: false roleQueryParam: name: role in: query type: string 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 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. - wheb `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. schema: type: string description: error message example: The body of the request could not be parsed. unauthorized: description: Authentication credentials were missing or incorrect. 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. 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. 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. schema: type: string description: error message example: An object with the same properties alreayd exists. internalServerError: description: An unexpected server error has occured, which needs further investigation. Please contact support. schema: type: string description: error message example: An unexpected error occured while processing the request. definitions: ####### Actors ####### 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: "#/definitions/idReference" name: type: string description: Name of the `Actor`. For display purposes only. example: My awesome company, Ltd. ####### Locations ####### 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. Used for display, filtering and display. example: "Main warehouse" externalIds: type: array description: An optional array of IDs by which the location may be known in other systems. items: $ref: "#/definitions/idReference" type: $ref: "#/definitions/locationType" geoReference: $ref: "#/definitions/geoReference" administrativeReference: $ref: "#/definitions/administrativeReference" contactDetails: type: array items: $ref: "#/definitions/contactDetail" constraint: $ref: "#/definitions/constraint" remarks: type: string description: Remarks about the location. Please don't misuse this field for external references, use the `externalIds` field instead. example: "The cafe around the corner has the best coffee in town." required: - geoReference locationType: type: object description: The type of location properties: type: type: string enum: - warehouse - store - environmental_zone - restricted_area - customer - other example: "warehouse" other: type: string description: | Name of the location type if `other` is chosen in the `type` field. example: playground example: { "type": "warehouse" } required: - type contactDetail: type: object description: Contact details, such as phone numbers and email addresses. properties: type: type: string enum: - phone - email - other description: Type of contact detail example: "email" value: type: string description: | The contact detail itself. Depending on the `type`, this can be a phone number, email address or some other address to contact a location or person. example: "info@opentripmodel.org" remarks: type: string description: Remarks about the contact detail. example: "Usually doesn't answer his phone the first time" example: { "type": "phone", "value": "+312012345678", "remarks": "private cellphone of the CEO" } required: - type - value geoReference: type: object description: Describes a geographic reference, which can be part of a location or route. properties: type: type: string description: Type of geographic reference example: "openLRGeoReference" discriminator: type required: - type example: { "type": "latLongPointGeoReference", "lat": 52.0838333, "lon": 5.8318803, "speed": { "unit": "km/h", "value": 76 }, "heading": { "unit": "degrees", "value": 143 } } latLongPoint: properties: lat: type: number format: double example: 52.192294 lon: type: number format: double example: 5.410124 required: - lat - lon example: { "lat": 52.0838333, "lon": 5.8318803 } movingInfo: properties: speed: description: | The speed of a moving `Vehicle`. $ref: "#/definitions/valueWithUnit" heading: description: | The heading of a `Vehicle`, that is: the direction the "nose" of the `Vehicle` is pointing to. $ref: "#/definitions/valueWithUnit" bearing: 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: "#/definitions/valueWithUnit" bearingType: description: | Denotes how the bearing is measured. type: string enum: - absolute - relative default: absolute latLongPointGeoReference: allOf: - $ref: "#/definitions/geoReference" - $ref: "#/definitions/latLongPoint" - $ref: "#/definitions/movingInfo" example: { "type": "latLongPointGeoReference", "lat": 52.0838333, "lon": 5.8318803, "speed": { "unit": "km/h", "value": 76 }, "heading": { "unit": "degrees", "value": 143 } } latLongArrayGeoReference: allOf: - $ref: "#/definitions/geoReference" - properties: points: type: array minLength: 1 items: $ref: "#/definitions/latLongPoint" required: - points example: { "type": "latLongArrayGeoReference", "points": [ { "lat": 52.0838333, "lon": 5.8318803 }, { "lat": 52.192294, "lon": 5.410124 }, { "lat": 52.188841, "lon": 5.414857 } ] } point2D: type: array maxItems: 2 minItems: 2 items: type: number format: double example: [ 5.408910512924194, 52.19404109179293 ] geoJSONPoint: type: object description: GeoJSon geometry externalDocs: url: http://geojson.org/geojson-spec.html#id2 allOf: - $ref: "#/definitions/geoReference" - $ref: "#/definitions/movingInfo" - properties: coordinates: $ref: '#/definitions/point2D' required: - coordinates geoJSONLineString: type: object description: GeoJSon geometry externalDocs: url: http://geojson.org/geojson-spec.html#id3 allOf: - $ref: "#/definitions/geoReference" - properties: coordinates: type: array minLength: 1 items: $ref: '#/definitions/point2D' required: - coordinates geoJSONPolygon: type: object description: GeoJSon geometry externalDocs: url: http://geojson.org/geojson-spec.html#id4 allOf: - $ref: "#/definitions/geoReference" - properties: coordinates: type: array items: type: array items: $ref: '#/definitions/point2D' required: - coordinates geoJSONMultiPoint: type: object description: GeoJSon geometry externalDocs: url: http://geojson.org/geojson-spec.html#id5 allOf: - $ref: "#/definitions/geoReference" - properties: coordinates: type: array items: $ref: '#/definitions/point2D' required: - coordinates geoJSONMultiLineString: type: object description: GeoJSon geometry externalDocs: url: http://geojson.org/geojson-spec.html#id6 allOf: - $ref: "#/definitions/geoReference" - properties: coordinates: type: array items: type: array items: $ref: '#/definitions/point2D' required: - coordinates geoJSONMultiPolygon: type: object description: GeoJSon geometry externalDocs: url: http://geojson.org/geojson-spec.html#id6 allOf: - $ref: "#/definitions/geoReference" - properties: coordinates: type: array items: type: array items: type: array items: $ref: '#/definitions/point2D' required: - coordinates openLRGeoReference: allOf: - $ref: "#/definitions/geoReference" - properties: openLRString: type: string format: openLR description: A base64 encoded binary OpenLR string example: CgOkbyUN6COJAwEB/8YjGQ== required: - openLRString example: { "type": "openLRGeoReference", "openLRString": "CgOkbyUN6COJAwEB/8YjGQ==" } tmcPoint: properties: locationCode: description: TMC location code type: string direction: description: TMC direction type: string default: positive enum: - positive - negative tmcLocation: properties: countryCode: description: TMC country code type: string tableId: description: TMC table ID type: string tableVersionId: description: TMC table version ID type: string locationCode: description: TMC location code type: string direction: description: TMC direction type: string default: positive enum: - positive - negative offset: description: Offset from the TMC location in meters type: number format: integer32 default: 0 required: - countryCode - tableId - tableVersionId - locationCode tmcLocationArray: properties: countryCode: description: TMC country code type: string tableId: description: TMC table ID type: string tableVersionId: description: TMC table version ID type: string points: type: array minLength: 1 items: $ref: "#/definitions/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: "#/definitions/geoReference" - $ref: "#/definitions/tmcLocation" - $ref: "#/definitions/movingInfo" tmcArrayGeoReference: allOf: - $ref: "#/definitions/geoReference" - $ref: "#/definitions/tmcLocationArray" addressGeoReference: allOf: - $ref: "#/definitions/geoReference" - $ref: "#/definitions/address" address: type: object properties: street: type: string description: Street of the address. houseNumber: type: string description: Housenumber houseNumberAddition: type: string description: Addition to the houseNumber. postalCode: type: string description: The postal code of the address. city: type: string description: The city of the address country: type: string description: | [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1) country code. example: { "street": "Langestraat", "houseNumber": "3a", "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: "#/definitions/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": "3a", "postalCode": "1234AB", "city": "Amersfoort", "country": "nl" } ####### Constraints ####### 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 refridgerated 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 type: description: | The constraint type. Set the type to `constraintReference` te refer to a predefined top-level constraint. In that case, use the `id` field to refer to the `id` of that predefined constraint. To define a constraint instead of referring to it, choose any of the other types and fill the fields that come with that constraint type. type: string discriminator: type required: - type example: { "type": "andConstraint", "and": [{ "type": "startDateTimeConstraint", "startDateTime": "2017-01-01T00:00:00Z" },{ "type": "endDateTimeConstraint", "endDateTime": "2018-12-31T23:59:59Z" },{ "type": "notConstraint", "not": { "type": "fuelTypeConstraint", "fuelTypes": [{ "type": "diesel", },{ "type": "biodiesel" },{ "type": "other", "other": "liquidGas" } ] } } ] } constraintReference: allOf: - $ref: "#/definitions/constraint" andConstraint: allOf: - $ref: "#/definitions/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: "#/definitions/constraint" orConstraint: allOf: - $ref: "#/definitions/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: "#/definitions/constraint" notConstraint: allOf: - $ref: "#/definitions/constraint" - properties: not: description: | This inverts the given constraint, like a boolean NOT operation. This means the resulting constraint will apply if the underlying constraint would not. $ref: "#/definitions/constraint" startDateTimeConstraint: allOf: - $ref: "#/definitions/constraint" - properties: startDateTime: type: string format: date-time description: This constraint applies from the given start date/time. example: "2012-01-01T00:00:00Z" endDateTimeConstraint: allOf: - $ref: "#/definitions/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: "#/definitions/constraint" - $ref: "#/definitions/dayOfWeekTimeRange" sizeConstraint: allOf: - $ref: "#/definitions/constraint" - properties: sizeConstraintType: description: | The type of size constraint. Available types are: - `maximum`: All sizes below and including the maximum value are allowed. - `minimum`: All sizes above and including the minimum value are allowed. - `range`: All sizes in between and including the minimum and maximum values are allowed. type: string enum: - maximum - minimum - range sizeConstraint: type: string enum: - vehicle-length - vehicle-height - vehicle-width maximum: description: Maximum size allowed $ref: "#/definitions/valueWithUnit" minimum: description: Minimum size allowed $ref: "#/definitions/valueWithUnit" weightConstraint: allOf: - $ref: "#/definitions/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: description: Maximum weight allowed $ref: "#/definitions/valueWithUnit" minimum: description: Minimum weight allowed $ref: "#/definitions/valueWithUnit" speedConstraint: allOf: - $ref: "#/definitions/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: description: Maximum speed allowed $ref: "#/definitions/valueWithUnit" minimum: description: Minimum speed allowed $ref: "#/definitions/valueWithUnit" sensorValueConstraint: allOf: - $ref: "#/definitions/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 sensorName: type: string description: Name of the sensor, for display purpose only. example: "Main temperature sensor" sensorId: $ref: "#/definitions/idReference" maximum: description: Maximum sensor value allowed $ref: "#/definitions/valueWithUnit" minimum: description: Minimum sensor value allowed $ref: "#/definitions/valueWithUnit" fuelTypeConstraint: allOf: - $ref: "#/definitions/constraint" - properties: fuelTypes: description: The fuel types to which this constraint apply. type: array items: $ref: "#/definitions/fuelType" vehicleTypeConstraint: allOf: - $ref: "#/definitions/constraint" - properties: vehicleTypes: description: The vehicle types that this constraint apply to. type: array items: $ref: "#/definitions/vehicleType" routeConstraint: allOf: - $ref: "#/definitions/constraint" - properties: route: $ref: "#/definitions/geoReference" dayOfWeekTimeRange: type: object description: A time range for a specific day of the week, for which the constraint will be applicable. properties: dayOfWeek: type: integer format: int32 minimum: 1 maximum: 7 description: | Day of the week, where - 1 = Monday - 2 = Tuesday - 3 = Wednesday - 4 = Thursday - 5 = Friday - 6 = Saturday - 7 = Sunday example: 1 ranges: type: array minLength: 1 items: $ref: "#/definitions/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 ####### Vehicles ####### 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`, mainly used for display and search purposes. example: "Otto's truck" externalIds: type: array items: $ref: "#/definitions/idReference" vehicleType: $ref: "#/definitions/vehicleType" fuel: $ref: "#/definitions/fuelType" maxLinks: type: integer format: int32 description: | Maximum number of links to other `Vehicle` s. Typical values are 0, 1 or 2. links: type: array readOnly: true description: list of URIs, pointing to vehicles this vehicle is linked to items: type: string format: uri example: https://api.opentripmodel.org/api/public/v4/vehicles/dc47d2b1-4a88-4f3e-a3f9-cb379dee3f1b loadCapacities: type: array items: $ref: "#/definitions/valueWithUnit" length: $ref: "#/definitions/valueWithUnit" height: $ref: "#/definitions/valueWithUnit" width: $ref: "#/definitions/valueWithUnit" emptyWeight: $ref: "#/definitions/valueWithUnit" required: - maxLinks - type vehicleType: type: object description: The type of vehicle properties: type: type: string enum: - boxtruck - tractor - trailer - airplane - deep sea vessel - barge - unknown - other other: type: string description: | Name of the vehcile type if `other` is chosen in the `type` field. example: teletransporter example: { "type": "tractor" } required: - type fuelType: type: object description: | The type of fuel the vehicle runs on. For vehicle without an engine of their own, such as a trailer, you may choose `not-applicable`. For trailers with cooling capabilities, choose the fuel type of the cooling engine. properties: type: type: string enum: - battery - biodiesel - diesel - dieselBatteryHybrid - ethanol - hydrogen - liquidGas - lpg - methane - petrol - petrolBatteryHybrid - notApplicable - unknown - other other: type: string description: | Name of the fuel type if `other` is chosen in the `type` field. example: nuclear-fusion example: { "type": "diesel" } required: - type ####### Shipments ####### 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 externalIds: type: array description: An optional array of IDs by which the location may be known in other systems. items: $ref: "#/definitions/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: "#/definitions/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: "#/definitions/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: "#/definitions/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: "#/definitions/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: $ref: "#/definitions/dimensions" weight: $ref: "#/definitions/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 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: $ref: "#/definitions/constraint" ####### Trips ####### 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 externalIds: type: array description: An optional array of IDs by which the location may be known in other systems. items: $ref: "#/definitions/idReference" name: type: string description: | Name of the `Trip`, only used for display and search purposes. example: "Warehouse to shop" linkedTrips: type: array readOnly: true items: type: string format: uri description: | URI of an endpoint to access trip that is linked to this `Trip`. A linked `Trip` can be a `Trip` that precedes or succeeds this `Trip`. example: https://api.opentripmodel.org/api/public/v4/trips/fce64357-f28b-4de2-a6ac-20f2d0e8d18f 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: $ref: "#/definitions/constraint" ####### Routes ####### 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 externalIds: type: array description: An optional array of IDs by which the location may be known in other systems. items: $ref: "#/definitions/idReference" geoReferences: $ref: "#/definitions/geoReference" required: - geoReferences ####### Bundles ####### bundle: type: object description: Bundle properties: meta: $ref: "#/definitions/bundle_meta" entities: type: array items: $ref: "#/definitions/bundledEntity" events: type: array items: $ref: "#/definitions/event" bundle_meta: type: object description: Meta-information about this bundle. properties: generator: type: string description: Description of the generator of this bundle example: "XYZ Planning software" creationTime: type: string format: date-time description: Date and time this bundle was generated bundledEntity: type: object description: Entity that is part of a `Bundle`. properties: entityType: type: string description: The type of entity. This is needed, since the type cannot be derived from the endpoint in a `Bundle`. enum: - vehicleEntity - locationEntity - tripEntity - routeEntity - shipmentEntity - actorEntity - constraintEntity discriminator: entityType required: - entityType example: { "entityType": "vehicleEntity", "id": "https://api.opentripmodel.org/api/public/v4/vehicles/635f6bd2-2568-45d8-b4e0-312f563b87de", "externalIds": [ { "schema": "https://opentripmodel.org/types/licensePlate/nl", "value": "T-123-AB", } ], "vehicleType": { "type": "tractor" }, "fuel": { "type": "diesel" } } vehicleEntity: type: object allOf: - $ref: "#/definitions/bundledEntity" - $ref: "#/definitions/vehicle" locationEntity: type: object allOf: - $ref: "#/definitions/bundledEntity" - $ref: "#/definitions/location" tripEntity: type: object allOf: - $ref: "#/definitions/bundledEntity" - $ref: "#/definitions/trip" routeEntity: type: object allOf: - $ref: "#/definitions/bundledEntity" - $ref: "#/definitions/route" shipmentEntity: type: object allOf: - $ref: "#/definitions/bundledEntity" - $ref: "#/definitions/shipment" actorEntity: type: object allOf: - $ref: "#/definitions/bundledEntity" - $ref: "#/definitions/actor" constraintEntity: type: object allOf: - $ref: "#/definitions/bundledEntity" - $ref: "#/definitions/constraint" ####### Events ####### 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 lifecyclePhase: $ref: "#/definitions/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. 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` life cycle phase, that typically are calculated. The generation (calculateion) time can be an indicator for the relevance of the event. The `eventGenerationTime` should always be 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. 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" discriminator: type required: - type # This is a work around for a Swagger/Redoc rendering issue, where only "leafs" in a tree of dependent event types are rendered. updateEvent_parent: allOf: - $ref: "#/definitions/event" - properties: location: $ref: "#/definitions/updateEvent_location" updateEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/updateEvent_parent" # This is a work around for a swagger rendering bug. 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: "#/definitions/geoReference" # This is a work around for a Swagger/Redoc rendering issue, where only "leafs" in a tree of dependent event types are rendered. locationUpdateEvent_parent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/updateEvent" required: - location locationUpdateEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/locationUpdateEvent_parent" startMovingEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/locationUpdateEvent_parent" stopMovingEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/locationUpdateEvent_parent" startWaitingEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/updateEvent_parent" stopWaitingEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/updateEvent_parent" startLoadingAndUnloadingEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/locationUpdateEvent_parent" stopLoadingAndUnloadingEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/locationUpdateEvent_parent" startEngineEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/updateEvent_parent" stopEngineEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/updateEvent_parent" coupleVehiclesEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/updateEvent_parent" assignToTripEvent: allOf: - $ref: "#/definitions/event" deassignFromTripEvent: allOf: - $ref: "#/definitions/event" decoupleVehiclesEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/locationUpdateEvent_parent" assignDriverEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/updateEvent_parent" deassignDriverEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/updateEvent_parent" sensorUpdateEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/updateEvent_parent" - properties: sensorId: type: string description: | ID of the sensor, must be unique within the `Vechicle` that is referenced in the `involvedObjects`. sensorValue: $ref: "#/definitions/valueWithUnit" 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: "#/definitions/event" - $ref: "#/definitions/updateEvent_parent" 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: "#/definitions/event" - $ref: "#/definitions/updateEvent_parent" 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: "#/definitions/event" - $ref: "#/definitions/locationUpdateEvent_parent" 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: "#/definitions/event" - $ref: "#/definitions/locationUpdateEvent_parent" restrictionWarningEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/locationUpdateEvent_parent" - properties: warning: type: string #TODO: define warning type description: Restriction warning description required: - warning trafficWarningEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/locationUpdateEvent_parent" - properties: warning: type: string #TODO: define warning type description: Traffic warning description required: - warning linkTripsEvent: allOf: - $ref: "#/definitions/event" pickupTimeWindowStartEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/updateEvent_parent" pickupTimeWindowEndEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/updateEvent_parent" deliveryTimeWindowStartEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/updateEvent_parent" deliveryTimeWindowEndEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/updateEvent_parent" constraintViolationEvent: allOf: - $ref: "#/definitions/event" - $ref: "#/definitions/updateEvent_parent" - properties: violatedConstraint: $ref: "#/definitions/constraint" cancelEvent: allOf: - $ref: "#/definitions/event" ignoreEvent: allOf: - $ref: "#/definitions/event" associateWithActorEvent: allOf: - $ref: "#/definitions/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" ####### Lifecycle phases ####### lifecyclePhase: type: object description: | Lifecycle phase, can be one of "planned", "projected", "actual" or "realized". All entities except `Event` exist in all life cycle phases. The events on an entity differ depending on the lifecycle phase. E.g. a vehicle in the "planned" life cycle 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 life cycle 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" } ####### General ####### valueWithUnit: type: object description: Value with unit properties: unit: type: string description: measurement unit of this value example: "kg" value: type: integer format: int32 description: value in the given unit example: 42 required: - unit - value dimensions: type: object description: Dimensions of an object. properties: width: $ref: "#/definitions/valueWithUnit" height: $ref: "#/definitions/valueWithUnit" length: $ref: "#/definitions/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/`, **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