TOON vs JSON vs CSV — Scegliere il Formato Giusto

Tre formati entrano in una riunione di pianificazione. JSON dice che può gestire qualsiasi cosa. CSV dice che è veloce e leggero. TOON dice che è lì per parlare con l'AI. Hanno tutti ragione — per lavori diversi. La parte frustrante non è che questi formati esistano, è che scegliere quello sbagliato per il tuo caso d'uso ti costa in modi reali e concreti: payload verbosi, importazioni rotte, costose fatture LLM, o mal di testa nell'analisi. Questa guida ti fornisce un framework chiaro per scegliere.

Un rapido ritratto di ciascun formato

JSON (JavaScript Object Notation) è emerso da JavaScript all'inizio degli anni 2000 ed è diventato il formato dominante per le API web grazie alla sua semplicità ed espressività. Gestisce le strutture annidate nativamente, distingue tra stringhe, numeri, booleani e null senza alcuna cerimonia aggiuntiva, ed è specificato dalla RFC 8259. Ogni linguaggio moderno ha una libreria JSON di prima classe.

CSV (Comma-Separated Values) è più vecchio del web. È definito dalla RFC 4180 ed è essenzialmente la lingua franca dei dati tabulari piatti. Apri qualsiasi CSV in Excel, Google Sheets, o Numbers e funziona subito. Per le tabelle piatte pure, è il formato più compatto e universalmente importabile che esiste.

TOON è un formato più recente costruito specificamente per i flussi di lavoro LLM. Si ispira a entrambi — come CSV utilizza una struttura intestazione-una-volta-poi-righe per i dati tabulari, ma come JSON può anche codificare oggetti e array annidati. L'intero design è orientato alla minimizzazione del conteggio dei token quando si passano dati da e verso i modelli linguistici di grandi dimensioni.

Gli stessi dati in tutti e tre i formati

Per rendere questo concreto, usiamo un catalogo di prodotti che include un oggetto specs annidato — una forma del mondo reale che esercita tutti e tre i formati in modo significativo. Ecco quattro prodotti da un negozio di elettronica:

JSON — espressivo, gestisce la nidificazione naturalmente, ma verboso per dati di riga ripetitivi:

[
  {
    "id": "P001",
    "name": "Wireless Headphones",
    "category": "Audio",
    "price": 79.99,
    "inStock": true,
    "specs": { "weight": "250g", "connectivity": "Bluetooth 5.2", "battery": "30h" }
  },
  {
    "id": "P002",
    "name": "USB-C Docking Station",
    "category": "Peripherals",
    "price": 129.99,
    "inStock": true,
    "specs": { "ports": 11, "maxPower": "100W", "display": "4K@60Hz" }
  },
  {
    "id": "P003",
    "name": "Mechanical Keyboard",
    "category": "Input",
    "price": 94.99,
    "inStock": false,
    "specs": { "layout": "TKL", "switches": "Cherry MX Red", "backlight": "RGB" }
  },
  {
    "id": "P004",
    "name": "27" IPS Monitor",
    "category": "Display",
    "price": 299.99,
    "inStock": true,
    "specs": { "resolution": "2560x1440", "refreshRate": "165Hz", "panel": "IPS" }
  }
]

CSV — compatto, compatibile con Excel, ma l'oggetto specs annidato deve essere appiattito. Non esiste un modo standard per rappresentarlo, quindi o si perde la nidificazione o la si manomette in una stringa:

id,name,category,price,inStock,specs_weight,specs_ports,specs_layout,specs_resolution
P001,Wireless Headphones,Audio,79.99,true,250g,,,
P002,USB-C Docking Station,Peripherals,129.99,true,,11,,
P003,Mechanical Keyboard,Input,94.99,false,,,TKL,
P004,27" IPS Monitor,Display,299.99,true,,,,2560x1440

TOON — intestazione dichiarata una volta, righe compatte, oggetti annidati codificati inline:

products[4]{id,name,category,price,inStock,specs}:
  P001,Wireless Headphones,Audio,79.99,true,{weight:250g,connectivity:Bluetooth 5.2,battery:30h}
  P002,USB-C Docking Station,Peripherals,129.99,true,{ports:11,maxPower:100W,display:4K@60Hz}
  P003,Mechanical Keyboard,Input,94.99,false,{layout:TKL,switches:Cherry MX Red,backlight:RGB}
  P004,27" IPS Monitor,Display,299.99,true,{resolution:2560x1440,refreshRate:165Hz,panel:IPS}

Dove ogni formato si rompe

Comprendere i punti di rottura è importante quanto conoscere i punti di forza.

