TOON vs YAML — Due Formati Compatti, Lavori Molto Diversi

YAML e TOON vengono entrambi descritti come "più leggibili di JSON" — e quella descrizione è tecnicamente vera per entrambi, il che la rende inutile. La vera domanda è: leggibile per chi, e per quale scopo? YAML è ottimizzato per la modifica umana: commenti, anchor, stringhe multi-riga, indentazione che rispecchia il modo in cui gli sviluppatori pensano alla configurazione. TOON è ottimizzato per l'elaborazione automatica: token minimi, nessuna ambiguità, nessuna sintassi che esiste puramente per il comfort umano. Questi sono lavori diversi. Confonderli porta YAML nei prompt LLM — che è peggio di JSON — e TOON nei manifest Kubernetes, che nessuno vuole modificare a mano. Questo articolo traccia la linea chiaramente.

YAML in due frasi

YAML è un formato di serializzazione dei dati adatto all'uomo progettato per file di configurazione, pipeline CI/CD e qualsiasi documento strutturato che uno sviluppatore leggerà, scriverà e manterrà a mano. Le sue caratteristiche distintive — commenti inline, meccanica DRY anchor/alias, letterali di stringa multi-riga e struttura basata sull'indentazione — esistono tutte per rendere il formato piacevole per gli umani, non efficiente per le macchine.

I casi d'uso canonici sono i workflow GitHub Actions, i manifest Kubernetes, i file Docker Compose e la configurazione delle applicazioni che viene fornita insieme al codice. Se ci si aspetta che un essere umano apra il file e lo modifichi, YAML è una scelta valida. La specifica YAML 1.2 ha formalizzato un certo numero di casi limite che affliggevano YAML 1.1 — il più famoso il Problema Norway, dove il codice paese NO veniva analizzato come booleano false nei parser YAML 1.1. I parser moderni che puntano a YAML 1.2 lo gestiscono correttamente, ma è un utile promemoria che la semplicità apparente di YAML nasconde una vera complessità del parser.

• Commenti. # questo è un commento — YAML supporta commenti inline e a riga intera. Questo solo lo rende la scelta giusta per qualsiasi configurazione che un umano manterrà.
• Anchor e alias. Definisci un blocco una volta con &anchor, riutilizzalo ovunque con *alias. Essenziale per le configurazioni Kubernetes DRY e le pipeline CI multi-ambiente.
• Stringhe multi-riga. Gli scalari di blocco letterali (|) e folded (>) ti permettono di incorporare in modo pulito script shell, query SQL o dati certificati all'interno di un file YAML.
• Indentazione leggibile. La struttura è definita dagli spazi bianchi, che si mappa naturalmente al modo in cui gli sviluppatori pensano alle gerarchie di configurazione annidate.
• Debolezze. La sensibilità all'indentazione significa che uno spazio mal posizionato è un errore di analisi. I caratteri tab sono vietati. La coercizione booleana YAML 1.1 (Problema Norway, yes/no, on/off) ha causato bug di produzione reali. I dati tabulari espressi come array di oggetti sono più verbosi persino di JSON.

TOON in due frasi

TOON è un formato di serializzazione compatto progettato per passare dati strutturati da e verso modelli linguistici di grandi dimensioni, dove ogni token costa denaro e lo spazio della finestra di contesto è finito. La sua innovazione chiave è la notazione tabulare: per i dataset dove ogni record condivide gli stessi campi, le chiavi vengono dichiarate una volta nell'intestazione e omesse da ogni riga successiva — che è l'opposto di ciò che fanno JSON e YAML.

TOON non è un formato di configurazione e non è mai stato pensato per esserlo. Non esiste sintassi per commenti. Non ci sono anchor. Non vorresti modificare a mano un dataset TOON di 500 righe più di quanto vorresti modificare a mano un file binario. Ciò che TOON ti dà è un formato che codifica le stesse informazioni di JSON in significativamente meno token — e meno token significa costi API inferiori, dataset effettivi più grandi per prompt e meno pressione sui limiti della finestra di contesto. Lo strumento di tokenizzazione OpenAI è il modo più rapido per vedere questo in pratica: incolla lo stesso dataset in entrambi i formati e confronta.

