Qu'est-ce que le format TOON ? Introduction pour développeurs

La plupart des développeurs ont une courte liste mentale de formats de données : JSON pour les API, CSV pour les feuilles de calcul, YAML pour les fichiers de configuration, peut-être XML si vous travaillez avec des systèmes hérités. Mais il existe un format plus récent qui fait discrètement son chemin dans l'espace des outils d'IA et qui mérite d'être connu — TOON, ou Token-Oriented Object Notation. Il a été conçu de zéro pour résoudre un problème spécifique : transmettre des données structurées aux grands modèles de langage sans épuiser votre budget de tokens.

Qu'est-ce que TOON ?

TOON signifie Token-Oriented Object Notation. C'est un format de sérialisation de données compact conçu spécifiquement pour minimiser le nombre de tokens consommés lorsque des données structurées sont intégrées dans des prompts LLM ou des réponses. Pensez-y comme du JSON avec toute la verbosité supprimée — pas de noms de clés répétés dans les tableaux, pas de guillemets redondants, pas d'espaces en fin de ligne — juste le signal avec aussi peu de bruit syntaxique que possible.

Le package npm est @toon-format/toon, et il vous offre une API simple encode / decode qui fonctionne dans n'importe quel projet Node.js ou bundler moderne. Les fichiers TOON utilisent l'extension .toon.

Pourquoi ne pas simplement utiliser JSON ?

JSON est excellent pour la communication machine à machine où la bande passante est bon marché et l'analyse syntaxique est gérée par le runtime. Mais quand vous envoyez des données dans le cadre d'un prompt à l'API OpenAI ou à l' API Anthropic, chaque caractère compte — littéralement. Les deux API facturent au token, et les tokens correspondent approximativement à 4 caractères de texte anglais.

Considérez un tableau de 100 enregistrements utilisateurs. En JSON, vous répéteriez les clés — "id", "name", "role", "email" — une fois par enregistrement. C'est 100 copies de la même information structurelle. La syntaxe tabulaire de TOON définit ces clés une seule fois puis liste les valeurs ligne par ligne, de la même façon qu'un CSV le fait, mais avec la structure d'objet préservée. Les économies de tokens sur des ensembles de données réels peuvent atteindre 40 à 70 % comparé au JSON compact.

La syntaxe TOON en un coup d'œil

TOON prend en charge quatre formes de données de base : les scalaires (chaînes, nombres, booléens), les tableaux, les objets et les données tabulaires. La syntaxe scalaire et de collection sera familière si vous avez travaillé avec JSON — le format tabulaire est là où TOON se différencie vraiment.

Un objet simple supprime les espaces des accolades extérieures, omet les guillemets inutiles et sépare les paires clé-valeur par des virgules :

{name:Alice,age:30,role:admin}

Un tableau simple de scalaires ressemble exactement à ce que vous attendez :

[1,2,3]

Voici maintenant où ça devient intéressant — les données tabulaires. C'est la syntaxe qui rend TOON convaincant pour les cas d'utilisation LLM. Au lieu de répéter les clés pour chaque objet dans un tableau, vous déclarez le schéma une fois dans l'en-tête et listez les valeurs ligne par ligne :

users[3]{id,name,role}:
  1,Alice,admin
  2,Bob,user
  3,Charlie,editor

Ce bloc représente un tableau de 3 objets utilisateurs — équivalent au JSON ci-dessous — mais en une fraction des tokens. L'en-tête users[3]{id,name,role} indique à un analyseur : "c'est une variable nommée users, elle a 3 lignes, et chaque ligne correspond aux champs id, name et role". Les lignes sont de pures valeurs, sans répétition de clés.

[
  { "id": 1, "name": "Alice", "role": "admin" },
  { "id": 2, "name": "Bob",   "role": "user"  },
  { "id": 3, "name": "Charlie", "role": "editor" }
]

Installation et utilisation du package @toon-format/toon

Le package npm officiel gère à la fois l'encodage des valeurs JavaScript en chaînes TOON et le décodage des chaînes TOON en objets et tableaux JavaScript. Installez-le depuis le registre npm :

npm install @toon-format/toon

Le package exporte deux fonctions — encode et decode :

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

// Decode a TOON string → JavaScript value
const toonString = `users[3]{id,name,role}:
  1,Alice,admin
  2,Bob,user
  3,Charlie,editor`;

const users = decode(toonString);
console.log(users[0].name); // "Alice"
console.log(users[1].role); // "user"

// Encode a JavaScript value → TOON string
const config = {
  model: 'gpt-4o',
  temperature: 0.7,
  maxTokens: 1024,
  stream: true
};

const toon = encode(config, { indent: 2 });
console.log(toon);
// {model:gpt-4o,temperature:0.7,maxTokens:1024,stream:true}

L'option indent dans encode() contrôle si la sortie est mise en forme. Pour les prompts LLM, vous voudrez généralement une sortie compacte (sans indentation) pour économiser des tokens. Pour le débogage ou des fichiers .toon lisibles par l'homme, { indent: 2 } vous donne une sortie bien formatée.

