JSON, TOML, YAML ou CSON : choisir un format de configuration

L'essentiel : utilisez JSON pour l'échange machine, et choisissez TOML ou YAML pour la configuration maintenue par des humains selon l'écosystème (YAML pour Kubernetes et la CI, TOML pour les structures plates ou les dates natives) ; retombez sur JSONC seulement si vous n'êtes pas sûr que le lecteur prenne en charge le dialecte.

JSON existe pour les machines qui échangent des données ; un fichier de configuration est écrit par des humains pour des humains. Confondez les deux et vous obtenez un config.json qui ne peut pas contenir un commentaire et que personne n'ose élaguer.

1. Commencez par deux types de fichiers différents

L'échange de données et la configuration ne partagent pas le même objectif, même si la même personne écrit souvent les deux sur la même machine.

JSON marque presque parfaitement dans la colonne de gauche : grammaire minimale, un parseur dans chaque langage, et pas de commentaires signifie pas de problème de « commentaire qui a dérivé de la valeur ». Dans la colonne de droite, sa sévérité est pure friction : pas de commentaires, pas de virgules finales, pas de dates, et le texte multi-ligne doit être replié sur une ligne avec \n.

2. Les quatre prétendants et leur syntaxe

• JSON : défini par la RFC 8259 et l'ECMA-404, avec exactement six types de valeurs : objet, tableau, chaîne, nombre, booléen et null. C'est le standard d'échange de facto et le seul format qui ne demande aucune décision de sélection.
• TOML : créé par Tom Preston-Werner, avec la v1.0.0 publiée en janvier 2021. Son objectif déclaré est un format de configuration minimal aux sémantiques évidentes, qui correspond sans ambiguïté à une table de hachage. Cargo.toml et pyproject.toml l'utilisent par défaut.
• YAML : la spécification actuelle est la 1.2.2. L'indentation exprime la hiérarchie, et il prend en charge commentaires, ancres et documents multiples. Les manifestes Kubernetes, GitHub Actions et Ansible en dépendent tous, au prix d'une spécification volumineuse et de divergences d'implémentation.
• CSON : CoffeeScript Object Notation, qui écrit la configuration à l'aide de littéraux d'objet CoffeeScript. Le config.cson d'Atom l'utilisait. Il prend en charge commentaires, clés non citées et virgules finales, mais son écosystème n'a jamais quitté le monde JavaScript.

2.1 Comparaison des capacités

Deux cellules méritent une note. TOML n'a pas de null, ce qui est l'échec le plus courant lors d'une conversion depuis JSON. Le comportement « date native » de YAML signifie qu'un parseur 1.1 transforme 2026-10-31 en objet date automatiquement, donc le type dérive entre langages.

3. Les commentaires : la seule faiblesse de JSON

La conclusion d'abord : si un humain maintient le fichier et doit expliquer pourquoi une valeur est ce qu'elle est, n'utilisez pas du JSON standard.

Quatre voies pratiques, classées par degré d'intrusion :

1. Passez à JSONC, qui est du JSON standard plus commentaires et virgules finales. Le settings.json et le tsconfig.json de VS Code l'utilisent. Le coût est que le lecteur doit utiliser un parseur conscient des commentaires comme jsonc-parser ; un simple JSON.parse échoue. Les détails sont dans JSON5 et JSONC : du JSON avec commentaires.
2. Gardez un document annexe. config.json reste lisible par machine, tandis que config.md explique ce que signifie chaque champ et pourquoi il porte cette valeur. Les deux vivent dans le même répertoire et changent dans le même commit.
3. Placez les explications dans le schéma. Les mots-clés description et $comment de JSON Schema peuvent documenter les champs, mais les schémas sont rarement livrés avec la configuration à l'exécution, donc la personne qui lit la config peut ne jamais les voir.
4. Passez à TOML ou YAML, en laissant le format fournir lui-même des commentaires que chaque parseur comprend.

复制{
  // Fixed at 8080: the frontend build script reads this port for its proxy
  "port": 8080,
  // Disable watching to avoid exhausting inodes in CI
  "watch": false
}

