OTM (v5)

Download OpenAPI specification:Download

Open Trip Model

Changelog

Found any bugs on this page? Or have any feature requests for OTM? Create a new ticket on the OTM5 change requests Github page

Version 5.1 candidate

Note a new version candidate does no promises on what will actually get in that release. It is very likely though that everything comes in unless oversights have been spotted. The changes will be added to the API definition below once made official.

  • 2021-02-02: Add an optional sensors association to vehicle.

Version 5.0 (only documentation changes)

  • 2021-01-15: Add documentation about validation endpoints
  • 2021-01-15: Add reference to the otm5-change-requests github.
  • 2020-12-03: Fix the broken checkbox for actions when choosing the Stop action.
  • 2020-12-03: Document the license plate on a TransportEquipment (i.e. a trailer).

Introduction

In this day and age more and more information about logistics and traffic is shared over the Internet between various parties. To make this communication easier the Open Trip Model specification was created. It is a lightweight data model used to exchange real-time logistic trip data on the web, and to make it easier for shippers, carriers, software vendors, OEMs, and truck manufacturers to create new multi-brand application and services.

So, why use OTM?

After years of working in the domain of logistics and traffic data we have experienced that various parties represent the same type of data differently. This is not unexpected, since every party optimizes for their own use case, but has as a result that custom translation layers need to be made over and over again when these parties want to communicate with each other. This is a costly and time consuming experience. When parties that use the same type of data actually use the same language, you don't have to make these translations layers anymore. This makes the technological landscape simpler and results in less custom-made software.

Instead, it is better to invest in this specification once, with a one-time cost of implementation and specification, creating a better understanding between various parties.

How does OTM5 differ from OTM4?

OTM4 has existed for quite a few years now and has proven to be useful in various use cases when communicating between various parties. However, there are still areas for improvement. The lack of a clear hierarchy provides a lot of flexibility, but also makes it harder than necessary to deal with data that is inherently hierarchical. Therefore OTM5 allows you to both use a normalized approach with decoupled entities, and means to also provide (parts of) the data in a hierarchy.

Concepts

The fundamental idea behind OTM is splitting data into static data (entities) and dynamic data (actions and events) and decouple their interaction. Entities contain data that changes relatively sparingly. Think for instance about consignments, locations, and vehicles. Though properties of these entities might change, this generally occurs quite rarely and is definitely not reflected in real-time. On the other hand, how these static entities interact is more prone to change. For example, a vehicle itself remains the same height, width, and weight over its lifetime, but it can move multiple different goods every single day. Actions are used to model this interaction between entities, and events allow you to easily update them after exchanging information beforehand.

Overview

