La documentazione dei formati ama gli esempi giocattolo — tre righe, nomi falsi, cinque colonne. Va bene per imparare la sintassi, ma non ti dice se un formato gestisce le forme con cui hai effettivamente a che fare al lavoro. Questo articolo salta i giocattoli. Di seguito sono riportati i pattern di dati che compaiono costantemente nello sviluppo backend reale — cataloghi prodotti, log di audit, tabelle di metriche, oggetti di configurazione, transazioni finanziarie — mostrati sia in JSON che in TOON affiancati, così puoi vedere esattamente cosa stai risparmiando e dove TOON guadagna il suo posto. Tutti i dati sono realistici; nessun foo, bar o nome segnaposto in vista. Per informazioni di base sul formato stesso, vedi la guida alla sintassi TOON.
Catalogo prodotti e-commerce
Un array di prodotti è probabilmente la cosa più comune che gli sviluppatori inviano a un LLM — "classifica questi articoli", "trova il più economico in ogni categoria", "segnala tutto fuori stock con un prezzo superiore a $50". Ecco prima una fetta realistica di catalogo in JSON:
[
{"id":"PRD-1041","name":"Logitech MX Master 3S","sku":"LOG-MX3S-GRY","price":99.99,"inStock":true,"category":"Peripherals"},
{"id":"PRD-1042","name":"Samsung 970 EVO Plus 1TB","sku":"SAM-970P-1TB","price":89.99,"inStock":true,"category":"Storage"},
{"id":"PRD-1043","name":"Keychron K2 Pro","sku":"KEY-K2P-BLK","price":119.99,"inStock":false,"category":"Peripherals"},
{"id":"PRD-1044","name":"Elgato Stream Deck MK.2","sku":"ELG-SD-MK2","price":149.99,"inStock":true,"category":"Streaming"},
{"id":"PRD-1045","name":"WD Blue 2TB HDD","sku":"WD-BLU-2TB","price":54.99,"inStock":true,"category":"Storage"},
{"id":"PRD-1046","name":"Razer DeathAdder V3","sku":"RZR-DAV3-BLK","price":69.99,"inStock":true,"category":"Peripherals"},
{"id":"PRD-1047","name":"Focusrite Scarlett Solo","sku":"FOC-SC-SOLO","price":119.99,"inStock":false,"category":"Audio"}
]Ora lo stesso catalogo in TOON. Le intestazioni delle colonne sono dichiarate una volta; ogni riga è solo valori:
products[7]{id,name,sku,price,inStock,category}:
PRD-1041,Logitech MX Master 3S,LOG-MX3S-GRY,99.99,true,Peripherals
PRD-1042,Samsung 970 EVO Plus 1TB,SAM-970P-1TB,89.99,true,Storage
PRD-1043,Keychron K2 Pro,KEY-K2P-BLK,119.99,false,Peripherals
PRD-1044,Elgato Stream Deck MK.2,ELG-SD-MK2,149.99,true,Streaming
PRD-1045,WD Blue 2TB HDD,WD-BLU-2TB,54.99,true,Storage
PRD-1046,Razer DeathAdder V3,RZR-DAV3-BLK,69.99,true,Peripherals
PRD-1047,Focusrite Scarlett Solo,FOC-SC-SOLO,119.99,false,AudioAttività utente / Log di audit
I log di audit sono esattamente il tipo di dati che vorresti fornire a un LLM con un prompt come "riepiloga cosa ha fatto questo utente nell'ultima ora" o "segnala eventuali pattern di accesso sospetti". Sono ad alto volume, ripetitivi, e i nomi delle colonne sono identici su ogni riga. Le tracce di audit tendono anche ad essere la prima cosa che fa saltare la finestra di contesto quando le incolli come JSON. Ecco un log realistico di 9 righe in TOON:
auditLog[9]{userId,action,resourceId,resourceType,timestamp,ip}:
U-8821,LOGIN,,session,2024-11-14T08:02:11Z,203.0.113.47
U-8821,VIEW,DOC-4490,document,2024-11-14T08:03:44Z,203.0.113.47
U-8821,DOWNLOAD,DOC-4490,document,2024-11-14T08:03:51Z,203.0.113.47
U-8821,VIEW,DOC-4491,document,2024-11-14T08:05:02Z,203.0.113.47
U-8821,EDIT,DOC-4491,document,2024-11-14T08:07:39Z,203.0.113.47
U-8821,SHARE,DOC-4491,document,2024-11-14T08:08:12Z,203.0.113.47
U-8821,VIEW,USR-0055,user_profile,2024-11-14T08:09:58Z,203.0.113.47
U-8821,VIEW,USR-0056,user_profile,2024-11-14T08:10:03Z,203.0.113.47
U-8821,LOGOUT,,session,2024-11-14T08:11:22Z,203.0.113.47Il JSON equivalente repetirebbe "userId", "action", "resourceId", "resourceType", "timestamp", e "ip" su tutte le nove righe — 54 ripetizioni di chiave per sei nomi di campo. In TOON appaiono esattamente una volta. Per i log di audit con centinaia di voci, questa è la differenza tra far entrare i dati nel prompt e non farcela.
Dati di metriche / Limite di velocità API
Le metriche operative — percentili di latenza, tassi di errore, throughput — sono un'altra adattabilità naturale per TOON. I dati sono a prevalenza numerica e perfettamente tabulari. Potresti inviarli a un LLM per chiedere "quali endpoint hanno latenza p99 superiore a 500ms?" o "dove il tasso di errore sta aumentando?" Questa è la forma dei dati che vedresti tipicamente uscire da una Node.js pipeline di metriche o da uno scrape Prometheus:
apiMetrics[8]{endpoint,method,p50ms,p99ms,errorRate,callsPerDay}:
/api/v2/products,GET,42,118,0.002,84200
/api/v2/products/:id,GET,38,95,0.001,31500
/api/v2/orders,POST,210,880,0.015,4800
/api/v2/orders/:id,GET,55,201,0.003,19200
/api/v2/cart,PUT,95,430,0.008,22100
/api/v2/search,GET,310,1240,0.021,61000
/api/v2/users/:id,GET,29,88,0.001,9700
/api/v2/checkout,POST,540,2100,0.034,3200L'LLM può rispondere immediatamente alle domande su questa tabella senza alcun overhead di contesto. Nota che /api/v2/search e /api/v2/checkout si distinguono entrambi con p99 alto e tassi di errore elevati — esattamente il tipo di pattern che un LLM può evidenziare immediatamente quando presenti i dati in modo pulito.
Oggetto di configurazione annidato
TOON gestisce più dei semplici dati tabulari. Per oggetti strutturati — il tipo di cosa che troveresti nella configurazione runtime di un'app — TOON usa una notazione oggetto inline con struttura annidata. Pensa ad esso come una controparte dei formati di serializzazione come TOML o YAML, ma più leggero. Ecco una configurazione app realistica che mostra impostazioni del server, impostazioni del database e flag di funzionalità:
{
"server": {
"host": "0.0.0.0",
"port": 8080,
"tlsEnabled": true,
"requestTimeoutMs": 30000
},
"database": {
"host": "db.internal.example.com",
"port": 5432,
"name": "commerce_prod",
"poolSize": 20,
"sslRequired": true
},
"features": {
"newCheckoutFlow": true,
"recommendationEngine": false,
"darkMode": true,
"betaDashboard": false
}
}La stessa configurazione nella notazione oggetto TOON — le chiavi non sono quotate, la nidificazione usa parentesi graffe inline:
{
server:{host:0.0.0.0,port:8080,tlsEnabled:true,requestTimeoutMs:30000},
database:{host:db.internal.example.com,port:5432,name:commerce_prod,poolSize:20,sslRequired:true},
features:{newCheckoutFlow:true,recommendationEngine:false,darkMode:true,betaDashboard:false}
}database sopra, host:db.internal.example.com va bene così com'è — nessuna virgoletta necessaria perché il valore non contiene né l'uno né l'altro. Se un valore contiene una virgola o un due punti, avvolgilo in virgolette doppie: dsn:"host:5432,sslmode=require".Transazioni finanziarie
I dati finanziari sono un altro caso d'uso LLM ad alto valore: suggerimenti per il rilevamento di frodi, controlli di riconciliazione, categorizzazione. Il mix di ID stringa, importi numerici, codici valuta, enumerazioni di stato e timestamp si mappa in modo pulito sul formato tabulare di TOON. Ecco una fetta di transazione realistica:
transactions[9]{txId,amount,currency,from,to,status,timestamp}:
TXN-88201,1250.00,GBP,ACC-1041,ACC-2209,settled,2024-11-14T09:15:00Z
TXN-88202,89.99,USD,ACC-3301,ACC-0047,settled,2024-11-14T09:16:34Z
TXN-88203,4500.00,EUR,ACC-2001,ACC-5512,pending,2024-11-14T09:18:02Z
TXN-88204,22.50,USD,ACC-0099,ACC-3301,settled,2024-11-14T09:21:47Z
TXN-88205,750.00,GBP,ACC-5512,ACC-1041,failed,2024-11-14T09:25:10Z
TXN-88206,12000.00,USD,ACC-7700,ACC-2001,pending,2024-11-14T09:28:55Z
TXN-88207,310.00,EUR,ACC-1041,ACC-0099,settled,2024-11-14T09:31:22Z
TXN-88208,55.00,USD,ACC-3301,ACC-7700,settled,2024-11-14T09:33:40Z
TXN-88209,8900.00,GBP,ACC-2209,ACC-5512,flagged,2024-11-14T09:37:15ZIncolla questo in un prompt insieme a "segnala le transazioni superiori a £5.000 o con stato flagged o failed" e il modello risponderà in pochi secondi. La rappresentazione TOON è abbastanza compatta da poter comodamente inserire diverse centinaia di righe in un singolo prompt senza raggiungere i limiti di contesto sulla maggior parte dei modelli.
Combinare dati tabulari e oggetti in un unico documento
Ecco qualcosa che né JSON né CSV gestisce in modo pulito: un documento che ha sia un'intestazione di metadati (un singolo oggetto di configurazione) che una tabella di dati nello stesso payload. Pensa a un report con un blocco di contesto in cima — chi lo ha generato, quale periodo di tempo copre, quali filtri sono stati applicati — seguito dalle righe di dati effettive. In JSON dovresti avvolgere tutto in un oggetto envelope con una chiave "meta" e una chiave "rows", il che aggiunge un altro livello di nidificazione. CSV non può farlo affatto. TOON lo gestisce nativamente:
{report:weekly_sales,generatedAt:2024-11-14T10:00:00Z,region:EMEA,currency:EUR,generatedBy:analytics-service}
salesByRep[6]{repId,repName,deals,revenue,avgDealSize,quota}:
REP-101,Marta Kowalski,14,84200.00,6014.28,75000
REP-102,James Okafor,11,61500.00,5590.90,75000
REP-103,Yuki Tanaka,18,102400.00,5688.88,90000
REP-104,Sofia Andersen,9,47800.00,5311.11,75000
REP-105,Liam Byrne,16,93100.00,5818.75,90000
REP-106,Priya Nair,21,118600.00,5647.61,100000La prima riga è un oggetto TOON — i metadati del report. La riga vuota la separa dalla sezione tabulare che segue. Una singola chiamata decode() da @toon-format/toon restituisce entrambi. Puoi inviare questo intero documento a un LLM con una domanda come "quali rappresentanti sono sulla buona strada per raggiungere la quota?" e ha tutto il necessario: il contesto del report e i dati, in un payload compatto.
Utilizzo del pacchetto npm
Tutti questi esempi possono essere codificati e decodificati programmaticamente. Il @toon-format/toon è l'implementazione di riferimento. Installalo in qualsiasi progetto Node.js o browser:
npm install @toon-format/toonQuindi codifica i tuoi dati prima di inviarli a qualsiasi API LLM, e decodifica la risposta al ritorno:
import { encode, decode } from '@toon-format/toon';
const transactions = [
{ txId: 'TXN-88201', amount: 1250.00, currency: 'GBP', from: 'ACC-1041', to: 'ACC-2209', status: 'settled', timestamp: '2024-11-14T09:15:00Z' },
{ txId: 'TXN-88202', amount: 89.99, currency: 'USD', from: 'ACC-3301', to: 'ACC-0047', status: 'settled', timestamp: '2024-11-14T09:16:34Z' },
// ...more rows
];
// Compact TOON string — send this to your LLM prompt
const toonPayload = encode(transactions);
// When the LLM returns TOON, decode back to a JS array
const decoded = decode(toonPayload);
console.log(decoded[0].status); // "settled"Conclusioni
I pattern sopra — cataloghi prodotti, log di audit, tabelle di metriche, oggetti di configurazione, dati finanziari, documenti misti header+tabella — coprono la stragrande maggioranza dei dati strutturati che gli sviluppatori inviano effettivamente agli LLM. TOON li gestisce tutti bene, e il risparmio di token è significativo in ogni caso. La regola di base è semplice: JSON ripete i nomi delle chiavi su ogni riga; TOON no. Per la serializzazione dei dati tabulari che va in una finestra di contesto LLM, quella ripetizione è puro spreco.
Per convertire JSON esistente in TOON, usa il convertitore da JSON a TOON. Per fare il percorso inverso dopo che un LLM restituisce TOON, usa il convertitore da TOON a JSON. Il Formattatore TOON pulisce e valida le stringhe TOON, e il Validatore TOON rileverà gli errori di sintassi prima che raggiungano la tua pipeline. Il pacchetto npm @toon-format/toon gestisce la codifica e la decodifica in due righe di codice — tutti gli esempi sopra funzionano immediatamente.