TOON vs YAML — Deux formats compacts, des rôles très différents

YAML et TOON sont tous deux décrits comme « plus lisibles que JSON » — et cette description est techniquement vraie pour les deux, ce qui la rend inutile. La vraie question est : lisible pour qui, et dans quel but ? YAML est optimisé pour l'édition humaine : commentaires, ancres, chaînes multi-lignes, indentation qui reflète la façon dont les développeurs pensent à la configuration. TOON est optimisé pour le traitement machine : tokens minimaux, aucune ambiguïté, aucune syntaxe qui existe uniquement pour le confort humain. Ce sont des rôles différents. Les confondre conduit à du YAML dans les prompts LLM — ce qui est pire que JSON — et à TOON dans les manifests Kubernetes, que personne ne veut éditer à la main. Cet article trace la ligne clairement.

YAML en Deux Phrases

YAML est un format de sérialisation de données convivial conçu pour les fichiers de configuration, les pipelines CI/CD, et tout document structuré qu'un développeur lira, écrira et maintiendra à la main. Ses caractéristiques définissantes — commentaires inline, mécaniques DRY ancre/alias, littéraux de chaîne multi-lignes, et structure basée sur l'indentation — existent toutes pour rendre le format agréable aux humains, pas efficace pour les machines.

Les cas d'utilisation canoniques sont les workflows GitHub Actions, les manifests Kubernetes, les fichiers Docker Compose, et la configuration d'application livrée avec le code. Si un être humain est censé ouvrir le fichier et le modifier, YAML est un choix solide. La spec YAML 1.2 a formalisé un certain nombre de cas limites qui affectaient YAML 1.1 — le plus célèbre étant le Problème de la Norvège, où le code pays NO était analysé comme booléen false dans les analyseurs YAML 1.1. Les analyseurs modernes ciblant YAML 1.2 gèrent cela correctement, mais c'est un rappel utile que la simplicité apparente de YAML cache une véritable complexité d'analyse.

• Commentaires. # ceci est un commentaire — YAML prend en charge les commentaires inline et pleine ligne. Cela seul en fait le bon choix pour toute configuration qu'un humain va maintenir.
• Ancres et alias. Définissez un bloc une fois avec &anchor, réutilisez-le partout avec *alias. Essentiel pour les configs Kubernetes DRY et les pipelines CI multi-environnements.
• Chaînes multi-lignes. Les scalaires de bloc littéral (|) et plié (>) vous permettent d'intégrer des scripts shell, des requêtes SQL, ou des données de certificat proprement dans un fichier YAML.
• Indentation lisible. La structure est définie par des espaces blancs, ce qui correspond naturellement à la façon dont les développeurs pensent aux hiérarchies de configuration imbriquées.
• Faiblesses. La sensibilité à l'indentation signifie qu'un espace mal placé est une erreur d'analyse. Les caractères de tabulation sont interdits. La coercition booléenne YAML 1.1 (Problème de la Norvège, yes/no, on/off) a causé de vrais bugs en production. Les données tabulaires exprimées comme un tableau d'objets sont plus verbeux que même JSON.

TOON en Deux Phrases

TOON est un format de sérialisation compact conçu pour transmettre des données structurées vers et depuis les grands modèles de langage, où chaque token coûte de l'argent et l'espace de fenêtre de contexte est limité. Son innovation clé est la notation tabulaire : pour les ensembles de données où chaque enregistrement partage les mêmes champs, les clés sont déclarées une seule fois dans un en-tête et omises de chaque ligne suivante — ce qui est l'opposé de ce que font JSON et YAML.

TOON n'est pas un format de configuration et n'a jamais été destiné à l'être. Il n'y a pas de syntaxe de commentaire. Il n'y a pas d'ancres. Vous ne voudriez pas modifier à la main un dataset TOON de 500 lignes, pas plus que vous ne modifieriez à la main un fichier binaire. Ce que TOON vous offre, c'est un format qui encode les mêmes informations que JSON en beaucoup moins de tokens — et moins de tokens signifie des coûts API plus bas, des datasets effectifs plus grands par prompt, et moins de pression sur les limites de la fenêtre de contexte. Le tokeniseur OpenAI est le moyen le plus rapide de voir cela en pratique : collez le même dataset dans les deux formats et comparez.

