TOML versus YAML versus JSON — Formats de configuration classés selon la fréquence avec laquelle ils vous irriteront

Chaque projet vous pousse finalement à choisir un format de configuration. YAML est partout. JSON est plus ancien que certains de vos collègues. TOML est apparu récemment, avec son bras levé en disant « en fait, j'ai été conçu pour cela ». Les trois vous trahiront un jour. Les trahisons sont simplement différentes.

Voici une comparaison directe — même configuration, trois formats — suivie de l'exact moment où chaque format vous fait regretter vos choix de vie.

La Même Configuration, Trois Manières

Une configuration de base pour une application web : nom, port, indicateur de débogage, chaîne de version, paramètres de base de données, origines autorisées. Rien d'exotique. C'est là que les différences de format commencent à se manifester.

TOML

# App configuration
[app]
name = "my-app"
port = 3000
debug = false
version = "1.2.3"
allowed_origins = ["https://example.com", "https://api.example.com"]

[database]
host = "localhost"
port = 5432
name = "mydb"

YAML

# App configuration
app:
  name: my-app
  port: 3000
  debug: false
  version: "1.2.3"
  allowed_origins:
    - https://example.com
    - https://api.example.com

database:
  host: localhost
  port: 5432
  name: mydb

JSON

{
  "app": {
    "name": "my-app",
    "port": 3000,
    "debug": false,
    "version": "1.2.3",
    "allowed_origins": [
      "https://example.com",
      "https://api.example.com"
    ]
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "mydb"
  }
}

En bref

Fonctionnalité	TOML	YAML	JSON
Commentaires	✅ Oui	✅ Oui	❌ Non
Inférence de type	Explicit	Agressive (souvent fausse)	Explicit
Tableaux	= ["a", "b"]	- item ou inline	["a", "b"]
Virgules finales	N / A	N / A	❌ Illégale
Configurations profondément imbriquées	Devient vite verbeuse	Lisible à peu près	Verbeuse mais sans ambiguïté
Stabilité du spécificateur	TOML 1.0 (2021, stable)	1.1 vs 1.2 : chaos des analyseurs	Stable
Support de null	❌ Aucun type null	✅ Oui (~ ou null)	✅ Oui (null)
Utilisation courante	Cargo.toml, pyproject.toml	GitHub Actions, k8s, Docker	package.json, tsconfig.json

YAML : Le plus lisible jusqu’à ce qu’il ne le soit plus

YAML semble excellent dans les démonstrations. Une configuration plane lit presque comme un texte. Le problème commence quand vous rencontrez l'un de ses cas limites — et à ce moment-là, votre fichier de configuration est déjà devenu une infrastructure essentielle.

Le Problème de la Norvège

Dans YAML 1.1 — qui est encore la valeur par défaut de la plupart des analyseurs — ces valeurs sont toutes des booléens : y, n, yes, no, on, off, true, false. Donc country: NO est analysé comme country: false. C'est la raison pour laquelle on l'appelle le Problème de la Norvège — le code ISO du pays de la Norvège est NO. PyYAML l'a corrigé dans la version 6.0 (publiée en 2022). SnakeYAML (utilisé par beaucoup de logiciels Java) n'a pas encore complètement résolu ce problème. Vérifiez votre analyseur avant d'utiliser des valeurs brutes no ou yes dans vos configurations.

Inférence de type qui se trompe

Les valeurs non encadrées dans YAML sont converties en type. port: 8080 devient un entier. version: 1.10 devient le flottant 1.1 — mathématiquement équivalent, mais sémantiquement erroné. Oubliez de mettre des guillemets autour d'une chaîne de version et vous passerez dix minutes à vous demander pourquoi votre application pense qu'elle est sur v1.1 au lieu de v1.10. La solution est banale : encadrez tout ce qui devrait rester une chaîne. Mais YAML ne vous force pas à le faire, donc il ne le fait pas.

L'indentation est essentielle

Les tabs sont illégaux dans YAML — pas recommandés, illégaux. Mélangez une indentation de deux espaces et quatre espaces dans un fichier et vous obtenez une erreur de parsing souvent pointant vers la ligne erronée. GitHub Actions est ici le plus aigu : une section mal indentée run: échoue en temps de fonctionnement, pas au moment de parsing, car les exécuteurs de workflow ne valident que la syntaxe, pas la structure des étapes. Vous obtenez « valeur inattendue » d'une tâche de CI sans indication de quel étape a échoué, et vous passerez vingt minutes à ajouter des sorties de débogage avant de réaliser que le problème était une indentation de deux espaces où quatre étaient attendus.

Si votre YAML est devenu une masse d'indentation incohérente, le formateur YAML le normalisera avant que vous ne commenciez à déboguer.

TOML : Le format qui a réellement pensé à la configuration

Tom Preston-Werner (co-fondateur de GitHub) a conçu TOML parce qu'il était las de rédiger des configurations au style INI avec un comportement de parsing incohérent et des configurations YAML qui le surprennent. TOML 1.0 est arrivé en janvier 2021 après des années de révisions. Il est aujourd'hui le standard pour les projets Rust (Cargo.toml), la gestion de paquets en Python (pyproject.toml) et les sites Hugo. Le spécificateur est stable, les analyseurs sont cohérents, et le système de types fait ce que vous attendez de lui.

Ce qu'il fait bien