It all starts with the TransportOrder that contains a sequence of Consignments. A consignment models the need to get various related Goods from one location to another. Note that goods are actual physical entities, whereas transport orders and consignments are administrative ones. Each consignment can be part of one or multiple [Trips](#tag/Trip], where various Constraints can be put in place to ensure consignments are delivered on time, or always abide to a certain temperature during the trip. The transport orders and consignments can be associated with various Actors. Such as the shipper, the carrier, the consignee, consignor, or any legal party that is involved in the logistic operation.

The earlier mentioned trip is an entity that models visiting various Locations using a single Vehicle. Each location that is visited at a certain time is a Stop action on which multiple other actions can occur, such as Loading and Unloading of various Goods. These goods are then (optionally) HandOver from one party (an actor) to the other. If needed you can use a Move action to model a detailed description of how to travel between two locations and which Route to take, or what other actions to take on that route, such as maintenance or adding fuel to the vehicle.

During a trip a Sensor in a vehicle can give LocationUpdateEvents with coordinates of the vehicle or SensorUpdateEvents with sensor values, for example the temperature of the goods, or the speed of the vehicle. After OTM data has been shared, it can be updated using UpdateEvents with the modified data of the entities that needed to be updates. Also entities can be associated and unassociated using the AssociationCreatedEvent and AssociationRemovedEvent. This can be useful to provide or modify information of which vehicle is going to drive which trip.

Associations

Entities, actions and events are decoupled from one another. It is possible to (loosely) couple them using associations. There are three different types of associations:

  • Inline, by creating an entity within another entity directly.
  • By reference through referencing an existing entity by ID.
  • By attribute restriction through a set of restrictions on external attributes.

Thus note that the following is both correct and mean the same thing:

// A stop that is visiting a location by referencing it
{
  "id": "https://simacan.com/v5/stops/acf8b1c9-f5fa-4f55-9f98-fc1e93cbd8b2",
  "location": {
    "associationType": "reference",
    "uuid": "11c11d75-e114-4b5f-9751-b3a4afa23ecf"
  },
  ... // Many more fields
}

// A stop that is visiting a location by creating it inline
{
  "id": "https://simacan.com/v5/stops/acf8b1c9-f5fa-4f55-9f98-fc1e93cbd8b2",
  "location": {
    "associationType": "inline",
    "entity": {
        "id": "https://simacan.com/v5/locations/11c11d75-e114-4b5f-9751-b3a4afa23ecf",
        "type": "warehouse",
        "geoReference": {
          "type": "latLongPointGeoReference",
          "lat": 52.0838333,
          "lon": 5.8318803
        },
        ... // Many more fields
    }
  },
  ...
}

If no location is known and the association is thus unassociated, you can also remove the reference all together:

// A stop that is visiting a location that is still unknown
{
  "id": "https://simacan.com/v5/stops/acf8b1c9-f5fa-4f55-9f98-fc1e93cbd8b2",
  // location is still unknown, so it is not mentioned yet.
}

If the OTM entity id is unknown but we know enough of the attribute values to select the entity we want, it is possible to use an attribute restriction:

{
  "id": "https://simacan.com/v5/stops/acf8b1c9-f5fa-4f55-9f98-fc1e93cbd8b2",
  "location": {
    "associationType": "attributeRestriction",
    "restriction": {
      "externalAttributes" : {
        "customerKey": "1234"
      }
    }
  },
  ... // Many more fields
}

OTM Profiles

As can be seen from the specification, there is no single top-level element in OTM. Depending on the use case your viewpoint might change and some other entity becomes top-level. For instance, for a 'home delivery' operation the trips are the central piece of the puzzle, which each visit multiple locations to deliver goods. However for a track-and-trace operation, the consignments and its contained goods are the central object, which might be part of multiple trips before arriving at its final destination.

This approach makes OTM flexible while remaining quite simple and small. However it also means that parties using OTM might not be able to actually communicate with each other. To counter this, different use cases in OTM make use of so-called OTM profiles which are a stricter set of rules on top of OTM to ensure that specific messages have a clear intent and are unambiguous. The provided rules in a profile show you the hierarchy of the entities, but also come with a stricter set of which fields are required than the official specification. Before parties communicate in OTM they have to determine which profile they are going to abide to.

The various profiles are currently still being discussed and will be thoroughly documented with examples once finalized. See below the first profile, 'transport orders'.

Validating the 'Transport Order profile'

The first profile provided is the transport order profile. This profile is concerned with modeling goods that need to be transported from one location to potentially multiple others. However, it does not include how these goods are going to be transported (in which vehicles/trips). At the bottom of the hierarchy we have goods, physical units with dimensions, weights, etc. that need to be transported. Goods are part of a consignment, which is an administrative unit that groups the goods together. On the top we have the transport order, that is able to group multiple consignments. For example, because they are part of one assignment given by some shipper.

Below follows a description of the rules on top of the OpenAPI specification to adhere to the 'transport order' profile for each of the involved entities. We start of with the Consignment since it is the entity with the most rules.

Consignments

To check whether your messages abide to the profile you can send a consignment to:

PUT https://otm5-documentation-api.services.simacan.com/api/v5/validate/consignments

For example, if you you send invalid JSON (there is a missing curly bracket after the UUID of goods).

    {
        "id":"89d45cf1-f3cd-4f60-98fd-50a4208c6b54",
        "goods":[
          {
            "associationType":"reference",
            "entityType":"goods",
            "uuid":"89d45cf1-f3cd-4f60-98fd-50a4208c6b54"

        ]

      }

You will get the error message as a 400 Bad Request:

[
    "Encountered an error while parsing JSON: expected } or , got ] (line 10, column 245) at index 244"
]

If you send valid JSON, but an invalid OTM you will be notified as well:

{
    "id":"test",
    "random": "message"
}
[
    "An entity id must end with a UUID"
]

Lastly, its possible that you send valid Consignments, but not those that are expected in this profile:

{
  "id":"89d45cf1-f3cd-4f60-98fd-50a4208c6b54",
  "actions":[
    {
      "associationType":"inline",
      "entity":{
        "id":"89d45cf1-f3cd-4f60-98fd-50a4208c6b54",
        "actionType":"unload"
      }
    }
  ]
}

This will return the list of error messages:

{
    "errors": [
        {
            "field": "goods",
            "message": "consignments are expected to contain at least one goods item",
            "type": "missingField"
        },
        {
            "field": "actions",
            "message": "List actions has size 1 but required at least 2",
            "type": "invalidField"
        }
    ]
}

Here is an example of a valid consignment. You can also see the use of inline and reference associations.

{
  "id":"89d45cf1-f3cd-4f60-98fd-50a4208c6b54",
  "goods":[
    {
      "uuid":"89d45cf1-f3cd-4f60-98fd-50a4208c6b54",
      "entityType":"goods",
      "associationType":"reference"
    }
  ],
  "actions":[
    {
      "entity":{
        "id":"89d45cf1-f3cd-4f60-98fd-50a4208c6b54",
        "location":{
          "uuid":"47bd36fa-9f15-4f5d-ab07-6eff4f11b846",
          "entityType":"location",
          "associationType":"reference"
        },
        "actionType":"load"
      },
      "associationType":"inline"
    },
    {
      "entity":{
        "id":"049ffbc8-b561-4b50-b82f-49854c4148da",
        "location":{
          "entity":{
            "id":"1662d54f-2031-4a55-b790-2b7715701640",
            "geoReference":{
              "lat":52.092995,
              "lon":5.1237933,
              "type":"latLonPointGeoReference"
            }
          },
          "associationType":"inline"
        },
        "startTime":"2021-01-17T10:00:00Z",
        "endTime":"2021-01-17T10:15:00Z",
        "actionType":"unload"
      },
      "associationType":"inline"
    }
  ]
}

The rules for consignments are as follows:

  • A consignment needs to have at least one goods to be transported.
  • A consignment should at least have one load action and one unload action.
  • Every load and unload actions needs to have a location.

TransportOrders

To check whether your messages abide to the profile you can send a transport order to:

PUT https://otm5-documentation-api.services.simacan.com/api/v5/validate/transportOrders

The error message systems works the same as for the consignments. There is only on rule for transport orders, which is that there needs to be at least one consignment.

Goods

Goods have many optional fields, and there none that are required for the transport order profile. So, as long as you send a valid Goods according to the specification below it will be accepted.

PUT https://otm5-documentation-api.services.simacan.com/api/v5/validate/goods

External attributes

ExternalAttributes are a data type that can be used to communicate data between parties that is not inherently part of OTM. This allows you to extend the data present in OTM without the need to change the specification. This usually will be administrative, or company-specific data. Note though, that if something can be modeled using just OTM entities it should be done that way.

External attributes are nothing more than a list of key-values. This is an example of what it could look like:

{
  "billedKilometers": "30km",
  "pricePerKilometer": "€0.50"
  "tags": [ "you", "can", "also", "provide", "a", "list", "of", "strings" ]
}

Lifecycles

In logistic operations it is quite common that data changes over time based on new information. This information can either be historic, in the present or model expected future events. To model this OTM introduced lifecycle phases. Lifecycle phases stay in OTM5 and can be used on actions and events. A lifecycle indicates in what phase the data was provided. It can either be:

  • requested: this pre-execution phase can be used to indicate that something is requested, but not yet confirmed by the authorizing party. This is a new lifecyle that did not exist in OTM before.

  • planned: this pre-execution phase is all about planning. Actions and events in this phase represent planned relationships, i.e. it is planned that a certain stop will be visited at 10:00. Planned actions/events typically originate from a planning system. For organizations which do not rely on planning systems this phase can be omitted.

  • projected: this phase models projected (or estimated) lifecyles. Given a series of "planned" events and some associated real-time data (i.e. traffic jams) projected actions/events can be calculated. E.g. when an event is planned to happen at 8:00, but the "actual" event happens at 8:30, all events that are planned after that delayed event can be projected 30 minutes later. Projections can also take into consideration other factors, such as traffic and weather conditions.

  • actual: this during-execution phase models the reality that is happening at present time. As opposed to planned events, actual actions/events typically originate from GPS tracking devices or traffic information systems.

  • realized: this post-execution phase can be used to view and analyze a logistic operation in retrospect. Actions and events in this phase are recorded and archived events from the actual phase.

Lifecycles can be added to both actions and events. If no lifecycle is given it will default to planned. If you want to enrich an existing action (or event) by providing data in another lifecycle you should create an action with the same UUID, since it represents the same action. Just with data in another lifecycle. If you retrieve an action or event by its UUID, it should return the action/event with the latest lifecycle, unless specified otherwise using path-parameters.

Authentication

Vehicle

A Vehicle is a means to transport consignments from one location to potentially multiple other locations. There are various types of vehicles, each with their own unique properties like size, dimensions, fuel type and means of tranport (by air, on land, over sea).

Adds a new Vehicle

Request Body schema: application/json
id
required
string

Uniquely identifies this entity. 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 for more information.

name
string

Name of the entity. For display purposes and search only.

externalAttributes
object

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

creationDate
string

The creation date of this entity

vehicleType
string

The type of vehicle

fuel
string

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.

maxLinks
integer <int32>

Maximum number of links to other Vehicle s. Typical values are 0, 1 or 2.

Array of objects

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.
object

The length of the Vehicle.

object

The height of the Vehicle.

object

The width of the Vehicle.

licensePlate
string

The license plate of the vehicle.

object

The weight of the Vehicle when empty.

Array of any

There are multiple roles in which actors can be associated with a vehicle, such as the owner or the driver of the vehicle.

Responses

Request samples

Content type
application/json
{
  • "id": "0000704f-b6d0-e702-5c33-003ee53ec29b",
  • "name": "Bob's Boxtruck",
  • "vehicleType": "boxtruck",
  • "fuel": "battery",
  • "length": {
    },
  • "height": {
    },
  • "width": {
    },
  • "licensePlate": "AB-12-CD",
  • "emptyWeight": {
    }
}

Response samples

Content type
application/json
{
  • "id": "0000704f-b6d0-e702-5c33-003ee53ec29b",
  • "name": "Bob's Boxtruck",
  • "vehicleType": "boxtruck",
  • "fuel": "battery",
  • "length": {
    },
  • "height": {
    },
  • "width": {
    },
  • "licensePlate": "AB-12-CD",
  • "emptyWeight": {
    }
}

Get a specific Vehicle by its UUID

path Parameters
UUID
required
string <uuid>

The unique ID of this Vehicle

Responses

Response samples

Content type
application/json
{
  • "id": "0000704f-b6d0-e702-5c33-003ee53ec29b",
  • "name": "Bob's Boxtruck",
  • "vehicleType": "boxtruck",
  • "fuel": "battery",
  • "length": {
    },
  • "height": {
    },
  • "width": {
    },
  • "licensePlate": "AB-12-CD",
  • "emptyWeight": {
    }
}

Deletes a Vehicle

path Parameters
UUID
required
string <uuid>

The unique ID of this Vehicle

Responses

Response samples

Content type
application/json
{
  • "id": "0000704f-b6d0-e702-5c33-003ee53ec29b",
  • "name": "Bob's Boxtruck",
  • "vehicleType": "boxtruck",
  • "fuel": "battery",
  • "length": {
    },
  • "height": {
    },
  • "width": {
    },
  • "licensePlate": "AB-12-CD",
  • "emptyWeight": {
    }
}

Route

A route models the path going from one location to at least one other location.

Deletes a Route

path Parameters
UUID
required
string <uuid>

The unique ID of this Route

Responses

Response samples

Content type
application/json
{
  • "id": "5d10345a-8d8f-4a79-8e7e-30216521f6f4",
  • "name": "An example route using coordinates to indicate how to drive.",
  • "geoReferences": {
    }
}

Get a specific Route by its UUID

path Parameters
UUID
required
string <uuid>

The unique ID of this Route

Responses

Response samples

Content type
application/json
{
  • "id": "8b5d3326-0027-4c9c-a92a-0ee9dfd951fa",
  • "name": "An example route using coordinates to indicate how to drive.",
  • "geoReferences": {
    }
}

Adds a new Route

Request Body schema: application/json
id
required
string

Uniquely identifies this entity. 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 for more information.

name
string

Name of the entity. For display purposes and search only.

externalAttributes
object

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

creationDate
string

The creation date of this entity

required
any

Geographic representation of this route.

Array of any

Actors associated with this route, for instance the Company that requires this route as a Last-Mile guidance.

Array of any (associations-actions)

All the actions that need to be executed on this route.

any

Constraints of using this route, for instance it might only be used by vehicles with below a certain weight.

Responses

Request samples

Content type
application/json
{
  • "id": "73ebfcd5-cb75-4a47-98a3-cf7470a2a7c1",
  • "name": "An example route using coordinates to indicate how to drive.",
  • "geoReferences": {
    }
}

Response samples

Content type
application/json
{
  • "id": "73ebfcd5-cb75-4a47-98a3-cf7470a2a7c1",
  • "name": "An example route using coordinates to indicate how to drive.",
  • "geoReferences": {
    }
}

Constraint

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.

Adds a new Constraint

Request Body schema: application/json
id
required
string

Uniquely identifies this entity. 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 for more information.

name
string

Name of the entity. For display purposes and search only.

externalAttributes
object

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

creationDate
string

The creation date of this entity

required
any (constraintValue)

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "value": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "value": {
    }
}

Get a specific Constraint by its UUID

path Parameters
UUID
required
string <uuid>

The unique ID of this Constraint

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "value": {
    }
}

