Wat is een JSON-bestand?

JSON is een puur tekstformaat dat in elke editor opengaat. Het wordt gebruikt voor gegevens tussen programma’s verplaatsen en het web.

De extensie is .json en de volledige naam JavaScript Object Notation. Allebei zeggen ze minder dan wat het bestand kan bevatten, en daar gaat de rest van deze pagina over.

Het gaat terug tot 2001. De specificatie is RFC 8259.

De leeftijd is om een praktische reden interessant: hoe ouder een formaat, hoe meer programma’s de tijd hebben gehad om het te leren.

Ze is volledig gepubliceerd, dus wie het formaat wil uitvoeren kan dat uit het document doen in plaats van door te kijken hoe anderen het doen. Daarom duikt het in zo veel programma’s op, en daarom gaan bestanden van twintig jaar geleden nog steeds open. Openbaar is niet hetzelfde als royaltyvrij: waar een formaat een codec omhult, is de octrooilicentie een aparte vraag waarop de standaard geen antwoord geeft.

JSON bewaart zijn inhoud precies. Opnieuw opslaan verandert niets, dus je kunt het zo vaak openen, bewerken en wegschrijven als je wilt zonder dat er schade opstapelt — en dat is wat er een werkformaat van maakt in plaats van een afleverformaat.

JSON heeft geen commentaarsyntaxis. Alles wat toelicht moet buiten het bestand leven, en dat is goed om te weten voordat je het kiest voor iets dat een mens met de hand bijhoudt.

Visual Studio Code, jq en Postman lezen het, en de meeste programma’s van dezelfde soort ook.

Als een bestand niet opengaat ligt het zelden aan het formaat — vaker is het programma ouder dan het formaat. Converteren naar iets ouders is de betrouwbare weg eromheen, en daarvoor is de rest van deze site bedoeld.

Elke actuele browser leest het.

Je kunt het dus zonder zorgen op een pagina zetten of aan een bericht hangen, zonder je af te vragen wat de andere kant geïnstalleerd heeft.

JSON is bedoeld om te openen en te wijzigen. Houd het bestand in dit formaat zolang het werk loopt, en exporteer eruit wanneer er een afgeronde versie nodig is.

Een JSON-document is opgebouwd uit objecten, arrays, tekenreeksen, getallen, booleans en null. Dat is de hele woordenschat, en de kortheid van die lijst is de reden dat het formaat de wereld veroverde: elke programmeertaal heeft die zes al.

De specificatie past op een paar pagina’s. Ze werd beschreven in plaats van ontworpen — Douglas Crockford schreef op wat de object-literalsyntax van JavaScript al deed — wat verklaart waarom het vanzelfsprekend aanvoelt.

JSON heeft bewust geen commentaar, en het is de meest beklaagde eigenschap van het formaat. De redenering was dat commentaar parseerinstructies uitnodigt.

Drie omwegen circuleren. Een sleutel genaamd zoiets als een underscore-comment, die elke parser accepteert en elke schemavalidator afwijst. JSON5 en JSONC, die commentaar en afsluitende komma’s toevoegen en geen JSON zijn — Visual Studio Codes instellingenbestand is JSONC. En het eerlijke antwoord: gebruik TOML of YAML voor alles wat een mens onderhoudt.

JSON maakt geen onderscheid tussen gehele getallen en kommagetallen. De meeste parsers lezen elk getal als een double, en een double houdt gehele getallen exact tot ongeveer negen biljard.

Daarna veranderen waarden stilletjes. Een 64-bits database-identifier, een groot financieel bedrag in de kleinste eenheid — allemaal kunnen ze als een ander getal terugkomen dan verzonden, zonder foutmelding. De remedie is zulke waarden als tekenreeksen versturen.

Dubbele sleutels zijn niet verboden. Parsers verschillen in wat ze doen — de meeste houden de laatste, sommige de eerste, enkele geven een fout. Een document dat op een van beide gedrag vertrouwt, vertrouwt op een implementatie, niet op JSON.

Sleutelvolgorde wordt evenmin gegarandeerd behouden. En er zijn geen datums: de universele conventie is ISO 8601-tekenreeksen, en elke parser geeft je een tekenreeks terug die iets anders moet interpreteren.

JSON is UTF-8. De specificatie zegt dat voor alles uitgewisseld tussen systemen, en het praktische gevolg is dat een byte-order-mark niet is toegestaan — die drie onzichtbare bytes veroorzaken een parseerfout die meestal het eerste teken de schuld geeft.

Faalt een JSON-bestand om te parsen en oogt het perfect in een editor, dan is dit het eerste om te controleren. "UTF-8 zonder BOM" is de instelling.

Een JSON-document moet compleet zijn voordat het geparseerd kan worden — de sluithaak maakt het geldig — dus een array van tien gigabyte moet volledig in het geheugen geladen worden voordat het eerste record beschikbaar is.

NDJSON, ook JSON Lines genoemd, lost dat op door één compleet JSON-object per regel te zetten, zonder omringende array. Elke regel parseert onafhankelijk, dus een bestand van elke grootte streamt rij voor rij.

JSON Schema is de standaardmanier om te beschrijven wat een geldig document is, en het is het gebruiken waard voor elke interface tussen twee systemen.

Voor dagelijks werk geeft een editor met JSON-ondersteuning het belangrijkste gratis: een ontbrekende of afsluitende komma wordt ter plekke gemarkeerd, en machinaal gegenereerde JSON op één lange regel kan netjes opgemaakt worden.