Le YAML expliqué : le langage de config qui ressemble à un poème

En une phrase

Le YAML est une façon humaine d'écrire des données structurées, qui troque les accolades et les guillemets de ses cousins contre les indentations propres d'une liste de courses bien organisée.

Le problème qu'il résout

Au commencement, il y avait le chaos. Puis vinrent les fichiers de configuration. Les premiers formats comme le .ini étaient simples mais ne pouvaient pas gérer de données complexes et imbriquées. Puis le XML est arrivé, puissant et structuré, mais si verbeux et lourd en balises que le lire donnait l'impression de monter un meuble IKEA avec une notice rédigée en jargon juridique. Les humains détestaient l'écrire.

Le JSON (JavaScript Object Notation) a suivi et a constitué une énorme amélioration. Il était léger, correspondait directement aux structures de données de la plupart des langages de programmation, et était bien plus agréable à regarder que le XML. Mais pour les fichiers que les humains devaient écrire et modifier souvent — comme les scripts DevOps, les paramètres d'application et les textes d'internationalisation — la syntaxe du JSON restait une corvée. Toutes ces accolades, virgules et guillemets n'étaient que du bruit visuel et il était facile de se tromper.

C'est là qu'intervient le YAML. Le nom est un acronyme récursif qui capture parfaitement son esprit : "YAML Ain't Markup Language" (YAML N'est Pas un Langage de Balisage). Il a été conçu de A à Z pour un public principal : l'être humain qui fixe l'écran. Il a repris les mêmes structures de données de base que le JSON (paires clé-valeur, listes et valeurs simples) et s'est posé la question : "Quelle est la syntaxe minimale absolue dont nous avons besoin pour représenter cela ?"

La réponse fut l'indentation. En utilisant les espaces pour dénoter la structure, YAML a créé un format qui est souvent assez propre pour s'auto-documenter. Il a été fait pour le monde de la configuration, où la clarté et la facilité d'édition l'emportent sur les besoins d'optimisation machine d'une API à haut débit.

Comment ça marche sous le capot

La "magie" du YAML n'est qu'un ensemble de règles simples et cohérentes pour transformer du texte indenté en données structurées. C'est un sur-ensemble (superset) du JSON, ce qui signifie que vous pouvez souvent coller du JSON valide dans un fichier YAML et ça fonctionnera. Mais la vraie puissance vient de sa syntaxe native et minimaliste.

Les briques de base : Scalaires, Séquences et Mappings

Toutes les données en YAML se résument à trois choses :

Mappings (alias Dictionnaires ou Objets) : Ce sont vos paires clé: valeur classiques. La clé est une chaîne de caractères (string), et la valeur peut être n'importe quoi : un autre mapping, une séquence ou un scalaire.
```
# Un mapping simple
character: "Bilbo Baggins"
race: "Hobbit"
age: 111
```
Séquences (alias Listes ou Tableaux/Arrays) : Ce sont des listes ordonnées d'éléments. Chaque élément est indiqué par un tiret suivi d'un espace (- ).
```
# Une séquence de chaînes de caractères
fellowship_members:
  - Frodo Baggins
  - Samwise Gamgee
  - Gandalf
  - Legolas
  - Gimli
```
Scalaires (alias Valeurs Simples) : C'est juste une valeur unique, comme une chaîne de caractères (string), un nombre ou un booléen. YAML est assez malin pour deviner le type. 123 est un nombre, true est un booléen, et Hello world est une chaîne de caractères. En général, vous n'avez pas besoin de guillemets, mais vous devriez les utiliser si votre chaîne de caractères risque d'être mal interprétée (par ex., "true", "1.23").

L'ingrédient secret : l'indentation et les espaces

C'est le concept le plus important en YAML. Il n'y a pas d'accolades {} ou de crochets [] pour montrer l'imbrication. À la place, on indente, tout simplement. La règle est simple : si une ligne est plus indentée que la ligne précédente, elle devient un enfant de cette ligne.

Combinons nos briques de base. Voici un profil de personnage avec une liste d'objets d'inventaire.

# Une structure imbriquée
character:
  name: "Gollum"
  aliases:
    - "Sméagol"
    - "My Precious"
  possessions:
    - item: "The One Ring"
      description: "A plain gold ring, surprisingly heavy."
    - item: "A fish"
      description: "Juicy and sweet!"
  is_wretched: true

Regardez la structure. name, aliases, possessions, et is_wretched sont toutes des propriétés de character parce qu'elles sont indentées en dessous. La séquence aliases est une valeur au sein du mapping character. La séquence possessions contient deux objets de type mapping, chacun avec un item et une description.

La profondeur de l'indentation n'a pas d'importance, tant qu'elle est cohérente au sein d'un même bloc. Deux espaces est le standard de la communauté. Mais vous devez utiliser des espaces, pas des tabulations. Utiliser des tabulations est le moyen N°1 de s'infliger un monde de souffrance invisible.

Astuces avancées : Ancres, alias et tags

Le YAML possède des fonctionnalités pour utilisateurs avancés que le JSON n'a pas, conçues pour garder vos fichiers DRY (Don't Repeat Yourself - Ne Vous Répétez Pas).