• JSON si rompe per le tabelle. Ripetere ogni nome di chiave su ogni riga è genuinamente dispendioso. Un dataset di 1000 righe dove ogni riga ha 8 chiavi significa "id", "name", "price" e così via scritti 1000 volte ciascuno. Per l'input LLM questo si traduce direttamente in costo dei token; per l'ispezione umana è solo rumore.
• CSV si rompe per i dati annidati. Il formato non ha concetto di nidificazione. Puoi stringificare un oggetto annidato in una cella, ma poi il consumer deve sapere di analizzare quella cella — hai solo spostato il problema. CSV non ha nemmeno un sistema di tipi nativo: true è una stringa, 42 è una stringa, null è ambiguo. Gli strumenti lo gestiscono in modo incoerente.
• TOON si rompe fuori dai contesti LLM. È un formato di nicchia con un ecosistema più ristretto. Non troverai supporto TOON nativo in PostgreSQL, nel tuo framework REST o in Excel. Il pacchetto npm copre bene i flussi di lavoro JavaScript/TypeScript, ma se stai cercando TOON in un contesto che non ha nulla a che fare con l'AI, probabilmente stai sovra-ingegnerizzando.
• CSV si rompe per valori contenenti virgole o a capo riga. Le regole di quoting RFC 4180 lo gestiscono, ma molti produttori e consumer CSV li implementano in modo incoerente. Un nome di prodotto come 27" IPS Monitor, Black o una descrizione con interruzioni di riga diventa un pericolo di affidabilità.

Matrice decisionale

Ecco una guida pratica. Abbina la tua situazione al formato appropriato:

• I tuoi dati vanno in un prompt LLM → TOON. Soprattutto se sono tabulari. Usa da JSON a TOON per convertire prima della chiamata API.
• I tuoi dati tornano da un LLM e devono essere elaborati → TOON (per l'output), poi decodifica in JSON o un oggetto nativo per uso downstream con da TOON a JSON.
• I tuoi dati sono puramente tabulari piatti (stesse chiavi su ogni riga) e vanno a/da fogli di calcolo → CSV. È la rappresentazione più piccola e universalmente importabile.
• I tuoi dati sono tabulari piatti ma saranno trasformati dal codice (non dai fogli di calcolo) → CSV o JSON. JSON è più sicuro se i tipi sono importanti (non vuoi "true" invece di true).
• I tuoi dati hanno oggetti o array annidati → JSON. Non combattere il limite solo-piatto di CSV. Se la nidificazione va a un LLM, codifica in TOON dopo aver costruito la struttura.
• I tuoi dati vanno a un'API REST o sono archiviati in un database → JSON. Sempre.
• I tuoi dati sono un file di configurazione → JSON o YAML. Né CSV né TOON appartengono qui.
• Hai bisogno della massima portabilità e di un parser senza dipendenze → JSON o CSV. Entrambi hanno supporto nativo o quasi-nativo ovunque.

Utilizzare tutti e tre in una pipeline

Una pipeline realistica potrebbe usarli tutti e tre. Immagina un flusso di lavoro e-commerce che arricchisce i dati dei prodotti con descrizioni generate dall'AI:

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

// Step 1: Products arrive as JSON from your REST API
const products = await fetch('/api/products').then(r => r.json());

// Step 2: Encode to TOON to minimise tokens before the LLM call
const toonInput = encode(products);

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: `Here is our product catalogue in TOON format:\n\n${toonInput}\n\n
                For each product, write a one-sentence marketing description.
                Return results as TOON with fields: id, description`
    }
  ]
});

// Step 3: Decode the LLM's TOON response back to objects
const enriched = decode(response.choices[0].message.content);

// Step 4: Export to CSV for the marketing team's spreadsheet
const csvRows = enriched.map(row => `${row.id},"${row.description}"`);
const csv = ['id,description', ...csvRows].join('\n');

JSON per il livello API, TOON attraverso il livello LLM, CSV per l'output leggibile dall'uomo. Ogni formato sta facendo esattamente il lavoro per cui è stato progettato.

Riferimento rapido agli strumenti

Se stai passando da un formato all'altro, questi strumenti copriranno le conversioni comuni. Il Formattatore TOON è il modo più rapido per validare e pulire le stringhe TOON. Il convertitore da JSON a TOON gestisce il passaggio di preparazione LLM. Andando nell'altra direzione dopo che un LLM restituisce TOON, da TOON a CSV può produrre un export pronto per fogli di calcolo direttamente, e da CSV a JSON è il punto di riferimento per normalizzare le importazioni da Excel o fornitori di dati di terze parti. Per i dettagli specifici di TOON, il pacchetto ufficiale si trova su npm.

Conclusioni

JSON, CSV e TOON hanno ciascuno un dominio chiaro. JSON è il formato universale per lo scambio di dati strutturati — annidato o piatto, API, configurazione, archiviazione. CSV è il formato universale per i dati tabulari piatti che devono viaggiare tra sistemi e persone — fogli di calcolo, importazioni, esportazioni. TOON è il formato per passare dati strutturati attraverso i sistemi AI in modo efficiente, dove ogni token conta. L'errore che la maggior parte degli sviluppatori commette è passare a JSON per tutto inclusi i prompt LLM, o passare a CSV e poi scoprire requisiti di nidificazione a metà progetto. Conosci la forma dei tuoi dati, sappi dove stanno andando, e il formato giusto di solito si sceglie da solo.

Per un approfondimento specifico sul tradeoff JSON vs TOON, consulta il confronto TOON vs JSON. Per informazioni sulla specifica CSV e le sue peculiarità, il articolo di Wikipedia su CSV copre bene la storia e le varianti del formato.