YAML ou JSON : lequel choisir, et quand

Vous ouvrez deux fichiers de configuration qui contiennent exactement les mêmes réglages. L’un est encadré d’accolades et de guillemets ; l’autre se lit presque comme un plan structuré. Ils portent des données identiques, et pourtant ils n’ont rien en commun à l’œil. Cet écart, du strict au lisible, résume toute l’histoire de YAML face à JSON, et il vous dit lequel choisir, et quand.

En bref : JSON et YAML décrivent les mêmes structures : tables d’association, listes et valeurs simples. JSON est strict, fait d’accolades et de crochets, et idéal pour les API et les échanges de machine à machine où l’analyse garantie compte. YAML repose sur l’indentation, accepte les commentaires et se prête bien mieux à l’édition manuelle, ce qui explique son succès pour les fichiers de configuration. Tout YAML se convertit en JSON et inversement. Choisissez JSON pour l’échange de données, YAML pour la configuration écrite par des humains.

Ce qu’ils ont en commun

Les deux formats représentent les mêmes trois briques de base : les mappings (paires clé-valeur), les séquences (listes ordonnées) et les scalaires (valeurs simples comme du texte, des nombres et des booléens). Imbriquez-les et vous pouvez décrire presque n’importe quelle donnée structurée. Comme le modèle sous-jacent est identique, les deux sont interchangeables sur le fond. Un document écrit dans l’un peut toujours être réécrit dans l’autre.

YAML formalise d’ailleurs ce recouvrement. La spécification YAML définit le format comme un sur-ensemble de JSON, ce qui signifie qu’un fichier JSON valide est déjà du YAML valide. Vous pouvez coller du JSON tel quel dans un parseur YAML, et ça fonctionne. L’inverse demande une étape de conversion, puisque YAML possède des fonctionnalités absentes de JSON, mais aucune information n’est perdue dans un sens comme dans l’autre. C’est pourquoi un convertisseur YAML vers JSON peut faire l’aller-retour sans abîmer vos données : les structures sont les mêmes, seule la syntaxe de surface change.

Alors quand on demande quel format est le plus puissant, la réponse honnête est que, pour des données ordinaires, ils sont à égalité. Les différences tiennent à l’ergonomie, pas à ce que vous pouvez exprimer.

Là où JSON l’emporte

JSON l’emporte partout où c’est une machine qui lit les données. Sa grammaire est minuscule et rigide : des accolades pour les objets, des crochets pour les tableaux, des guillemets doubles sur chaque clé et chaque chaîne, des virgules entre les éléments, et rien d’autre. Cette rigueur est un atout. Un parseur n’a quasiment aucune ambiguïté à lever, si bien que JSON s’analyse vite, se comporte de façon identique d’un langage à l’autre et vous surprend rarement.

C’est cette fiabilité qui a poussé les API à l’adopter. Quand un serveur envoie des données à un navigateur, ou qu’un service en appelle un autre, les deux côtés doivent s’accorder instantanément sur le sens, sans aucun humain dans la boucle pour repérer une erreur. JSON garantit cela. Presque tous les langages de programmation embarquent le support de JSON dans leur bibliothèque standard, et tout client HTTP le comprend sans configuration supplémentaire.

Le prix à payer, c’est le confort. JSON interdit les commentaires : impossible donc d’annoter un fichier de configuration en ligne. Il refuse aussi les virgules finales, cette virgule inoffensive après le dernier élément d’une liste, ce qui fait constamment trébucher lors des éditions manuelles. Et chaque chaîne a besoin de guillemets, chaque clé a besoin de guillemets, chaque niveau a besoin de ses accolades fermées. Pour une machine, c’est anodin. Pour quelqu’un qui le tape à la main, c’est une source de friction.

Là où YAML l’emporte

