Guide de syntaxe TOON — Des scalaires aux données tabulaires

La plupart des formats de données ont été conçus pour un seul public : les humains ou les machines. JSON penche vers l'humain. Les formats binaires comme MessagePack penchent vers la machine. TOON est explicitement conçu pour un troisième public qui n'existait pas lorsque ces formats ont été inventés : les grands modèles de langage. Chaque décision syntaxique de TOON priorise l'efficacité des tokens — faire rentrer le maximum de données structurées dans le minimum de tokens pour pouvoir passer plus de contexte à une IA sans faire exploser votre budget. Ce guide couvre chaque fonctionnalité syntaxique TOON, des scalaires simples à la notation tabulaire qui le rend véritablement différent.

Ce qui rend TOON différent

TOON signifie Token-Optimised Object Notation. L'idée centrale est simple : les formats de sérialisation de données comme JSON ont été conçus bien avant que la tarification API par token soit une réalité. JSON convient pour la communication machine à machine, mais quand votre charge utile est un dataset de 200 lignes entrant dans un prompt gpt-4o, vous payez pour chaque guillemet, chaque accolade et chaque nom de clé répété. TOON élimine ce gaspillage. Il s'installe comme un seul package npm — @toon-format/toon — et les fichiers utilisent l'extension .toon.

Valeurs scalaires — chaînes, nombres, booléens

Les scalaires TOON ressemblent beaucoup à leurs homologues JSON, avec une différence importante : les valeurs de chaîne ne nécessitent pas de guillemets sauf si elles contiennent des caractères spéciaux comme des virgules, des deux-points ou des crochets. Cela seul coupe une portion significative de tokens dans les datasets lourds en texte.

// 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

Quand une chaîne contient une virgule, un deux-points ou un crochet, enveloppez-la dans des guillemets doubles comme en JSON. Donc "New York, NY" nécessite des guillemets, mais London non. Règle simple, grandes économies.

Objets — paires clé:valeur sans le bruit

Les objets TOON utilisent des accolades avec une syntaxe key:value. Les clés ne sont jamais entre guillemets — cela seul économise deux caractères par clé par rapport à JSON. Les paires sont séparées par des virgules. Pas de virgules finales, pas de deux-points après la dernière paire.

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

Comparez cela au JSON équivalent :

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

Mêmes données, moins de caractères, et les économies de tokens se multiplient considérablement quand vous travaillez avec des tableaux d'objets. À ce sujet...

Tableaux — listes ordonnées de valeurs

Les tableaux en TOON utilisent des crochets avec des valeurs séparées par des virgules — exactement comme JSON, juste sans guillemets sur les valeurs de chaîne nues.

// 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}]

Les tableaux d'objets fonctionnent, mais c'est là que la fonctionnalité phare de TOON entre en jeu. Si vous avez plus de deux ou trois lignes de données structurées, la notation tabulaire est dramatiquement plus efficace.

Notation tabulaire — la fonctionnalité qui change tout

La notation tabulaire est la fonctionnalité principale de TOON. Elle est conçue pour le scénario que vous rencontrez constamment dans le travail réel : une liste d'objets similaires — produits, utilisateurs, transactions, entrées de journal — où répéter les clés sur chaque ligne est du pur gaspillage. La syntaxe est :

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

En détail : name est l'étiquette du dataset, [count] est le nombre de lignes de données (requis — il indique au parseur exactement combien de lignes lire), {col1,col2,...} est la ligne d'en-tête, le deux-points : termine l'en-tête, et chaque ligne indentée suivante est une ligne de valeurs. Voici un vrai exemple de produits :

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

Imaginez maintenant ces mêmes données comme un tableau d'objets JSON. Vous écririez "id", "name", "price", "inStock" et "category" cinq fois chacun — plus toutes les accolades, crochets et guillemets entourants. La représentation TOON tabulaire est environ 60% plus petite en nombre de tokens pour cette forme de données.

Un dataset d'utilisateurs suit le même pattern :

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

Imbrication — objets, tableaux et tabulaire ensemble