Deletes a Constraint

path Parameters
UUID
required
string <uuid>

The unique ID of this Constraint

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "value": {
    }
}

Action

Actions are dynamic entities that are able to couple together various static entities at a certain moment in time. For instance a Load action couples together a Consignment and a Vehicle at the moment the Loading happens.

There are various types of Actions:

  • The Stop that models visiting a certain location at a certain time and potentially doing several other actions at that location.
  • The Load action, that models loading in one or multiple Consignments into a vehicle or some sort of container.
  • The Unload action, that models unloading one or multiple Consignments from a vehicle or some other sort of container.
  • The HandOver that indicates transferring a consignment from one Actor to another.
  • The Move that models moving between two or more locations, potentially with detailed route information on how to move between these locations.
  • The AttachTransportEquipment that allows you to attach some equipment to the associated vehicle. Note that you can both load/unload and attach/detach TransportEquipments. For instance loading a container on a ship, or attach a trailer to a truck. So choose the one that is most appropriate.
  • The DetachTransportEquipment that allows you to detach some previously attached equipment from the associated vehicle.
  • The GenericAction for whenever any of the above actions cannot model the situation appropriately.

Get a specific Action by its UUID

path Parameters
UUID
required
string <uuid>

The unique ID of this Action

Responses

Response samples

