Last updated 1 hour ago

Data Format - Basics

OpenTripModel

As we mentioned earlier, we are using the OpenTripModel standard to model the messages we send you. On the next pages, we will guide you through our most common fields and logic. However, if you feel the need for more in-depth knowledge on the complete OpenTripModel, feel free to go to the official website at https://www.opentripmodel.org/

References

Objects within the data you will receive, can either be inlined or referenced. We use references to reduce the total size of the message. References are not made with JSON pointers, but with the OTM standard key associationType. In general an associationType can have a value of inline or reference. Let's show you an example.

References Examples

See underneath snippet for an inline example

"location": {
  "associationType": "inline",
  "entity": {
    "name": "DCT",
    "id": "8f14e45f-ceea-367a-9a36-dedd4bea2543",
    "externalAttributes": {
      "globalLocationNumber": "9210400000327",

What happens in the above example is that the location object has an associationType of inline; what follows is basically all information of a specific location, like the id, in the same object. This likely resembles the standard way you use to structure your JSON files.

Now, when you will see a associationType of reference, we create a pointer to a different entity in the same data structure. Check the following snippet, for a small example

"actionType": "Move",
"associationType": "inline",
"entity": {
  "id": "3c56ceea-cbb0-408d-ae61-0dcc86455c33",
  "from": {
    "associationType": "reference",
    "uuid": "8f14e45f-ceea-367a-9a36-dedd4bea2543"
  },

As OTM is human readable, we are able to analyse this, without any further details on the entities. We can see that a particular action Move is going on. All information on the Move is inlined. What follow is an entity, with a specific id. Apparently there is a Move from a particular location. The from tells us that it has a associationType as reference. With the UUID supplied 8f14e45f-ceea-367a-9a36-dedd4bea2543, we can look up any further information in the JSON structure. In this example, it references to the previous example. As you can see the unique ID is equal.

Basic Structure

We are going to take you through the data structure, which you will receive when we send you a full planning, step by step. Let's see the basic structure first. A bare minimal message could look like underneath. (No, we won't be sending you empty ones, like this)

{
  "id": "2a8af6c6-e4d5-5dfb-9532-e8b17c3ffd88",
  "name": "DCX|2020|32-2-888",
  "externalAttributes": {},
  "vehicle": {},
  "actors": [],
  "actions": []
}
id
uuid

Universally Unique Identifier to the trip.

name
string

Identifier of this trip as typically seen in the URL that is unique within a shipper in the Simacan domain.

externalAttributes
object

Any attributes related to this trip

vehicle
object

Currently linked vehicle to the planning, at the moment of sending the data this is the vehicle we have monitored for the realization data.

actors
array

All actors that are involved in this trip, and typically have access to at least its planning.

actions
array

All actions that are involved in this trip