Cosa è il formato TOON (Token-Oriented Object Notation)

Come TOON può cambiare il modo in cui l’IA “vede” i dati

Nel mondo dell’intelligenza artificiale moderna, in particolare quando si usano modelli di linguaggio di grandi dimensioni (Large Language Models, LLM), ogni token conta. Il costo di un’API, così come la latenza e l’efficienza del prompt, dipendono direttamente da quanti token vengono inviati al modello. In questo contesto emerge TOON (Token-Oriented Object Notation), un formato di serializzazione compatto, leggibile e progettato specificamente per ridurre al minimo il numero di token necessari per rappresentare dati strutturati.

Invece di usare il classico formato JSON (o altri), TOON “impacchetta” le stesse informazioni in un modo più snello e ottimizzato, pur restando facilmente leggibile dall’essere umano.

Vediamo più nel dettaglio cos’è TOON, perché è utile, come funziona, i suoi limiti e il suo stato attuale. 

 

Perché TOON è importante adesso

Il problema con JSON nei flussi AI

JSON è ampiamente usato per rappresentare dati strutturati. Ma ha una grammatica “verbosa”: parentesi graffe {}, quadre [], virgolette ", virgole, indentazione… tutto ciò genera token extra quando si inviano payload a un LLM.

Nei casi in cui si hanno molti oggetti uniformi (per esempio una lista di utenti, prodotti, record), le chiavi si ripetono continuamente, aumentando ulteriormente il peso in token.

La soluzione? TOON!

TOON nasce proprio per risolvere questo problema: è un formato pensato per massimizzare la token-efficienza, mantenendo però la leggibilità umana e la struttura semantica completa del JSON.
Secondo diversi benchmark, TOON può ridurre l’utilizzo di token del 30-60% rispetto al JSON tradizionale.
Questa riduzione si traduce in minori costi API, maggior spazio nella finestra di contesto del modello e, in alcuni casi, anche maggiore accuratezza nella comprensione dei dati da parte dell’LLM.

Anche in Openapi stiamo lavorando in questo senso e a breve (già dalle prossime settimane) anche le nostre API gestiranno il nuovo formato.

 

Cos’è TOON: definizione e principi

TOON è l’acronimo di Token-Oriented Object Notation. È un formato di serializzazione testo per i dati strutturati, pensato appositamente per essere inviato a LLM come input.
TOON è:

• Compatto e token-efficiente: cioè elimina molti elementi sintattici ridondanti del JSON.
  
• Schema-aware: usa dichiarazioni esplicite di lunghezza di array e campi per rendere la struttura più formale.
  
• Human-readable: rimane leggibile anche per gli sviluppatori, grazie a indentazione simile a YAML.
  
• Tabulare per array uniformi: per array in cui tutti gli oggetti hanno gli stessi campi, TOON usa una struttura a tabella (header + righe) che assomiglia al CSV.
  
  

Secondo il repository ufficiale su GitHub, TOON è lossless rispetto a JSON: si possono convertire dati JSON → TOON → JSON senza perdita di informazione.

 

Come funziona il formato TOON

Sintassi di base

Oggetti semplici

TOON elimina le parentesi graffe e usa l’indentazione per annidare. 

Per esempio:

id: 123  

name: Ada  

active: true  

Questo rappresenta lo stesso oggetto JSON { "id": 123, "name": "Ada", "active": true }.

Oggetti annidati

Usando l’indentazione simile a YAML:

user:

  id: 123  

  name: Ada  

Rappresentazione in JSON { "user": { "id": 123, "name": "Ada" } }.

Array di primitivi (“primitive array”)

TOON dichiara la lunghezza e i valori inline:

tags[3]: foo,bar,baz

Questo equivale a ["foo", "bar", "baz"] in JSON.

Array di oggetti uniformi (tabular array)

Questa è la parte più potente per il risparmio di token:

users[2]{id,name,role}:

  1,Alice,admin  

  2,Bob,user  

• users[2]: indica un array di 2 elementi
  
• {id,name,role}: le chiavi (campi) che ogni oggetto avrà
  
• Le righe sotto contengono i dati separati da virgole, una riga per ogni oggetto.
  
  
2. Opzioni di delimiter
   Per separare i valori nelle righe, TOON supporta vari delimitatori: virgola (,), tab (\t) o pipe (|).
   L'uso di tab o pipe può offrire ulteriori risparmi di token, perché riduce la necessità di quoting o escape.
   
   
3. Key folding (collasso delle chiavi)
   La specifica di TOON prevede l’opzione di “key folding”: se una struttura ha catene di chiavi con un solo livello (“wrapper” con una sola chiave), queste possono essere rappresentate con percorsi puntati per risparmiare token.
   
   
4. Quoting delle stringhe
   Le stringhe in TOON vengono quotate solo quando necessario: ad esempio se contengono il delimitatore attivo, due punti :, spazi iniziali/finali, caratteri di controllo, ecc.
   
   