• Notation tabulaire. name[count]{col1,col2,...}: suivi d'une ligne de valeurs par ligne. Les clés apparaissent exactement une fois quel que soit le nombre de lignes.
• Notation d'objet. {key:value,key2:value2} — pas de guillemets sur les clés, pas d'espace supplémentaire.
• Analyse non ambiguë. Pas de coercition booléenne, pas de sensibilité à l'indentation, pas de divergence de version de spec.
• Pas de syntaxe de commentaire. TOON n'a aucun mécanisme pour les commentaires inline — par conception. C'est un format de données, pas un format de document.
• Faiblesses. Outillage de niche, pas d'histoire d'édition humaine, pas approprié pour tout fichier qu'un développeur ouvrira et modifiera directement.

Côte à Côte : Les Mêmes Données dans l'Élément de Chaque Format

La comparaison la plus honnête montre chaque format faisant ce pour quoi il est réellement bon — pas de confrontation directe où l'un est clairement le mauvais outil.

D'abord, un manifest de déploiement Kubernetes. C'est le territoire de YAML : un fichier de configuration maintenu par des humains avec des commentaires, des ancres pour les valeurs partagées, et une imbrication profonde qui reflète la hiérarchie logique d'un objet Kubernetes :

# Deployment manifest for the payments-service
apiVersion: apps/v1
kind: Deployment
metadata:
  name: payments-service
  namespace: production
  labels:
    app: payments-service
    version: "2.4.1"
spec:
  replicas: 3
  selector:
    matchLabels:
      app: payments-service
  template:
    metadata:
      labels:
        app: payments-service
    spec:
      containers:
        - name: payments-service
          image: registry.example.com/payments-service:2.4.1
          ports:
            - containerPort: 8080
          env:
            - name: DB_HOST
              valueFrom:
                secretKeyRef:
                  name: payments-db-secret
                  key: host
            - name: LOG_LEVEL
              value: "info"
          resources:
            requests:
              cpu: "250m"
              memory: "256Mi"
            limits:
              cpu: "500m"
              memory: "512Mi"

Écrire cela en TOON serait inutile — ce ne sont pas des données tabulaires, elles seront modifiées par des humains, et elles bénéficient de commentaires qui expliquent les valeurs non évidentes. YAML est le bon outil ici, et il n'y a pas de concurrence.

Maintenant les mêmes données dans le territoire de TOON : un dataset utilisateur passé à un LLM pour analyse. C'est là que la notation tabulaire de TOON fait le travail :

users[12]{id,email,plan,mrr,country,signupDate,churned}:
  1001,[email protected],pro,99.00,US,2024-01-15,false
  1002,[email protected],starter,19.00,GB,2024-02-03,false
  1003,[email protected],enterprise,499.00,DE,2023-11-20,false
  1004,[email protected],pro,99.00,CA,2024-03-10,true
  1005,[email protected],starter,19.00,AU,2024-01-28,false
  1006,[email protected],pro,99.00,US,2023-12-05,false
  1007,[email protected],enterprise,499.00,FR,2024-02-14,false
  1008,[email protected],starter,19.00,IN,2024-03-22,true
  1009,[email protected],pro,99.00,US,2024-01-09,false
  1010,[email protected],enterprise,499.00,JP,2023-10-31,false
  1011,[email protected],starter,19.00,BR,2024-04-01,false
  1012,[email protected],pro,99.00,US,2024-02-19,true

Écrire cela en YAML — un tableau de 12 objets, chacun avec 7 clés — répéterait les 7 noms de clés 12 fois. C'est 84 déclarations de clés pour 84 valeurs. TOON déclare chaque clé une seule fois.

Où YAML Bat TOON à Chaque Fois

Tout fichier qu'un être humain ouvrira, lira et modifiera appartient à YAML (ou JSON, pour les cas plus simples). Les avantages décisifs sont les commentaires et les ancres — deux fonctionnalités que TOON n'a tout simplement pas.

