Qu’est-ce qu’un fichier YAML ?

YAML est un format texte que n’importe quel éditeur ouvre. Il est utilisé pour l’échange entre programmes et la retouche.

L’extension est .yaml et le nom complet YAML Ain't Markup Language. L’un et l’autre comptent moins que ce que le fichier peut contenir, et c’est le sujet du reste de cette page.

Il remonte à 2001. La spécification est YAML 1.2.

L’âge est utile à connaître pour une raison pratique : plus un format est ancien, plus les programmes ont eu le temps de l’apprendre.

Elle est publiée intégralement : n’importe qui peut l’implémenter à partir du document plutôt qu’en l’observant, et c’est pourquoi ce format apparaît dans tant de programmes et pourquoi des fichiers écrits il y a vingt ans s’ouvrent encore. Une spécification publiée n’est pas pour autant libre de redevances : quand un format enveloppe un codec, les brevets sont une question à part, que la norme ne tranche pas.

YAML enregistre son contenu à l’identique. Le réenregistrer ne change rien : vous pouvez l’ouvrir, le modifier et le réenregistrer autant de fois que vous voulez sans accumuler de dégâts, et c’est ce qui en fait un format de travail plutôt qu’un format de livraison.

YAML a une syntaxe de commentaires, et c’est la différence entre un fichier qu’une personne entretient et un fichier qu’un programme écrit. Les commentaires sont la première chose perdue en convertissant vers un format qui n’en a pas, et rien ne vous prévient.

Visual Studio Code et yq le lisent, comme la plupart des programmes du même genre.

Quand un fichier ne s’ouvre pas, le format est rarement en cause : le plus souvent, c’est le programme qui est plus ancien que lui. Convertir vers quelque chose de plus ancien est le contournement fiable, et c’est à cela que sert le reste de ce site.

Aucun navigateur ne le lit.

C’est de loin la raison la plus fréquente de le convertir : non pas que le format soit mauvais, mais que l’endroit où vous voulez montrer le fichier ne sache pas le lire.

YAML est fait pour être ouvert et modifié. Gardez le fichier dans ce format tant que le travail dure, et exportez depuis lui chaque fois qu’une version finie est nécessaire.

Très peu de gens choisissent YAML. On vous le donne : manifestes Kubernetes, pipelines GitHub Actions et GitLab CI, playbooks Ansible, Docker Compose, spécifications OpenAPI, front matter de site statique. Tous ces outils se sont fixés dessus, et les écosystèmes qui les entourent sont assez gros pour que le format ne soit pas une décision que qui que ce soit peut revisiter.

Cela conditionne à quoi ressemble une page utile à son sujet. La question est rarement faut-il utiliser YAML — c’est comment éviter les façons spécifiques dont cela se passe mal, parce que cela échoue en silence plus souvent que tout autre format de configuration d’usage courant.

Il n’y a ni crochets ni marqueurs de fermeture. La profondeur à laquelle une ligne est indentée détermine à quoi elle appartient, donc une seule espace mal placée change le sens du document — et produit fréquemment un document qui reste valide, seulement différent de ce que vous vouliez dire. C’est une propriété qui rend le format très lisible une fois qu’on l’a comprise, et très piégeuse tant qu’on ne l’a pas, parce qu’aucun message d’erreur n’intervient à la hauteur de la fautif.

Deux règles préviennent la plupart des problèmes. N’utilisez jamais de tabulations : la spécification les interdit, et un éditeur qui en insère une produit une erreur d’analyse dont le message dit rarement cela. Et gardez l’indentation cohérente, deux espaces par niveau par convention, parce que mélanger les largeurs dans un fichier est légal et rend la structure impossible à lire d’un coup d’œil. La troisième règle, qui découle des deux premières : un éditeur avec un mode YAML est un investissement qui se rentabilise dès la première mauvaise indentation évitée, parce que les guides visuels et la conversion automatique des tabulations enlèvent le risque d’y penser.

YAML devine ce qu’est une valeur nue, et ces suppositions ont causé de vraies pannes. Le plus célèbre est le problème de la Norvège : en YAML 1.1, un no non entouré de guillemets est le booléen false, donc une liste de codes pays transforme NO en false. Il en va de même avec on, off, y et n.

