JSON vs YAML: de verschillen uitgelegd

Je hebt vast gemerkt dat sommige projecten .json-bestanden gebruiken voor config, terwijl andere .yaml of .yml gebruiken. Beide formaten stellen gestructureerde data voor. Beide zijn leesbaar voor mensen. Wat is het echte verschil, en wanneer kies je voor het een of het ander?

Ik heb beide uitgebreid gebruikt — JSON is mijn dagelijkse driver voor API's en data-uitwisseling, YAML is mijn go-to voor Kubernetes-manifesten, GitHub Actions en Docker Compose. Ze lossen vergelijkbare problemen op, maar hebben heel verschillende karakters.

Naast Elkaar: Dezelfde Config in Beide Formaten

Hier is een database-configuratie-object geschreven in JSON:

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "myapp",
    "ssl": true,
    "pool": {
      "min": 2,
      "max": 10
    },
    "replicas": ["replica1.db", "replica2.db"]
  }
}

En hier dezelfde config in YAML:

database:
  host: localhost
  port: 5432
  name: myapp
  ssl: true
  pool:
    min: 2
    max: 10
  replicas:
    - replica1.db
    - replica2.db

YAML is zichtbaar minder rommelig. Geen quotes om de meeste strings, geen accolades, geen komma's. Voor een configbestand dat mensen regelmatig aanpassen, telt die duidelijkheid. Maar YAML bereikt dit door aanzienlijk complexer te zijn onder de motorkap.

Waar YAML Uitblinkt

• Door mensen bewerkte configbestanden. CI/CD-pipelines (GitHub Actions, GitLab CI), Kubernetes-manifesten, Docker Compose, Ansible-playbooks. Allemaal YAML. Geen toeval — dit zijn bestanden die mensen met de hand schrijven.
• Comments. YAML ondersteunt comments met #. Enorm handig voor configbestanden waar je wilt uitleggen waarom een instelling is wat hij is. JSON ondersteunt helemaal geen comments.
• Meerdere regels strings. YAML heeft block scalars voor meerdere regels content die natuurlijk leest. JSON vereist \n escape-sequences.
• Minder visuele ruis. Geen verplichting om de meeste strings te quoten, geen sluitende accolades, geen trailing komma's om je zorgen over te maken.
• Anchors en aliases. YAML laat je een waarde eenmalig definiëren en er elders naar verwijzen met &anchor en *alias — handig voor DRY-configbestanden.

Waar JSON Wint

• Strengheid. JSON heeft één geldige weergave voor elke datastructuur. YAML heeft een dozijn manieren om hetzelfde te schrijven, wat inconsistentie binnen teams veroorzaakt.
• Geen inspringing-valkuilen. JSON gebruikt accolades en haakjes. YAML gebruikt inspringing, wat betekent dat één verkeerd geplaatste spatie je hele config stil kan breken.
• Parse-performance. JSON-parsers zijn snel en eenvoudig. YAML-parsers zijn complex — YAML 1.1 heeft notoir lastige impliciete type-coercieregels.
• Universele library-ondersteuning. Elke taal heeft een battle-tested, zero-dependency JSON-parser. YAML-libraries variëren in kwaliteit en spec-naleving.
• Tooling. Linters, formatters, schemavalidators — JSON-tooling is volwassener en breder beschikbaar.
• API-payloads. JSON is de universele taal van web-API's. YAML via HTTP sturen zou onconventioneel zijn en wrijving veroorzaken.

De YAML-Valkuilen Die Je Zullen Bijten

YAML heeft een aantal echt verrassende gedragingen die echte productie-incidenten hebben veroorzaakt. De meeste komen van de impliciete type-regels in YAML 1.1, die YAML 1.2 heeft aangescherpt. Ken deze voordat je op YAML vertrouwt voor iets kritisch:

# YAML 1.1 implicit type coercion — all of these become booleans:
enabled: yes   # → true
disabled: no   # → false
country: NO    # → false (!)  ← the Norway Problem

# Safe practice: quote strings that look like booleans
country: "NO"
enabled: "yes"

• Octale integers. In YAML 1.1 wordt 010 geparsed als 8 (octaal), niet 10. Relevant voor dingen als bestandsrechten.
• Tabs vs spaties. YAML verbiedt tabs voor inspringing. Laat er één tab van een code-editor inslippen en je bestand breekt stil of gooit een cryptische fout.
• Impliciete nulls. Een lege waarde in YAML wordt null. Makkelijk over het hoofd te zien bij handmatig bewerken.
• String vs number-ambiguïteit. port: 8080 geeft je een integer. version: 1.0 geeft je misschien een float. Soms wil je de string "1.0". Quote altijd als het uitmaakt.

Praktische Beslissingsgids

Kies YAML als je:

• Configbestanden schrijft die mensen direct bewerken: CI/CD, Kubernetes, Docker Compose, Ansible
• Het bestand comments heeft die de instellingen uitleggen
• Meerdere regels string-waarden gangbaar zijn
• Het ecosysteem waarin je werkt al YAML gebruikt (vecht niet tegen de conventie)

Kies JSON als je:

• Data verstuurt of ontvangt via een API
• De data programmatisch wordt gegenereerd en geconsumeerd (geen handmatige bewerking)
• Gegarandeerde parse-consistentie nodig hebt over verschillende tools en talen
• Werkt in een ecosysteem dat standaardiseert op JSON: npm (package.json), VS Code (settings.json), Angular, TypeScript

Converteren Tussen de Twee

Moet je YAML-config omzetten naar JSON voor een tool die geen YAML begrijpt? Gebruik de YAML naar JSON-converter. De andere kant op? De JSON naar YAML-converter regelt het. De YAML Formatter is ook handig als je YAML plakt die uit het lood is geraakt. En als je YAML niet parsed, vertelt de YAML Validator je precies waar het probleem zit.

De Conclusie

JSON en YAML zijn complementair, niet concurrerend. Gebruik JSON voor data-uitwisseling — API's, programmatische data-opslag, serialisatie. Gebruik YAML voor configbestanden die mensen lezen en bewerken. De meeste volwassen projecten gebruiken beide: package.json voor dependencies, .github/workflows/*.yml voor CI. Zodra je begrijpt waarvoor elk formaat geoptimaliseerd is, wordt de keuze vanzelfsprekend.