TOON vs JSON vs CSV — Choisir le bon format

Trois formats entrent dans une réunion de planification. JSON dit qu'il peut tout gérer. CSV dit qu'il est rapide et léger. TOON dit qu'il est là pour parler à l'IA. Ils ont tous raison — pour des travaux différents. La partie frustrante n'est pas que ces formats existent, c'est que choisir le mauvais pour votre cas d'utilisation vous coûte de manière réelle et concrète : des charges utiles verbeuses, des imports cassés, des factures LLM coûteuses, ou des maux de tête de parsing. Ce guide vous donne un cadre clair pour choisir.

Un portrait rapide de chaque format

JSON (JavaScript Object Notation) a émergé de JavaScript au début des années 2000 et est devenu le format dominant pour les API web grâce à sa simplicité et son expressivité. Il gère les structures imbriquées nativement, distingue entre chaînes, nombres, booléens et nulls sans cérémonie supplémentaire, et est spécifié par RFC 8259. Chaque langage moderne a une bibliothèque JSON de première classe.

CSV (Comma-Separated Values) est plus ancien que le web. Il est défini par RFC 4180 et est essentiellement la lingua franca des données tabulaires plates. Ouvrez n'importe quel CSV dans Excel, Google Sheets, ou Numbers et ça fonctionne immédiatement. Pour les tables plates pures, c'est le format le plus compact et universellement importable qui existe.

TOON est un format plus récent construit spécifiquement pour les flux de travail LLM. Il s'inspire des deux — comme CSV il utilise une structure en-tête-une-fois-puis-lignes pour les données tabulaires, mais comme JSON il peut également encoder des objets et tableaux imbriqués. Toute sa conception est orientée vers la minimisation du nombre de tokens lors du passage de données vers et depuis les grands modèles de langage.

Les mêmes données dans les trois formats

Pour rendre cela concret, utilisons un catalogue de produits qui inclut un objet specs imbriqué — une forme du monde réel qui met à l'épreuve les trois formats de manière significative. Voici quatre produits d'un magasin d'électronique :

JSON — expressif, gère l'imbrication naturellement, mais verbeux pour les données de lignes répétitives :

[
  {
    "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 — compact, compatible Excel, mais l'objet specs imbriqué doit être aplati. Il n'y a pas de façon standard de le représenter, donc nous perdons l'imbrication ou la tordons en une chaîne :

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 — en-tête déclaré une fois, lignes compactes, objets imbriqués encodés en ligne :

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}

Où chaque format échoue

Comprendre les modes d'échec est aussi important que connaître les forces.

• JSON échoue pour les tables. Répéter chaque nom de clé sur chaque ligne est véritablement gaspilleur. Un dataset de 1000 lignes où chaque ligne a 8 clés signifie "id", "name", "price" et ainsi de suite écrits 1000 fois chacun. Pour l'entrée LLM cela se traduit directement en coût de tokens ; pour l'inspection humaine c'est juste du bruit.
• CSV échoue pour les données imbriquées. Le format n'a aucun concept d'imbrication. Vous pouvez transformer un objet imbriqué en chaîne dans une cellule, mais le consommateur doit alors savoir analyser cette cellule — vous avez juste déplacé le problème. CSV n'a également aucun système de type natif : true est une chaîne, 42 est une chaîne, null est ambigu. Les outils gèrent cela de manière incohérente.
• TOON échoue en dehors des contextes LLM. C'est un format de niche avec un écosystème plus étroit. Vous ne trouverez pas de support TOON natif dans PostgreSQL, dans votre framework REST, ou dans Excel. Le package npm couvre bien les flux de travail JavaScript/TypeScript, mais si vous utilisez TOON dans un contexte qui n'a rien à voir avec l'IA, vous sur-ingénieriez probablement.
• CSV échoue pour les valeurs contenant des virgules ou des sauts de ligne. Les règles de citation RFC 4180 le gèrent, mais beaucoup de producteurs et consommateurs CSV les implémentent de manière incohérente. Un nom de produit comme 27" IPS Monitor, Black ou une description avec des sauts de ligne devient un risque de fiabilité.

Matrice de décision

Voici un guide pratique. Associez votre situation au format approprié :

• Vos données vont dans un prompt LLM → TOON. Surtout si c'est tabulaire. Utilisez JSON vers TOON pour convertir avant l'appel API.
• Vos données proviennent d'un LLM et doivent être traitées → TOON (pour la sortie), puis décodez en JSON ou objet natif pour l'utilisation en aval avec TOON vers JSON.
• Vos données sont purement tabulaires plates (mêmes clés sur chaque ligne) et vont vers/depuis les feuilles de calcul → CSV. C'est la représentation la plus petite et universellement importable.
• Vos données sont tabulaires plates mais seront transformées par du code (pas des feuilles de calcul) → CSV ou JSON. JSON est plus sûr si les types comptent (vous ne voulez pas "true" au lieu de true).
• Vos données ont des objets ou tableaux imbriqués → JSON. Ne luttez pas contre la limitation plates-uniquement de CSV. Si l'imbrication va vers un LLM, encodez en TOON après avoir construit la structure.
• Vos données vont vers une API REST ou sont stockées dans une base de données → JSON. Toujours.
• Vos données sont un fichier de configuration → JSON ou YAML. Ni CSV ni TOON n'appartient ici.
• Vous avez besoin d'une portabilité maximale et d'un analyseur sans dépendances → JSON ou CSV. Les deux ont un support natif ou quasi-natif partout.

Utiliser les trois dans un même pipeline

Un pipeline réaliste pourrait utiliser les trois. Imaginez un flux de travail e-commerce qui enrichit les données produit avec des descriptions générées par IA :

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 pour la couche API, TOON à travers la couche LLM, CSV pour la sortie consommable par l'humain. Chaque format fait exactement le travail pour lequel il a été conçu.

Référence rapide des outils

Si vous vous déplacez entre ces formats, ces outils couvriront les conversions courantes. Le formateur TOON est le moyen le plus rapide de valider et nettoyer les chaînes TOON. Le convertisseur JSON vers TOON gère l'étape de préparation LLM. Dans l'autre direction après qu'un LLM retourne du TOON, TOON vers CSV peut produire une exportation prête pour tableur directement, et CSV vers JSON est la référence pour normaliser les imports depuis Excel ou les fournisseurs de données tiers. Pour les détails spécifiques à TOON, le package officiel vit sur npm.

En résumé

JSON, CSV et TOON ont chacun un domaine clair. JSON est le format universel pour l'échange de données structurées — imbriqué ou plat, APIs, config, stockage. CSV est le format universel pour les données tabulaires plates qui doivent circuler entre systèmes et humains — feuilles de calcul, imports, exports. TOON est le format pour passer des données structurées à travers des systèmes IA efficacement, où chaque token compte. L'erreur que la plupart des développeurs font est de se rabattre sur JSON pour tout y compris les prompts LLM, ou de se rabattre sur CSV et de découvrir ensuite des besoins d'imbrication en cours de projet. Connaissez la forme de vos données, sachez où elles vont, et le bon format se choisit généralement de lui-même.

Pour une exploration plus approfondie du compromis JSON vs TOON spécifiquement, consultez la comparaison TOON vs JSON. Pour des informations sur la spécification CSV et ses particularités, l' article Wikipedia sur CSV couvre bien l'histoire et les variations de format.