La défense tient plus à une habitude qu’à une connaissance : entourez de guillemets tout ce qui est censé être du texte. Les numéros de version, codes pays, identifiants, heures, tout ce qui a des zéros en tête. YAML 1.2 a corrigé plusieurs de ces cas et de nombreux analyseurs implémentent encore 1.1, donc c’est l’habitude qui vous protège plutôt que la spécification.

YAML peut définir un bloc une fois et le réutiliser. Une ancre le marque, un alias s’y réfère, et une clé de fusion déplie un bloc partagé à plusieurs endroits — c’est ainsi qu’un pipeline CI évite de répéter les mêmes six lignes dans chaque job.

C’est réellement utile et c’est là où YAML cesse d’être lisible pour quelqu’un qui n’a pas vu la syntaxe auparavant. Deux mises en garde pratiques : un alias est une référence plutôt qu’une copie, donc ce qui est partagé est partagé ; et plusieurs outils qui consomment YAML n’implémentent pas les ancres du tout, ou les déplient d’une manière qui surprend. Vérifiez avant de bâtir une grande configuration par-dessus.

Un scalaire de bloc écrit avec une barre verticale conserve les sauts de ligne : parfait pour un script, un certificat, un message avec des paragraphes. Écrit avec un signe supérieur, il replie les lignes en une seule, ce qui convient à une longue phrase coupée pour la lisibilité dans le fichier.

Chacun prend un suffixe contrôlant le saut de ligne final — un moins le supprime, un plus les conserve tous. Cela compte bien plus qu’il n’y paraît quand la valeur est une clé, un jeton ou un script : un saut de ligne final inattendu est la raison classique pour laquelle un certificat est rejeté ou une commande se comporte différemment dans un pipeline que sur votre machine.

Trois traits d’union sur leur propre ligne commencent un nouveau document, donc un seul fichier peut en contenir une suite. Kubernetes en use constamment — un déploiement, un service et un config map dans un seul fichier — et chaque outil qui le lit s’y attend. C’est aussi la façon dont Helm range plusieurs manifestes dans un chart, et la convention qui rend `kubectl apply -f` capable de traiter un dossier entier sans qu’on ait à les nommer un par un.

Cela mérite d’être su parce que cela change ce que signifie « analyser ce fichier ». Un analyseur qui ne lit qu’un document ignore silencieusement tout ce qui suit le premier séparateur, et c’est ainsi qu’une moitié de configuration disparaît sans erreur. La fonction correspondante est en général nommée pour charger tous les documents plutôt qu’un seul, et c’est précisément le nom de cette fonction qu’il faut vérifier dans la documentation d’une bibliothèque avant d’introduire des séparateurs dans un fichier — il est arrivé plus d’une fois qu’une dépendance soit mise à jour et que la fonction de chargement change de nom ou de comportement, faisant silencieusement passer un fichier à un seul document actif.

Tout document JSON est du YAML valide, puisque YAML 1.2 a été défini comme un sur-ensemble. Convertir JSON en YAML est donc trivial et en grande partie cosmétique — le résultat contient les mêmes données, plus lisible, et maintenant capable de porter des commentaires.

L’autre sens perd des choses que JSON n’a pas où mettre : les commentaires, les ancres, et la distinction entre les différentes façons d’écrire une chaîne multiligne. Faire passer un manifeste Kubernetes par JSON lui retire donc tous les commentaires explicatifs qu’il contenait, et c’est le genre de perte que personne ne remarque avant de revenir au fichier six mois plus tard et de ne plus comprendre pourquoi un réglage est à cette valeur. Pour un projet où les manifests YAML sont versionnés, la convention saine consiste à conserver le YAML comme source de vérité et à générer le JSON au moment de l’application, jamais l’inverse.

Utilisez un éditeur avec un mode YAML. Il affichera les guides d’indentation, convertira les tabulations, et signalera une erreur de structure en place plutôt que de laisser un pipeline la découvrir. Pour tout ce qui va dans un dépôt, un linter dans le hook de commit vaut les dix minutes qu’il faut pour le mettre en place.

Et validez avant d’expédier quand un schéma existe. Kubernetes, OpenAPI et la plupart des systèmes de CI en publient un, et une vérification validante attrape la clé mal placée qu’un analyseur accepte sans broncher et que le système rejette à trois heures du matin.