JSON opmaken

Opmaken betekent hier: het hele document lezen en opnieuw schrijven. Het goedkope alternatief — regeleindes en spaties invoegen waar een accolade staat — werkt tot er een accolade binnen een tekstwaarde staat, en dan sloopt het het document op een manier die nog steeds op JSON lijkt.

Het nuttige gevolg is dat opmaken meteen een controle is. Komt er iets uit, dan was het document geldig; komt er niets uit, dan niet, en daarvoor is de validatiepagina, die zegt op welke regel het vastloopt. Een opmaker die nooit faalt is een opmaker die niet leest wat je hem geeft.

Twee spaties is wat `JSON.stringify` schrijft als je om inspringing vraagt, en wat vrijwel al het JavaScript-gereedschap standaard doet. Vier komt uit de wereld van Python en Java. De tab bespaart bytes en laat iedereen in zijn eigen editor de breedte kiezen.

Geen van de drie verandert het document: voor een parser bestaat de witruimte tussen elementen niet. Het telt alleen als het resultaat in een repository terechtkomt, waar een mengeling van conventies verschillen oplevert op regels die niemand heeft aangeraakt — de reden om er één vast te leggen en die door het gereedschap te laten afdwingen en niet door de persoon.

Een JSON-object heeft geen vastgelegde volgorde, dus twee diensten kunnen dezelfde gegevens teruggeven met de sleutels op een andere plek. Alfabetisch sorteren maakt van een tekstvergelijking een zinnige vergelijking, en dat is precies wat je nodig hebt vóór een diff of een contracttest.

Een array is het tegenovergestelde: de volgorde is deel van het gegeven. Die wordt hier nooit aangeraakt, en die asymmetrie is met opzet. Een hulpmiddel dat ook arrays zou sorteren, levert documenten op die netjes vergelijken en iets anders betekenen, en dat is de slechtst denkbare combinatie.

Een object met twee keer dezelfde sleutel is volgens de specificatie niet verboden, alleen ongedefinieerd. Elke gangbare parser, ook die in de browser, houdt de laatste en gooit de eerdere weg. Bij het opmaken zie je dus één sleutel terug waar er in de invoer twee stonden.

Dat is zelden wat iemand bedoelde, en het is bijna altijd het gevolg van een document dat regel voor regel is samengeplakt in plaats van uit een structuur geschreven. Merk je dat een veld na het opmaken de verkeerde waarde heeft, dan is dit het eerste om te controleren: het gaat om verloren gegevens, niet om opmaak.

JSON schrijft getallen als tekst en JavaScript leest ze als drijvende komma met dubbele precisie. Gehele getallen boven ongeveer negen biljard verliezen cijfers: een identifier van 19 tekens komt er anders uit, en omdat het resultaat nog steeds een geldig getal lijkt, merkt niemand het.

Het treft elke verwerking die door een JavaScript-parser loopt, deze inbegrepen, en er wordt gemeld wanneer het gebeurt. De gebruikelijke aanleiding zijn snowflake-achtige identifiers van Twitter en Discord en sommige databasereeksen. De oplossing ligt bij wie ze uitgeeft: zulke waarden horen als tekst te reizen, en dan komen ze onveranderd door elke stap.

Geen commentaar, geen komma achter het laatste element, geen enkele aanhalingstekens en geen sleutels zonder aanhalingstekens. Elk van die dingen is een gewoonte uit JavaScript, en elk laat de parser staan met een melding die zelden de juiste plek aanwijst.

Wie commentaar in een configuratie nodig heeft, heeft drie uitwegen: een formaat kiezen dat het kent — YAML, TOML, JSON5 —, een veld `_comment` opnemen dat met opzet genegeerd wordt, of het weghalen vóór het verwerken. De derde is de meest gebruikte en de meest broze, want een dubbele schuine streep staat ook binnen een URL.

Het resultaat komt er als UTF-8 uit, zonder niet-ASCII-tekens om te zetten in `\uXXXX`-ontsnappingen. Beide vormen zijn geldige JSON en betekenen hetzelfde, maar de eerste laat zich lezen en de tweede niet: een woord als «ideeën» geschreven als `idee\u00ebn` is correct en onleesbaar.

Sommige bibliotheken ontsnappen standaard, omdat ze aannemen dat het transport niet schoon is, en dat is al lang niet meer waar. Komen jouw gegevens met zulke reeksen binnen, dan zet deze opmaker ze niet terug — ze horen bij het document zoals je het hebt ontvangen, en ze wijzigen zou het gegeven herschrijven en niet de presentatie.

Deze pagina lost een leesprobleem op: er ligt een document en de vorm ervan is niet te zien. Dat is wat je nodig hebt als een API-antwoord op één regel binnenkomt, als een logveld JSON bevat of als iemand een blok configuratie in een ticket plakt.

Het omgekeerde probleem lost het niet op. Om het terug op één regel te krijgen is er de minificatiepagina, en om uit te zoeken waarom iets het weigert is er de validatiepagina, die regel en kolom geeft. De drie delen dezelfde motor en staan apart omdat het drie momenten met drie vragen zijn.

Geminificeerde JSON in een bestand onder versiebeheer maakt van elke wijziging één gewijzigde regel. De diff wordt alles of niets, reviewen wordt onmogelijk en een merge-conflict raakt het hele document in plaats van de twee velden waar het over ging.

De verdeling die werkt is de voor de hand liggende: opgemaakt in de repository, geminificeerd bij het uitleveren. Daartussen zit precies de stap die een buildproces zelf hoort te zetten, en geen van beide vormen is in het algemeen de juiste — ze zijn het op hun eigen plek.

Veel hulpmiddelen tonen JSON als een boom met driehoekjes om takken in te klappen. Dat is prettig bij een document van tienduizend regels en het is een ander product: het vraagt om toestand, om toetsenbedienbaarheid en om een weergave die zonder JavaScript niets meer is dan een lege lijst.

Wat hier staat is tekst die je kunt selecteren, kopiëren en in je editor plakken, en dat is wat de meeste bezoekers vervolgens doen. Wie werkelijk door een enorm document wil navigeren, is beter af in een editor die er al is dan in een tabblad dat het per ongeluk ook probeert.

Een JSON-payload bevat vaak precies wat je liever niet verplaatst: klantrecords, ordergegevens, een webhook met adressen erin. Omdat er hier op de pagina zelf wordt geparseerd en herschreven, is er geen verstrekking aan ons en dus ook geen verwerking in onze opdracht van die inhoud.

Het netwerktabblad toont het aan: terwijl je het gebruikt vertrekt er geen enkel verzoek dat je document draagt. Dat is de reden dat dit hulpmiddel bruikbaar is waar een serverversie tegen intern beleid zou botsen, en het controleren kost een minuut.