• Notazione tabulare. name[count]{col1,col2,...}: seguita da una riga di valori per riga. Le chiavi appaiono esattamente una volta indipendentemente dal numero di righe.
• Notazione oggetto. {key:value,key2:value2} — nessuna virgoletta sulle chiavi, nessuno spazio extra.
• Analisi non ambigua. Nessuna coercizione booleana, nessuna sensibilità all'indentazione, nessuna divergenza della versione delle specifiche.
• Nessuna sintassi per commenti. TOON non ha meccanismi per commenti inline — per design. È un formato di dati, non un formato di documento.
• Debolezze. Ecosistema di nicchia, nessuna storia di modifica umana, non appropriato per qualsiasi file che uno sviluppatore aprirà e modificherà direttamente.

Affiancati: gli stessi dati in ciò in cui ciascun formato eccelle

Il confronto più onesto mostra ciascun formato fare ciò per cui è effettivamente bravo — non forzare un testa-a-testa dove uno è chiaramente lo strumento sbagliato.

Prima, un manifest di Kubernetes Deployment. Questo è il territorio di casa di YAML: un file di configurazione mantenuto da umani con commenti, anchor per valori condivisi e nidificazione profonda che si mappa alla gerarchia logica di un oggetto Kubernetes:

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

Scriverlo in TOON sarebbe privo di senso — non sono dati tabulari, verranno modificati da umani e beneficia di commenti che spiegano valori non ovvi. YAML è lo strumento giusto qui, e non c'è gara.

Ora gli stessi dati nel territorio di casa di TOON: un dataset utente passato a un LLM per l'analisi. È qui che la notazione tabulare di TOON fa il lavoro:

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

Scriverlo come YAML — un array di 12 oggetti, ognuno con 7 chiavi — ripeterebbe tutti i 7 nomi di chiave 12 volte. Sono 84 dichiarazioni di chiave per 84 valori. TOON dichiara ogni chiave una volta.

Dove YAML batte TOON ogni volta

Qualsiasi file che un essere umano aprirà, leggerà e modificherà appartiene a YAML (o JSON, per i casi più semplici). I vantaggi decisivi sono i commenti e gli anchor — due funzioni che TOON semplicemente non ha.

• Pipeline CI/CD. GitHub Actions, GitLab CI, CircleCI — tutti nativi YAML. La possibilità di commentare un passaggio durante il debug è genuinamente utile.
• Kubernetes e Helm. Ogni manifest, ogni file values, ogni template di chart. Il sistema di anchor YAML viene utilizzato attivamente nei chart Helm complessi per evitare di ripetere le configurazioni degli ambienti.
• Docker Compose. Definizioni di servizi multipli con commenti che spiegano binding di porte non ovvi, mount di volumi e configurazioni di rete.
• File di configurazione delle applicazioni. Configurazioni in stile pyproject.toml, impostazioni delle applicazioni, flag di funzionalità con commenti esplicativi inline.
• Qualsiasi file nel controllo versione che gli umani rivedono nelle PR. I commenti nella configurazione YAML fanno parte della documentazione. TOON non può partecipare a questo flusso di lavoro affatto.

Dove TOON batte YAML ogni volta

Qualsiasi dato generato programmaticamente e passato a un LLM appartiene a TOON. YAML è effettivamente peggio di JSON per questo caso d'uso — la sua sintassi pesante di indentazione e i nomi di chiave ripetuti aggiungono token senza aggiungere informazioni di cui il modello ha bisogno.

