TOON vs YAML — Twee compacte formaten, zeer verschillende taken

YAML en TOON worden beiden beschreven als "leesbaarder dan JSON" — en die beschrijving is technisch waar voor beide, wat het nutteloos maakt. De echte vraag is: leesbaar voor wie, en voor welk doel? YAML is geoptimaliseerd voor menselijke bewerking: commentaar, ankers, meerregelige strings, inspringing die weerspiegelt hoe ontwikkelaars denken over configuratie. TOON is geoptimaliseerd voor machineverwerking: minimale tokens, geen dubbelzinnigheid, geen syntaxis die puur bestaat voor menselijk comfort. Dit zijn verschillende taken. Ze verwarren leidt tot YAML in LLM-prompts — wat erger is dan JSON — en TOON in Kubernetes-manifesten, die niemand met de hand wil bewerken. Dit artikel trekt de lijn duidelijk.

YAML in twee zinnen

YAML is een mensenvriendelijk dataserialisatieformaat ontworpen voor configuratiebestanden, CI/CD-pijplijnen en elk gestructureerd document dat een ontwikkelaar met de hand zal lezen, schrijven en onderhouden. De bepalende functies — inline commentaar, anker/alias DRY-mechanica, meerregelige letterlijke strings en op inspringing gebaseerde structuur — bestaan allemaal om het formaat aangenaam te maken voor mensen, niet efficiënt voor machines.

De canonieke use cases zijn GitHub Actions-workflows, Kubernetes-manifesten, Docker Compose-bestanden en applicatieconfiguratie die naast code wordt meegeleverd. Als van een mens wordt verwacht dat hij het bestand opent en bewerkt, is YAML een sterke keuze. De YAML 1.2-specificatie heeft een aantal randgevallen geformaliseerd die YAML 1.1 plaagden — het meest beruchte het Norway-probleem, waarbij de landcode NO werd geparsed als boolean false in YAML 1.1-parsers. Moderne parsers gericht op YAML 1.2 behandelen dit correct, maar het is een nuttige herinnering dat de schijnbare eenvoud van YAML echte parserscomplexiteit verbergt.

• Commentaar. # dit is een commentaar — YAML ondersteunt inline en volregel-commentaar. Dit alleen al maakt het de juiste keuze voor elke configuratie die een mens zal onderhouden.
• Ankers en aliassen. Definieer een blok één keer met &anchor, hergebruik het overal met *alias. Essentieel voor DRY Kubernetes-configs en multi-environment CI-pijplijnen.
• Meerregelige strings. Letterlijke (|) en gevouwen (>) blokscalars laten je shellscripts, SQL-queries of certificaatdata netjes insluiten in een YAML-bestand.
• Leesbare inspringing. Structuur wordt gedefinieerd door witruimte, wat op een natuurlijke manier overeenkomt met hoe ontwikkelaars denken over geneste configuratiehiërarchieën.
• Zwakke punten. Inspringgevoeligheid betekent dat een verkeerd geplaatste spatie een parsefout is. Tabtekens zijn verboden. YAML 1.1 booleaanse coercitie (Norway-probleem, yes/no, on/off) heeft echte productiebugs veroorzaakt. Tabulaire data uitgedrukt als array van objecten is nog uitgebreider dan JSON.

TOON in twee zinnen

TOON is een compact serialisatieformaat ontworpen voor het doorgeven van gestructureerde data naar en van grote taalmodellen, waarbij elke token geld kost en contextvensterruimte eindig is. De belangrijkste innovatie is tabulaire notatie: voor datasets waarbij elk record dezelfde velden deelt, worden sleutels één keer gedeclareerd in een header en weggelaten uit elke volgende rij — wat het tegenovergestelde is van wat JSON en YAML doen.

TOON is geen configuratieformaat en was nooit bedoeld als zodanig. Er is geen commentaarsyntaxis. Er zijn geen ankers. Je wilt een TOON-dataset van 500 rijen niet met de hand bewerken, net zomin als je een binair bestand met de hand wilt bewerken. Wat TOON je geeft is een formaat dat dezelfde informatie codeert als JSON in aanzienlijk minder tokens — en minder tokens betekent lagere API-kosten, grotere effectieve datasets per prompt en minder druk op contextvensterlimieten. De OpenAI-tokenizer is de snelste manier om dit in de praktijk te zien: plak dezelfde dataset in beide formaten en vergelijk.

