JSON Toolkit

Guide du format TOON : alléger le JSON avant de le donner à un LLM

L’essentiel : Quand vous transmettez un tableau uniforme à un grand modèle de langage en JSON, les noms de clés répétés et les crochets consomment des tokens. TOON déclare la structure une seule fois grâce aux objets indentés et aux tableaux tabulaires, puis déroule les données ligne par ligne. Les benchmarks officiels montrent environ 40 % de tokens en moins avec une meilleure précision d'analyse. Ce guide couvre la syntaxe, les limites réelles des économies, les cas où il ne faut pas convertir, et l'intégration d'encode et de decode.

Intermédiaire~6 min de lecturePublié le 2026-11-10Mis à jour le 2026-11-10
Syntaxe du tableau tabulaire TOON : en-tête de champs déclaré une fois, lignes de données déroulées

La surcharge syntaxique du JSON est sans importance pour un transfert entre machines, mais du côté entrée d'un LLM facturé au token, c'est de l'argent réel : le même tableau uniforme répète ses noms de clés des dizaines de fois, et chaque accolade ou guillemet prend une part du budget. TOON n'invente pas un nouveau modèle de données — il réécrit le modèle de données JSON dans une notation moins coûteuse.

Ce qu'est TOON : un autre encodage du JSON, pas un concurrent

TOON (Token-Oriented Object Notation) est un format ouvert apparu en 2025, dont le positionnement officiel tient en une phrase : un encodage compact, sans perte et lisible du modèle de données JSON. Il n'introduit aucun nouveau type — objets, tableaux, chaînes, nombres, booléens et null correspondent un à un au JSON, et decode(encode(x)) est strictement égal aux données d'origine (les types hors JSON comme Date ou NaN doivent être normalisés au préalable). Le aller-retour est sans perte et déterministe : la même entrée produit toujours la même sortie, ce qui compte pour des prompts reproductibles.

Comme il encode exactement le modèle de données JSON, la bonne façon d'utiliser TOON est comme format de frontière : l'application continue de fonctionner en JSON en interne, convertit en TOON juste avant de placer les données dans un prompt, puis reconvertit à la réception de la réponse du modèle. La documentation officielle parle de « translation layer ». L'extension de fichier conventionnelle est .toon ; pour le transport HTTP, le type média provisoire est text/toon, en UTF-8.

Attention à un bruit de recherche : ne le confondez pas avec les Toon Shaders de l'imagerie 3D. Ils ne partagent que le mot.

Pourquoi le JSON est particulièrement coûteux côté entrée d'un LLM

Prenons une liste de commandes, un annuaire d'utilisateurs ou un résumé de journaux écrits en tableau JSON. Les tokens partent à trois endroits :

  1. Les noms de clés répétés. Cinquante enregistrements écrivent "id", "amount" et "status" cinquante fois chacun. Doublez les données, doublez la surcharge.
  2. La ponctuation structurelle. Accolades, crochets, deux-points et virgules consomment tous des tokens, et l'imbrication les densifie.
  3. Les guillemets. Presque chaque clé et valeur de chaîne est entourée de guillemets doubles.

Résultat : le coût API facturé au token monte directement ; les entrées longues atteignent plus vite le plafond de la fenêtre de contexte ; et sur de très longues entrées, le modèle omet ou décale des champs plus souvent. Le benchmark de la page d'accueil officielle : sur un jeu de test à structures mixtes et quatre modèles, environ 40 % de tokens en moins avec une précision d'analyse passant de 70 % (JSON) à 74 % (TOON). Économie et précision ne s'opposent pas ici, car une structure plus resserrée rend les frontières plus visibles pour le modèle.

La syntaxe : objets indentés + tableaux tabulaires

Les mêmes données météo sous trois formes. Version JSON, environ 117 tokens :

{
  "location": { "city": "Berlin", "country": "DE", "units": "metric" },
  "alerts": ["frost", "wind"],
  "forecast": [
    { "day": "Mon", "temp": { "min": -2, "max": 4 }, "condition": "snow", "rainChance": 80 },
    { "day": "Tue", "temp": { "min": 1, "max": 7 }, "condition": "cloudy", "rainChance": 20 },
    { "day": "Wed", "temp": { "min": 3, "max": 11 }, "condition": "sunny", "rainChance": 5 }
  ]
}

Version TOON, environ 66 tokens :

location:
  city: Berlin
  country: DE
  units: metric
alerts[2]: frost,wind
forecast[3]{day,temp{min,max},condition,rainChance}:
  Mon,-2,4,snow,80
  Tue,1,7,cloudy,20
  Wed,3,11,sunny,5

Trois formes couvrent tout, choisies automatiquement par le sérialiseur selon la forme des données :

Forme Convient à Équivalent JSON
Objet indenté Objets imbriqués { "location": { ... } }, l'indentation remplace les accolades
Tableau en ligne Tableaux de primitives ["frost","wind"], [2] déclare la longueur
Tableau tabulaire Tableaux d'objets uniformes Les noms de champs n'apparaissent qu'une fois dans l'en-tête {day,temp{min,max},...} ; chaque ligne ne contient que des valeurs séparées par des virgules

Les objets imbriqués uniformes (temp{min,max}) se replient dans l'en-tête en tant que groupe de champs imbriqué, les lignes de données restent à plat. La règle de citation est minimale : les chaînes ne sont guillemetées que si elles contiennent des délimiteurs, des caractères spéciaux ou risquent d'être lues comme des nombres — l'une des raisons pour lesquelles TOON bat le « JSON compact » en nombre de tokens. La différence clé avec YAML : TOON possède des déclarations de longueur explicites et des en-têtes de champs vérifiables par machine ; avec CSV : il conserve l'imbrication et les types.