Ancres (&) et Alias (*) : Si vous avez un bloc de données que vous devez réutiliser, vous pouvez lui donner un nom avec une ancre (&nom_ancre) puis y faire référence ailleurs avec un alias (*nom_ancre).

# Définir un profil utilisateur par défaut avec une ancre
default_user: &default_user_profile
  theme: "dark"
  notifications: "enabled"
  permissions: "read-only"

# Maintenant, créer des utilisateurs spécifiques qui héritent des valeurs par défaut
users:
  - name: "Alice"
    # Utiliser un alias pour importer le profil par défaut
    <<: *default_user_profile
    # Et surcharger une clé spécifique
    permissions: "admin"
  - name: "Bob"
    # Bob reçoit le profil standard
    <<: *default_user_profile

Ici, << est une clé de fusion spéciale. Alice et Bob reçoivent tous les deux le profil par défaut, mais la clé permissions d'Alice est surchargée. C'est une bouée de sauvetage dans les configurations complexes.

Tags (!!) : YAML déduit généralement les types, mais vous pouvez être explicite avec les tags. Cela peut être utile pour éviter toute ambiguïté. Par exemple, si vous voulez la chaîne de caractères "12.0" et non le nombre 12.0.
```
version: !!str 12.0 # Forcer ceci à être une chaîne de caractères
not_a_boolean: !!str "no" # Forcer ceci à être une chaîne de caractères
```

Histoires vécues

Le Cas du Pipeline Disparu

Une ingénieure DevOps junior, appelons-la Chloé, était chargée d'ajouter un nouveau scan de sécurité au pipeline CI/CD de son entreprise, défini dans un fichier gitlab-ci.yml. Elle a ajouté le nouveau job, poussé son code, et... rien. Le pipeline s'est exécuté, mais son nouveau job de scan était introuvable. Il n'a pas échoué ; il a simplement disparu. Pendant deux heures, Chloé a vérifié la syntaxe de son script, la configuration du runner et les définitions de phase. Finalement, exaspérée, elle a demandé à un ingénieur senior de jeter un œil. Les yeux du développeur senior ont balayé le fichier pendant environ cinq secondes avant de pointer une seule ligne. Chloé avait indenté son nouveau job avec trois espaces au lieu des deux espaces utilisés partout ailleurs. Le parser YAML l'a vu comme un enfant malformé du job précédent, et non comme un nouveau job de premier niveau, et l'a ignoré en silence.

Leçon : En YAML, les espaces sont de la syntaxe. Un seul espace mal placé peut changer tout le sens de votre fichier. Utilisez un linter ou un éditeur structuré qui visualise l'arborescence des données pour attraper ces erreurs instantanément.

La Config qui est devenue une Forêt

Une petite startup gérait ses environnements d'application (développement, staging, production) avec un unique config.yml. Au début, c'était simple. Mais à mesure qu'ils ajoutaient des environnements (prod-us, prod-eu, dev-feature-x), le fichier a explosé. D'énormes blocs de configuration pour les URL de base de données, les clés API et les feature flags étaient copiés-collés pour chaque environnement, avec seulement des changements mineurs. Le fichier est devenu un monstre de 500 lignes, et changer une seule valeur partagée, comme un paramètre de timeout, nécessitait de la trouver et de la remplacer à cinq endroits différents. Une nouvelle recrue, fraîchement arrivée d'une plus grande entreprise, a vu cela et a introduit les ancres YAML. Il a défini un bloc &default_config avec tous les paramètres communs. Ensuite, la configuration de chaque environnement utilisait simplement un alias vers la configuration par défaut (<<: *default_config) et surchargeait les quelques valeurs qui étaient différentes. Le fichier de 500 lignes est passé à moins de 100 lignes.