• Tabulaire notatie. name[count]{col1,col2,...}: gevolgd door één rij waarden per regel. Sleutels verschijnen precies één keer ongeacht het rijenaantal.
• Objectnotatie. {key:value,key2:value2} — geen aanhalingstekens op sleutels, geen extra witruimte.
• Ondubbelzinnige parsing. Geen booleaanse coercitie, geen inspringgevoeligheid, geen specificatieversiedivergentie.
• Geen commentaarsyntaxis. TOON heeft geen mechanisme voor inline commentaar — by design. Het is een dataformaat, geen documentformaat.
• Zwakke punten. Niche tooling, geen verhaal voor menselijke bewerking, niet geschikt voor bestanden die een ontwikkelaar direct zal openen en bewerken.

Naast elkaar: Dezelfde data in elk formaat zijn element

De meest eerlijke vergelijking toont elk formaat doen waarvoor het goed is — niet een kop-aan-kop afdwingen waarbij één duidelijk het verkeerde gereedschap is.

Eerst een Kubernetes Deployment-manifest. Dit is YAML's thuisgebied: een door mensen onderhouden configuratiebestand met commentaar, ankers voor gedeelde waarden en diepe nesting die overeenkomt met de logische hiërarchie van een Kubernetes-object:

# Deployment manifest for the payments-service
apiVersion: apps/v1
kind: Deployment
metadata:
  name: payments-service
  namespace: production
  labels:
    app: payments-service
    version: "2.4.1"
spec:
  replicas: 3
  selector:
    matchLabels:
      app: payments-service
  template:
    metadata:
      labels:
        app: payments-service
    spec:
      containers:
        - name: payments-service
          image: registry.example.com/payments-service:2.4.1
          ports:
            - containerPort: 8080
          env:
            - name: DB_HOST
              valueFrom:
                secretKeyRef:
                  name: payments-db-secret
                  key: host
            - name: LOG_LEVEL
              value: "info"
          resources:
            requests:
              cpu: "250m"
              memory: "256Mi"
            limits:
              cpu: "500m"
              memory: "512Mi"

Dit in TOON schrijven zou zinloos zijn — het zijn geen tabulaire data, het wordt door mensen bewerkt, en het profiteert van commentaar dat niet-voor-de-hand-liggende waarden uitlegt. YAML is het juiste gereedschap hier en er is geen wedstrijd.

Nu dezelfde data in TOON's thuisgebied: een gebruikersdataset die aan een LLM wordt doorgegeven voor analyse. Dit is waar TOON's tabulaire notatie het werk doet:

users[12]{id,email,plan,mrr,country,signupDate,churned}:
  1001,[email protected],pro,99.00,US,2024-01-15,false
  1002,[email protected],starter,19.00,GB,2024-02-03,false
  1003,[email protected],enterprise,499.00,DE,2023-11-20,false
  1004,[email protected],pro,99.00,CA,2024-03-10,true
  1005,[email protected],starter,19.00,AU,2024-01-28,false
  1006,[email protected],pro,99.00,US,2023-12-05,false
  1007,[email protected],enterprise,499.00,FR,2024-02-14,false
  1008,[email protected],starter,19.00,IN,2024-03-22,true
  1009,[email protected],pro,99.00,US,2024-01-09,false
  1010,[email protected],enterprise,499.00,JP,2023-10-31,false
  1011,[email protected],starter,19.00,BR,2024-04-01,false
  1012,[email protected],pro,99.00,US,2024-02-19,true

Dit als YAML schrijven — een array van 12 objecten, elk met 7 sleutels — zou alle 7 sleutelnamen 12 keer herhalen. Dat zijn 84 sleuteldeclaraties voor 84 waarden. TOON declareert elke sleutel één keer.

Waar YAML TOON elke keer verslaat

Elk bestand dat een mens zal openen, lezen en bewerken hoort in YAML (of JSON, voor eenvoudigere gevallen). De beslissende voordelen zijn commentaar en ankers — twee functies die TOON simpelweg niet heeft.

