JSON Schema Validation

"𝐓𝐡𝐢𝐬 𝐢𝐬 𝐭𝐡𝐞 𝐟𝐢𝐫𝐬𝐭 𝐫𝐮𝐥𝐞 𝐨𝐟 𝐭𝐡𝐞 𝐥𝐚𝐬𝐭 𝐰𝐚𝐫:𝐓𝐫𝐮𝐬𝐭 𝐍𝐨 𝐎𝐧𝐞"

Als ik iets geleerd heb van Rick Yancey's 'The 5th Wave' is het wel mijn belangrijkste regel bij wat voor integratie dan ook: Trust no one!

En daar ligt bij TOPdesk dus een beetje de crux. Alleen al een simpele JSON schema check gewoon is niet te doen als je een webhook maakt. En da's nou net een van de dingen die ik graag zou willen: "FAIL FAST!"

Even de context. In TOPdesk actiereeksen kun je geen Java toevoegen. Dat is een keuze die ik respecteer, zoals je ook een muur respecteert waar je tegenaan loopt. Dus alles wat ik bouw, bouw ik in Freemarker. Ja, dezelfde Freemarker waarmee je ook je factuur zou kunnen opmaken. Het is een templating-taal die binnen TOPdesk's action sequences gebruikt wordt en geen programmeertaal. Maar goed, als dat het enige beschikbare is, wordt dat de tool of choice.

Dus nu heb ik een jsonSchemaLib, een zelfstandige JSON Schema-validator in één .ftl-bestand. Geen Java, geen externe engine, geen “even dit npm-pakketje installeren”. Je geeft hem een bericht en een schema, en hij vertelt je precies wat er mis is:

/𝘢𝘨𝘦 [𝘮𝘪𝘯𝘪𝘮𝘶𝘮]: 𝘕𝘶𝘮𝘣𝘦𝘳 𝘪𝘴 𝘣𝘦𝘭𝘰𝘸 𝘮𝘪𝘯𝘪𝘮𝘶𝘮.

Het pad naar de fout, het keyword dat het veroorzaakte en een melding. Geen “er ging iets mis”, maar een wijzende vinger met coördinaten. Zo hoort een foutmelding te zijn.

Een paar dingen die ik stiekem zelf wel tof vind:

• Alle fouten tegelijk, niet één per keer. Niets is zo deprimerend als drie keer opnieuw testen om elke keer uit de doos van Pandora precies één fout tegelijk te krijgen.
• Onbekende keywords zijn een fout. Typ je requried in plaats van required, dan slaat de validator alarm in plaats van het bericht vrolijk goed te keuren. Een validator die typefouten door de vingers ziet, is net als een partner die tongzoenen niet vreemdgaan vindt. Het is een hellend vlak 😉
• Ondersteuning voor $ref, $defs, $anchor, allOf/anyOf/oneOf, if/then/else en zelfs recursieve schema’s. In Freemarker. Ik weet het. Ik vond het zelf ook spannend.
• Getest met échte FreeMarker-runs, ook op de geminificeerde en geobfusceerde varianten. Want code die alleen werkt als je er niet naar kijkt, is geen code, dat is futiele hoop op wereldvrede (of een onverwachte salarisverhoging, reken er niet op).

Eerlijk is eerlijk: het is een subset van JSON Schema draft 2020-12 en geen volledige implementatie. Geen format, geen externe $refs, geen patternProperties. Wat het niet ondersteunt meldt hij netjes als schemafout, dus je krijgt nooit een onterechte “geldig”. Een beperkte validator die eerlijk is over zijn grenzen vind ik prettiger dan een volledige die als de gemiddelde account manager loopt te bluffen dat het werkt.

Is het perfect? Nee. Is het nuttig? Elke keer dat een webhook iets stuurt wat incorrect lijkt op JSON-met-goede-bedoelingen: ja.

Want uiteindelijk geldt in integraties één wet: vertrouw nooit een payload die je niet zelf hebt gecontroleerd. Zeker niet als hij “altijd zo is binnengekomen”.

Wie de rest van de libraries (hashLib, seqLib, strLib, numLib, dateLib) nog niet heeft gezien: die staan ook gewoon in de collectie. Reacties en nieuwsgierigheid zijn welkom.

#TOPdesk #Freemarker #JSONSchema #ESM #Integraties #Webhooks #ServiceManagement