Leçon : Ne vous répétez pas. Si vous vous surprenez à copier-coller de gros blocs dans un fichier YAML, il est temps d'apprendre et d'utiliser les ancres et les alias.

Le Problème Norvégien

Un développeur construisait une fonctionnalité qui permettait aux utilisateurs de sélectionner leur pays dans une liste déroulante. La liste des codes de pays était stockée dans un simple fichier YAML : supported_countries: [ US, DE, UK, NO ]. Pendant les tests, les utilisateurs de Norvège (NO) se sont plaints de ne pas pouvoir s'inscrire. Le développeur a débogué le code pendant des heures, traquant les variables, mais ne voyait pas le problème. La valeur NO était correctement transmise depuis le frontend. Finalement, il a inspecté les données chargées depuis le fichier YAML. Le tableau supported_countries dans son programme était ['US', 'DE', 'UK', false]. Le parser YAML, suivant une ancienne version de la spécification, avait interprété le NO non entouré de guillemets comme une valeur booléenne pour "faux" (false).

Leçon : Dans le doute, mettez vos chaînes de caractères entre guillemets. Tout scalaire qui pourrait ressembler à un nombre ("1.0"), un booléen ("yes", "no", "on", "off"), ou une valeur spéciale devrait être explicitement mis entre guillemets pour éviter une mauvaise surprise lors du parsing.

Erreurs et pièges courants

Utiliser des tabulations au lieu d'espaces. C'est le péché capital du YAML. La spécification interdit les tabulations. Comme elles sont invisibles, elles peuvent causer des erreurs de parsing incroyablement difficiles à trouver. Configurez votre éditeur pour qu'il utilise des espaces pour les fichiers YAML.
Indentation incohérente. Si un élément de liste est indenté de deux espaces et le suivant de quatre, vous allez passer un mauvais moment. La structure sera interprétée incorrectement. Gardez des niveaux d'indentation cohérents.
Oublier de mettre les chaînes ambiguës entre guillemets. Le "Problème Norvégien" est un classique. Les chaînes comme Yes, No, true, false, On, Off seront interprétées comme des booléens. Les nombres avec des zéros en tête ou des caractères spéciaux pourraient être mal interprétés. Dans le doute, mettez-les entre "guillemets".
Confusion sur les chaînes multilignes. Oublier la différence entre | (style littéral, préserve les sauts de ligne) et > (style plié, convertit les sauts de ligne en espaces). Cela peut déformer votre bloc de texte ou votre script shell soigneusement formaté.
Valeurs null inattendues. Une clé sans rien après les deux-points (key: ) est une valeur null. C'est souvent une suppression accidentelle qui peut causer des échecs silencieux si votre code ne vérifie pas la présence de null.

Pourquoi vous devriez vous y intéresser

Si vous écrivez du code en 2024, vous ne pouvez pas échapper au YAML. C'est le roi incontesté de la configuration.

DevOps & Infrastructure-as-Code : Kubernetes, Ansible, Docker Compose, GitHub Actions, AWS CloudFormation et d'innombrables autres outils utilisent le YAML comme langage de définition principal.
Configuration d'applications : De nombreux frameworks (comme Symfony et Ruby on Rails) et applications utilisent le YAML pour les fichiers de paramètres car il est très facile à lire et à modifier pour les développeurs.
Générateurs de sites statiques : Des outils comme Jekyll et Hugo utilisent le YAML pour le "frontmatter" afin de définir les métadonnées des articles et des pages.

Connaître le YAML, ce n'est pas seulement écrire des fichiers de config. C'est comprendre la structure des systèmes avec lesquels vous travaillez. Être capable de repérer une erreur d'indentation subtile ou de savoir quand utiliser une ancre peut faire la différence entre une solution rapide et une journée entière perdue à déboguer.

Pour aller plus loin

YAML Spec 1.2.2: La source officielle de vérité. C'est dense, mais c'est la référence ultime.
Wikipedia: YAML: Un excellent aperçu de haut niveau sur l'histoire, les fonctionnalités et les versions du langage.
Learn YAML in Y minutes: Un fantastique aide-mémoire sur une seule page avec des exemples concrets qui couvre 80% de ce dont vous aurez jamais besoin.
YAML Lint: Un validateur en ligne qui est inestimable pour trouver ces satanées erreurs de syntaxe et pour comprendre ce que le parser "voit".
GitHub Docs: Workflow syntax for GitHub Actions: Un excellent exemple concret d'un système complexe entièrement défini en YAML. L'étudier révèle de nombreux patterns courants.