YAML vs JSON vs TOML — Quel format de configuration devriez-vous vraiment utiliser ?

En 2015, un playbook Ansible a été corrompu à cause de cette ligne :

country: NO

La configuration a été chargée sans erreur. Aucun avertissement de parser. Mais country n’était pas défini comme une chaîne "NO". Il était défini comme false. Puisque dans YAML 1.1, NO est un booléen. De même, yes, on, off, yet n. C’est le problème de Norvège, et il a corrompu silencieusement les configurations depuis des années.

Ce n’est pas un rapport de bug YAML. C’est une mise en contexte pour la décision que vous allez prendre : YAML, JSON ou TOML pour votre prochaine configuration de fichier ? Chaque format présente des compromis réels, et la réponse « utilise simplement ce que l’écosystème utilise » ne s’applique pas toujours.

La Même Configuration, Trois Manières

Avant le crash, voici la même configuration d’application écrite dans les trois formats :

YAML

# App configuration
app:
  name: my-api
  port: 8080
  debug: false

database:
  host: localhost
  port: 5432
  name: mydb
  pool_size: 10

logging:
  level: info
  format: json
  outputs:
    - stdout
    - /var/log/app.log

JSON

{
  "app": {
    "name": "my-api",
    "port": 8080,
    "debug": false
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "mydb",
    "pool_size": 10
  },
  "logging": {
    "level": "info",
    "format": "json",
    "outputs": [
      "stdout",
      "/var/log/app.log"
    ]
  }
}

TOML

# App configuration
[app]
name = "my-api"
port = 8080
debug = false

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

[logging]
level = "info"
format = "json"
outputs = ["stdout", "/var/log/app.log"]

YAML est le plus compact mais le plus chargé syntaxiquement. JSON est le plus verbeux mais le plus explicite. TOML se situe au milieu : lisible sans les conversions implicites de type de YAML.

YAML : Puissant, permis, et plein de pièges

YAML est le choix par défaut pour les pipelines CI/CD (GitHub Actions, GitLab CI, CircleCI), les manifestes Kubernetes, les playbooks Ansible et la plupart des outils développés. Vous n’avez pas vraiment le choix de YAML — c’est YAML qui choisit vous.

Les pièges documentés :

1. Le problème des booléens (le problème de Norvège)

YAML 1.1 — le spécificateur que la plupart des parsers implémentent — considère un nombre alarmant de chaînes comme des booléens :

# YAML 1.1 boolean values (all parsed as true or false)
enabled: yes      # true
disabled: no      # false  
active: on        # true
paused: off       # false
valid: true       # true
invalid: false    # false

# The Norway Problem in practice:
country_codes:
  NO: Norway      # Key "NO" is fine, but value "NO" becomes false
  SE: Sweden
  YES: Yemen      # "YES" also becomes true

# The fix: quote your strings
country_codes:
  NO: "Norway"
  SE: "Sweden"

YAML 1.2 (publiée en 2009) a corrigé cela — seulement true et false sont des booléens. Le problème est que PyYAML n’a pas entièrement adopté le comportement de 1.2 avant la version 6.0 en 2021, et Go utilise encore les sémantiques de 1.1 en 2024. Si vous utilisez Psych (Ruby) version inférieure à 4.0 ou n’importe quelle version antérieure à 6.0 de PyYAML, vous êtes sur 1.1. gopkg.in/yaml.v2 2. Les tabs vont tuer votre configuration

YAML interdit les caractères de tabulation pour l’indentation. Seuls les espaces sont valides. Votre éditeur peut afficher les tabs et les espaces de manière identique, le fichier peut paraître correct, mais YAML lancera toujours :

C’est l’erreur qui fait que les développeurs débutants remettent en question leur parcours professionnel. Configurez votre éditeur pour transformer les tabs en espaces dans les fichiers YAML. Tous les éditeurs le supportent ; pas tous ont cette fonction par défaut.

