JSON vs YAML vs XML: syntaxis, toepassingen en omzetten

JSON, YAML en XML zijn allemaal platte-tekstformaten voor gestructureerde gegevens. Geef ze dezelfde informatie en ze beschrijven die alle drie correct, maar in de praktijk heeft elk formaat zijn eigen terrein gevonden: JSON in API's, YAML in configuratiebestanden, XML in documenten en bedrijfssystemen. Als je weet waarom, kies je het juiste formaat en kom je bij het omzetten niet voor verrassingen te staan.

Dezelfde gegevens in drie formaten

Hier is de definitie van een kleine service, op drie manieren geschreven. Eerst JSON:

{
  "service": "web",
  "port": 8080,
  "debug": false,
  "tags": ["api", "public"]
}

Hetzelfde in YAML:

# web service
service: web
port: 8080
debug: false
tags:
  - api
  - public

En in XML:

<?xml version="1.0" encoding="UTF-8"?>
<service name="web">
  <port>8080</port>
  <debug>false</debug>
  <tags>
    <tag>api</tag>
    <tag>public</tag>
  </tags>
</service>

Een paar verschillen vallen meteen op:

• JSON gebruikt accolades, vierkante haken en aanhalingstekens. Het is streng: geen commentaar, geen komma aan het eind, sleutels altijd tussen dubbele aanhalingstekens.
• YAML vertrouwt op inspringing in plaats van haakjes en staat commentaar toe met #. Het is het compactst en het makkelijkst in één oogopslag te lezen.
• XML zet elke waarde tussen een openings- en sluittag en kan attributen aan elementen koppelen (name="web"). Het is het meest omslachtig, maar ook het meest expressief.

JSON: de taal van API's

JSON sluit direct aan op de objecten en arrays van vrijwel elke programmeertaal, en werd daardoor het standaardformaat van web-API's. Parsers zijn snel, ingebouwd in browsers en standaardbibliotheken, en de grammatica is zo klein dat er weinig manieren zijn om een document verkeerd te lezen.

Die strengheid is een voordeel voor machines en een klein ongemak voor mensen. Je kunt geen commentaar achterlaten om een instelling uit te leggen, en één ontbrekende komma maakt het hele bestand ongeldig. Daarom werkt JSON het best als software het schrijft en software het leest: API-antwoorden, logs, data-exports, package.json.

YAML: configuratie geschreven door mensen

YAML is ontworpen om door mensen geschreven en nagekeken te worden. Daarom kozen zoveel DevOps-tools ervoor: Kubernetes-manifesten, GitHub Actions-workflows en Docker Compose-bestanden zijn allemaal YAML. Commentaar, strings over meerdere regels en het ontbreken van leestekens maken lange configuratiebestanden prettig om te onderhouden.

De keerzijde zijn de subtiliteiten. Inspringing heeft betekenis, dus één verkeerd geplaatste spatie verandert de structuur. En YAML raadt het type van waarden zonder aanhalingstekens, wat tot zijn bekendste valkuilen leidt:

country: NO      # YAML 1.1: false
version: 1.10    # 1.1 (number)
zip: 01234       # 1234 or octal

Volgens de regels van YAML 1.1, die veel parsers nog gebruiken, worden NO, yes, on en off booleans. Getallen verliezen hun nullen aan het eind en voorloopnullen kunnen als octaal worden gelezen. De oplossing is eenvoudig: zet alles wat tekst moet blijven tussen aanhalingstekens.

country: "NO"
version: "1.10"
zip: "01234"

XML: documenten, schema's en zakelijke feeds

XML is ouder dan de andere twee en heeft functies die zij missen: namespaces om vocabulaires te combineren, schema's (XSD) om de structuur streng te valideren, attributen en gemengde inhoud waarin tekst en tags elkaar afwisselen. Dat maakt het geschikt voor documenten en voor systemen waarin een formeel contract telt: RSS- en Atom-feeds, SOAP-services, facturatie- en bankstandaarden, SVG-afbeeldingen, de pom.xml van Maven en de bestanden in een DOCX of XLSX.

Begin je aan iets nieuws en hoef je alleen gegevens uit te wisselen, dan is XML zelden de eerste keuze. Maar je blijft het ontvangen van partners, oudere systemen en openbare databronnen, dus weten hoe je het naar JSON omzet is een erg praktische vaardigheid.

Snelle vergelijking

• Leesbaarheid: YAML > JSON > XML.
• Strengheid en voorspelbaarheid: JSON en XML zijn eenduidig; YAML hangt af van inspringing en typeherkenning.
• Commentaar: YAML en XML wel, JSON niet.
• Validatie: XML heeft de meest volwassen schematools; JSON Schema wordt breed gebruikt; YAML wordt meestal ook met JSON Schema gevalideerd.
• Typisch terrein: JSON voor API's en data, YAML voor configuratie, XML voor documenten en zakelijke integratie.

Omzetten: waar je op moet letten

Omdat alle drie gegevensbomen beschrijven, is omzetten meestal eenvoudig. Een paar details zijn wel goed om te weten:

• Van YAML naar JSON verdwijnt het commentaar. JSON heeft er geen plek voor. Ankers en aliassen (& en *) worden uitgeschreven tot gewone kopieën.
• Van JSON naar YAML gaat niets verloren. Elk geldig JSON-document is in YAML uit te drukken; in YAML 1.2 is JSON vrijwel een deelverzameling van YAML.
• XML-attributen vragen om een afspraak. JSON kent geen attributen, dus converters slaan ze op als gewone sleutels, vaak met een voorvoegsel zoals @. Controleer het resultaat voordat je het aan een ander programma doorgeeft.
• Eén element of een lijst. In XML zien één <tag> en drie <tag>-elementen er hetzelfde uit. In JSON kan het ene een object worden en het andere een array, dus code die het resultaat verwerkt moet beide aankunnen.
• In XML is alles tekst. 8080 en false zijn gewoon tekens tussen tags; van XML naar JSON moet je ze misschien terugzetten naar een getal of boolean.
• Van JSON naar XML is één root-element nodig en sleutels die geldige elementnamen zijn (geen spaties, niet beginnend met een cijfer).

Omzetten in je browser

De dataconverters van Azpy werken volledig in je browser: plak je tekst of sleep een bestand erin en het resultaat verschijnt direct, zonder dat er iets wordt geüpload. Je kunt ze dus zorgeloos gebruiken voor configuratiebestanden met interne hostnamen of API-antwoorden met klantgegevens. JSON naar YAML, YAML naar JSON, XML naar JSON en JSON naar XML vind je tussen de tools.

Een vuistregel

Machines die met machines praten → JSON. Mensen die configuratie bewerken → YAML, met aanhalingstekens rond alles wat dubbelzinnig is. Documenten, strenge schema's of een bestaand zakelijk contract → XML. En is het formaat dat je hebt niet het formaat dat je nodig hebt, zet het dan om en controleer de randgevallen hierboven.