JSON, YAML en XML: wanneer gebruik je wat?

Bijna elke configuratie en elke API in de IT-wereld gebruikt een van drie tekstformaten: JSON, YAML of XML. Ze bewaren hetzelfde soort gegevens, maar ze zien er anders uit en zijn voor andere dingen handig. In dit artikel zie je de verschillen naast elkaar, waar je ze tegenkomt en welke fouten je het vaakst maakt. Handig als je een compose.yaml schrijft, een Home Assistant-automatisering aanpast of een API-antwoord wilt lezen.

Dezelfde gegevens, drie keer

Stel, je wilt een server beschrijven met een naam, een IP-adres en twee poorten. Zo ziet dat er in elk formaat uit.

JSON

{
  "naam": "nas",
  "ip": "192.168.1.20",
  "poorten": [22, 443],
  "actief": true
}

YAML

naam: nas
ip: 192.168.1.20
poorten:
  - 22
  - 443
actief: true

XML

<server>
  <naam>nas</naam>
  <ip>192.168.1.20</ip>
  <poorten>
    <poort>22</poort>
    <poort>443</poort>
  </poorten>
  <actief>true</actief>
</server>

De verschillen op een rij

	JSON	YAML	XML
Leesbaar voor mensen	Redelijk	Heel goed	Minder, veel tekst eromheen
Commentaar toegestaan	Nee	Ja, met #	Ja, met <!-- -->
Structuur	Accolades en haken	Inspringen met spaties	Open- en sluittags
Typische plek	API’s, instellingen van apps	Compose, Home Assistant, Ansible	RSS, SVG, sitemaps, oudere systemen
Strengheid	Streng: een komma te veel geeft een fout	Gevoelig voor inspringing	Streng: elke tag moet netjes dicht

JSON

JSON is de standaard voor gegevens tussen programma’s. Het kent objecten ({ } met "sleutel": waarde), lijsten ([ ]) en een paar typen: tekst, getal, true of false en null. De regels zijn strikt:

• Tekst staat altijd tussen dubbele aanhalingstekens. Enkele aanhalingstekens zijn niet geldig.
• Er mag geen komma achter het laatste element.
• Er is geen plek voor commentaar.

Een JSON-bestand dat in één lange regel staat, maak je leesbaar met de JSON-formatter. Een bepaald stuk eruit halen kan met de JSONPath-tester. Op de opdrachtregel doe je dat met jq:

jq . antwoord.json                       # netjes opmaken
jq '.poorten[]' server.json              # alle poorten tonen
python3 -m json.tool antwoord.json       # opmaken zonder jq

YAML

YAML is gemaakt om door mensen gelezen en geschreven te worden. Je gebruikt inspringen met spaties in plaats van haken en accolades, en je mag commentaar toevoegen. Daarom zie je het in Docker Compose, Home Assistant, Ansible en veel Kubernetes-bestanden.

De valkuilen:

• Tabs zijn niet toegestaan. Gebruik spaties, meestal twee per niveau. Een verkeerd ingesprongen regel hoort ineens bij een ander onderdeel of geeft een fout.
• Poorten als tekst. Een waarde als 22:22 kan door sommige parsers als een getal in het zestigtallig stelsel worden gelezen. Zet poortkoppelingen daarom tussen aanhalingstekens: "22:22". Docker raadt dit zelf ook aan.
• Waarden die op iets anders lijken. In sommige YAML-programma’s worden yes, no, on en off gelezen als waar en onwaar. Een versienummer als 3.10 kan 3.1 worden. Twijfel je, zet de tekst dan tussen aanhalingstekens.
• Dubbele punt in tekst. Een waarde die : bevat, hoort tussen aanhalingstekens.

Maak je een fout en weet je niet waar? Plak je bestand in de YAML ↔ JSON-tool: een fout in de inspringing komt dan meteen aan het licht. Staat het in een compose-bestand, dan vindt de Compose-validator ook dubbele poorten en ontbrekende volumes.

XML

XML bestaat al het langst. Het gebruikt tags met een naam, kan ook attributen hebben (<poort protocol="tcp">22</poort>) en is erg precies. Je komt het tegen in RSS-feeds, sitemaps, SVG-afbeeldingen, Maven en Android-instellingen, en in de beschrijving van virtuele machines in libvirt.

• Elke tag moet gesloten worden, en in de juiste volgorde.
• Tekens als & en < in de tekst moet je schrijven als & en <.

Met de XML-formatter maak je XML leesbaar en controleer je of het geldig is. Op de opdrachtregel kan dat met xmllint --format bestand.xml (pakket libxml2-utils).

Omzetten tussen formaten

JSON en YAML lijken sterk op elkaar: bijna elk JSON-bestand is ook geldige YAML. Omzetten van het ene naar het andere gaat dus meestal zonder verlies, behalve voor commentaar, want dat kent JSON niet. Gebruik daarvoor de YAML ↔ JSON-tool. Van XML naar JSON is lastiger, omdat XML attributen en volgorde kent die JSON niet heeft.

Welk formaat kies je?

• Een API of gegevens tussen programma’s: JSON.
• Een bestand dat jij met de hand bewerkt: YAML, vanwege de leesbaarheid en het commentaar.
• Het formaat wordt je opgelegd door het programma of de standaard (RSS, SVG): XML.

En kies je zelf niet? Dan gebruik je gewoon wat het programma verwacht. De meeste fouten komen niet van het kiezen van het formaat, maar van een komma, een spatie of een aanhalingsteken op de verkeerde plek.