JSON controleren

Een JSON-parser stopt zodra hij iets tegenkomt dat niet past, en dat punt ligt vaak een stuk voorbij de echte fout. Een komma die op regel 12 ontbreekt wordt op regel 13 ontdekt, wanneer er een aanhalingsteken staat waar een komma had moeten staan; de melding wijst 13 aan.

Daarom komt hier niet alleen een getal maar ook het fragment met de plek gemarkeerd. De context zien is wat «kolom 4» verandert in «de komma van de regel erboven ontbreekt», en dat is het verschil tussen tien seconden herstelwerk en staren naar tweehonderd regels.

Hetzelfde kapotte document levert in Chrome, in Firefox en in Safari een andere melding op, want elke JavaScript-motor schrijft de zijne. Sommige geven de positie als een tekenverschuiving, andere geven helemaal geen positie.

Hier worden regel en kolom uit die verschuiving berekend in plaats van uit de tekst van de melding gevist. Zo is het antwoord in elke browser hetzelfde, en dat is het minste wat je mag vragen van een hulpmiddel waarvan de enige taak is te zeggen waar je moet kijken.

Een komma te veel vóór een sluitende accolade of blokhaak; een komma die tussen twee elementen ontbreekt; enkele aanhalingstekens in plaats van dubbele; en een sleutel zonder aanhalingstekens. Samen dekken die vier de overgrote meerderheid van de geweigerde documenten, en alle vier komen ze voort uit JSON schrijven alsof het JavaScript is.

De vijfde is verraderlijker: een onzichtbaar teken helemaal vooraan, bijna altijd de byte order mark die Excel en sommige Windows-editors ervoor zetten. Het document ziet er onberispelijk uit en de parser faalt in kolom 1, wat precies de plek is waar niemand kijkt.

Dat een document geldige JSON is, betekent dat de syntaxis klopt, en verder niets. Een veld dat een getal had moeten zijn en als tekst binnenkomt, een datum in een vorm die de tegenpartij niet verwacht of een object waar de helft van de sleutels aan ontbreekt, komen hier zonder moeite doorheen.

Weigert een API een document dat hier geldig heet, dan is het probleem geen syntaxis meer maar een schema. Dat controleer je met een JSON Schema-validator tegen het concrete schema van die API, en dat is een andere vraag, die precies begint waar deze pagina ophoudt.

Kolommen tellen met tabs ertussen is dubbelzinnig: een tab is één teken, maar op het scherm neemt hij vier of acht plaatsen in, afhankelijk van de instelling van de editor. Een kolomnummer dat op tekens is berekend, komt dan niet overeen met wat je ziet.

Hier worden tekens geteld, want dat is wat de parser doet, en het fragment wordt getoond met de tabs uitgeschreven zodat de gemarkeerde plek valt waar het oog haar verwacht. Het is een minuscuul detail en het is het verschil tussen een aanwijzing die helpt en een die in de war brengt.

Logbestanden en exports komen vaak als één JSON-object per regel — NDJSON of JSON Lines. Elke regel op zich is geldig, het geheel is dat niet, want een JSON-document bevat precies één waarde. Een parser struikelt dan aan het begin van de tweede regel, op het eerste teken na de eerste sluitende accolade.

De melding die daaruit volgt klinkt alsof er iets mis is met regel 2, en dat is er niet: het formaat is anders dan de parser aanneemt. Controleer in dat geval één regel tegelijk, of zet er blokhaken omheen met komma’s ertussen en controleer het geheel als array.

Staat dezelfde sleutel twee keer in één object, dan is dat volgens de specificatie niet ongeldig maar ongedefinieerd. Elke gangbare parser houdt de laatste, dus dit document komt hier als geldig terug terwijl er onderweg een waarde verdwijnt.

Het is het enige gebruikelijke geval waarin «geldig» en «wat je bedoelde» merkbaar uiteenlopen zonder dat er ergens iets faalt. Krijgt de ontvangende kant een waarde die je nooit hebt gestuurd, dan is een dubbele sleutel een goede tweede verdachte, na een schemafout.

Komt het document erdoor, dan verschijnt ook de vorm ervan: of het bovenste niveau een object of een array is, hoeveel sleutels het heeft, hoe diep het nest en hoe groot het is. Dat zijn de gegevens waar je naar kijkt voordat je besluit hoe je het verwerkt.

De nestdiepte is van de vier de nuttigste. Veel parsers en veel API’s hebben een grens, en een document dat automatisch wordt gegenereerd kan die overschrijden zonder dat iemand het voorzag. Het is een getal waar nooit naar wordt gekeken tot de dag dat het een onbegrijpelijke fout verklaart.

Bevat het document een geheel getal dat te groot is om exact te blijven, dan wordt dat gemeld, ook al is het document volkomen geldig. Het is geen syntaxisfout: het is een stil verlies dat bij het lezen optreedt, en het treedt op in elk systeem dat een JavaScript-parser gebruikt.

Het verdient een eigen waarschuwing omdat het de fout is die het slechtst te diagnosticeren valt. Het document gaat er goed in, komt er goed uit, en onderweg zijn de laatste cijfers van een identifier veranderd — waarna het ontvangende systeem het record niet vindt en er geen enkele aanwijzing is waarom.

Deze pagina beantwoordt één vraag en geen twee: waar het faalt. Het document met inspringing zien is wat de opmaakpagina doet, en die heeft bovendien de keuze voor inspringing en het sorteren van sleutels, wat hier niets toevoegt.

Het is dezelfde beslissing die in de rest van deze sectie coderen van decoderen scheidt. Wie hier belandt heeft iets kapots en wil de plek; wie daar belandt heeft iets onleesbaars en wil het zien. Samengevoegd zou het een pagina worden waarvan voor allebei de helft overbodig is.

Het document dat ergens wordt geweigerd is meestal het echte document: een bestelling, een klantrecord, de body van een webhook met namen en adressen erin. Omdat de controle op de pagina gebeurt, wordt niets daarvan aan ons verstrekt en staat het in geen enkel verzoeklogboek van ons.

Het is precies het geval dat intern beleid wil voorkomen — persoonsgegevens in een dienst van derden plakken om te debuggen — en het doet zich hier niet voor, want er is geen dienst van derden die iets ontvangt. Het netwerktabblad laat dat zien terwijl je het gebruikt.