OTM 5.7: The Actor Becomes a Company or a Person

Eighteen months separate OTM 5.6 and 5.7. That is the longest silence in the entire 5.x series — and the release that followed was proportionate.

The release candidate appeared on 16 May 2025; on 23 May 2025 the documentation was officially marked as 5.7. What it contains is the largest intervention in the data model since 5.4.

Just to be sure — what is OTM again? The Open Trip Model is the open standard for exchanging logistics trip data: a trip, a consignment, a transport order, a vehicle, a location, the goods inside it and the events around it — as lightweight JSON over a REST API.

The value is not in the format but in the agreement. OTM is stewarded by the Stichting Uniforme Transport Code together with TLN, evofenedex and DALTI, and every change is proposed, debated and labelled in the open on GitHub. Anyone building an OTM integration can read back exactly why a field exists. That is rare, and it is the difference between implementing a standard and reverse-engineering a vendor format.

In OTM up to and including 5.6, an actor was a name with a role and a list of contactDetails. If you needed to record a party's chamber of commerce number, VAT number, IBAN, website or GLN — it went into contactDetails.

That worked, in the way a kitchen junk drawer works. But a chamber of commerce number is not a contact detail, and the consequence was that every new integration required a fresh agreement about which type you used for which kind of identifier. Precisely the problem a standard is supposed to solve.

5.7 makes the actor type-specific, just as action and event already were. Two types to start with:

company gets its own fields: chamber of commerce number, VAT number, IBAN, website, GLN, a headOffice association to a location, and an actors list for sister companies or employees.

person gets: first name, last name, role, department, and the languages someone speaks.

The contact detail types this made redundant — GLN, vatcode, iban, name, firstName, lastName and other — are deprecated.

Note the word deprecated. They are not removed. That is how OTM handles this sort of intervention: the new form arrives, the old one keeps working, and you migrate when it suits you. Your integration does not break on release day — but it does become dated, and it pays to plan when you follow.

Alongside it came a second, smaller correction attacking the same problem from the other side: the GLN belongs directly on the location, not on an actor or on contact details.

That is substantively right — a GLN identifies a physical place, not an organisation — and it makes the field findable for anyone looking up a location rather than a party.

The second thread in 5.7 is about what goes wrong en route. An action could already succeed, fail, partially succeed or be cancelled, with only damage and receiverAbsent as reasons. For most real situations that is too little, so everyone fell back on the free-text remark field — after which nothing can be done with it programmatically.

5.7 extends the reasons with:

• incomplete — delivered, but not in full as agreed.
• deliveredElsewhere — delivered, but not at the agreed place. A different dock, or the neighbours.
• locationUnreachable — the driver could not get there: gate shut, road up, barrier locked.
• rejected — the receiver refused the goods.

And in the same spirit: distance per move, so you can send the actually driven distance of a movement instead of reconstructing it afterwards.

Four changes are pure consistency work, and those are exactly what makes a specification implementable:

• fuelStation and terminal as new location types. The refuel action has existed since 5.5; the place where you do it deserves its own type too.
• geoReferences becomes geoReference on a route. Everywhere else in the specification this object is singular; only on routes was it plural, even though there too it is exactly one geographical representation.
• arbitraryJsonBlob gets a proper name instead of a description with spaces in it.
• A broken reference at goods.packagingMaterial straightened out.

Three things, in this order.

First: check whether you use geoReferences on routes. That is the only rename in this release that can quietly yield an empty value instead of an error.

Then: inventory where you have stuffed identifiers into contactDetails. They keep working, but every new counterparty will expect them in the new place.

And finally: if you do anything with exception handling — not delivered, refused, unreachable — then from 5.7 onwards you can stop parsing free text. That is usually the change that pays off fastest.

In Keana the last one is immediately visible: a stop that failed because the location was unreachable calls for different rescheduling than a stop where the receiver refused the goods. As long as that difference lives in a remark field, your planning can do nothing with it. See the Keana case.

OTM 5.7 shipped on 23 May 2025, eighteen months after 5.6, with a release candidate on 16 May.

The core: actor becomes type-specific with company and person and their own fields, moving identifiers out of contactDetails (deprecated, not removed). GLN moves to the location. Action result reasons are extended with incomplete, deliveredElsewhere, locationUnreachable and rejected. A move gains distance. And fuelStation and terminal become location types.

Watch the rename of geoReferences to geoReference in particular — that is the change that hits your integration most quietly.