• Pipelines CI/CD. GitHub Actions, GitLab CI, CircleCI — tous natifs YAML. La capacité de commenter une étape pendant le débogage est vraiment utile.
• Kubernetes et Helm. Chaque manifest, chaque fichier de valeurs, chaque template de chart. Le système d'ancres YAML est activement utilisé dans les charts Helm complexes pour éviter de répéter les configs d'environnement.
• Docker Compose. Définitions multi-services avec des commentaires expliquant les liaisons de ports non évidentes, les montages de volumes et les configs réseau.
• Fichiers de configuration d'application. Configs de style pyproject.toml, paramètres d'application, indicateurs de fonctionnalité avec des commentaires explicatifs inline.
• Tout fichier en contrôle de version que les humains examinent dans les PRs. Les commentaires dans la config YAML font partie de la documentation. TOON ne peut pas participer à ce workflow du tout.

Où TOON Bat YAML à Chaque Fois

Toutes les données générées par programme et passées à un LLM appartiennent à TOON. YAML est en fait pire que JSON pour ce cas d'utilisation — sa syntaxe lourde en indentation et ses noms de clés répétés ajoutent des tokens sans ajouter d'informations dont le modèle a besoin.

• Charges utiles de prompt LLM. Alimenter un dataset à GPT-4o, Claude ou Gemini pour analyse, classification ou enrichissement. La notation tabulaire de TOON réduit le nombre de tokens de 40 à 60 % par rapport à JSON, et par rapport à YAML l'écart est encore plus grand.
• Instructions de sortie LLM. Demander à un modèle de répondre en TOON produit une sortie plus courte et moins chère. La sortie YAML d'un LLM est verbeuse et sensible à l'indentation — un espace mal aligné et l'analyse échoue.
• Datasets générés par programme. Si votre code construit les données, il devrait construire TOON. Il n'y a pas d'éditeur humain pour bénéficier de commentaires ou d'une indentation lisible.
• Pipelines de traitement par lots à volume élevé. Traitement de 10 000 enregistrements via un LLM par jour ? Une réduction de 50 % des tokens est une réduction de 50 % sur cette ligne de votre facture API.
• Pression sur la fenêtre de contexte. Lorsque vous devez faire tenir plus de données dans la limite de contexte d'un modèle, TOON vous permet d'insérer plus de lignes au même coût en tokens.

La Réalité du Nombre de Tokens

Voici le même dataset de 10 lignes dans trois formats. Les chiffres sont approximatifs mais cohérents avec ce que le tokeniseur OpenAI rapporte pour la tokenisation de GPT-4o.

Tableau d'objets YAML :

- id: 1
  username: alice_chen
  plan: pro
  mrr: 99.00
  country: US
- id: 2
  username: bob_martin
  plan: starter
  mrr: 19.00
  country: GB
- id: 3
  username: carol_white
  plan: enterprise
  mrr: 499.00
  country: DE
- id: 4
  username: dan_patel
  plan: pro
  mrr: 99.00
  country: CA
- id: 5
  username: eve_torres
  plan: starter
  mrr: 19.00
  country: AU
- id: 6
  username: frank_liu
  plan: pro
  mrr: 99.00
  country: US
- id: 7
  username: grace_kim
  plan: enterprise
  mrr: 499.00
  country: FR
- id: 8
  username: henry_obi
  plan: starter
  mrr: 19.00
  country: IN
- id: 9
  username: iris_novak
  plan: pro
  mrr: 99.00
  country: US
- id: 10
  username: james_sato
  plan: enterprise
  mrr: 499.00
  country: JP

Notation tabulaire TOON, mêmes données :

users[10]{id,username,plan,mrr,country}:
  1,alice_chen,pro,99.00,US
  2,bob_martin,starter,19.00,GB
  3,carol_white,enterprise,499.00,DE
  4,dan_patel,pro,99.00,CA
  5,eve_torres,starter,19.00,AU
  6,frank_liu,pro,99.00,US
  7,grace_kim,enterprise,499.00,FR
  8,henry_obi,starter,19.00,IN
  9,iris_novak,pro,99.00,US
  10,james_sato,enterprise,499.00,JP