5. Conversione di tipi speciali
   
   
• Numeri: formattati in forma decimale (es. non in notazione scientifica).
  
• NaN o ±Infinity diventano null.
  
• BigInt: se entro il range sicuro, convertito in numero; altrimenti, rappresentato come stringa decimale quotata.
  
• Date: convertite in stringhe ISO quotate.
  
• Valori non serializzabili tipicamente a null.
  
  

Come funziona TOON (per chi non vuole entrare nei codici)

Per chi non è sviluppatore, basti pensare a TOON come a un linguaggio più “magro” per descrivere dati.

Quando si devono inviare un gruppo di elementi tutti simili (per esempio una lista di utenti, tutti con nome, età, ruolo), TOON consente di dichiarare una volta sola quali campi ci sono (nome, età, ruolo) e poi dare riga per riga i dati. In questo modo non si deve riscrivere sempre “nome”, “età”, “ruolo” per ogni utente, come invece potrebbe succedere nel JSON classico e questo fa risparmiare “carburante” (i token).
Se ci sono dati semplici (per esempio solo una lista di tag, o parole), TOON rappresenta tutto in modo compatto: meno simboli, meno “punteggiatura inutile”.
Per dati annidati (per esempio un oggetto dentro un altro), TOON usa l’indentazione (cioè spazi) per mostrare la gerarchia, in modo simile a come funziona un documento ben organizzato, ma senza parentesi pesanti.

In breve: TOON mantiene la struttura logica dei dati, ma riduce le “parole vuote”.

 

Quali sono i vantaggi di TOON?

Di seguito elenchiamo i vantaggi dell’utilizzo del formato TOON:

1. Efficienza token

Grazie alla sintassi minimale, alla dichiarazione delle chiavi una sola volta e alla struttura tabellare, TOON consente un risparmio medio del 30-60% dei token rispetto a JSON.
Questo risparmio è particolarmente significativo nei flussi LLM dove si inviano dati tabellari ripetitivi.

2. Maggiore accuratezza (guardrails schema-aware)

TOON non è solo compatto: è schema-aware. Dichiarare la lunghezza dell’array ([N]) e i campi ({…}) aiuta i modelli LLM a validare meglio la struttura, riducendo la possibilità di errori, omissioni o “hallucinations” (allucinazioni) quando il modello deve rispondere o ragionare su dati strutturati.
Nel repository ufficiale, i benchmark mostrano che TOON può ottenere una precisione di recupero (retrieval accuracy) superiore rispetto a JSON compatto.

3. Leggibilità umana

Nonostante la riduzione di simboli, TOON rimane leggibile per gli sviluppatori grazie all’indentazione, all’organizzazione tabellare e alla sintassi molto chiara. Questo facilita il debugging, la scrittura manuale di prompt e l’interpretazione da parte di ingegneri prompt.

4. Compatibilità e perdita nulla di informazione

TOON è lossless rispetto a JSON: qualsiasi struttura JSON può essere rappresentata in TOON e riconvertita senza perdita di dati.
Esistono librerie e SDK per codificare (encode) e decodificare (decode) tra JSON e TOON in diversi linguaggi (ad es. TypeScript, Elixir, PHP).

5. Implementazioni cross-lingua

TOON non è solo un’idea astratta: ci sono implementazioni concrete in molti linguaggi:

• TypeScript / JavaScript: il repository ufficiale include SDK TypeScript 
• Elixir: implementazione Toon per Elixir
• PHP: port di TOON per PHP
• R: pacchetto CRAN per serializzare oggetti R in TOON

E altri linguaggi continuano ad arrivare grazie alla natura open-source della specifica.

Quando TOON è particolarmente utile

TOON dà il massimo vantaggio in alcuni scenari tipici:

1. Liste di elementi simili: Quando ci sono molti oggetti che condividono gli stessi campi (es. elenco di utenti, ordini, prodotti); è qui che il risparmio di token è più evidente.
   
   
2. Prompt per AI: Se si sta interagendo con un modello di AI e bisogna passare dati strutturati, TOON aiuta il modello a interpretare meglio e con meno “sovraccarico”.
   
   
3. Situazioni in cui il costo token conta: Se si paga per i token (come in molti casi con le API di modelli di AI), usare TOON può ridurre significativamente la bolletta.
   
   
4. Debug o modifiche di dati leggibili: Per chi costruisce o mette a punto i dati, la leggibilità di TOON facilita la comprensione rispetto a un JSON molto minificato.

 

Quando non usare TOON

È importante sottolineare che TOON non è sempre la scelta ideale. Ci sono casi in cui altri formati possono essere più efficienti:

1. Strutture molto annidate o non uniformi
   Se i dati hanno molti livelli di oggetti annidati o se gli array contengono oggetti con campi diversi, il risparmio token di TOON può diminuire o addirittura essere peggiore rispetto a JSON compatto.
   
   