Content type
application/json
Example
{
  • "actionType": "load",
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "lifecycle": "requested",
  • "remark": "string",
  • "stop": {
    },
  • "consignment": {
    },
  • "location": {
    },
  • "startTime": "string",
  • "endTime": "string",
  • "actions": [
    ],
  • "constraint": {
    }
}

Deletes a Action

path Parameters
UUID
required
string <uuid>

The unique ID of this Action

Responses

Response samples

Content type
application/json
Example
{
  • "actionType": "load",
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "lifecycle": "requested",
  • "remark": "string",
  • "stop": {
    },
  • "consignment": {
    },
  • "location": {
    },
  • "startTime": "string",
  • "endTime": "string",
  • "actions": [
    ],
  • "constraint": {
    }
}

Adds a new Action

Request Body schema: application/json
actionType
required
string
id
required
string

Uniquely identifies this entity. 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 for more information.

name
string

Name of the entity. For display purposes and search only.

externalAttributes
object

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

creationDate
string

The creation date of this entity

lifecycle
string
Enum: "requested" "planned" "projected" "actual" "realized"

A lifecycle models when the data in the action is taking place. You can provide the same action in multiple lifecycles to model how it changes over time. For example the planned and realized time of an action taking place can differ because of unforseen circumstances (such as traffic jams).

