La maggior parte degli sviluppatori ha una breve lista mentale di formati di dati: JSON per le API, CSV per i fogli di calcolo, YAML per i file di configurazione, forse XML se si lavora con sistemi legacy. Ma c'è un formato più recente che si sta silenziosamente facendo strada nello spazio degli strumenti AI e che vale la pena conoscere — TOON, o Token-Oriented Object Notation. È stato progettato da zero per un problema specifico: passare dati strutturati ai modelli linguistici di grandi dimensioni senza consumare il proprio budget di token.

Che cos'è TOON?

TOON sta per Token-Oriented Object Notation. È un formato di serializzazione dei dati compatto progettato appositamente per ridurre al minimo il numero di token consumati quando i dati strutturati vengono incorporati nei prompt LLM o nelle risposte. Pensatelo come JSON con tutta la verbosità eliminata — nessun nome di chiave ripetuto negli array, nessuna virgoletta ridondante, nessuno spazio finale — solo il segnale con il minimo rumore sintattico possibile.

Il pacchetto npm è @toon-format/toon, e fornisce una semplice API encode / decode che funziona in qualsiasi progetto Node.js o bundler moderno. I file TOON utilizzano l'estensione .toon.

Perché non usare semplicemente JSON?

JSON è eccellente per la comunicazione da macchina a macchina dove la larghezza di banda è economica e l'analisi è gestita dal runtime. Ma quando si inviano dati come parte di un prompt all' API OpenAI o all' API Anthropic, ogni carattere conta — letteralmente. Entrambe le API addebitano per token, e i token corrispondono approssimativamente a 4 caratteri di testo in inglese.

Considerate una tabella di 100 record utente. In JSON, si ripeterebbero le chiavi — "id", "name", "role", "email" — una volta per record. Sono 100 copie della stessa informazione strutturale. La sintassi tabulare di TOON definisce quelle chiavi una volta e poi elenca i valori riga per riga, allo stesso modo di un CSV, ma con la struttura dell'oggetto preservata. Il risparmio di token su dataset reali può essere del 40–70% rispetto a JSON compatto.

Regola empirica: Se si incorporano più di una manciata di record in un prompt, TOON sarà quasi sempre più economico di JSON. Usa il nostro convertitore da JSON a TOON per vedere esattamente quanto si riduce il payload.

Sintassi TOON in breve

TOON supporta quattro forme di dati fondamentali: scalari (stringhe, numeri, booleani), array, oggetti e dati tabulari. La sintassi scalare e delle collezioni sembrerà familiare se si è lavorato con JSON — il formato tabulare è dove TOON si differenzia davvero.

Un semplice oggetto elimina gli spazi bianchi delle parentesi graffe esterne, omette le virgolette non necessarie e separa le coppie chiave–valore con virgole:

text
{name:Alice,age:30,role:admin}

Un semplice array di scalari appare esattamente come ci si aspetterebbe:

text
[1,2,3]

Ora ecco dove diventa interessante — dati tabulari. Questa è la sintassi che rende TOON convincente per i casi d'uso LLM. Invece di ripetere le chiavi per ogni oggetto in un array, si dichiara lo schema una volta nell'intestazione e si elencano i valori riga per riga:

text
users[3]{id,name,role}:
  1,Alice,admin
  2,Bob,user
  3,Charlie,editor

Quel blocco rappresenta un array di 3 oggetti utente — equivalente al JSON sottostante — ma in una frazione dei token. L'intestazione users[3]{id,name,role} dice a un parser: "questa è una variabile chiamata users, ha 3 righe, e ogni riga corrisponde ai campi id, name e role". Le righe sono valori puri, nessuna ripetizione di chiave.

json
[
  { "id": 1, "name": "Alice", "role": "admin" },
  { "id": 2, "name": "Bob",   "role": "user"  },
  { "id": 3, "name": "Charlie", "role": "editor" }
]

Installazione e utilizzo del pacchetto @toon-format/toon

Il pacchetto npm ufficiale gestisce sia la codifica dei valori JavaScript in stringhe TOON che la decodifica delle stringhe TOON in oggetti e array JavaScript. Installalo dal registro npm:

bash
npm install @toon-format/toon

Il pacchetto esporta due funzioni — encode e decode:

ts
import { encode, decode } from '@toon-format/toon';

// Decode a TOON string → JavaScript value
const toonString = `users[3]{id,name,role}:
  1,Alice,admin
  2,Bob,user
  3,Charlie,editor`;

const users = decode(toonString);
console.log(users[0].name); // "Alice"
console.log(users[1].role); // "user"

// Encode a JavaScript value → TOON string
const config = {
  model: 'gpt-4o',
  temperature: 0.7,
  maxTokens: 1024,
  stream: true
};

const toon = encode(config, { indent: 2 });
console.log(toon);
// {model:gpt-4o,temperature:0.7,maxTokens:1024,stream:true}

L'opzione indent in encode() controlla se l'output viene formattato con rientri. Per i prompt LLM di solito si vorrà un output compatto (senza rientro) per risparmiare token. Per il debug o file .toon leggibili dall'uomo, { indent: 2 } fornisce un output ben formattato.