2. Dati puramente tabulari, ma semplici
   Se si hanno solo dati piatti (tabella semplice) senza annidamento, il CSV può essere più compatto di TOON, perché TOON aggiunge metadati come la dichiarazione della lunghezza e i nomi dei campi.
   
   
3. Applicazioni con latenza critica
   In scenari in cui il tempo di serializzazione/deserializzazione conta di più dei token, potrebbe valere la pena confrontare le prestazioni: in alcune configurazioni, JSON compatto è più veloce anche se usa più token.
   
   

Come usare TOON nei prompt LLM

Encoding prima dell’invio

Si possono usare le librerie ufficiali per convertire gli oggetti JSON in TOON: ad esempio, con il pacchetto TypeScript ufficiale (@toon-format/toon)

Quando si costruisce il prompt, includere il TOON serializzato in un blocco di codice, ad esempio:

```toon

users[3]{id,name,role}:

  1,Alice,admin

  2,Bob,user

  3,Charlie,user

Questo aiuta il modello a riconoscere la struttura e a rispondere in modo coerente.

Generazione di TOON da parte dell’LLM

Se vogliamo che il modello generi dati in TOON possiamo:

• Mostrare un esempio di header TOON (come users[N]{…}:)
  
  
• Specificare che il modello deve produrre righe corrispondenti e il numero [N] corretto
  
  
• Richiedere di restituire la risposta solo nel blocco di codice e nel formato TOON
  
  

Questo schema è utile perché il modello non deve “indovinare” i nomi delle chiavi ogni volta: sono stati già dichiarati.

Esistono strumenti semplici per usare TOON

Non serve essere un esperto di programmazione per provare TOON. Ci sono strumenti pensati per chi ha dati ma non vuole scrivere codice complesso:

• Convertitori web: Esistono siti dove incollare i dati (ad esempio in JSON o CSV) e ottenere la versione TOON “ottimizzata” in modo automatico, tutto nel browser.
• Playground interattivi: Alcuni strumenti permettono anche di vedere in tempo reale quanti token occupa il formato, così da valutarne il risparmio.
• Tool sicuri: Ci sono applicazioni client-side (cioè che girano nel browser) che fanno la conversione senza inviare i dati su server esterni, garantendo maggiore privacy. 

 

Stato attuale del progetto TOON e roadmap

Il progetto TOON è attivo e open-source. Il repository ufficiale su GitHub include la specifica, il codice e i benchmark.
La specifica ufficiale (spec) è aggiornata alla versione 2.0 (working draft) ed è disponibile.
Ci sono già implementazioni in molti linguaggi, come visto sopra (TypeScript, Elixir, PHP, R, ecc.) e altri ne potrebbero arrivare.
Esistono strumenti e converter web (es. ToonParse) per convertire JSON → TOON e viceversa, lato client, senza inviare dati a server esterni.
I benchmark indicano che TOON non solo riduce i token, ma può anche migliorare la precisione di recupero (retrieval accuracy) quando si usano LLM su dati strutturati.

Criticità e cautela: cosa non è ancora confermato

Come evidenziato da alcuni commenti nella comunità, molti LLM non sono stati “allenati” su TOON: i dati di addestramento sono stati probabilmente quasi interamente in JSON o altri formati.
Ciò significa che l’uso di TOON potrebbe richiedere adattamenti, e in alcuni casi il modello potrebbe rispondere in modo meno ottimale se non “familiarizza” con la struttura.
Pur essendo open-source e in rapido sviluppo, TOON è ancora relativamente nuovo. La specifica è in evoluzione, quindi alcune implementazioni potrebbero non essere completamente compatibili tra loro se non viene seguita la versione giusta della spec.

 

In definitiva (o in sintesi se vogliamo)

TOON (Token-Oriented Object Notation) rappresenta un’innovazione significativa nella serializzazione dei dati per applicazioni LLM. Grazie alla sua struttura compatta, human-readable e schema-aware, permette di ridurre drasticamente il numero di token rispetto al JSON tradizionale (spesso fino al 60%) senza perdere la piena semantica e struttura dei dati.

Tuttavia, è importante essere realistici: ancora non tutti gli scenari sono adatti a TOON. Al momento, TOON è uno strumento affiancante al JSON: utile quando il risparmio token ha un impatto economico o tecnico, ma non ancora un sostituto universale.

Se sei uno sviluppatore che lavora con LLM, vale la pena esplorare TOON: puoi usarlo per costruire prompt più efficienti, ottimizzare i costi delle API e aumentare lo spazio utile nella finestra di contesto del modello. Ma mantieni un approccio pragmatico: misura sempre i benefici nel tuo caso d’uso e testa l’affidabilità della conversione JSON ↔ TOON nella tua pipeline.

Openapi sta per supportare TOON nelle sue API e questa è una novità molto importante: significa che le applicazioni che usano queste API potranno diventare più efficienti e meno costose, sfruttando un formato moderno e ottimizzato.