JSON vs YAML : choisir le bon format de configuration

JSON et YAML ressemblent à la même chose sous des costumes différents jusqu’à ce que vous essayiez de maintenir un fichier de configuration de mille lignes dans l’un ou l’autre. Les différences comptent, et la plupart d’entre elles ne concernent pas la syntaxe — elles concernent ce que chaque format fait quand vous êtes légèrement dans l’erreur.

Le même exemple dans les deux formats

La façon la plus rapide de ressentir la différence est de lire des données identiques côte à côte.

JSON

{
  "name": "convertitive",
  "version": "1.4.0",
  "ports": [80, 443],
  "features": {
    "darkMode": true,
    "telemetry": false
  },
  "owners": ["[email protected]", "[email protected]"]
}

YAML

name: convertitive
version: 1.4.0
ports:
  - 80
  - 443
features:
  darkMode: true
  telemetry: false
owners:
  - [email protected]
  - [email protected]

Le YAML est environ 30 % plus court et sans doute plus lisible par un humain qui n’a jamais vu l’un ni l’autre. Le JSON est sans ambiguïté pour une machine, compatible avec les analyseurs, et survit au copier-coller dans n’importe quel éditeur de texte sur n’importe quel système d’exploitation sans dommages de caractères invisibles.

Ce dans quoi YAML excelle

Commentaires

YAML prend en charge les # commentaires de lignepartout. JSON ne le fait pas — la RFC 8259 les exclut délibérément. Pour un fichier de configuration que des humains liront et éditeront, les commentaires ne sont pas un luxe ; c’est ainsi que vous documentez pourquoi un indicateur est désactivé ou quelle plage de valeurs un paramètre accepte réellement.

# pin to a specific patch release; do not auto-update
version: 1.4.0

ports:
  - 80
  # 443 is here so the LB health check works; do not remove
  - 443

Chaînes multi-lignes

YAML a deux styles de scalaires en bloc pour les chaînes multi-lignes. | préserve les sauts de ligne, >les replie en espaces. Les deux permettent d’écrire des valeurs de longueur paragraphe sans soupe d’échappement.

description: |
  Convertitive est un site d'outils.
  Il charge vite et n'a pas de popups.

summary: >
  Une seule phrase écrite sur
  plusieurs lignes pour le confort de l'éditeur.

Ancres et alias

YAML vous permet d’étiqueter un nœud avec & et de le référencer ailleurs avec *. Les clés de fusion (<<) étendent un mapping avec un autre. Le résultat est un vrai DRY dans un fichier de configuration :

defaults: &defaults
  retries: 3
  timeout_ms: 5000

production:
  <<: *defaults
  endpoint: api.example.com

staging:
  <<: *defaults
  endpoint: staging.api.example.com
  timeout_ms: 30000  # remplace la valeur par défaut

JSON n’a rien d’équivalent. La solution de contournement est soit un moteur de templates (Jinja, Helm) soit un post-traitement au moment du chargement, les deux ajoutant de la machinerie que les configurations natives JSON évitent.

Ce dans quoi JSON excelle

Analyse sans ambiguïté

JSON a une grammaire de cinq pages. Deux analyseurs corrects s’accorderont sur chaque document. YAML a une grammaire de quatre-vingt-dix pages avec de multiples interprétations valides du même document selon la version de l’analyseur. La rigueur de JSON est la fonctionnalité.

Omniprésence des outils

Chaque langage est livré avec un analyseur JSON dans sa bibliothèque standard. YAML nécessite une dépendance tierce dans la plupart des environnements — PyYAML, js-yaml, snakeyaml, go-yaml. Pour un fichier de configuration intégré dans un outil qui doit fonctionner partout, la portabilité zéro-dépendance de JSON compte.

Le problème de la Norvège — littéralement

L’erreur YAML la plus célèbre : dans YAML 1.1, la chaîne NO est analysée comme le booléen false. Les listes de pays qui incluent le code ISO de la Norvège (NO) deviennent [false, ...] sauf entre guillemets. La même chose se produit avec YES, ON, OFF, et diverses capitalisations. YAML 1.2 corrige cela en ne traitant que les minuscules true et falsecomme des booléens, mais une quantité surprenante d’outils utilise encore 1.1 par défaut en 2026.

Sécurité par défaut

La spec YAML inclut des balises de type qui permettent à un document d’instruire l’analyseur d’instancier des classes arbitraires. Plusieurs liaisons de langages ont honoré cela par défaut pendant des années, ce qui signifie que charger un document YAML contrôlé par un attaquant pouvait exécuter du code arbitraire. La correction est d’utiliser un chargeur « safe » (yaml.safe_load en Python, YAML.safe_load en Ruby).

Pièges partagés

Précision des nombres JSON

La spec JSON dit que les nombres peuvent être de magnitude et précision arbitraires. JSON.parse de JavaScript et la plupart des implémentations non-JS les désérialisent en réalité en doubles IEEE 754, qui ne peuvent représenter les entiers exactement que jusqu’à 2^53 - 1. Un ID Twitter snowflake, un ID de charge Stripe, ou tout entier à 19 chiffres s’arrondira silencieusement. La correction est d’encoder les grands entiers comme des chaînes ou d’utiliser un analyseur avec prise en charge BigInt.

Un arbre de décision

Pour les nouveaux projets où vous contrôlez le consommateur :

1. Format de transfert machine à machine ?Utilisez JSON. Chaque langage l’analyse, les commentaires ne comptent pas, et la rigueur élimine toute une classe de bugs d’intégration.
2. Configuration éditée par des humains de moins de 100 lignes ?Utilisez YAML si le consommateur attend YAML, TOML sinon.
3. Configuration éditée par des humains de plus de 100 lignes, profondément imbriquée ? Les ancres et scalaires de bloc de YAML commencent à rapporter à cette taille. Fixez YAML 1.2 dans la documentation.
4. Entrée non fiable ? JSON est plus sûr par défaut. Si vous devez accepter YAML, utilisez le chargeur safe et un schéma.
5. Le consommateur est fixe (Kubernetes, npm) ?Suivez le consommateur. Ne combattez pas l’écosystème.

Conversion entre les deux

La conversion est mécanique car YAML 1.2 est un sur-ensemble de JSON. JSON en entrée, YAML en sortie est toujours sans perte. YAML en entrée, JSON en sortie est sans perte uniquement si le YAML utilise des types primitifs et pas d’ancres/alias qui nécessiteraient une expansion.

Notre convertisseur JSON ↔ YAML gère les deux directions dans le navigateur et vous montre la ligne où l’analyse échoue si l’entrée est invalide. Pour le travail JSON pur — formatage, validation, minification — le formateur JSON est un outil plus précis.

La conclusion honnête

JSON est le bon choix par défaut pour tout ce sur quoi deux programmes doivent s’accorder. YAML est le bon choix par défaut pour tout ce qu’un humain éditera longuement. La plupart des systèmes de production finissent par utiliser les deux : YAML à la frontière humaine (charts Helm, workflows GitHub Actions, configuration d’application), JSON sur le réseau et au repos dans les bases de données.