TOON vs YAML — Two Compact Formats, Very Different Jobs

YAML og TOON beskrives begge som "mere læsbare end JSON" — og den beskrivelse er teknisk korrekt for begge, hvilket gør den ubrugelig. Det virkelige spørgsmål er: læsbar for hvem, og til hvilket formål? YAML er optimeret til menneskelig redigering: kommentarer, ankre, flerlinjesstrenge, indrykning, der afspejler, hvordan udviklere tænker på konfiguration. TOON er optimeret til maskinbehandling: minimale tokens, ingen tvetydighed, ingen syntaks, der kun eksisterer til menneskelig komfort. Dette er forskellige job. At forveksle dem fører til YAML i LLM-prompts — hvilket er værre end JSON — og TOON i Kubernetes-manifester, som ingen ønsker at redigere i hånden. Denne artikel trækker linjen tydeligt.

YAML i to sætninger

YAML er et menneskevenligt dataserialiseringsformat designet til konfigurationsfiler, CI/CD-rørledninger og ethvert struktureret dokument, som en udvikler vil læse, skrive og vedligeholde i hånden. Dets definerende funktioner — inline-kommentarer, anker/alias DRY-mekanik, flerlinjes strengliteraler og indrykningsbaseret struktur — eksisterer alle for at gøre formatet behageligt for mennesker, ikke effektivt for maskiner.

De kanoniske use cases er GitHub Actions-arbejdsgange, Kubernetes-manifester, Docker Compose-filer og applikationskonfiguration, der leveres ved siden af kode. Hvis et menneske forventes at åbne filen og redigere den, er YAML et stærkt valg. YAML 1.2-specifikationen formaliserede en række edge cases, der plagede YAML 1.1 — mest berygtet Norge-problemet, hvor landekoden NO parsede som booleansk false i YAML 1.1-parsere. Moderne parsere, der retter sig mod YAML 1.2, håndterer dette korrekt, men det er en nyttig påmindelse om, at YAMLs tilsyneladende enkelhed gemmer på reel parserkompleksitet.

• Kommentarer. # dette er en kommentar — YAML understøtter inline- og fuldlinjekommentarer. Dette alene gør det til det rigtige valg for enhver konfiguration, et menneske vil vedligeholde.
• Ankre og aliaser. Definer en blok én gang med &anchor, genbrug den overalt med *alias. Afgørende for DRY Kubernetes-konfigurationer og multi-miljø CI-rørledninger.
• Flerlinjesstrenge. Literal (|) og foldet (>) blok-skalarer lader dig indlejre shell-scripts, SQL-forespørgsler eller certifikatdata rent i en YAML-fil.
• Læselig indrykning. Struktur defineres af whitespace, som naturligt afspejler, hvordan udviklere tænker om indlejrede konfigurationshierarkier.
• Svagheder. Indryktningsfølsomhed betyder, at et misplaceret mellemrum er en parse-fejl. Tab-tegn er forbudt. YAML 1.1 booleansk tvang (Norge-problemet, yes/no, on/off) har forårsaget rigtige produktionsfejl. Tabeldata udtrykt som et array af objekter er mere ordrigt end selv JSON.

TOON i to sætninger

TOON er et kompakt serialiseringsformat designet til at sende strukturerede data til og fra store sprogmodeller, hvor hvert token koster penge og kontekstvinduepladsen er begrænset. Dets vigtigste innovation er tabelnotation: for datasæt, hvor hver post deler de samme felter, erklæres nøgler én gang i en header og udelades fra alle efterfølgende rækker — hvilket er det modsatte af, hvad JSON og YAML gør.

TOON er ikke et konfigurationsformat og var aldrig meningen at være det. Der er ingen kommenter-syntaks. Der er ingen ankre. Du ville ikke ville redigere et 500-rækkers TOON-datasæt i hånden mere end du ville redigere en binær fil i hånden. Hvad TOON giver dig er et format, der koder de samme oplysninger som JSON i betydeligt færre tokens — og færre tokens betyder lavere API-omkostninger, større effektive datasæt pr. prompt og mindre pres på kontekstvinduegrænser. OpenAI-tokenizeren er den hurtigste måde at se dette i praksis: indsæt det samme datasæt i begge formater og sammenlign.