remark
string

Free text field for adding an on remark on this action.

any

The stop that is associated with this action.

any

The consignment that is the subject of this action.

any

The location at which this action is taking place.

startTime
string

The time at which the actions starts in ISO format.

endTime
string

The time at which the action is completed in ISO format.

Array of any (associations-actions)
any

The constraints this action abides to, such as start and end time windows.

Responses

Request samples

Content type
application/json
Example
{
  • "actionType": "load",
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "lifecycle": "requested",
  • "remark": "string",
  • "stop": {
    },
  • "consignment": {
    },
  • "location": {
    },
  • "startTime": "string",
  • "endTime": "string",
  • "actions": [
    ],
  • "constraint": {
    }
}

Response samples

Content type
application/json
Example
{
  • "actionType": "load",
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "lifecycle": "requested",
  • "remark": "string",
  • "stop": {
    },
  • "consignment": {
    },
  • "location": {
    },
  • "startTime": "string",
  • "endTime": "string",
  • "actions": [
    ],
  • "constraint": {
    }
}

Event

Events - like actions - model dynamic entities that couple various static entities at a certain moment in time. Events are used for either real-time updates, or updates on earlier provided data. Notice that in both event types these are updates on earlier provided data, whereas actions are usually used together with the entities they dynamically couple.