JSONC reste un dialecte : l'extension reste .json, mais seuls certains outils le comprennent. Quand les données quittent l'équipe ou franchissent une frontière de service, la ligne entre JSONC et JSON standard doit être documentée.

4. Dates et chaînes multi-lignes : le terrain de prédilection de TOML

TOML promeut la date-heure au rang de type de première classe avec quatre variantes : date-heure avec offset, date-heure locale, date locale et heure locale. Les chaînes multi-lignes ont une syntaxe dédiée qui préserve les retours à la ligne :

复制title = "json-toolkit"
created = 2026-10-31T09:00:00+08:00
description = """
A JSON toolkit for developers.
Every operation runs locally in the browser.
"""

La même information en JSON doit rétrograder la date en chaîne et échapper les retours à la ligne :

复制{
  "title": "json-toolkit",
  "created": "2026-10-31T09:00:00+08:00",
  "description": "A JSON toolkit for developers.\nEvery operation runs locally in the browser."
}

En JSON, "created" n'est qu'une chaîne qui ressemble par hasard à une date, donc l'information de type doit vivre dans un contrat de champ : les deux côtés doivent convenir que le champ est toujours RFC 3339. TOML donne au parseur un véritable objet date sans accord verbal requis.

YAML peut aussi contenir du texte multi-ligne, mais les deux styles de bloc signifient des choses différentes : | préserve les retours à la ligne tandis que > les replie en espaces. Choisissez le mauvais et une adresse ou une instruction SQL s'effondre sur une seule ligne, une erreur très difficile à attraper en revue.

5. Nombres : la différence la plus négligée

La spécification JSON n'impose aucune limite à la précision numérique, mais la RFC 8259 avertit aussi que l'interopérabilité est plus sûre quand les nombres sont traités comme des doubles IEEE 754. En JavaScript, les entiers au-delà de 2^53 - 1 perdent silencieusement de la précision :

复制JSON.parse('{"id":9007199254740993}').id
// 9007199254740992: the last digit is gone

TOML exige que les entiers 64 bits signés soient traités sans perte et qu'ils lèvent une erreur au lieu de tronquer silencieusement ; les flottants suivent binary64 et peuvent aussi être inf ou nan. YAML 1.1 porte un fardeau plus ancien : 1:30 est parsé comme 90 (sexagésimal), et les booléens acceptent yes, no, on et off. D'où le fameux « problème de la Norvège », où le code pays NO devient false.

Pour l'argent, ne comptez jamais sur le flottant dans aucun de ces formats : utilisez des unités mineures entières, des chaînes ou un type décimal de base de données. Le formatage et la précision sont traités plus en profondeur dans les frontières de la conversion JSON, YAML et XML.

6. Tables et imbrication : les frontières dures de TOML

TOML exprime l'imbrication avec des tables et des tableaux de tables :

复制[server]
port = 8080

[[routes]]
path = "/parse"
method = "POST"

[[routes]]
path = "/minify"
method = "POST"

Il a deux frontières dures que vous devez connaître avant de convertir :

• La racine d'un document TOML est une table, donc un document JSON dont le niveau supérieur est un tableau (comme [1, 2, 3]) n'a aucune représentation TOML légale ; il doit être enveloppé en {"items": [...]} ;
• TOML n'a pas de null, donc un champ JSON null doit soit être supprimé, soit remplacé par une chaîne vide ou une valeur sentinelle, avec la sémantique poussée vers le consommateur.

YAML est l'inverse : la profondeur d'imbrication est illimitée, et les ancres plus les clés de fusion peuvent réutiliser des fragments :

复制defaults: &defaults
  retries: 3
  timeoutMs: 5000

server:
  <<: *defaults
  port: 8080

Les ancres sont une capacité propre à YAML et une perte garantie lors de la conversion : JSON n'a aucune syntaxe de référence, donc le fichier étendu grossit et rien n'enregistre que les deux sections étaient autrefois la même configuration.