• CI/CD-pijplijnen. GitHub Actions, GitLab CI, CircleCI — allemaal YAML-native. De mogelijkheid om een stap uit te commentariëren tijdens foutopsporing is echt nuttig.
• Kubernetes en Helm. Elk manifest, elk waarden-bestand, elke chart-template. Het YAML-ankersysteem wordt actief gebruikt in complexe Helm-charts om het herhalen van omgevingsconfiguraties te voorkomen.
• Docker Compose. Multi-service-definities met commentaar dat niet-voor-de-hand-liggende poortbindingen, volumemounts en netwerkconfiguraties uitlegt.
• Applicatieconfiguratiebestanden. pyproject.toml-stijl configs, applicatie-instellingen, feature-flags met verklarend inline commentaar.
• Elk bestand in versiebeheer dat mensen reviewen in PR's. Commentaar in YAML-configuratie maakt deel uit van de documentatie. TOON kan helemaal niet deelnemen aan deze workflow.

Waar TOON YAML elke keer verslaat

Elke data die programmatisch wordt gegenereerd en aan een LLM wordt doorgegeven hoort in TOON. YAML is eigenlijk slechter dan JSON voor dit gebruik — de inspringing-zware syntaxis en herhaalde sleutelnamen voegen tokens toe zonder informatie toe te voegen die het model nodig heeft.

• LLM-prompt-payloads. Een dataset voeden aan GPT-4o, Claude of Gemini voor analyse, classificatie of verrijking. TOON's tabulaire notatie verlaagt het tokenaantal met 40–60% vergeleken met JSON, en vergeleken met YAML is het gat nog groter.
• LLM-uitvoerinstructies. Een model instrueren om in TOON te antwoorden produceert kortere, goedkopere uitvoer. YAML-uitvoer van een LLM is uitgebreid en inspringgevoelig — één verkeerd uitgelijnde spatie en parsing mislukt.
• Programmatisch gegenereerde datasets. Als je code de data bouwt, moet het TOON bouwen. Er is geen menselijke editor die profiteert van commentaar of leesbare inspringing.
• Hoogvolume batchpijplijnen. 10.000 records per dag door een LLM laten lopen? Een tokenreductie van 50% is een reductie van 50% in die regel van je API-rekening.
• Contextvensterdruk. Wanneer je meer data wilt passen binnen de contextlimiet van een model, laat TOON je meer rijen inpakken tegen dezelfde tokenkosten.

De tokentelrealiteit

Hier is dezelfde 10-rijen dataset in drie formaten. De cijfers zijn benaderend maar consistent met wat de OpenAI-tokenizer rapporteert voor GPT-4o's tokenisatie.

YAML-array van objecten:

- id: 1
  username: alice_chen
  plan: pro
  mrr: 99.00
  country: US
- id: 2
  username: bob_martin
  plan: starter
  mrr: 19.00
  country: GB
- id: 3
  username: carol_white
  plan: enterprise
  mrr: 499.00
  country: DE
- id: 4
  username: dan_patel
  plan: pro
  mrr: 99.00
  country: CA
- id: 5
  username: eve_torres
  plan: starter
  mrr: 19.00
  country: AU
- id: 6
  username: frank_liu
  plan: pro
  mrr: 99.00
  country: US
- id: 7
  username: grace_kim
  plan: enterprise
  mrr: 499.00
  country: FR
- id: 8
  username: henry_obi
  plan: starter
  mrr: 19.00
  country: IN
- id: 9
  username: iris_novak
  plan: pro
  mrr: 99.00
  country: US
- id: 10
  username: james_sato
  plan: enterprise
  mrr: 499.00
  country: JP

TOON-tabulaire notatie, dezelfde data:

users[10]{id,username,plan,mrr,country}:
  1,alice_chen,pro,99.00,US
  2,bob_martin,starter,19.00,GB
  3,carol_white,enterprise,499.00,DE
  4,dan_patel,pro,99.00,CA
  5,eve_torres,starter,19.00,AU
  6,frank_liu,pro,99.00,US
  7,grace_kim,enterprise,499.00,FR
  8,henry_obi,starter,19.00,IN
  9,iris_novak,pro,99.00,US
  10,james_sato,enterprise,499.00,JP

