Guida alla Sintassi TOON — Dagli Scalari ai Dati Tabulari

La maggior parte dei formati di dati è stata progettata per un pubblico: umani o macchine. JSON tende verso gli umani. I formati binari come MessagePack tendono verso le macchine. TOON è esplicitamente progettato per un terzo pubblico che non esisteva quando quei formati furono inventati: i modelli linguistici di grandi dimensioni. Ogni decisione sintattica in TOON dà priorità all'efficienza dei token — inserendo il massimo dei dati strutturati nel minimo di token così da poter passare più contesto a un'AI senza sforare il budget. Questa guida copre ogni funzione di sintassi TOON, dai semplici scalari alla notazione tabulare che lo rende genuinamente diverso.

Cosa rende TOON diverso

TOON sta per Token-Optimised Object Notation. L'idea centrale è semplice: i formati di serializzazione dei dati come JSON sono stati progettati molto prima che i prezzi API per token fossero una cosa. JSON va bene per la comunicazione da macchina a macchina, ma quando il tuo payload è un dataset di 200 righe diretto in un prompt gpt-4o, stai pagando per ogni virgoletta, ogni parentesi graffa e ogni nome di chiave ripetuto. TOON elimina questo spreco. Si installa come un singolo pacchetto npm — @toon-format/toon — e i file usano l'estensione .toon.

Valori scalari — Stringhe, Numeri, Booleani

Gli scalari TOON sembrano molto simili alle loro controparti JSON, con una differenza importante: i valori stringa non richiedono virgolette a meno che non contengano caratteri speciali come virgole, due punti o parentesi quadre. Questo da solo elimina una parte significativa di token dai dataset ricchi di testo.

// Numbers — exactly like JSON
42
3.14
-7

// Booleans — lowercase, same as JSON
true
false

// Strings — no quotes needed for simple values
hello
Alice
Widget Pro

Quando una stringa contiene una virgola, un due punti o una parentesi quadra, avvolgila in virgolette doppie come in JSON. Quindi "New York, NY" ha bisogno di virgolette, ma London no. Regola semplice, grandi risparmi.

Oggetti — Coppie Chiave:Valore senza rumore

Gli oggetti TOON usano parentesi graffe con la sintassi chiave:valore. Le chiavi non sono mai quotate — da solo risparmia due caratteri per chiave rispetto a JSON. Le coppie sono separate da virgole. Nessuna virgola finale, nessun due punti dopo l'ultima coppia.

{name:Alice,age:31,city:London,active:true}

Confronta con il JSON equivalente:

{"name": "Alice", "age": 31, "city": "London", "active": true}

Stessi dati, meno caratteri, e il risparmio di token si moltiplica drammaticamente quando si lavora con array di oggetti. A proposito...

Array — Liste ordinate di valori

Gli array in TOON usano parentesi quadre con valori separati da virgole — esattamente come JSON, solo senza virgolette sui valori stringa semplici.

// Array of strings
[Alice,Bob,Carol]

// Array of numbers
[10,20,30,40,50]

// Mixed types (same rules as JSON)
[Widget Pro,29.99,true,101]

// Array of objects
[{id:1,name:Alice},{id:2,name:Bob}]

Gli array di oggetti funzionano, ma è qui che entra in gioco la killer feature di TOON. Se hai più di due o tre righe di dati strutturati, la notazione tabulare è notevolmente più efficiente.

Notazione tabulare — La funzione che cambia tutto

La notazione tabulare è la funzione principale di TOON. È progettata per lo scenario che si incontra costantemente nel lavoro reale: un elenco di oggetti simili — prodotti, utenti, transazioni, voci di log — dove ripetere le chiavi su ogni riga è puro spreco. La sintassi è:

name[count]{col1,col2,col3,...}:
  row1val1,row1val2,row1val3
  row2val1,row2val2,row2val3

Analizzandola: name è l'etichetta del dataset, [count] è il numero di righe di dati (obbligatorio — dice al parser esattamente quante righe leggere), {col1,col2,...} è la riga di intestazione, i due punti : terminano l'intestazione, e ogni successiva riga indentata è una riga di valori. Ecco un esempio reale di prodotti:

products[5]{id,name,price,inStock,category}:
  101,Widget Pro,29.99,true,Tools
  102,Gadget Plus,49.99,true,Electronics
  103,Thing Basic,9.99,false,Misc
  104,Super Doohickey,74.99,true,Electronics
  105,Budget Widget,14.99,true,Tools

Ora immagina gli stessi dati come un array di oggetti JSON. Scriveresti "id", "name", "price", "inStock" e "category" cinque volte ciascuno — più tutte le parentesi graffe, le parentesi quadre e le virgolette circostanti. La rappresentazione TOON tabulare è circa il 60% più piccola nel conteggio dei token per questa forma di dati.

Un dataset di utenti segue lo stesso schema:

users[4]{id,username,email,role,active}:
  1,alice_dev,[email protected],admin,true
  2,bob_writer,[email protected],editor,true
  3,carol_ops,[email protected],viewer,false
  4,dan_qa,[email protected],editor,true

Nidificazione — Oggetti, Array e Tabulare insieme

