JSON vs YAML : différences et quand utiliser chacun

JSON et YAML résolvent le même problème —— représenter des données structurées sous forme de texte —— mais font des compromis opposés. JSON est optimisé pour un parsing machine sans ambiguïté ; YAML est optimisé pour l'écriture humaine. Depuis YAML 1.2, tout document JSON valide est aussi un YAML valide. Ce guide compare leur syntaxe, leurs types et leurs fonctionnalités, et explique quand utiliser chacun.

La réponse courte

Utilise JSON pour les données échangées entre programmes —— réponses d'API, payloads de messages, tout ce qui est généré par machine. Utilise YAML pour les fichiers que les humains écrivent et éditent à la main —— pipelines CI, manifests Kubernetes, config d'application —— là où les commentaires et la lisibilité comptent.

Syntaxe côte à côte

Les mêmes données dans les deux formats :

# YAML
service: api
replicas: 3
ports:
  - 8080
  - 8443
env:
  LOG_LEVEL: info
  DEBUG: false

// JSON
{
  "service": "api",
  "replicas": 3,
  "ports": [8080, 8443],
  "env": {
    "LOG_LEVEL": "info",
    "DEBUG": false
  }
}

YAML utilise l'indentation au lieu des accolades et des crochets, supprime la plupart des guillemets et autorise les commentaires. JSON est plus verbeux mais n'a pas d'espacement significatif, ce qui le rend bien plus facile à parser et générer de façon fiable.

YAML est un sur-ensemble de JSON

Depuis YAML 1.2 (2009), YAML est un sur-ensemble strict de JSON —— tout document JSON valide est un YAML valide, parce que YAML a adopté directement la syntaxe « flow » de JSON. C'est pour cela qu'on peut coller du JSON dans un fichier YAML et que ça marche tel quel. Pour l'histoire derrière tout ça, voir YAML 1.2 et compatibilité JSON.

# Ceci est du YAML valide —— c'est aussi du JSON valide
{"service": "api", "replicas": 3}

Comparaison des fonctionnalités

Gestion des types : les arêtes vives de YAML

L'empressement de YAML à inférer des types provoque des surprises que les guillemets explicites de JSON évitent :

# Le « Norway problem » —— deviennent des booléens dans les parsers YAML 1.1
countries:
  - NO   # → false (!)
  - SE
  - true # → booléen, pas la chaîne "true"

version: 1.20   # → le nombre 1.2, le zéro final perdu
zip: 01234      # → 668 (parsé en octal) dans certains parsers

JSON n'a aucune de ces ambiguïtés : "NO" est toujours la chaîne NO, et "01234" est toujours cette chaîne. Quand une valeur YAML doit être une chaîne, mets-la explicitement entre guillemets.

Où TOML et JSON5 se situent

Deux autres formats de config « human-friendly » courants qui apparaissent dans la même conversation :

• TOML —— style section/clé, conçu pour la configuration d'app éditée à la main (Cargo, Poetry, Hugo). Plus strict que YAML, pas d'indentation significative, valeurs typées natives (datetime, entier, flottant, tableau, table inline). Idéal quand les données sont surtout des tables plates.
• JSON5 —— JSON avec des assouplissements pratiques pour les devs : commentaires, virgules finales, clés sans guillemets, apostrophes, chaînes multi-lignes. Pas quelque chose qu'un parser JSON standard acceptera ; tu opt-in avec une lib JSON5 (ou un parser JSONC pour le sous-ensemble commentaires + virgules finales, par ex. tsconfig.json).

Positionnement approximatif : JSON pour l'échange machine, YAML pour la config profondément imbriquée éditée par des humains, TOML pour la config plate d'app/outil, JSON5/JSONC quand tu veux JSON-avec-commentaires pour des configs d'éditeur sans adopter les règles d'espaces de YAML.

Quand utiliser lequel

• Utilise JSON pour : APIs REST/GraphQL, files de messages, localStorage du navigateur, package.json, tout ce qui est généré ou consommé par du code.
• Utilise YAML pour : GitHub Actions / GitLab CI, Kubernetes et Docker Compose, playbooks Ansible, config d'app que des humains éditent et veulent commenter.

Un motif courant : écrire la config en YAML pour la lisibilité, puis convertir en JSON au build ou au load pour que ton application ne parse que du JSON.

Convertir entre JSON et YAML

# Python —— YAML vers JSON
import yaml, json
data = yaml.safe_load(open('config.yaml'))
print(json.dumps(data, indent=2))

# Ligne de commande avec yq
yq -o=json '.' config.yaml      # YAML → JSON
yq -P '.' config.json           # JSON → YAML

Ou convertis instantanément dans ton navigateur avec le convertisseur YAML ⇄ JSON de fixjson —— colle du YAML, obtiens du JSON (ou l'inverse), sans envoyer de données à aucun serveur.

Foire aux questions

YAML est-il meilleur que JSON ?

Aucun n'est « meilleur » —— ils sont calibrés pour des tâches différentes. YAML est meilleur pour la config éditée par des humains (commentaires, lisibilité) ; JSON est meilleur pour l'échange de données machine (parsing simple, rapide, sans ambiguïté).

Le JSON est-il du YAML valide ?

Oui. Depuis YAML 1.2, YAML est un sur-ensemble strict de JSON, donc tout document JSON valide est aussi un YAML valide. L'inverse n'est pas vrai —— la plupart du YAML n'est pas du JSON valide.

Pourquoi YAML transforme-t-il « NO » en false ?

YAML infère les types à partir des scalaires sans guillemets, et certains parsers lisent NO, yes, on, off comme des booléens (le « Norway problem »). Mets la valeur entre guillemets ("NO") pour forcer une chaîne. JSON évite ça entièrement avec des guillemets obligatoires.

Dois-je utiliser YAML ou JSON pour les fichiers de config ?

Utilise YAML si des humains éditent le fichier et profitent des commentaires et chaînes multi-lignes ; utilise JSON s'il est généré ou consommé par du tooling. Beaucoup d'équipes écrivent du YAML et convertissent en JSON au load.

Convertis et valide dans ton navigateur

• Convertisseur YAML ⇄ JSON —— convertis dans les deux sens, côté client
• Formateur YAML —— formate, ré-indente et valide du YAML
• Qu'est-ce que JSON ? —— le format dont YAML est un sur-ensemble
• Comment formater du JSON —— pretty-print la sortie convertie
• YAML 1.2 et compatibilité JSON —— comment YAML est devenu un sur-ensemble de JSON