De OTM .NET-packages springen van 1.1 naar 5.7

Op 4 augustus 2025 stonden alle drie de OTM .NET-packages op versie 5.7.1.1. Een maand eerder, bij hun eerste release, stonden ze nog op 1.0.x en 1.1.1.x. Dat nummer antwoordt op de vraag die iedereen stelt die een clientbibliotheek voor een standaard binnenhaalt: welke versie van de standaard zit hier eigenlijk in?

Voor wie hier binnenvalt: wat is OTM? Het Open Trip Model is een open standaard voor het uitwisselen van logistieke ritgegevens (ritten, zendingen, transportorders, voertuigen, locaties, goederen en events) als lichtgewicht JSON over een REST-API. De standaard bestaat om te voorkomen dat iedere partij in de keten een eigen vertaallaag naar iedere andere partij bouwt. Hij wordt sinds 2018 beheerd door de Stichting Uniforme Transport Code, samen met TLN, evofenedex en DALTI, en wordt in versies uitgebracht: 5.4 in mei 2022, 5.5 in februari 2023, 5.6 in november 2023, 5.7 in mei 2025.

Een clientbibliotheek voor een standaard heeft twee versies die er tegelijk toe doen: die van de bibliotheek zelf, en die van de standaard die erin zit. Zolang je die twee los van elkaar nummert, moet je bij elke upgrade in de release notes duiken om te zien of je nu 5.6 of 5.7 spreekt. En als je tegenpartij vraagt welke OTM-versie jouw koppeling ondersteunt, is het eerlijke antwoord: "even kijken."

Dat is precies het soort wrijving waar een standaard geacht wordt vanaf te helpen.

De verandering ging in twee stappen:

• 31 juli 2025: OpenTripModel.Profile gaat als eerste over, van 1.1.1.8 naar de 5.7-reeks.
• 4 augustus 2025: OpenTripModel.Model en OpenTripModel.Serializer volgen, allebei naar 5.7.1.1.

Vanaf dat moment lees je aan 5.7.1.1 twee dingen tegelijk af: dit spreekt OTM 5.7, en dit is de tweede patch van deze library daarop. Er zit een prijs aan. Semantische versienummers verliezen hun gebruikelijke betekenis: de major staat vanaf nu voor de versie van de standaard in plaats van voor een breaking change in de library. Een breaking change in de library zelf moet dus ergens anders in het nummer landen.

Voor een clientbibliotheek van een standaard is dat een verdedigbare ruil. De vraag "welke OTM spreek jij" wordt in de praktijk veel vaker gesteld dan "is deze upgrade breaking".

Interessant genoeg is de Java-kant niet meegegaan. org.opentripmodel:otm-toolkit verscheen op 9 juli 2025 als 1.0.1.0 en houdt zijn eigen nummering aan. Dat valt te verdedigen, en het is ook een inconsistentie tussen twee libraries die verder duidelijk vanuit hetzelfde ontwerp gebouwd zijn: dezelfde driedeling in model, profielvalidatie en serializer, dezelfde keuze om geen transportlaag mee te leveren.

Als je Java en .NET door elkaar gebruikt, en dat is in logistiek eerder regel dan uitzondering, betekent het dat je voor .NET aan het pakketnummer genoeg hebt en voor Java nog steeds de documentatie in moet.

Twee praktische dingen. Zet de OTM-versie in je koppelvlakdocumentatie, niet het libraryversienummer. Ook als die nu toevallig hetzelfde zijn. De dag dat een van beide libraries van schema wisselt, wil je niet ontdekken dat je contractdocumentatie naar een pakketversie verwijst. Bouw een controle in je pipeline die de gebruikte OTM-versie logt. Niet omdat je hem elke dag nodig hebt, maar omdat de vraag "draaien wij nog op 5.6?" anders alleen te beantwoorden is door in een lockfile te kijken.

En de vraag die hierboven zweeft: gáát zo'n library de standaard bijhouden? Een clientbibliotheek die achterloopt is gevaarlijker dan geen clientbibliotheek, want een versienummer dat 5.7 zegt suggereert dat je bij bent. Dat is een belofte die je pas kunt beoordelen bij de volgende release van de standaard. Tot die tijd geldt: het nummer vertelt je welke versie erin zat toen hij werd uitgebracht, niet of dat nog de nieuwste is.

Bij Keana, onze planningssoftware voor groene stadslogistiek, sluit elke nieuwe verlader of vervoerder aan op dezelfde standaard. Hoe minder gesprek er nodig is over welke versie iedereen spreekt, hoe sneller die aansluiting rond is. Een versienummer dat de vraag zelf beantwoordt scheelt in de praktijk meer tijd dan het klinkt. Bekijk de Keana-case. Op 31 juli 2025 ging OpenTripModel.Profile over op de 5.7-reeks; op 4 augustus volgden OpenTripModel.Model en OpenTripModel.Serializer, allebei naar 5.7.1.1. Het versienummer van de .NET-packages draagt sindsdien de versie van de standaard; de Java-toolkit houdt zijn eigen 1.0.x-reeks aan.

Ik vind het een goede ruil, en ik zou willen dat Java meeging: de vraag "welke OTM spreek jij" wordt in de praktijk veel vaker gesteld dan "is deze upgrade breaking". Maar laat je er niet door in slaap sussen. Een nummer dat 5.7 zegt vertelt je welke versie erin zat toen hij werd uitgebracht, niet of dat nog de nieuwste is, en bij de volgende release van de standaard zul je zien of de library het tempo bijhoudt. Zet daarom de OTM-versie in je koppelvlakdocumentatie en log hem in je pipeline, dan ben je bij die release niet degene die in een lockfile moet zoeken. Dat inregelen hoort bij hoe wij koppelingen tussen systemen opleveren.