yaml.scanner.ScannerError: while scanning a block mapping
  found character '\t' that cannot start any token

3. Les chaînes multilignes ne sont pas évidentes

Personne ne se les rappelle sans les consulter. Le mnémonique que j’utilise :

# | (literal block): preserves newlines exactly
description: |
  Line one.
  Line two.
  Line three.
# Result: "Line one.\nLine two.\nLine three.\n"

# > (folded block): folds newlines into spaces
short_desc: >
  This will all become
  one long line.
# Result: "This will all become one long line.\n"

# Trailing newlines: | adds one, |+ adds all, |- strips them all
desc_stripped: |-
  No trailing newline.

ressemble à une ligne de retour, | ressemble à quelque chose qui est comprimé. C’est encore confus après trois ans. > Quand YAML gagne

Vous écrivez des manifestes Kubernetes, des workflows GitHub Actions ou des playbooks Ansible — vous n’avez pas le choix.

• Votre configuration comporte de nombreux commentaires expliquant des valeurs non évidentes. YAML supporte les commentaires inline ; JSON et TOML les supportent aussi, mais YAML semble le plus naturel pour les configurations annotées.
• Vos données ont des structures fortement imbriquées qui seraient affichées de manière désagréable avec les tables planes de TOML.
• L’équipe est déjà familière avec le format et dispose d’un linter (yamllint) dans le pipeline.
• JSON : Le travailleur fiable et banal

JSON a été conçu comme un format d’échange de données, pas comme un format de configuration. Douglas Crockford a délibérément omis les commentaires — son argument était que les commentaires seraient utilisés pour des directives que les parsers pourraient interpréter différemment. C’est pourquoi

n’a pas de commentaires et package.json est techniquement JSON avec commentaires (JSONC), qui est une chose séparée que la plupart des parsers JSON ne supportent pas. tsconfig.json Les vrais problèmes de JSON pour les fichiers de configuration :

Aucun commentaire.

• Vous ne pouvez pas expliquer pourquoi et pas 5. Vous ne pouvez pas laisser une TODO. Vous ne pouvez pas marquer un champ comme déprécié. C’est vraiment douloureux pour des fichiers de configuration qui survivent à leurs auteurs. "maxRetries": 3 Aucune virgule en fin de ligne.
• Ajouter un élément à un tableau signifie modifier la ligne précédente en ajoutant une virgule. Chaque modification JSON devient une modification de deux lignes. Chaque conflit de fusion est légèrement pire qu’il n’aurait dû l’être. Trop verbeux pour les données imbriquées.
• Six lignes de crochets et de parenthèses pour ce que YAML fait en trois lignes d’indentation. Tous les nombres sont du même type.
• JSON ne distingue pas les entiers des flottants. sont tous simplement des nombres, et ce que votre langage les déserialise dépend du parser. 1 et 1.0 Mais la prévisibilité de JSON est aussi sa principale caractéristique. Chaque langage dispose d’un parser JSON. Le spécificateur est clair. Il n’y a pas de conversions implicites. Une chaîne est toujours une chaîne —

ne devient jamais "yes" . Si vous devez valider un fichier de configuration JSON de manière programmée, truepeut détecter les erreurs de syntaxe avant qu’elles ne touchent la production — utile lorsque quelqu’un édite un fichier de configuration à la main et oublie une virgule en fin de ligne. IO Tools’ JSON Formatter Quand JSON gagne

Des configurations ou réponses API consommées par plusieurs langages ou services. JSON est universel ; le support de TOML est fragmenté dans certains écosystèmes.

• Vous avez besoin de garanties strictes sur les types. La validation de schéma JSON est mature, bien supportée et largement utilisée (VS Code l’utilise pour l’autocomplétion des paramètres).
• La configuration est générée par machine. Personne n’écrira du JSON à la main s’il peut l’éviter — mais les machines le font parfaitement.
• Vous travaillez dans Node.js ou JavaScript front-end, où JSON est un citoyen natif.
• TOML : Une configuration opiniâtre, bien faite