YAML l’emporte partout où c’est un humain qui écrit et lit le fichier. Il se débarrasse de l’essentiel de la ponctuation : la structure vient de l’indentation plutôt que des accolades et des crochets, les clés se passent généralement de guillemets, et on sépare les éléments par des sauts de ligne plutôt que par des virgules. Le résultat se lit davantage comme une note structurée que comme du code, ce qui explique sa domination en matière de configuration.

La fonctionnalité phare, ce sont les commentaires. YAML vous laisse commencer une ligne par un dièse et expliquer un réglage juste à côté, ce que le JSON standard ne sait pas faire. Pour un fichier qu’un collègue éditera le mois prochain, ce commentaire courant vaut de l’or. YAML gère aussi les ancres, une façon de définir une valeur une seule fois et de la réutiliser, ce qui réduit les répétitions dans les configurations longues.

C’est précisément pour cela qu’une grande partie de l’outillage de configuration mise sur YAML : définitions de pipelines d’intégration continue, manifestes d’orchestration de conteneurs et d’innombrables fichiers de réglages d’applications s’appuient dessus. Les personnes qui maintiennent ces fichiers sont des humains, qui les éditent à la main, et qui profitent des commentaires et d’une mise en page facile à parcourir. La contrepartie, c’est que YAML exige plus de précaution à la saisie, ce que la section suivante détaille.

Les pièges des espaces en YAML

La souplesse de YAML a ses arêtes vives, et la plupart remontent à deux origines : les espaces et une déduction de type trop zélée. Comme la structure dépend de l’indentation, les espaces en début de ligne ont du sens. Mal placés, le fichier échoue à l’analyse ou, pire, s’analyse en une structure différente de celle que vous vouliez tout en paraissant correct.

La principale règle sur les espaces : ne jamais indenter avec des tabulations. La spécification YAML interdit les caractères de tabulation pour l’indentation, si bien qu’une tabulation égarée, identique à des espaces dans votre éditeur, peut casser tout le document. Des espaces uniquement, de façon cohérente, à chaque niveau.

Vient ensuite la déduction de type, qui produit le fameux problème norvégien. YAML tente d’inférer les types à partir des valeurs non guillemetées : il lit donc yes, true et on comme des booléens. Le code pays de la Norvège, NO, est interprété comme le booléen false au lieu du texte que vous visiez. Les nombres précédés d’un zéro, les chaînes de version et les dates peuvent glisser de la même manière. La parade tient en une habitude : mettez entre guillemets toute valeur qui doit rester une chaîne littérale. Les guillemets coûtent deux caractères et éliminent toute une catégorie de bugs.

JSON contourne tout cela. Sa rigueur fait que les espaces sont décoratifs, jamais structurels, et chaque chaîne est guillemetée par définition, donc rien n’est silencieusement réinterprété.

Comment choisir

La règle tient en une phrase : JSON pour l’échange de données, YAML pour la configuration écrite par des humains. Si une machine produit ou consomme les données, surtout à travers un réseau, optez pour JSON et profitez de sa rapidité, de son support universel et de son absence d’ambiguïté. Si une personne écrit et maintient le fichier, optez pour YAML et profitez des commentaires et d’une mise en page lisible.

La plupart des équipes finissent par utiliser les deux, et c’est un bon réflexe plutôt qu’une indécision. Votre API parle JSON parce que les machines ont besoin d’un contrat strict. Vos réglages de déploiement et de pipeline vivent en YAML parce que des humains les ajustent à la main. Les deux sont moins des rivaux que des outils destinés à des lecteurs différents.

Et quand vous avez besoin de passer de l’un à l’autre, la conversion est mécanique. Glissez une configuration YAML dans un convertisseur YAML vers JSON pour alimenter un outil qui n’accepte que du JSON, ou affichez en YAML un bloc JSON dense pour le lire plus facilement. Comme ils partagent un seul modèle de données, l’aller-retour est sans perte. Le format que vous avez n’est jamais celui auquel vous êtes condamné.