TOON supporta la nidificazione nei posti che ci si aspetterebbe. Un oggetto può contenere un valore array. Una riga tabulare può contenere un oggetto. Questo permette di rappresentare dati del mondo reale che non si adattano perfettamente alle righe piatte.

Oggetto contenente un array:

{name:Alice,roles:[admin,editor],active:true}

Dati tabulari con un oggetto incorporato in una colonna (utile per dati di indirizzo, metadati, ecc.):

orders[3]{orderId,customer,total,address}:
  1001,alice_dev,89.97,{city:London,country:UK}
  1002,bob_writer,49.99,{city:Berlin,country:DE}
  1003,carol_ops,124.50,{city:Paris,country:FR}

Mantieni la nidificazione superficiale quando possibile. Due o tre livelli di profondità è dove TOON vince ancora nel conteggio dei token. Le strutture profondamente ricorsive sono meglio servite da JSON, che ha strumenti più ricchi per la validazione dello schema — vedi il riferimento JSON MDN se ne hai bisogno.

Lavorare con il pacchetto npm

Installa con npm o qualsiasi gestore di pacchetti compatibile. TOON funziona in Node.js e nei browser moderni.

npm install @toon-format/toon

Il pacchetto esporta due funzioni: encode e decode. Questa è l'intera API pubblica — intenzionalmente minimale.

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

// decode: TOON string → JS value
const toonString = `products[3]{id,name,price,inStock}:
  101,Widget Pro,29.99,true
  102,Gadget Plus,49.99,true
  103,Thing Basic,9.99,false`;

const data = decode(toonString);
console.log(data);
// [
//   { id: 101, name: "Widget Pro", price: 29.99, inStock: true },
//   { id: 102, name: "Gadget Plus", price: 49.99, inStock: true },
//   { id: 103, name: "Thing Basic", price: 9.99, inStock: false }
// ]

// encode: JS value → TOON string
const users = [
  { id: 1, username: 'alice_dev', active: true },
  { id: 2, username: 'bob_writer', active: false }
];

const toon = encode(users, { indent: 2 });
console.log(toon);
// users[2]{id,username,active}:
//   1,alice_dev,true
//   2,bob_writer,false

L'opzione { indent: 2 } controlla il rientro dei valori delle righe. Puoi anche usare encode su semplici oggetti e valori primitivi, non solo array — sceglie automaticamente la rappresentazione TOON più compatta. Incolla l'output nel Formattatore TOON per ispezionarlo e stamparlo con rientri.

Errori comuni

Questi sono gli errori che colgono di sorpresa gli sviluppatori nuovi a TOON, di solito nella prima ora:

• Conteggio righe sbagliato nella notazione tabulare. Scrivere products[3] ma poi includere 4 righe di dati causerà un errore di analisi o eliminerà silenziosamente l'ultima riga a seconda della versione del parser. Conta le righe e tieni aggiornato il numero. Il Validatore TOON lo rileva immediatamente.
• Virgolettare le chiavi degli oggetti. {"name":Alice} è TOON non valido — le chiavi non vengono mai quotate. Elimina le virgolette: {name:Alice}.
• Dimenticare i due punti dopo l'intestazione. products[2]{id,name} seguito da una nuova riga fallirà. È necessario il due punti finale: products[2]{id,name}:.
• Usare spazi intorno ai due punti nelle coppie chiave:valore. {name : Alice} non è valido. Nessuno spazio: {name:Alice}.
• Incorporare virgole in valori stringa non quotati. Se il nome di un prodotto è "Bulloni, Dadi e Altro", devi quotarlo nelle righe tabulari: 101,"Bulloni, Dadi & Altro",4.99,true.
• Aspettarsi output JSON da decode sugli scalari. decode("42") restituisce il numero JavaScript 42, non un oggetto JSON. TOON decodifica nei tipi JS nativi.

Conversione tra TOON e JSON

TOON e JSON sono completamente intercambiabili — TOON è un superset dello stesso modello di dati logico che JSON serializza. Usa da JSON a TOON per ridurre un dataset esistente prima di inviarlo a un LLM, e da TOON a JSON per riconvertire quando hai bisogno di alimentare il risultato in un sistema downstream solo-JSON. Le funzioni encode e decode lo gestiscono programmaticamente se stai automatizzando il flusso di lavoro in Node.js. La specifica della struttura dati sottostante è strettamente correlata ai concetti di JSON globale in JavaScript.

Conclusioni

La sintassi TOON è intenzionalmente compatta. Nessuna chiave quotata, nessun nome di chiave ripetuto nelle tabelle, nessuna virgoletta obbligatoria sui valori stringa semplici. Una volta scritto a mano un blocco tabulare vedrai immediatamente perché — un dataset che occupa 40 righe di JSON si adatta in 8 righe di TOON. Il pacchetto npm su npmjs.com/@toon-format/toon mantiene la superficie API minimale: encode e decode, nient'altro da imparare. Usa il Formattatore TOON per stampare con rientri, Validatore TOON per rilevare gli errori di sintassi, da JSON a TOON per convertire i dati esistenti, e da TOON a JSON quando hai bisogno del risultato di nuovo in forma standard.