YAML vs JSON — quand utiliser lequel, et pourquoi la plupart des équipes utilisent les deux

Si vous avez déjà ouvert un manifest Kubernetes, un workflow GitHub Actions ou un fichier docker-compose, vous avez utilisé YAML. Si vous avez déjà appelé une API REST ou écrit un fichier de config pour un projet Node.js, vous avez utilisé JSON. Ce sont tous les deux des formats de sérialisation. Ils décrivent tous les deux les mêmes types de structures de données — maps, tableaux, chaînes, nombres, booléens, null. Alors pourquoi en avons-nous deux ?

La réponse courte : YAML optimise pour les humains, JSON optimise pour les machines. La réponse longue implique quelques décennies d’expérience de développement, quelques réunions de comité et un étonnant nombre de cas limites. Explorons.

Ce que JSON fait bien

JSON (JavaScript Object Notation) s’est popularisé au début des années 2000 comme format de payload pour les requêtes AJAX. Il était volontairement petit — six types de valeur, pas de commentaires, pas de virgules de fin, pas d’ambiguïté. Cette rigueur est sa superpuissance sur le réseau :

• Les analyseurs sont petits et rapides. JSON.parse est livré avec chaque navigateur et chaque runtime. Il n’y a rien à réfléchir.
• Les erreurs sont sans ambiguïté. Quand le JSON est cassé, l’analyseur vous indique exactement la ligne et la colonne.
• Les machines s’accordent sur la sémantique. Un nombre est un nombre, une chaîne est une chaîne, true est true. Il n’y a pas de débat « est-ce que yes est un booléen ou une chaîne ? »

C’est pourquoi JSON est la lingua franca des API. Quand deux services communiquent, vous voulez le format avec le moins de surprises.

Ce que YAML fait bien

YAML (YAML Ain’t Markup Language) a été conçu pour les fichiers de configuration écrits par des humains. Il a sacrifié une partie de la rigueur de JSON pour la lisibilité :

• Pas d’accolades, pas de crochets. La structure est l’indentation. Un docker-compose.yml se lit de haut en bas comme une liste.
• Les commentaires. Un # commence un commentaire. JSON n’a pas de syntaxe de commentaire — et l’absence de commentaires est la raison la plus courante pour laquelle les équipes passent de JSON à YAML pour les fichiers de config.
• Les ancres et références. &anchor et *reference vous permettent de définir une valeur une seule fois et de la réutiliser. JSON n’a pas d’équivalent ; vous devez copier-coller.
• Les chaînes multi-lignes. Les blocs littéraux (|) et les blocs pliés (>) gèrent le texte et le code sans jongler avec les échappements.

C’est pourquoi YAML domine dans les endroits où les humains lisent et écrivent à la main : Kubernetes, GitHub Actions, GitLab CI, les livrables Ansible, docker-compose, CloudFormation, les spécifications OpenAPI et la vague de 2025 des fichiers de config d’agents IA (.github/agents.yml, les manifests de serveur MCP, les équipements d’évaluation).

L’asymétrie

Voici le secret bien gardé : YAML est un sur-ensemble du modèle de données de JSON. Chaque fichier JSON valide peut être exprimé en YAML, mais l’inverse n’est pas vrai. YAML a des fonctionnalités que JSON n’a tout simplement pas — commentaires, ancres, fichiers multi-documents, balises personnalisées. Une fois que vous écrivez du YAML avec des ancres, vous ne pouvez pas le reconvertir en JSON sans perte. Les ancres disparaissent.

Cela compte pour les outils. Si vous avez un fichier YAML avec &defaults *defaults, la conversion en JSON étendra soit les références (produisant silencieusement un fichier plus grand) soit les supprimera (produisant silencieusement un fichier plus petit). Il en va de même pour les commentaires. JSON n’a nulle part où les mettre.

Quand utiliser lequel

Utilisez JSON quand :

• Vous envoyez des données sur le réseau (API, files d’attente de messages, payloads d’événements).
• Le fichier est lu par du code, pas par des humains.
• Vous voulez des messages d’erreur sans ambiguïté avec des analyseurs rigoureux.
• Vous optimisez la vitesse d’analyse sur des appareils contraints.

Utilisez YAML quand :

• Un humain est l’auteur et le lecteur principal du fichier.
• Vous voulez des commentaires pour expliquer l’intention.
• Vous voulez réutiliser des morceaux de config avec des ancres.
• Les outils de votre domaine l’attendent (Kubernetes, CI, etc.).

La réponse pragmatique pour la plupart des équipes : JSON pour le réseau, YAML pour la config, les deux pour l’échange de données. En cas de doute, stockez la version canonique en JSON (sans perte) et émettez du YAML pour la consommation humaine (avec commentaires et ancres) uniquement lorsque le public est un développeur qui ouvre un éditeur de texte.

Les pièges courants lors de la conversion entre les deux

1. Les nombres et booléens sont typés automatiquement en YAML. port: 8080 est un nombre. port: "8080" est une chaîne. Oublier de mettre des guillemets peut changer votre type.
2. Les ancres et commentaires sont supprimés en JSON. Pas de solution — le format n’a pas de place pour les mettre.
3. Le null de YAML est ambigu. key: (valeur vide) est null. key: null est aussi null. key: "" est une chaîne vide. Trois choses différentes.
4. Les tabulations cassent YAML. L’indentation doit être en espaces. Les tabulations sont une erreur.
5. YAML 1.1 vs 1.2 vs 1.2.2. YAML 1.1 traitait yes, no, on, off comme des booléens. YAML 1.2 (la spec utilisée par js-yaml, PyYAML et la plupart des analyseurs en 2026) ne le fait pas. La version de maintenance 1.2.2 en 2025 a resserré quelques cas limites autour des marqueurs de fin de document et de la gestion du BOM — la plupart des analyseurs ont adopté les corrections silencieusement. Si vous migrez d’un codebase de 2018, votre config pourrait encore casser de façon subtile.

Les outils qui aident

Quand vous passez de l’un à l’autre — et vous le ferez, parce que chaque équipe utilise les deux — un convertisseur rapide côté client est votre allié. Les outils YAML to JSON et JSON to YAML de DevSpeedTools s’exécutent entièrement dans votre navigateur, donc les fichiers de config avec des secrets ne quittent jamais votre machine. Ouvrez DevTools → Réseau et vous verrez aucune requête transportant vos données.

Pour le YAML qui est devenu désordonné au fil du temps, le formateur YAML normalisera l’indentation à deux espaces et corrigera la citation incohérente. Pour les fichiers qui ne s’analysent pas, le validateur YAML vous montre la ligne et la colonne exactes de chaque erreur.

Le fond du problème : arrêtez de traiter YAML et JSON comme des formats concurrents. Ils sont complémentaires. Le bon format dépend de qui lit le fichier — une machine, ou un développeur épuisé à 23h qui essaie de comprendre pourquoi son déploiement est cassé.