• Tabelnotation. name[count]{col1,col2,...}: efterfulgt af én rækkei værdier pr. linje. Nøgler fremgår præcis én gang uanset rækketal.
• Objektnotation. {key:value,key2:value2} — ingen anførselstegn på nøgler, ingen ekstra whitespace.
• Utvetydig parsing. Ingen booleansk tvang, ingen indrykningsfølsomhed, ingen spec-version-divergens.
• Ingen kommenter-syntaks. TOON har ingen mekanisme til inline-kommentarer — af design. Det er et dataformat, ikke et dokumentformat.
• Svagheder. Niche-værktøjer, ingen menneskeredigeringshistorie, ikke egnet til filer en udvikler vil åbne og redigere direkte.

Side om side: de samme data i hvert formats element

Den mest ærlige sammenligning viser hvert format, der gør det, det faktisk er godt til — ikke tvinger et hoved-til-hoved, hvor det ene er åbenlyst det forkerte værktøj.

Først et Kubernetes Deployment-manifest. Dette er YAMLs hjemmebane: en menneskeholdt konfigurationsfil med kommentarer, ankre for delte værdier og dyb indlejring, der kortlægger til den logiske hierarki i et Kubernetes-objekt:

# 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"

At skrive det i TOON ville være meningsløst — det er ikke tabeldata, det vil blive redigeret af mennesker, og det drager fordel af kommentarer, der forklarer ikke-åbenlyse værdier. YAML er det rigtige værktøj her, og der er ingen konkurrence.

Nu de samme data i TOONs hjemmebane: et brugerdatasæt, der sendes til en LLM til analyse. Det er her TOONs tabelnotation udfører arbejdet:

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

At skrive det som YAML — et array af 12 objekter, hvert med 7 nøgler — ville gentage alle 7 nøglenavne 12 gange. Det er 84 nøgleerklæringer for 84 værdier. TOON erklærer hver nøgle én gang.

Hvor YAML slår TOON hver gang

Enhver fil, som et menneske vil åbne, læse og redigere, hører hjemme i YAML (eller JSON, for enklere tilfælde). De afgørende fordele er kommentarer og ankre — to funktioner TOON simpelthen ikke har.

• CI/CD-rørledninger. GitHub Actions, GitLab CI, CircleCI — alle YAML-native. Muligheden for at udkommentere et trin under fejlretning er genuint nyttigt.
• Kubernetes og Helm. Alle manifester, alle values-filer, alle chart-skabeloner. YAML-ankersystemet bruges aktivt i komplekse Helm-charts for at undgå at gentage miljøkonfigurationer.
• Docker Compose. Multi-service-definitioner med kommentarer, der forklarer ikke-åbenlyse portbindinger, volumenmounts og netværkskonfigurationer.
• Applikationskonfigurationsfiler. pyproject.toml-stil-konfigurationer, applikationsindstillinger, funktionsflags med forklarende kommentarer inline.
• Enhver fil i versionskontrol, som mennesker gennemgår i PR'er. Kommentarer i YAML-konfiguration er en del af dokumentationen. TOON kan slet ikke deltage i denne arbejdsgang.

Hvor TOON slår YAML hver gang

Alle data, der genereres programmatisk og sendes til en LLM, hører hjemme i TOON. YAML er faktisk værre end JSON til dette use case — dens indrykningsintensive syntaks og gentagne nøglenavne tilføjer tokens uden at tilføje nogen information, som modellen har brug for.