There are various kinds of events that fall into the two earlier mentioned kinds.

Real-time updates:

  • The LocationUpdateEvent that provides location data received from some GPS.

  • The SensorUpdateEvent that provides sensor value updates (such as temperature or speed measurements) received from a sensor.

  • The StartMovingEvent, StopMovingEvent, StartEngineEvent, StopEngineEvent that indicate events provided by Fleet Management Systems.

  • Updates on earlier provided data*:

  • The UpdateEvent that is used to update an earlier provided entity with new information. Note that only the changed data has to be provided.

  • The AssociationCreatedEvent and AssociationRemovedEvent that allow for static entities to be coupled after the fact. Such as coupling a Vehicle to a Trip.

Deletes a Event

path Parameters
UUID
required
string <uuid>

The unique ID of this Event

Responses

Response samples

Content type
application/json
Example
{
  • "entityType": "associationCreatedEvent",
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "lifecycle": "requested",
  • "eventType": "string",
  • "entity1": {
    },
  • "entity2": {
    }
}

Adds a new Event

Request Body schema: application/json
entityType
required
string
id
required
string

Uniquely identifies this entity. 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 for more information.

name
string

Name of the entity. For display purposes and search only.

externalAttributes
object

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

creationDate
string

The creation date of this entity

lifecycle
string
Enum: "requested" "planned" "projected" "actual" "realized"

A lifecycle models when the data in the action is taking place. You can provide the same action in multiple lifecycles to model how it changes over time. For example the planned and realized time of an action taking place can differ because of unforseen circumstances (such as traffic jams).

eventType
required
string
required
any (entity1)
required
any (entity2)

Responses

Request samples

Content type
application/json
Example
{
  • "entityType": "associationCreatedEvent",
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "lifecycle": "requested",
  • "eventType": "string",
  • "entity1": {
    },
  • "entity2": {
    }
}