De reden dat YAML slechter presteert dan JSON op tabulaire data is structureel: YAML gebruikt één regel per sleutel-waardepaar met inspringing, dus een 5-veld object kost 5 regels plus de lijstmarkering. JSON wikkelt tenminste het hele object in één set accolades. TOON elimineert sleutelherhalingen volledig — sleutels verschijnen één keer, waarden worden ingepakt in rijen. De besparingen vermenigvuldigen zich met rijenaantal en veldenaantal.

TOON gebruiken in je code

Het @toon-format/toon-pakket verwerkt coderen en decoderen:

npm install @toon-format/toon

import { encode, decode } from '@toon-format/toon';

// Your dataset — could come from a database query, API response, anywhere
const users = [
  { id: 1001, email: '[email protected]', plan: 'pro',        mrr: 99.00,  country: 'US' },
  { id: 1002, email: '[email protected]',   plan: 'starter',    mrr: 19.00,  country: 'GB' },
  { id: 1003, email: '[email protected]', plan: 'enterprise', mrr: 499.00, country: 'DE' },
  // ...more rows
];

// Encode to TOON before inserting into your LLM prompt
const toonPayload = encode(users);
// users[3]{id,email,plan,mrr,country}:
//   1001,[email protected],pro,99.00,US
//   1002,[email protected],starter,19.00,GB
//   1003,[email protected],enterprise,499.00,DE

const prompt = `Analyse this user dataset and identify churn risk signals.
Return your findings as a TOON dataset with columns: id, riskScore, reason.

Dataset:
${toonPayload}`;

// After the LLM responds with TOON output, decode it back
const llmResponse = '...'; // TOON string from the model
const findings = decode(llmResponse);
console.log(findings[0]); // { id: 1001, riskScore: 'low', reason: 'Active, pro plan' }

Beslissingsgids

De keuze tussen YAML en TOON is in de praktijk bijna nooit dubbelzinnig:

• Gebruik YAML als een mens het bestand zal lezen of bewerken — CI/CD-pijplijnen, Kubernetes-manifesten, Docker Compose, applicatieconfiguratie, Ansible-playbooks.
• Gebruik YAML als je inline commentaar nodig hebt om niet-voor-de-hand-liggende waarden uit te leggen.
• Gebruik YAML als je ankers en aliassen nodig hebt om een complexe configuratie DRY te houden.
• Gebruik YAML als je werkt met een tool die YAML bij conventie verwacht (Helm, GitHub Actions, k8s kubectl apply).
• Gebruik TOON als de data in een LLM-prompt gaat — vooral tabulaire data met meerdere rijen.
• Gebruik TOON als je een LLM vraagt om gestructureerde data te retourneren en je kortere, goedkopere uitvoer wilt.
• Gebruik TOON als het tokenaantal ertoe doet — hoogvolume pijplijnen, lange datasets, contextvensterdruk.
• Gebruik TOON als de data programmatisch wordt gegenereerd en geen mens het direct zal bewerken.
• Gebruik JSON (niet YAML of TOON) als je een REST API bouwt, data opslaat in een database of integreert met externe tooling die JSON verwacht.

Samenvatting

YAML en TOON bezetten volkomen verschillende posities in je stack. YAML hoort in je repository naast je code — configuratiebestanden, pijplijndefinities, infrastructuurmanifesten. TOON hoort aan de grens tussen je applicatie en LLM API's, waar het je gestructureerde data converteert naar de meest tokenefficiënte representatie voor verzending en de reactie van het model terugconverteert bij uitgang. Er is geen betekenisvolle overlap tussen deze taken, waardoor de vraag niet is "welke is beter" maar "welke hoort hier".

Als je met TOON werkt, zijn de TOON Formatter en TOON Validator de snelste manier om TOON-strings te inspecteren en te verifiëren. De JSON naar TOON converter converteert bestaande JSON-payloads naar TOON voor LLM-gebruik, en de TOON naar JSON converter verwerkt de terugrit wanneer een model in TOON antwoordt en je downstream-systeem JSON verwacht. Zie ook het Wikipedia-artikel over YAML voor een beknopte geschiedenis van het formaat en een samenvatting van zijn bekende randgevallen.