JSON vs YAML: différences et quand utiliser chacun

YAML est un sur-ensemble du modèle de données de JSON : tout document JSON valide est aussi du YAML valide, mot pour mot. La différence n’est pas ce que chaque format peut représenter, mais comment chacun est écrit et à quel point chacun est confortable à éditer à la main.

Les mêmes données, deux manières

{
  "name": "web-app",
  "version": "1.0.0",
  "scripts": { "build": "vite build", "test": "vitest" },
  "dependencies": ["react", "vite"]
}

name: web-app
version: 1.0.0
scripts:
  build: vite build
  test: vitest
dependencies:
  - react
  - vite

Même document, même une fois analysé. YAML supprime les accolades, les crochets, les guillemets autour des chaînes simples et la plupart des virgules, et utilise l’indentation pour montrer l’imbrication à la place.

Là où ils diffèrent vraiment

Commentaires. YAML en a, # comme ça. JSON n’en a aucun, par conception ; un fichier de configuration .json avec une explication à côté d’un paramètre doit mettre cette explication ailleurs, généralement dans un README, car le parser rejettera une ligne // ou # sans hésitation. C’est déjà pourquoi la configuration maintenue à la main (pipelines CI, Docker Compose, manifestes Kubernetes) utilise YAML par défaut : la personne qui l’éditera dans un an a besoin de savoir pourquoi un paramètre est ce qu’il est, et un commentaire est le seul endroit qui survit à côté de la valeur.

Sensibilité aux espaces. L’indentation de YAML est structurelle, comme celle de Python. Deux espaces au lieu de quatre, ou une tabulation là où on attendait un espace, change ce que le document signifie ou le casse immédiatement, et le message d’erreur pour une mauvaise indentation est souvent moins précis que le “token inattendu à la ligne 4, colonne 12” d’un parser JSON. Les accolades et crochets de JSON sont explicites, donc l’indentation est uniquement cosmétique, ce qui fait partie de la raison pour laquelle JSON est le format que les machines génèrent et consomment : un script ne se soucie pas de la lisibilité et préfère des délimiteurs sans ambiguïté.

Plusieurs manières d’écrire la même valeur. YAML a un scalaire simple, une chaîne entre guillemets simples, une chaîne entre guillemets doubles, des scalars de bloc pour le texte multi-ligne, des ancres et des alias pour répéter une valeur par référence, et quelques conversions de type implicites (yes et no étaient analysés comme des booléens en YAML 1.1, ce qui est exactement le genre de surprise qui a fait du “problème de Norvège”, un code pays NO lu comme faux booléen, un piège YAML bien connu). JSON a une manière d’écrire une chaîne, une manière d’écrire un nombre, et aucune conversion implicite. Moins de manières d’écrire la même chose, c’est moins de manières de l’écrire mal, ce qui est le vrai argument pour JSON dans une charge utile machine à machine.

Taille à part la verbosité et les commentaires. Une fois les espaces supprimés, JSON et YAML se comparent à des tailles comparables pour les mêmes données ; l’avantage de YAML est la lisibilité lorsqu’il est édité par une personne, pas le nombre d’octets brut.

Quand utiliser chacun

JSON pour tout ce qu’un programme génère et qu’un autre programme consomme sans qu’un humain le lise entre les deux : charges API, échange de données, tout ce qui est sérialisé et désérialisé dans le même cycle requête-réponse.
YAML pour tout ce qu’une personne édite régulièrement à la main et qui a besoin de commentaires ou de chaînes multi-ligne pour rester maintenable : configuration CI, manifestes Kubernetes, fichiers de configuration d’application livrés avec de la documentation en ligne.

Beaucoup d’outils acceptent les deux et convertissent en interne, ce qui est généralement plus utile que de choisir un camp permanent : écrivez la configuration dans le format que les personnes qui la maintiennent préfèrent, et convertissez en JSON au point où autre chose a besoin de la consommer programmatiquement.

Conversion entre les deux

Le Convertisseur JSON en YAML fonctionne dans les deux sens : il écrit correctement les ancres, les alias et les flux multi-documents plutôt que d’aplatir tout en scalaires simples, et en lisant le YAML en retour, il met entre guillemets tout ce qui ne ferait pas le tour complet sous le même type (une chaîne de version comme "1.0" reste une chaîne, pas le nombre 1). Rien de ce que vous convertissez n’est téléchargé ; la conversion s’exécute dans votre navigateur comme chaque outil de ce site.