Les bases de YAML

L’indentation est la syntaxe

Dans YAML, les espaces ne sont pas de la décoration — elles sont toute la structure. Un mapping, c’est une clé, un deux-points, une espace, puis une valeur ; une valeur imbriquée s’écrit à la ligne suivante, plus indentée, et deux lignes de même indentation sont sœurs. Les tabulations y sont purement et simplement interdites : la spécification ne parvient pas à se décider sur la largeur d’une tabulation, alors les parseurs les rejettent au lieu de deviner. Les éditeurs n’arrêtent pas d’insérer des tabulations au copier-coller, et voilà pourquoi tant de fichiers ont l’air parfaits et refusent de se parser.

La convention est de deux espaces par niveau. Quatre ou six sont tout aussi valables — la spécification n’interdit que les tabulations — mais deux, c’est ce qu’utilisent Kubernetes et Compose, ce qu’attend chaque linter et ce qui évite aux manifests profonds de défiler sur le côté. Mélanger les largeurs dans un même fichier, c’est ainsi que naissent les erreurs d’indentation ; choisissez donc deux espaces et laissez l’éditeur veiller au respect.

• Un niveau = un nombre fixe d’espaces, au choix ; deux est la convention.
• Les tabulations dans l’indentation sont rejetées par les parseurs, pas converties.
• Un élément de séquence peut se placer à l’indentation de sa clé parente — le tiret fait office de marqueur.
• Les valeurs peuvent aussi s’écrire en ligne, en style flow : ports: [8080].

services:
  web:
    image: nginx:1.27
    ports:
      - "8080:80"
  cache:
    image: redis:7

services
├─ web
│  ├─ image: "nginx:1.27"
│  └─ ports: ["8080:80"]
└─ cache
   └─ image: "redis:7"

Les scalaires et le problème de la Norvège

Les valeurs entre guillemets sont des chaînes, toujours. Les valeurs nues sont typées par inférence, et c’est de cette inférence que vient la réputation de YAML : un 8080 nu devient le nombre 8080 et une valeur vide devient null, ce qui aide — jusqu’à ce que l’inférence type quelque chose que vous pensiez comme du texte, un code pays ou une chaîne de version par exemple.

L’échec classique, c’est la liste de codes pays ISO dans laquelle NO — la Norvège — se parse en booléen false : le problème de la Norvège, drôle jusqu’à ce qu’il désactive en silence un drapeau de déploiement. La version 1.1 allait bien plus loin, comme le montre le tableau. Le schéma cœur de la 1.2 ne résout que true et false comme booléens et lit le reste du tableau ci-dessous comme des chaînes ordinaires ou des nombres décimaux — mais comme tant de logiciels déployés appliquent encore les règles 1.1, l’habitude défensive consiste à mettre entre guillemets tout ce qui doit rester une chaîne.

Guillemets et blocs scalaires

YAML propose trois façons d’écrire une chaîne. Sans guillemets, c’est le défaut, et cela convient à la plupart des valeurs. Les guillemets simples sont littéraux — la seule échappatoire consiste à doubler le guillemet ('it''s fine'). Les guillemets doubles acceptent les échappements par antislash tels que \n et \t, le style qu’emploie JSON. La règle défensive se transmet : si une valeur contient quoi que ce soit qui pourrait passer pour de la structure — deux-points, dièses, mots réservés — mettez-la délibérément entre guillemets.

Le texte multiligne passe par les blocs scalaires. Un bloc littéral, écrit |, conserve chaque retour à la ligne exactement comme tapé — la forme qui convient aux scripts shell et aux certificats. Un bloc plié, écrit >, réunit les lignes en un seul paragraphe fluide — la forme qui convient à une longue description. Tous deux acceptent un indicateur de chomping : |- supprime le retour à la ligne final, |+ garde tous ceux de la fin, et | seul en garde exactement un.

script: |
  set -e
  make build
  make deploy

summary: >
  Deploys finish
  in under a minute.

script:   "set -e\nmake build\nmake deploy\n"
summary:  "Deploys finish in under a minute.\n"

Ancres, alias et réutilisation

YAML permet à un nœud de porter un nom que d’autres nœuds référencent. Écrivez &name après une clé pour ancrer sa valeur ; écrivez *name n’importe où ailleurs pour en faire un alias, et le parseur substitue une copie du nœud ancré. Des jobs qui partagent une même politique de réessai pointent alors vers une définition unique, et la modification n’a à être faite qu’une fois.

Deux extensions s’appuient sur ce mécanisme. Les clés de fusion, écrites <<: *name, injectent chaque clé d’un mapping ancré dans le mapping courant — monnaie courante dans les fichiers Compose et Ansible, et convention de l’ère 1.1 qui n’a jamais intégré la grammaire cœur de la 1.2. Les ancres peuvent aussi être détournées : des alias imbriqués dans des alias permettent à dix définitions de s’étendre en un million de nœuds — l’attaque billion-laughs — aussi les parseurs dignes de confiance plafonnent-ils l’expansion et signalent-ils le plafond au lieu de se figer.

defaults: &base
  retries: 3
  timeout: 30s

staging:
  retries: 3
  timeout: 30s
  log: *base

defaults:  { retries: 3, timeout: "30s" }
log alias: { retries: 3, timeout: "30s" }   (staging.log)

Commentaires et documents multiples

Les commentaires commencent par # et courent jusqu’à la fin de la ligne ; un dièse à l’intérieur d’une chaîne entre guillemets ne compte pas. C’est le plus grand avantage ergonomique de YAML sur JSON, qui a supprimé les commentaires par conception, et la raison pour laquelle la config tenue par des humains gravite ici : le fichier s’explique en ligne, et les revues citent une ligne et son commentaire dans un même hunk de diff.

Un même fichier peut aussi contenir plusieurs documents, séparés par des lignes de trois tirets ; un --- en tête est le marqueur de début optionnel et ... termine un document. C’est ainsi qu’un seul artefact embarque côte à côte une config de staging et une config de production. Les convertisseurs de ce site parsent chaque document et opèrent sur le dernier, à l’image du comportement des CLI courantes.

env: staging
region: eu-1
---
env: production
region: us-2

env: production
region: us-2   (the last document)

Ce que les convertisseurs de ce site acceptent

Chaque parseur YAML est le parseur d’un sous-ensemble — la grammaire 1.2 complète est célèbre pour sa taille — et un convertisseur mérite la confiance en déclarant son sous-ensemble au lieu de vous laisser le découvrir par l’échec. La bibliothèque YAML de ce site implémente le schéma cœur de la 1.2 sur les constructions block et flow qui apparaissent dans les vrais fichiers de configuration, avec des limites délibérées là où la spécification autorise un travail sans bornes. Le tableau tient lieu de contrat.