TOML (Tom’s Obvious, Minimal Language) a été créé par Tom Preston-Werner, co-fondateur de GitHub, spécifiquement pour les fichiers de configuration. Il a atteint la version 1.0 en janvier 2021. C’est le format par défaut pour Rust’s

, Python’s Cargo.toml, et les sites statiques Hugo. pyproject.tomlLa philosophie de conception de TOML : les types doivent être explicites, la structure doit être plane autant que possible, et il doit y avoir exactement une manière évidente d’écrire toute valeur de configuration.

Les inconvénients bruts :

# Types are unambiguous in TOML
name = "my-app"          # string: always quoted
port = 8080              # integer
threshold = 3.14         # float
enabled = true           # boolean: only true/false, no yes/no
created = 2024-01-15     # date: native type
tags = ["api", "prod"]   # array

# "yes" is just a string. Always.
country = "NO"           # string "NO", no boolean nonsense

La syntaxe des tableaux de tables est vraiment maladroite.

• ressemblent mais se comportent complètement différemment. Le spécificateur a du sens ; la distinction visuelle ne l’a pas. [[products]] et [products.details] L’imbriquation profonde devient verbeuse.
• Ce que YAML fait en 5 lignes indentées, TOML le fait en 3 en-têtes séparés. Pour des configurations de plus de 3 niveaux, TOML commence à sembler le mauvais outil. La disponibilité des parsers.
• Des parsers TOML existent pour chaque langage majeur, mais ils varient en conformité avec le spécificateur. Le ensemble de tests de conformité TOML révèle régulièrement des cas limites. Les parsers JSON ont été testés à des échelles de usage bien supérieures. La familiarité de l’équipe.
• Si vous utilisez TOML en dehors de l’écosystème Rust ou Python, attendez qu’au moins un membre de l’équipe ouvre une PR avec « qu’est-ce que ce format ? » Quand TOML gagne

Les projets Rust —

• est le standard et le outillage est excellent. Cargo.toml Les projets Python utilisant
• (PEP 518) — c’est désormais la maison recommandée pour les configurations d’outils comme Black, Ruff, mypy et pytest. pyproject.toml Des configurations simples et planes où la sensibilité à l’indentation de YAML serait un inconvénient.
• Vous souhaitez un support natif des dates/heures sans les sérialiser en chaînes.
• Le guide de décision rapide

Kubernetes / pipeline CI/CD / playbook Ansible ?

• YAML. Aucune autre possibilité. Configuration d’API consommée par plusieurs services dans des langages différents ?
• JSON. Projet Rust ?
• TOML (convention Cargo.toml). Configuration de projet Python (linters, formatters, outils de construction) ?
• TOML (pyproject.toml est désormais le standard). Configuration d’un site statique (Hugo, Zola) ?
• TOML, bien que ces derniers supportent généralement les trois formats. Configuration de projet Node.js ?
• JSON (écosystème package.json), ou YAML si vous avez besoin de commentaires. Les humains vont éditer fréquemment ce fichier et doivent laisser des notes ?
• YAML ou TOML (les deux supportent les commentaires). Pas JSON. Vous souhaitez une sécurité stricte sur les types et une validation de schéma ?
• JSON + schéma JSON. La réponse honnête pour la plupart des nouveaux projets : utilisez ce que l’écosystème du langage principal attend. Rust attend TOML. Les outils Python attendent TOML ou YAML. Node.js attend JSON. Si vous écrivez quelque chose d’indépendant de langage, TOML pour les configurations éditées par les humains et JSON pour les configurations générées par machine ou consommées par des machines est une division raisonnable par défaut.

YAML vs JSON vs TOML — Quel format de configuration devez-vous vraiment utiliser ? 2

Vous aimerez peut-être aussi