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.

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

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

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.

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.