La raison pour laquelle YAML est moins performant que JSON sur les données tabulaires est structurelle : YAML utilise une ligne par paire clé-valeur avec indentation, donc un objet à 5 champs coûte 5 lignes plus le marqueur de liste. JSON enveloppe au moins tout l'objet dans un ensemble d'accolades. TOON élimine entièrement la répétition des clés — les clés apparaissent une fois, les valeurs sont empaquetées dans des lignes. Les économies augmentent avec le nombre de lignes et de champs.

Utiliser TOON dans Votre Code

Le paquet @toon-format/toon gère l'encodage et le décodage :

npm install @toon-format/toon

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

// Your dataset — could come from a database query, API response, anywhere
const users = [
  { id: 1001, email: '[email protected]', plan: 'pro',        mrr: 99.00,  country: 'US' },
  { id: 1002, email: '[email protected]',   plan: 'starter',    mrr: 19.00,  country: 'GB' },
  { id: 1003, email: '[email protected]', plan: 'enterprise', mrr: 499.00, country: 'DE' },
  // ...more rows
];

// Encode to TOON before inserting into your LLM prompt
const toonPayload = encode(users);
// users[3]{id,email,plan,mrr,country}:
//   1001,[email protected],pro,99.00,US
//   1002,[email protected],starter,19.00,GB
//   1003,[email protected],enterprise,499.00,DE

const prompt = `Analyse this user dataset and identify churn risk signals.
Return your findings as a TOON dataset with columns: id, riskScore, reason.

Dataset:
${toonPayload}`;

// After the LLM responds with TOON output, decode it back
const llmResponse = '...'; // TOON string from the model
const findings = decode(llmResponse);
console.log(findings[0]); // { id: 1001, riskScore: 'low', reason: 'Active, pro plan' }

Guide de Décision

Le choix entre YAML et TOON n'est presque jamais ambigu en pratique :

• Utilisez YAML si un humain lira ou modifiera le fichier — pipelines CI/CD, manifests Kubernetes, Docker Compose, configuration d'application, playbooks Ansible.
• Utilisez YAML si vous avez besoin de commentaires inline pour expliquer des valeurs non évidentes.
• Utilisez YAML si vous avez besoin d'ancres et d'alias pour garder une configuration complexe DRY.
• Utilisez YAML si vous travaillez avec un outil qui attend du YAML par convention (Helm, GitHub Actions, k8s kubectl apply).
• Utilisez TOON si les données vont dans un prompt LLM — surtout des données tabulaires avec plusieurs lignes.
• Utilisez TOON si vous demandez à un LLM de retourner des données structurées et que vous voulez une sortie plus courte et moins chère.
• Utilisez TOON si le nombre de tokens est important — pipelines à volume élevé, longs datasets, pression sur la fenêtre de contexte.
• Utilisez TOON si les données sont générées par programme et qu'aucun humain ne les modifiera directement.
• Utilisez JSON (ni YAML ni TOON) si vous construisez une API REST, stockez des données dans une base de données, ou intégrez avec des outils tiers qui attendent du JSON.

En Conclusion

YAML et TOON occupent des positions complètement différentes dans votre stack. YAML appartient à votre dépôt aux côtés de votre code — fichiers de configuration, définitions de pipeline, manifests d'infrastructure. TOON appartient à la frontière entre votre application et les API LLM, où il convertit vos données structurées dans la représentation la plus efficace en tokens avant l'envoi et convertit la réponse du modèle en retour à la sortie. Il n'y a pas de chevauchement significatif entre ces rôles, c'est pourquoi la question n'est pas « lequel est meilleur » mais « lequel appartient ici ».

Si vous travaillez avec TOON, le Formateur TOON et le Validateur TOON sont le moyen le plus rapide d'inspecter et de vérifier les chaînes TOON. Le convertisseur JSON vers TOON convertit les charges utiles JSON existantes en TOON pour une utilisation avec les LLM, et le convertisseur TOON vers JSON gère le voyage de retour lorsqu'un modèle répond en TOON et que votre système en aval attend du JSON. Voir aussi l'article Wikipedia sur YAML pour une histoire concise du format et un résumé de ses cas limites connus.