• Aucune coercition inattendue. version = "1.10" est toujours une chaîne. port = 3000 est toujours un entier. Ce que vous écrivez, c'est ce que vous obtenez.
• Les commentaires fonctionnent exactement comme on le souhaite (# à la fin de la ligne), contrairement à JSON.
• Les configurations planes à modérément imbriquées sont véritablement lisibles, contrairement aux configurations profondément imbriquées en JSON.

La syntaxe tableau d'objets

Le principal obstacle de TOML est sa syntaxe tableau d'objets. Si vous souhaitez un tableau d'objets — par exemple, plusieurs connexions de base de données — la notation ressemble à ceci :

[[databases]]
name = "primary"
host = "db1.example.com"

[[databases]]
name = "replica"
host = "db2.example.com"

reçoit une part égale de l'espace restant après soustraction de l'espacement. Trois colonnes à [[double bracket]] section est un élément du databases tableau. Cela fonctionne. C'est clair. Mais chaque développeur qui ouvre un fichier TOML pour la première fois se demande « est-ce que c'est INI ? » — parce qu'il ressemble un peu à cela. Cette inconnu a un coût réel lors de l'adoption de nouveaux contributeurs qui n'ont jamais vu de TOML.

TOML n'a pas de null type — intentionnellement. Si votre schéma utilise null pour signifier « la clé est présente mais explicitement non définie », vous devrez la modéliser autrement (en omettant la clé entière ou en utilisant une valeur sentinelle). Et les configurations profondément imbriquées deviennent vite verbeuses : TOML n'a pas le système d'ancrage/alias de YAML pour réutiliser des sous-structures, donc il y a beaucoup de copier-coller si votre configuration a une structure répétée.

Le Formateur TOML est utile lorsque vous tentez de nettoyer un fichier TOML qui s'est développé organiquement au fil du temps.

JSON : Le diable que vous connaissez

JSON a été conçu pour l'échange de données — des machines qui communiquent entre elles — et non pour les humains qui écrivent des fichiers de configuration. Il est devenu un format de configuration parce que chaque langage avait déjà un analyseur JSON, et ce confort a gagné. Aujourd'hui, nous avons package.json, tsconfig.json, .eslintrc.json, et environ 40 autres fichiers JSON dans chaque projet JavaScript, tous édités à la main.

Aucun commentaire. Toujours.

Douglas Crockford a retiré les commentaires de JSON intentionnellement en 2012 — il s'inquiétait que les développeurs les utiliseraient comme des directives de parsing (comme les commentaires conditionnels de IE). L'internet a plaint ce choix chaque jour depuis. Les solutions utilisées par les gens :

• JSONC — JSON avec des commentaires. VS Code l'utilise pour settings.json et launch.json. Non parseable par les analyseurs standard de JSON. Non standard.
• JSON5 — ajoute des commentaires, des virgules à la fin, des clés non encadrées, des chaînes multilignes. A une spécification et un analyseur autonome. Babel l'utilise pour les configurations. N'est pas encore standard JSON.
• UN "_comment" clé — un champ de type string qui contient le texte de votre commentaire. Fonctionne. Regarde comme une absurdité. Entre dans votre modèle de données.

Virgules finales

Également illégal. Ajoutez une virgule à la fin de l'élément final d'un tableau ou d'un objet et JSON.parse lance SyntaxError: Unexpected token } — vous indiquant qu'il y a un problème, mais pas où se trouve la virgule erronée. C'est le premier erreur de parsing JSON dans les fichiers de configuration humains, et cela se produit parce que tous les autres langages modernes (tableaux en JavaScript, listes en Python, enums en Rust) permettent des virgules à la fin, et les humains écrivent du JSON à la main avec les mêmes habitudes.

Ce que JSON fait bien

Le système de types est clair et universel. Chaque analyseur JSON dans chaque langage convient sur ce que true, 1, "1"et null signifie. JSON Schema est la validation de configuration la plus mature des trois — VS Code l'utilise pour valider tsconfig.json et package.json en temps réel, avec des indications d'erreurs en ligne. Quand les outils génèrent votre JSON (webpack, tsc, npm), vous n'avez pas besoin de lisibilité — c'est ce que le Formateur JSON est pour.

Conclusion : Choisissez selon le contexte, pas selon la préférence

Utilisez JSON lorsque les outils le génèrent ou le consomment (package.json, tsconfig, configurations AWS, réponses de l'API GitHub), ou lorsque vous avez besoin de validation via JSON Schema. N'essayez pas de l'écrire à la main plus que nécessaire. L'absence de commentaires est un problème, mais l'ubiquité et le soutien des outils sont difficiles à contester.

Utilisez YAML lorsque la configuration est principalement rédigée par des humains et est relativement plane — GitHub Actions workflows, fichiers Docker Compose, manifestes Kubernetes. Encadrez tout ce qui pourrait être mal interprété comme un booléen ou un nombre (chaînes de version, codes pays, tout commençant par un chiffre). Exécutez un linter. N'utilisez jamais des tabs. Considérez l'inférence de type comme une erreur, pas comme une fonctionnalité.

Utilisez TOML lorsque vous contrôlez le choix du format et que vous voulez éviter les coercions de type inattendues. C'est le plus honnête des trois sur ce qu'il est. Si vous commencez un projet de nouvelle génération et que aucun outil ne vous impose un format, TOML est le moins susceptible de vous surprendre dans les six mois à venir. L'inconnu est un coût à un moment donné ; l'explicitité est permanente.

Vous aimerez peut-être aussi