• LLM-prompt-payloads. Fodring af et datasæt til GPT-4o, Claude eller Gemini til analyse, klassificering eller berigelse. TOONs tabelnotation skærer tokenantal med 40–60% sammenlignet med JSON, og sammenlignet med YAML er gabet endnu større.
• LLM-output-instruktioner. At instruere en model i at svare i TOON producerer kortere, billigere output. YAML-output fra en LLM er ordrig og indrykningsfølsom — ét fejlplaceret mellemrum og parsing bryder ned.
• Programmatisk genererede datasæt. Hvis din kode bygger dataene, bør den bygge TOON. Der er ingen menneskelig redaktør til at drage fordel af kommentarer eller læselig indrykning.
• Høj-volume batch-rørledninger. Kører du 10.000 poster gennem en LLM om dagen? En 50% tokenreduktion er en 50% reduktion i den linje af din API-regning.
• Kontekstvindues-pres. Når du skal passe mere data inden for en models kontekstgrænse, lader TOON dig pakke flere rækker ind til de samme tokenomkostninger.

Tokenantal-virkelighed

Her er det samme 10-rækkers datasæt i tre formater. Tallene er omtrentlige, men konsistente med, hvad OpenAI-tokenizeren rapporterer for GPT-4os tokenisering.

YAML-array af objekter:

- 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-tabelnotation, samme 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

Grunden til, at YAML klarer sig dårligere end JSON på tabeldata, er strukturel: YAML bruger én linje pr. nøgle-værdi-par med indrykning, så et 5-felts objekt koster 5 linjer plus listemarkøren. JSON omgiver i det mindste hele objektet i ét sæt klammeparenteser. TOON eliminerer nøglegentagelse fuldstændigt — nøgler fremgår én gang, værdier pakkes ind i rækker. Besparelserne vokser med rækketal og feltantal.

Brug af TOON i din kode

Pakken @toon-format/toon håndterer kodning og afkodning:

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' }

Beslutningsguide

Valget mellem YAML og TOON er næsten aldrig tvetydigt i praksis:

• Brug YAML, hvis et menneske vil læse eller redigere filen — CI/CD-rørledninger, Kubernetes-manifester, Docker Compose, applikationskonfiguration, Ansible-playbooks.
• Brug YAML, hvis du har brug for inline-kommentarer til at forklare ikke-åbenlyse værdier.
• Brug YAML, hvis du har brug for ankre og aliaser for at holde en kompleks konfiguration DRY.
• Brug YAML, hvis du arbejder med et værktøj, der forventer YAML af konvention (Helm, GitHub Actions, k8s kubectl apply).
• Brug TOON, hvis dataene skal ind i en LLM-prompt — særligt tabeldata med flere rækker.
• Brug TOON, hvis du beder en LLM om at returnere strukturerede data og ønsker kortere, billigere output.
• Brug TOON, hvis tokenantal har betydning — høj-volume rørledninger, lange datasæt, kontekstvindues-pres.
• Brug TOON, hvis dataene genereres programmatisk, og intet menneske vil redigere dem direkte.
• Brug JSON (ikke YAML eller TOON), hvis du bygger et REST API, gemmer data i en database eller integrerer med tredjepartsværktøjer, der forventer JSON.

Opsummering

YAML og TOON besidder fuldstændigt forskellige positioner i dit stack. YAML hører hjemme i dit repository ved siden af din kode — konfigurationsfiler, rørledningsdefinitioner, infrastrukturmanifester. TOON hører hjemme ved grænsen mellem din applikation og LLM API'er, hvor det konverterer dine strukturerede data til den mest tokeneffektive repræsentation, inden de sendes, og konverterer modellens svar tilbage på vej ud. Der er ingen meningsfuld overlap mellem disse job, hvilket er grunden til, at spørgsmålet ikke er "hvad er bedst" men "hvad hører hjemme her".

Hvis du arbejder med TOON, er TOON Formatter og TOON Validator den hurtigste måde at inspicere og verificere TOON-strenge på. JSON til TOON-konverteren konverterer eksisterende JSON-payloads til TOON til LLM-brug, og TOON til JSON-konverteren håndterer returrejsen, når en model svarer i TOON, og dit downstream-system forventer JSON. Se også Wikipedia-artiklen om YAML for en kortfattet historik om formatet og en opsummering af dets kendte edge cases.