JSON vs YAML — Les différences expliquées

Vous avez probablement remarqué que certains projets utilisent des fichiers .json pour la configuration tandis que d'autres utilisent .yaml ou .yml. Les deux formats représentent des données structurées. Les deux sont lisibles par un humain. Alors quelle est la vraie différence, et quand faut-il en choisir un plutôt que l'autre ?

J'ai utilisé les deux abondamment — JSON est mon format quotidien pour les APIs et l'échange de données, YAML est mon choix privilégié pour les manifests Kubernetes, GitHub Actions, et Docker Compose. Ils résolvent des problèmes similaires mais ont des personnalités très différentes.

Côte à côte : la même configuration dans les deux formats

Voici un objet de configuration de base de données écrit en JSON :

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "myapp",
    "ssl": true,
    "pool": {
      "min": 2,
      "max": 10
    },
    "replicas": ["replica1.db", "replica2.db"]
  }
}

Et voici la même configuration en YAML :

database:
  host: localhost
  port: 5432
  name: myapp
  ssl: true
  pool:
    min: 2
    max: 10
  replicas:
    - replica1.db
    - replica2.db

YAML est visiblement moins encombré. Pas de guillemets autour de la plupart des chaînes, pas d'accolades, pas de virgules. Pour un fichier de configuration que les humains éditent régulièrement, cette clarté s'accumule. Mais YAML y parvient en étant nettement plus complexe sous le capot.

Là où YAML excelle

• Fichiers de configuration éditables par des humains. Pipelines CI/CD (GitHub Actions, GitLab CI), manifests Kubernetes, Docker Compose, playbooks Ansible. Tout ça en YAML. Ce n'est pas un hasard — ce sont des fichiers que les humains écrivent à la main.
• Commentaires. YAML supporte les commentaires avec #. C'est très important pour les fichiers de configuration où vous voulez expliquer pourquoi un paramètre est ce qu'il est. JSON ne supporte pas les commentaires.
• Chaînes multi-lignes. YAML dispose de scalaires en bloc pour du contenu multi-ligne qui se lit naturellement. JSON requiert des séquences d'échappement \n.
• Moins de bruit visuel. Pas d'obligation de mettre des guillemets autour de la plupart des chaînes, pas d'accolades fermantes, pas de virgules finales à gérer.
• Ancres et alias. YAML vous permet de définir une valeur une seule fois et de la référencer ailleurs avec &anchor et *alias — pratique pour les fichiers de configuration DRY.

Là où JSON l'emporte

• Rigueur. JSON n'a qu'une seule représentation valide pour une structure de données donnée. YAML offre une douzaine de manières d'écrire la même chose, ce qui crée des incohérences entre les équipes.
• Pas de pièges liés à l'indentation. JSON utilise des accolades et des crochets. YAML utilise l'indentation, ce qui signifie qu'un seul espace mal placé peut silencieusement casser toute votre configuration.
• Performance de parsing. Les parseurs JSON sont rapides et simples. Les parseurs YAML sont complexes — YAML 1.1 a des règles de coercition de type implicite notoirement délicates.
• Support universel des bibliothèques. Chaque langage possède un parseur JSON robuste, sans dépendances. Les bibliothèques YAML varient en qualité et en conformité aux specs.
• Outillage. Linters, formateurs, validateurs de schéma — l'outillage JSON est plus mature et plus largement disponible.
• Payloads d'API. JSON est le langage universel des APIs web. Envoyer du YAML via HTTP serait non conventionnel et créerait des frictions.

Les pièges YAML qui vont vous brûler

YAML a des comportements véritablement surprenants qui ont causé de vrais incidents en production. La plupart proviennent des règles de types implicites dans YAML 1.1, que YAML 1.2 a resserrées. Mémorisez ces points avant de compter sur YAML pour quoi que ce soit de critique :

# YAML 1.1 implicit type coercion — all of these become booleans:
enabled: yes   # → true
disabled: no   # → false
country: NO    # → false (!)  ← the Norway Problem

# Safe practice: quote strings that look like booleans
country: "NO"
enabled: "yes"

• Entiers octaux. Dans YAML 1.1, 010 est parsé comme 8 (octal), pas 10. Pertinent pour des choses comme les permissions de fichiers.
• Tabulations vs espaces. YAML interdit les tabulations pour l'indentation. Mélangez une tabulation issue d'un éditeur de code et votre fichier se casse silencieusement ou lance une erreur cryptique.
• Null implicites. Une valeur vide en YAML devient null. Facile à manquer lors d'une édition manuelle.
• Ambiguïté chaîne vs nombre. port: 8080 vous donne un entier. version: 1.0 peut vous donner un float. Parfois vous voulez la chaîne "1.0". Mettez toujours des guillemets quand ça compte.

Guide de décision pratique

Optez pour YAML quand :

• Vous écrivez des fichiers de configuration que les humains éditent directement : CI/CD, Kubernetes, Docker Compose, Ansible
• Le fichier aura des commentaires expliquant les paramètres
• Les valeurs de chaînes multi-lignes sont fréquentes
• L'écosystème dans lequel vous travaillez utilise déjà YAML (ne combattez pas la convention)

Optez pour JSON quand :

• Vous envoyez ou recevez des données via une API
• Les données sont générées et consommées programmatiquement (sans édition humaine)
• Vous avez besoin d'une cohérence garantie de parsing entre différents outils et langages
• Vous travaillez dans un écosystème qui standardise sur JSON : npm (package.json), VS Code (settings.json), Angular, TypeScript

Convertir entre les deux

Besoin de convertir une configuration YAML en JSON pour un outil qui ne parle pas YAML ? Utilisez le convertisseur YAML vers JSON. Dans l'autre sens ? Le convertisseur JSON vers YAML s'en chargera. Le Formateur YAML est aussi pratique quand vous collez du YAML qui s'est désaligné. Et si votre YAML refuse de parser, le Validateur YAML vous indiquera exactement où se trouve le problème.

Le mot de la fin

JSON et YAML sont complémentaires, pas concurrents. Utilisez JSON pour l'échange de données — APIs, stockage de données programmatique, sérialisation. Utilisez YAML pour les fichiers de configuration que les humains lisent et éditent. La plupart des projets matures utilisent les deux : package.json pour les dépendances, .github/workflows/*.yml pour le CI. Une fois que vous comprenez pour quoi chaque format est optimisé, le choix devient évident.