Un caso d'uso reale: invio di record a un LLM

Immaginate di costruire una funzione di analisi dei prodotti che deve riassumere l'attività degli utenti. Si recuperano i record di sessione recenti dal database e si vogliono inviare a un LLM per una sintesi in linguaggio naturale. Ecco come appare con TOON:

ts
import { encode } from '@toon-format/toon';

const sessions = [
  { userId: 101, action: 'login',        duration: 0,   page: '/dashboard' },
  { userId: 101, action: 'view_report',  duration: 142, page: '/reports/q1' },
  { userId: 101, action: 'export_csv',   duration: 8,   page: '/reports/q1' },
  { userId: 102, action: 'login',        duration: 0,   page: '/dashboard' },
  { userId: 102, action: 'edit_profile', duration: 37,  page: '/settings'  }
];

const toonPayload = encode(sessions);
// sessions[5]{userId,action,duration,page}:
//   101,login,0,/dashboard
//   101,view_report,142,/reports/q1
//   101,export_csv,8,/reports/q1
//   102,login,0,/dashboard
//   102,edit_profile,37,/settings

const prompt = `Summarise the following user activity. Data is in TOON format.\n\n${toonPayload}`;

La rappresentazione TOON di quei 5 record di sessione è significativamente più corta del JSON equivalente, che ripeterebbe "userId", "action", "duration" e "page" cinque volte ciascuno. Su centinaia di record il risparmio è sostanziale e si traduce direttamente in costi API inferiori e tempi di risposta più rapidi (meno token da elaborare nella finestra di attenzione).

Tipi di dati principali in TOON

TOON si mappa in modo pulito sui primitivi già usati in JavaScript e nella maggior parte degli altri linguaggi:

  • Stringhe — Non quotate quando non contengono caratteri speciali. Quotate con virgolette doppie quando includono virgole, due punti o spazi bianchi.
  • Numeri — Interi e float scritti così come sono: 42, 3.14, -7.
  • Booleani — true e false, come in JSON.
  • Null — Scritto come null per valori assenti o indefiniti.
  • Array — Sintassi inline con parentesi quadre [val1,val2,val3] per liste brevi; sintassi con intestazione tabulare per array di oggetti.
  • Oggetti — Sintassi con parentesi graffe {key:value,key2:value2} per singoli oggetti.
  • Dati tabulari — La protagonista: intestazione name[n]{col1,col2,...}: seguita da righe separate da virgole — ideale per qualsiasi collezione di record della stessa forma.

Quando usare TOON rispetto ad altri formati

TOON non cerca di sostituire JSON come formato di interscambio generico. Occupa una nicchia specifica. Ecco una guida rapida alle decisioni:

  • Usa JSON quando stai costruendo API REST, archiviando documenti in un database o passando dati tra servizi. JSON è universalmente supportato, ben strumentato e leggibile dall'uomo.
  • Usa TOON quando i dati strutturati fanno parte di un prompt o di una finestra di contesto LLM e il conteggio dei token è importante. Il formato tabulare eccelle ogni volta che si lavora con righe di record — liste utenti, voci di log, cataloghi di prodotti, eventi di analisi.
  • Usa CSV quando si hanno solo dati tabulari piatti e il consumer si aspetta CSV (fogli di calcolo, strumenti BI). CSV non ha nidificazione di oggetti, quindi TOON è più espressivo.
  • Usa YAML per file di configurazione modificati dall'uomo dove la leggibilità e i commenti contano più della compattezza.
  • Usa TOON anche per gli output degli strumenti LLM: se un LLM chiama il tuo strumento e restituisce risultati strutturati, la codifica di quei risultati in TOON risparmia token sia sul lato input che output della chiamata API.
Non sei sicuro di come TOON si confronta con il tuo payload JSON attuale? Inserisci il tuo JSON nel convertitore da JSON a TOON e lo strumento mostrerà entrambe le rappresentazioni fianco a fianco, insieme a un confronto stimato del conteggio dei token.

Conclusioni

TOON — Token-Oriented Object Notation — è un formato di serializzazione compatto costruito per l'era LLM. Mantiene la struttura familiare di JSON (oggetti, array, scalari) introducendo una sintassi tabulare che elimina la ripetizione ridondante delle chiavi tra i record. Il risultato è un formato che può essere del 40–70% più piccolo di JSON equivalente, che si traduce direttamente in costi token inferiori quando si lavora con l' API OpenAI, l'API Anthropic, o qualsiasi altro servizio LLM con fatturazione per token.

Se vuoi esplorare TOON in modo pratico, abbiamo una suite completa di strumenti proprio qui: usa il Formattatore TOON per stampare e ispezionare i documenti TOON, il Validatore TOON per rilevare gli errori di sintassi, il convertitore da JSON a TOON per migrare i payload esistenti, e il convertitore da TOON a JSON se hai bisogno di fare il percorso inverso. Il pacchetto npm @toon-format/toon ti fornisce encode e decode per integrare TOON direttamente nel tuo codice Node.js o lato browser in pochi minuti.

← All TOON articles Browse all categories →