Response samples

Content type
application/json
Example
{
  • "entityType": "associationCreatedEvent",
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "lifecycle": "requested",
  • "eventType": "string",
  • "entity1": {
    },
  • "entity2": {
    }
}

Get a specific Event by its UUID

path Parameters
UUID
required
string <uuid>

The unique ID of this Event

Responses

Response samples

Content type
application/json
Example
{
  • "entityType": "associationCreatedEvent",
  • "id": "string",
  • "name": "string",
  • "externalAttributes": {
    },
  • "creationDate": "string",
  • "lifecycle": "requested",
  • "eventType": "string",
  • "entity1": {
    },
  • "entity2": {
    }
}

Sensor

A sensor is a device that is able to measure a quantity in a certain unit, such as measuring the speed in km/h.

Adds a new Sensor

Request Body schema: application/json
id
required
string

Uniquely identifies this entity. 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 for more information.

name
string

Name of the entity. For display purposes and search only.

externalAttributes
object

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

creationDate
string

The creation date of this entity

placement
string

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.

sensorType
string

The type of sensor.

Array of any

The actors associated with this sensor, for instance the owners, the producers or the users of this sensor.

any

In the context of a Sensor, only sensorValueConstraints 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.

Responses

Request samples

Content type
application/json
{
  • "id": "3f8913ee-c69f-bc4f-1417-edd9ae2fff3d",
  • "name": "My temperature sensor",
  • "placement": "Trailer main compartment",
  • "sensorType": "temperature"
}

Response samples

Content type
application/json
{
  • "id": "3f8913ee-c69f-bc4f-1417-edd9ae2fff3d",
  • "name": "My temperature sensor",
  • "placement": "Trailer main compartment",
  • "sensorType": "temperature"
}

Deletes a Sensor

path Parameters
UUID
required
string <uuid>

The unique ID of this Sensor

Responses

Response samples

Content type
application/json
{
  • "id": "3f8913ee-c69f-bc4f-1417-edd9ae2fff3d",
  • "name": "My temperature sensor",
  • "placement": "Trailer main compartment",
  • "sensorType": "temperature"
}

Get a specific Sensor by its UUID

path Parameters
UUID
required
string <uuid>

The unique ID of this Sensor

Responses

Response samples

Content type
application/json
{
  • "id": "3f8913ee-c69f-bc4f-1417-edd9ae2fff3d",
  • "name": "My temperature sensor",
  • "placement": "Trailer main compartment",
  • "sensorType": "temperature"
}

Actor

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.

Get a specific Actor by its UUID

path Parameters
UUID
required
string <uuid>

The unique ID of this Actor

Responses

Response samples

Content type
application/json
{
  • "id": "00031877-2307-3103-000f-9794dd120862",
  • "name": "Logistics manager",
  • "contactDetails": [
    ]
}

Adds a new Actor

Request Body schema: application/json
id
required
string

Uniquely identifies this entity. 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 for more information.

name
string

Name of the entity. For display purposes and search only.

externalAttributes
object

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

creationDate
string

The creation date of this entity

Array of any

Contact details for this Actor.

Array of any

Locations for this Actor.

Responses

Request samples

Content type
application/json
{
  • "id": "00031877-2307-3103-000f-9794dd120862",
  • "name": "Logistics manager",
  • "contactDetails": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "00031877-2307-3103-000f-9794dd120862",
  • "name": "Logistics manager",
  • "contactDetails": [
    ]
}

Deletes a Actor

path Parameters
UUID
required
string <uuid>

The unique ID of this Actor

Responses

Response samples

Content type
application/json
{
  • "id": "00031877-2307-3103-000f-9794dd120862",
  • "name": "Logistics manager",
  • "contactDetails": [
    ]
}

TransportOrder

The TransportOrder is the top-level entity to model a group of related consignments that might be transported separately, but need to be administered together.

Adds a new TransportOrder

Request Body schema: application/json
id
required
string

Uniquely identifies this entity. 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 for more information.

name
string

Name of the entity. For display purposes and search only.