Guida al formato TOON: alleggerire il JSON prima di darlo a un LLM
In sintesi: Quando passi un array uniforme a un modello linguistico in formato JSON, i nomi delle chiavi ripetuti e le parentesi consumano token. TOON dichiara la struttura una sola volta con oggetti indentati e array tabellari, e scarica i dati riga per riga. I benchmark ufficiali mostrano circa il 40% di token in meno con maggiore accuratezza di parsing. Questa guida copre la sintassi, quando il risparmio si applica, quando non conviene convertire e come collegare encode e decode.

L'overhead sintattico del JSON è irrilevante in un trasferimento tra macchine, ma sul lato di input di un LLM fatturato a token è denaro reale: lo stesso array uniforme ripete i nomi delle chiavi decine di volte, e ogni parentesi graffa e ogni virgoletta prendono una fetta del budget. TOON non inventa un nuovo modello di dati — riscrive il modello di dati JSON con una notazione più economica.
Che cos'è TOON: un'altra codifica di JSON, non un concorrente
TOON (Token-Oriented Object Notation) è un formato aperto apparso nel 2025, e il posizionamento ufficiale sta in una frase: una codifica compatta, senza perdita di dati e leggibile del modello di dati JSON. Non introduce tipi nuovi — oggetti, array, stringhe, numeri, booleani e null corrispondono uno a uno al JSON, e decode(encode(x)) è strettamente uguale ai dati originali (i tipi fuori dal JSON come Date o NaN vanno normalizzati prima). Il round-trip è senza perdite e deterministico: lo stesso input produce sempre lo stesso output, cosa importante per costruire prompt riproducibili.
Poiché codifica esattamente il modello di dati JSON, il modo corretto di usare TOON è come formato di frontiera: l'applicazione continua a lavorare in JSON internamente, converte in TOON subito prima di mettere i dati in un prompt e riconverte alla risposta del modello. La documentazione ufficiale lo chiama "translation layer". L'estensione convenzionale dei file è .toon; per il trasporto HTTP il media type provvisorio è text/toon, in UTF-8.
Un avvertimento sul rumore di ricerca: non confonderlo con i Toon Shader della grafica 3D. Condividono solo la parola.
Perché il JSON è particolarmente costoso sul lato input di un LLM
Prendi una lista di ordini, un elenco utenti o un riassunto di log scritti come array JSON. I token vanno in tre posti:
- Nomi delle chiavi ripetuti. Cinquanta record di ordini scrivono
"id","amount"e"status"cinquanta volte ciascuno. Raddoppia i dati e raddoppi l'overhead. - Punteggiatura strutturale. Graffe, parentesi quadre, due punti e virgole consumano tutti token, e l'annidamento li impacchetta più fitti.
- Virgolette. Quasi ogni chiave e ogni valore stringa è avvolto in doppi apici.
Sommando il tutto: il costo dell'API fatturato a token sale direttamente; gli input lunghi toccano prima il tetto della finestra di contesto; e su input molto lunghi il modello omette o disallinea i campi più spesso. Il benchmark della pagina ufficiale: su un set di test a strutture miste e quattro modelli, circa il 40% di token in meno con l'accuratezza di parsing che sale dal 70% (JSON) al 74% (TOON). Risparmio e accuratezza qui non sono un trade-off, perché la struttura più compatta rende i confini più visibili al modello.
La sintassi: oggetti indentati + array tabellari
Gli stessi dati di previsione meteo in tre forme. Versione JSON, circa 117 token:
{
"location": { "city": "Berlin", "country": "DE", "units": "metric" },
"alerts": ["frost", "wind"],
"forecast": [
{ "day": "Mon", "temp": { "min": -2, "max": 4 }, "condition": "snow", "rainChance": 80 },
{ "day": "Tue", "temp": { "min": 1, "max": 7 }, "condition": "cloudy", "rainChance": 20 },
{ "day": "Wed", "temp": { "min": 3, "max": 11 }, "condition": "sunny", "rainChance": 5 }
]
}
Versione TOON, circa 66 token:
location:
city: Berlin
country: DE
units: metric
alerts[2]: frost,wind
forecast[3]{day,temp{min,max},condition,rainChance}:
Mon,-2,4,snow,80
Tue,1,7,cloudy,20
Wed,3,11,sunny,5
Tre forme coprono tutto, e il serializzatore le sceglie automaticamente dalla forma dei dati:
| Forma | Adatta a | Equivalente JSON |
|---|---|---|
| Oggetto indentato | Oggetti annidati | { "location": { ... } }, l'indentazione sostituisce le graffe |
| Array in linea | Array di primitivi | ["frost","wind"], [2] dichiara la lunghezza |
| Array tabellare | Array di oggetti uniformi | I nomi dei campi compaiono una sola volta nell'intestazione {day,temp{min,max},...}; ogni riga contiene solo valori separati da virgole |
Gli oggetti annidati uniformi (temp{min,max}) si ripiegano nell'intestazione come gruppo di campi annidato, e le righe di dati restano piatte. La regola delle virgolette è minimale: le stringhe prendono virgolette solo se contengono delimitatori, caratteri speciali o rischierebbero di essere letti come numeri — una delle ragioni per cui TOON batte il "JSON compatto" nel conteggio dei token. La differenza chiave con YAML: TOON ha dichiarazioni di lunghezza esplicite e intestazioni di campi verificabili dalle macchine; con CSV: conserva l'annidamento e i tipi.
[N] e {fields}: parapetti strutturali per il modello
[3] e {day,...} non servono solo a risparmiare token — sono anche un contratto verificabile consegnato al modello:
- La lunghezza dell'array permette al modello di rispondere direttamente a "quanti record contiene il dataset" e smaschera subito un troncamento quando il numero di righe non torna.
- L'intestazione dei campi dichiara i nomi una volta; il modello allinea i valori per posizione invece di reindovinare la corrispondenza delle chiavi a ogni riga.
Questa è prevenzione, l'opposto del recupero a posteriori. Un riparatore di JSON (vedi la pipeline di riparazione) recupera i dati dopo che il modello ha sputato JSON rotto; le dichiarazioni di lunghezza e campi di TOON riducono, in ingresso, la probabilità di dati rotti. Fai entrambe le cose e il tasso di fallimento del parsing a metà pipeline scende.
Quando non usare TOON
La sezione ufficiale "When Not to Use TOON" è rinfrescantemente diretta. Quattro scenari, da tenere così come sono:
| Scenario | Perché evitare | Scelta migliore |
|---|---|---|
| Strutture profondamente annidate, non uniformi | Idoneità tabellare ≈ 0%; il JSON compatto spesso vince | JSON compatto |
| Array semi-uniformi | Campi irregolari, il risparmio svanisce | Mantieni la pipeline JSON |
| Dati puramente tabellari | TOON costa il 5–10% di overhead rispetto a CSV | CSV |
| Sensibile alla latenza (modelli locali/quantizzati) | Meno token ≠ inferenza più rapida | Misura prima il TTFT |
Il semi-uniforme si giudica dall'idoneità tabellare (tabular eligibility): ufficialmente, con un'idoneità del 40–60% il risparmio è già marginale. Una migrazione di formato ha costi reali — parser, validatori e script a valle cambiano tutti — quindi se il guadagno è sotto il dieci per cento, non toccare nulla.
Messa in opera: encode / decode e la CLI
La libreria TypeScript ufficiale, in entrambe le direzioni:
npm install @toon-format/toon
# La conversione in blocco passa anche dalla CLI
npx @toon-format/cli input.json -o output.toon
import { encode, decode } from '@toon-format/toon'
const data = {
users: [
{ id: 1, name: 'Ada', role: 'admin' },
{ id: 2, name: 'Bob', role: 'user' },
],
}
const toon = encode(data)
// users[2]{id,name,role}:
// 1,Ada,admin
// 2,Bob,user
const back = decode(toon) // strettamente uguale ai dati originali
Esistono implementazioni Python, Go, Rust e .NET; consulta la lista delle implementazioni nel repository ufficiale della specifica prima di adottarne una, e conferma che copra le caratteristiche sintattiche che usi. Prima della produzione, esegui un'asserzione di round-trip: decode(encode(originali)) deve essere profondamente uguale all'originale; se non lo è, l'implementazione o i dati hanno un problema.
Come si incastra nella tua catena JSON esistente
TOON non cambia nulla nella tua pipeline JSON; aggiunge una conversione di frontiera. Ordine consigliato:
- Assicurati prima che il JSON sia pulito. JSON rotto produce TOON rotto. La validazione sintattica e la riparazione sono coperte nella Guida alla riparazione di JSON.
- Verifica la forma dei dati. Gli oggetti dell'array hanno tutti i campi? Normalizza prima, o concludi che la conversione non vale la pena.
- Converti e campiona. Dopo la conversione, confronta una riga di dati con il JSON originale per confermare che l'allineamento dei campi non è slittato.
- Stima il beneficio. Per liste uniformi, il ragionamento riga per riga del manuale JSONL si applica alla conversione in flusso; per il rapporto tra dimensione e costo, la vera relazione tra JSON minify e gzip dà la stessa lezione: misurare prima, convertire dopo.
TOON sostituirà JSON?
No. TOON codifica il modello di dati JSON; il suo posto è la frontiera del prompt, mentre l'archiviazione e lo scambio tra programmi restano territorio JSON. Usa TOON per il segmento "dare al modello" e lascia intatto il resto della catena.
Che rapporto ha TOON con YAML e CSV?
Gli oggetti somigliano a YAML (indentazione al posto delle graffe); gli array uniformi somigliano a CSV (intestazione dichiarata una volta, righe in flusso). Ma TOON ha dichiarazioni di lunghezza esplicite che YAML non ha, e conserva annidamento e tipi che CSV non ha — sta tra i due, con parapetti verificabili dalle macchine.
La conversione da TOON a JSON perde dati?
No: oggetti, array, stringhe, numeri, booleani e null corrispondono uno a uno, e decode(encode(x)) è strettamente uguale. L'unica cautela è normalizzare prima i tipi fuori dal JSON come Date e NaN; altrimenti l'uguaglianza vale solo dopo il round-trip.
Come verifico che il TOON convertito sia corretto?
Due controlli: un'asserzione di round-trip (encode e poi decode, uguaglianza profonda con l'originale) e un'ispezione visiva dell'intestazione — il numero di [N] deve eguagliare il numero di righe, e i campi di {fields} devono allinearsi uno a uno con i valori separati da virgole di ogni riga. Sul lato modello, puoi anche chiedergli di riportare la lunghezza dell'array prima di rispondere.