JSON Toolkit

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.

Intermedio~6 min di letturaPubblicato il 2026-11-10Aggiornato il 2026-11-10
Sintassi dell'array tabellare TOON: intestazione dei campi dichiarata una volta, righe di dati scaricate riga per riga

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:

  1. Nomi delle chiavi ripetuti. Cinquanta record di ordini scrivono "id", "amount" e "status" cinquanta volte ciascuno. Raddoppia i dati e raddoppi l'overhead.
  2. Punteggiatura strutturale. Graffe, parentesi quadre, due punti e virgole consumano tutti token, e l'annidamento li impacchetta più fitti.
  3. 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:

  1. 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.
  2. Verifica la forma dei dati. Gli oggetti dell'array hanno tutti i campi? Normalizza prima, o concludi che la conversione non vale la pena.
  3. Converti e campiona. Dopo la conversione, confronta una riga di dati con il JSON originale per confermare che l'allineamento dei campi non è slittato.
  4. 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.