Un cas d'utilisation réel : envoyer des enregistrements à un LLM

Imaginez que vous construisez une fonctionnalité d'analyse de produit qui doit résumer l'activité des utilisateurs. Vous récupérez des enregistrements de session récents de votre base de données et souhaitez les envoyer à un LLM pour un résumé en langage naturel. Voici à quoi cela ressemble avec TOON :

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

const sessions = [
  { userId: 101, action: 'login',        duration: 0,   page: '/dashboard' },
  { userId: 101, action: 'view_report',  duration: 142, page: '/reports/q1' },
  { userId: 101, action: 'export_csv',   duration: 8,   page: '/reports/q1' },
  { userId: 102, action: 'login',        duration: 0,   page: '/dashboard' },
  { userId: 102, action: 'edit_profile', duration: 37,  page: '/settings'  }
];

const toonPayload = encode(sessions);
// sessions[5]{userId,action,duration,page}:
//   101,login,0,/dashboard
//   101,view_report,142,/reports/q1
//   101,export_csv,8,/reports/q1
//   102,login,0,/dashboard
//   102,edit_profile,37,/settings

const prompt = `Summarise the following user activity. Data is in TOON format.\n\n${toonPayload}`;

La représentation TOON de ces 5 enregistrements de session est significativement plus courte que le JSON équivalent, qui répéterait "userId", "action", "duration" et "page" cinq fois chacun. Sur des centaines d'enregistrements, les économies sont substantielles et se traduisent directement par des coûts d'API réduits et des temps de réponse plus rapides (moins de tokens à traiter dans la fenêtre d'attention).

Types de données clés dans TOON

TOON se mappe proprement sur les primitives que vous utilisez déjà en JavaScript et dans la plupart des autres langages :

• Chaînes — Non entre guillemets lorsqu'elles ne contiennent pas de caractères spéciaux. Entre guillemets doubles lorsqu'elles incluent des virgules, des deux-points ou des espaces.
• Nombres — Entiers et flottants écrits tels quels : 42, 3.14, -7.
• Booléens — true et false, comme en JSON.
• Null — Écrit comme null pour les valeurs absentes ou indéfinies.
• Tableaux — Syntaxe d'accolades en ligne [val1,val2,val3] pour les listes courtes ; syntaxe d'en-tête tabulaire pour les tableaux d'objets.
• Objets — Syntaxe avec accolades {key:value,key2:value2} pour les objets individuels.
• Données tabulaires — La vedette du spectacle : en-tête name[n]{col1,col2,...}: suivi de lignes séparées par des virgules — idéal pour toute collection d'enregistrements de même forme.

Quand utiliser TOON plutôt que d'autres formats

TOON n'essaie pas de remplacer JSON en tant que format d'échange polyvalent. Il occupe une niche spécifique. Voici un guide de décision rapide :

• Utilisez JSON lorsque vous construisez des API REST, stockez des documents dans une base de données ou transmettez des données entre services. JSON est universellement pris en charge, bien outillé et lisible par l'homme.
• Utilisez TOON lorsque des données structurées font partie d'un prompt ou d'une fenêtre de contexte LLM et que le nombre de tokens compte. Le format tabulaire brille chaque fois que vous travaillez avec des lignes d'enregistrements — listes d'utilisateurs, entrées de journal, catalogues de produits, événements analytiques.
• Utilisez CSV lorsque vous n'avez besoin que de données tabulaires plates et que le consommateur attend du CSV (feuilles de calcul, outils BI). CSV n'a pas d'imbrication d'objets, donc TOON est plus expressif.
• Utilisez YAML pour les fichiers de configuration édités par des humains où la lisibilité et les commentaires importent plus que la compacité.
• Utilisez TOON pour les sorties d'outils LLM également : si un LLM appelle votre outil et renvoie des résultats structurés, encoder ces résultats en TOON économise des tokens des deux côtés de l'appel API.

En résumé

TOON — Token-Oriented Object Notation — est un format de sérialisation compact conçu pour l'ère LLM. Il conserve la structure familière de JSON (objets, tableaux, scalaires) tout en introduisant une syntaxe tabulaire qui élimine la répétition redondante des clés entre les enregistrements. Le résultat est un format qui peut être 40 à 70 % plus petit que le JSON équivalent, ce qui se traduit directement par des coûts de tokens réduits lorsque vous travaillez avec l' API OpenAI, l'API Anthropic, ou tout autre service LLM facturé au token.

Si vous souhaitez explorer TOON de manière pratique, nous avons une suite complète d'outils ici : utilisez le formateur TOON pour afficher et inspecter les documents TOON, le validateur TOON pour détecter les erreurs de syntaxe, le convertisseur JSON vers TOON pour migrer des charges utiles existantes, et le convertisseur TOON vers JSON si vous avez besoin d'aller dans l'autre sens. Le package npm @toon-format/toon vous donne encode et decode pour intégrer TOON directement dans votre code Node.js ou côté navigateur en quelques minutes.