• Payload di prompt LLM. Alimentare un dataset a GPT-4o, Claude o Gemini per analisi, classificazione o arricchimento. La notazione tabulare di TOON riduce il conteggio dei token del 40–60% rispetto a JSON, e rispetto a YAML il divario è ancora più grande.
• Istruzioni di output LLM. Istruire un modello a rispondere in TOON produce output più breve ed economico. L'output YAML da un LLM è verboso e sensibile all'indentazione — uno spazio disallineato e l'analisi si rompe.
• Dataset generati programmaticamente. Se il tuo codice sta costruendo i dati, dovrebbe costruire TOON. Non c'è editor umano che benefici di commenti o indentazione leggibile.
• Pipeline batch ad alto volume. Stai eseguendo 10.000 record attraverso un LLM al giorno? Una riduzione del 50% dei token è una riduzione del 50% di quella riga della tua fattura API.
• Pressione della finestra di contesto. Quando hai bisogno di inserire più dati entro il limite di contesto di un modello, TOON ti permette di inserire più righe allo stesso costo di token.

La realtà del conteggio dei token

Ecco lo stesso dataset di 10 righe in tre formati. I numeri sono approssimativi ma coerenti con ciò che lo strumento di tokenizzazione OpenAI riporta per la tokenizzazione di GPT-4o.

Array YAML di oggetti:

- 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

Notazione tabulare TOON, stessi dati:

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

Il motivo per cui YAML si comporta peggio di JSON sui dati tabulari è strutturale: YAML usa una riga per coppia chiave-valore con indentazione, quindi un oggetto con 5 campi costa 5 righe più il marcatore di lista. JSON almeno avvolge l'intero oggetto in un set di parentesi graffe. TOON elimina completamente la ripetizione delle chiavi — le chiavi appaiono una volta, i valori sono compressi nelle righe. I risparmi si moltiplicano con il numero di righe e il numero di campi.

Utilizzo di TOON nel codice

Il pacchetto @toon-format/toon gestisce la codifica e la decodifica:

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

Guida alle decisioni

La scelta tra YAML e TOON è quasi mai ambigua in pratica:

• Usa YAML se un umano leggerà o modificherà il file — pipeline CI/CD, manifest Kubernetes, Docker Compose, configurazione delle applicazioni, playbook Ansible.
• Usa YAML se hai bisogno di commenti inline per spiegare valori non ovvi.
• Usa YAML se hai bisogno di anchor e alias per mantenere una configurazione complessa DRY.
• Usa YAML se stai lavorando con uno strumento che si aspetta YAML per convenzione (Helm, GitHub Actions, k8s kubectl apply).
• Usa TOON se i dati vanno in un prompt LLM — specialmente dati tabulari con più righe.
• Usa TOON se stai chiedendo a un LLM di restituire dati strutturati e vuoi output più breve ed economico.
• Usa TOON se il conteggio dei token è importante — pipeline ad alto volume, dataset lunghi, pressione della finestra di contesto.
• Usa TOON se i dati vengono generati programmaticamente e nessun umano li modificherà direttamente.
• Usa JSON (non YAML o TOON) se stai costruendo un'API REST, archiviando dati in un database o integrandoti con strumenti di terze parti che si aspettano JSON.

Conclusioni

YAML e TOON occupano posizioni completamente diverse nel tuo stack. YAML appartiene nel tuo repository insieme al codice — file di configurazione, definizioni di pipeline, manifest dell'infrastruttura. TOON appartiene al confine tra la tua applicazione e le API LLM, dove converte i tuoi dati strutturati nella rappresentazione più efficiente in termini di token prima dell'invio e converte la risposta del modello al ritorno. Non esiste una sovrapposizione significativa tra questi lavori, motivo per cui la domanda non è "quale è meglio" ma "quale appartiene qui".

Se stai lavorando con TOON, il Formattatore TOON e il Validatore TOON sono il modo più rapido per ispezionare e verificare le stringhe TOON. Il convertitore da JSON a TOON converte i payload JSON esistenti in TOON per l'uso LLM, e il convertitore da TOON a JSON gestisce il viaggio di ritorno quando un modello risponde in TOON e il sistema downstream si aspetta JSON. Vedi anche il articolo di Wikipedia su YAML per una concisa storia del formato e un riepilogo dei suoi casi limite noti.