OTM 5.7: de actor wordt een bedrijf of een persoon

Tussen OTM 5.6 en 5.7 zit achttien maanden. Dat is de langste stilte in de hele 5.x-reeks — en de release die er daarna uitkwam was navenant.

Op 16 mei 2025 verscheen de release candidate, op 23 mei 2025 werd de documentatie officieel gemarkeerd als 5.7. Wat erin zit is de grootste ingreep in het datamodel sinds 5.4.

Voor de zekerheid, wat is OTM ook alweer? Het Open Trip Model is de open standaard voor het uitwisselen van logistieke ritgegevens: een rit, een zending, een transportorder, een voertuig, een locatie, de goederen erin en de events eromheen — als lichtgewicht JSON over een REST-API.

De waarde zit niet in het formaat maar in de afspraak. OTM wordt beheerd door de Stichting Uniforme Transport Code samen met TLN, evofenedex en DALTI, en elke wijziging wordt in het openbaar op GitHub voorgesteld, bediscussieerd en gelabeld. Wie een OTM-koppeling bouwt kan dus precies teruglezen waarom een veld er is. Dat is zeldzaam, en het is het verschil tussen een standaard implementeren en een leveranciersformaat reverse-engineeren.

In OTM tot en met 5.6 was een actor een naam met een rol en een lijst contactDetails. Wilde je het KvK-nummer, het btw-nummer, het IBAN, de website of het GLN van een partij kwijt — dan ging dat in contactDetails.

Dat werkte, in de zin waarin een la in de keuken werkt. Maar een KvK-nummer is geen contactgegeven, en het gevolg was dat je bij elke koppeling opnieuw moest afspreken welk type je gebruikte voor welk soort identificatie. Precies het probleem dat een standaard geacht wordt op te lossen.

5.7 maakt de actor typespecifiek, net zoals action en event dat al waren. Twee types om mee te beginnen:

company krijgt eigen velden: KvK-nummer, btw-nummer, IBAN, website, GLN, een headOffice als associatie naar een locatie, en een lijst actors voor zusterbedrijven of medewerkers.

person krijgt: voornaam, achternaam, functie, afdeling en de talen die iemand spreekt.

De contactgegeven-types die daarmee overbodig werden — GLN, vatcode, iban, name, firstName, lastName en other — zijn gedeprecieerd.

Let op het woord gedeprecieerd. Ze zijn niet verwijderd. Dat is de manier waarop OTM dit soort ingrepen doet: de nieuwe vorm komt erbij, de oude blijft werken, en je migreert wanneer het je uitkomt. Je koppeling breekt niet op de releasedatum — maar hij wordt wel ouderwets, en het loont om te plannen wanneer je meegaat.

Hiernaast kwam een tweede, kleinere correctie die hetzelfde probleem van de andere kant aanpakt: het GLN hoort direct op de location, niet op een actor of op contactgegevens.

Dat is inhoudelijk juist — een GLN identificeert een fysieke plek, niet een organisatie — en het maakt het veld vindbaar voor wie een locatie opzoekt in plaats van een partij.

De tweede lijn in 5.7 gaat over wat er misgaat onderweg. Een actie kon al slagen, mislukken, deels slagen of geannuleerd zijn, met als redenen alleen damage en receiverAbsent. Voor de meeste praktijksituaties is dat te weinig, en dan valt iedereen terug op het vrije tekstveld remark — waarna er machinaal niets meer mee te doen is.

5.7 breidt de redenen uit met:

• incomplete — geleverd, maar niet volledig zoals afgesproken.
• deliveredElsewhere — wel geleverd, niet op de afgesproken plek. Een ander dok, of bij de buren.
• locationUnreachable — de chauffeur kwam er niet: poort dicht, weg open, hek op slot.
• rejected — de ontvanger weigerde de goederen.

En verder in dezelfde geest: distance per move, zodat je de daadwerkelijk gereden afstand van een verplaatsing kunt meesturen in plaats van hem achteraf te reconstrueren.

Vier wijzigingen zijn puur consistentiewerk, en juist die maken een specificatie implementeerbaar:

• fuelStation en terminal als nieuwe locatietypes. Sinds 5.5 bestaat de refuel-actie; dan hoort de plek waar je dat doet ook een eigen type te hebben.
• geoReferences wordt geoReference op een route. Overal in de specificatie heet dit object enkelvoudig; alleen bij routes stond het in het meervoud, terwijl het ook daar precies één geografische representatie is.
• arbitraryJsonBlob krijgt een fatsoenlijke naam in plaats van een omschrijving met spaties.
• Een kapotte verwijzing bij goods.packagingMaterial rechtgetrokken.

Drie dingen, in deze volgorde.

Eerst: kijk of je geoReferences gebruikt op routes. Dat is de enige hernoeming in deze release die stilletjes een lege waarde kan opleveren in plaats van een foutmelding.

Daarna: inventariseer waar je identificatienummers in contactDetails hebt gestopt. Die blijven werken, maar elke nieuwe tegenpartij zal ze op de nieuwe plek verwachten.

En tot slot: als je iets doet met afhandeling van uitzonderingen — niet geleverd, geweigerd, niet bereikbaar — dan kun je vanaf 5.7 stoppen met het parsen van vrije tekst. Dat is meestal de wijziging die het snelst geld oplevert.

In Keana is dat laatste direct zichtbaar: een stop die niet gelukt is omdat de locatie onbereikbaar was, vraagt om een andere herplanning dan een stop waar de ontvanger de goederen weigerde. Zolang dat verschil in een opmerkingveld zit, kan je planning er niets mee. Bekijk de Keana-case.

OTM 5.7 verscheen op 23 mei 2025, achttien maanden na 5.6, met een release candidate op 16 mei.

De kern: actor wordt typespecifiek met company en person en hun eigen velden, waarmee identificatienummers uit contactDetails verdwijnen (gedeprecieerd, niet verwijderd). GLN verhuist naar de locatie. De resultaatredenen op acties worden uitgebreid met incomplete, deliveredElsewhere, locationUnreachable en rejected. Een move krijgt distance. En fuelStation en terminal worden locatietypes.

Let vooral op de hernoeming van geoReferences naar geoReference — dat is de wijziging die je koppeling het stilst raakt.