7. Choisir par scénario

Une règle empirique : laissez l'écosystème choisir le format de configuration, pas les préférences personnelles. Écrire du Rust signifie Cargo.toml, déployer sur Kubernetes signifie YAML, et construire une extension VS Code signifie JSONC. Ce n'est que dans un nouveau projet sans contrainte d'écosystème que « lequel est plus agréable à écrire » est une vraie question.

8. Frontières de conversion

Les outils de conversion garantissent les valeurs, jamais les commentaires. Ne concevez donc pas un pipeline bidirectionnel où « JSON est la source et YAML un artefact de build ». Soit vous générez dans un seul sens, soit vous maintenez un seul fichier source.

9. Liste de vérification

• [ ] Documentez quels types de fichiers utilisent quel format, et listez les dialectes autorisés ;
• [ ] Préférez TOML ou YAML pour la configuration maintenue par des humains, et JSON pour l'échange machine ;
• [ ] Stockez les dates en JSON comme chaînes RFC 3339 et marquez le format dans le schéma ;
• [ ] Représentez l'argent et les entiers au-delà de 2^53 en chaînes ou unités mineures, jamais en flottants ;
• [ ] Validez chaque format en CI avec son propre parseur, jamais avec JSON.parse pour YAML ;
• [ ] Migrez les formats dans un seul sens, et supprimez l'ancien fichier pour que les deux ne puissent pas dériver.

FAQ

Pourquoi la conversion JSON vers TOML échoue-t-elle sur certains champs ?

TOML n'a pas de null, et la racine d'un document TOML est une table, donc un champ JSON null doit être supprimé ou remplacé par une chaîne vide ou une sentinelle, et un tableau au niveau supérieur doit être enveloppé en {"items": [...]}. Les commentaires, types date et inf/nan sont aussi perdus en sens inverse, ce qui explique pourquoi la conversion devrait être à sens unique.

Faut-il garder deux fichiers de configuration dans des formats différents ?

Non. Les outils de conversion garantissent les valeurs mais jamais les commentaires, donc un pipeline où « JSON est la source et YAML un artefact de build » dérivera. Soit vous générez dans un seul sens, soit vous maintenez un seul fichier source et supprimez l'ancien après migration.

Comment ajouter des commentaires à un fichier de configuration JSON ?

Le JSON standard n'a pas de commentaires. Vous pouvez passer à JSONC (le dialecte de VS Code, lu avec jsonc-parser), garder un document annexe qui explique chaque champ, ou passer à TOML ou YAML. Les fichiers envoyés à d'autres systèmes devraient rester du JSON standard, avec les explications dans la documentation ou un schéma.

TOML ou YAML pour la configuration d'application ?

Choisissez TOML quand la structure est plate, majoritairement des paires clé-valeur, et que les dates natives comptent ; sa sémantique est plus prévisible et les différences entre parseurs plus faibles. Choisissez YAML quand il faut une imbrication profonde, des documents multiples, la réutilisation par ancres, ou quand l'écosystème cible est YAML-first, comme Kubernetes ou la CI. Les deux prennent en charge les commentaires, donc le vrai discriminant est la complexité structurelle et le verrouillage de l'écosystème.

Pourquoi NO devient-il false en YAML ?

YAML 1.1 traite yes, no, on, off, y et n comme des booléens, donc le code pays NO de la Norvège est parsé comme false. C'est le « problème de la Norvège ». Évitez-le en utilisant une implémentation qui suit YAML 1.2, ou en mettant entre guillemets chaque chaîne susceptible d'être mal interprétée.

CSON vaut-il encore la peine ?

Pas pour les nouveaux projets. CSON dépend de l'écosystème CoffeeScript, a peu d'outils maintenus, et un support éditeur et CI limité ; après l'arrêt de la maintenance d'Atom, ses cas d'usage se sont encore réduits. Si un projet a déjà de la configuration CSON, planifiez une migration ponctuelle vers JSON, TOML ou YAML plutôt que d'en ajouter.