[N] et {fields} : des garde-fous structurels pour le modèle

[3] et {day,...} ne servent pas qu'à économiser des tokens — ce sont aussi un contrat vérifiable remis au modèle :

  • La longueur du tableau permet au modèle de répondre directement à « combien d'enregistrements contient le jeu de données » et expose immédiatement une troncature quand le nombre de lignes ne colle pas.
  • L'en-tête de champs déclare les noms une fois ; le modèle aligne les valeurs par position au lieu de deviner la correspondance des clés à chaque ligne.

C'est de la prévention, l'opposé du dépannage a posteriori. Un réparateur JSON (voir le pipeline de réparation) récupère les données après que le modèle a produit du JSON cassé ; les déclarations de TOON réduisent en amont la probabilité de données cassées. Faites les deux et le taux d'échec d'analyse au milieu du pipeline baisse.

Quand ne pas utiliser TOON

La section officielle « When Not to Use TOON » est rafraîchissamment franche. Quatre scénarios, à retenir tels quels :

Scénario Pourquoi éviter Meilleure option
Structures profondément imbriquées, non uniformes Éligibilité tabulaire ≈ 0 % ; le JSON compact gagne souvent JSON compact
Tableaux semi-uniformes Champs irréguliers, économies presque nulles Garder le pipeline JSON
Données purement tabulaires TOON ajoute 5–10 % de surcharge par rapport à CSV CSV
Sensible à la latence (modèles locaux/quantifiés) Moins de tokens ≠ inférence plus rapide Mesurer le TTFT d'abord

Le caractère semi-uniforme s'évalue par l'éligibilité tabulaire (tabular eligibility) : officiellement, à 40–60 % d'éligibilité l'économie devient marginale. Une migration de format a un coût réel — parseurs, validateurs, scripts en aval changent tous — donc si le gain est inférieur à dix pour cent, n'y touchez pas.

Mise en œuvre : encode / decode et CLI

La bibliothèque TypeScript officielle, dans les deux sens :

npm install @toon-format/toon
# La conversion par lots passe aussi par la CLI
npx @toon-format/cli input.json -o output.toon
import { encode, decode } from '@toon-format/toon'

const data = {
  users: [
    { id: 1, name: 'Ada', role: 'admin' },
    { id: 2, name: 'Bob', role: 'user' },
  ],
}

const toon = encode(data)
// users[2]{id,name,role}:
//   1,Ada,admin
//   2,Bob,user

const back = decode(toon)  // strictement égal aux données d'origine

Des implémentations Python, Go, Rust et .NET existent ; consultez la liste des implémentations du dépôt officiel de spécification avant d'en adopter une, et vérifiez qu'elle couvre les fonctionnalités syntaxiques utilisées. Avant la production, exécutez une assertion aller-retour : decode(encode(données)) doit être profondément égal à l'original, sinon l'implémentation ou les données posent problème.

Comment l'intégrer à votre chaîne JSON existante

TOON ne change rien à votre pipeline JSON ; il ajoute une conversion de frontière. Ordre recommandé :

  1. Assurez-vous d'abord que le JSON est propre. Un JSON cassé produit un TOON cassé. La validation syntaxique et la réparation sont couvertes par le Guide de réparation JSON.
  2. Vérifiez la forme des données. Les objets du tableau ont-ils tous leurs champs ? Normalisez d'abord, ou concluez que la conversion n'en vaut pas la peine.
  3. Convertissez et contrôlez par échantillon. Après conversion, comparez une ligne de données au JSON d'origine pour confirmer l'alignement des champs.
  4. Estimez le bénéfice. Pour les listes uniformes, la réflexion ligne par ligne du manuel JSONL s'applique à la conversion en flux ; pour le rapport taille/coût, la vraie relation entre JSON minify et gzip fait la même leçon : mesurer d'abord, convertir ensuite.

TOON remplacera-t-il JSON ?

Non. TOON encode le modèle de données JSON ; sa place est la frontière du prompt, tandis que stockage et échanges entre programmes restent en JSON. Utilisez TOON pour le segment « donner au modèle » et laissez le reste de la chaîne intact.

Quel rapport entre TOON, YAML et CSV ?

Les objets ressemblent à YAML (indentation au lieu d'accolades) ; les tableaux uniformes ressemblent à CSV (en-tête déclaré une fois, lignes déroulées). Mais TOON a des déclarations de longueur explicites que YAML n'a pas, et conserve l'imbrication et les types que CSV n'a pas — il se tient entre les deux, avec des garde-fous vérifiables par machine.

La conversion TOON vers JSON perd-elle des données ?

Non : objets, tableaux, chaînes, nombres, booléens et null correspondent un à un, et decode(encode(x)) est strictement égal. La seule précaution est de normaliser d'abord les types hors JSON comme Date et NaN, sinon l'égalité n'est vérifiée qu'après l'aller-retour.

Comment vérifier que le TOON converti est correct ?

Deux contrôles : une assertion aller-retour (encode puis decode, égalité profonde avec l'original), et une inspection visuelle de l'en-tête — le nombre dans [N] doit égaliser le nombre de lignes, et les champs de {fields} doivent s'aligner un à un avec les valeurs séparées par virgules de chaque ligne. Côté modèle, vous pouvez aussi lui demander de rapporter la longueur du tableau avant de répondre.