TOON supporte l'imbrication aux endroits attendus. Un objet peut contenir une valeur de tableau. Une ligne tabulaire peut contenir un objet. Cela vous permet de représenter des données du monde réel qui ne s'adaptent pas parfaitement aux lignes plates.

Objet contenant un tableau :

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

Données tabulaires avec un objet intégré dans une colonne (utile pour les données d'adresse, les métadonnées, etc.) :

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}

Gardez l'imbrication peu profonde quand c'est possible. Deux ou trois niveaux de profondeur, c'est là où TOON gagne encore sur le nombre de tokens. Les structures profondément récursives sont mieux servies par JSON, qui a un outillage plus riche pour la validation de schéma — voir la référence JSON MDN si vous en avez besoin.

Travailler avec le package npm

Installez avec npm ou tout gestionnaire de packages compatible. TOON fonctionne dans Node.js et les navigateurs modernes.

npm install @toon-format/toon

Le package exporte deux fonctions : encode et decode. C'est toute l'API publique — intentionnellement 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'option { indent: 2 } contrôle l'indentation des valeurs de ligne. Vous pouvez également utiliser encode sur des objets simples et des valeurs primitives, pas seulement les tableaux — il choisit automatiquement la représentation TOON la plus compacte. Collez la sortie dans le formateur TOON pour l'inspecter et l'afficher proprement.

Erreurs courantes

Ce sont les erreurs qui piègent les développeurs nouveaux dans TOON, généralement dans la première heure :

• Mauvais nombre de lignes dans la notation tabulaire. Écrire products[3] mais inclure ensuite 4 lignes de données causera une erreur de parsing ou abandonnera silencieusement la dernière ligne selon la version du parseur. Comptez vos lignes et gardez le nombre à jour. Le validateur TOON le détecte immédiatement.
• Mettre les clés d'objet entre guillemets. {"name":Alice} est du TOON invalide — les clés ne sont jamais entre guillemets. Supprimez les guillemets : {name:Alice}.
• Oublier le deux-points après l'en-tête. products[2]{id,name} suivi d'une nouvelle ligne échouera. Vous avez besoin du deux-points final : products[2]{id,name}:.
• Utiliser des espaces autour du deux-points dans les paires clé:valeur. {name : Alice} n'est pas valide. Pas d'espaces : {name:Alice}.
• Intégrer des virgules dans des valeurs de chaîne non entre guillemets. Si un nom de produit est "Bolts, Nuts & More", vous devez le mettre entre guillemets dans les lignes tabulaires : 101,"Bolts, Nuts & More",4.99,true.
• S'attendre à une sortie JSON de decode sur les scalaires. decode("42") retourne le nombre JavaScript 42, pas un objet JSON. TOON décode vers des types JS natifs.

Conversion entre TOON et JSON

TOON et JSON sont entièrement interconvertibles — TOON est un sur-ensemble du même modèle de données logique que JSON sérialise. Utilisez JSON vers TOON pour réduire un dataset existant avant de l'envoyer à un LLM, et TOON vers JSON pour reconvertir quand vous devez alimenter le résultat dans un système aval uniquement JSON. Les fonctions encode et decode gèrent cela programmatiquement si vous automatisez le flux de travail dans Node.js. La spécification de structure de données sous-jacente est étroitement liée aux concepts de l'objet JSON global en JavaScript.

En résumé

La syntaxe TOON est intentionnellement compacte. Pas de clés entre guillemets, pas de noms de clés répétés dans les tables, pas de guillemets obligatoires sur les valeurs de chaîne simples. Une fois que vous avez écrit un bloc tabulaire à la main, vous verrez immédiatement pourquoi — un dataset qui prend 40 lignes en JSON tient en 8 lignes TOON. Le package npm à npmjs.com/@toon-format/toon garde la surface de l'API minuscule : encode et decode, rien d'autre à apprendre. Utilisez le formateur TOON pour afficher proprement, le validateur TOON pour détecter les erreurs de syntaxe, JSON vers TOON pour convertir vos données existantes, et TOON vers JSON quand vous avez besoin du résultat en forme standard.