Introduction au YAML

YAML est un langage de sérialisation de données conçu pour être lisible par les humains. Il est surtout utilisé pour les fichiers de configuration, mais il peut représenter les mêmes structures de base que JSON : des associations, des séquences et des valeurs scalaires.

Cette page est une version condensée et actualisée de mon ancien guide Introduction to YAML. Elle couvre YAML 1.2 et la révision actuelle 1.2.2 de la spécification.

Les bases

Un fichier YAML est un simple texte Unicode. Utilisez UTF-8. Indentez avec des espaces, jamais avec des tabulations. La profondeur d’indentation est libre, mais tous les éléments d’un même niveau doivent être alignés.

Les commentaires commencent par #, sauf lorsque ce caractère se trouve dans une chaîne entre guillemets.

# Cette ligne est ignorée
debug: false # Cette partie est également ignorée
name: '#pas-un-commentaire'

YAML est sensible aux espaces. Deux espaces par niveau constituent une convention courante : le fichier reste lisible sans devenir trop large lorsque les structures sont profondément imbriquées.

Associations

Les associations relient des clés à des valeurs. Elles sont comparables aux objets en JSON, aux dictionnaires en Python ou aux tableaux associatifs en PHP.

project: arthak.fr
public: true
port: 8080

Les associations imbriquées sont créées grâce à l’indentation :

server:
  host: 127.0.0.1
  port: 8080
  tls:
    enabled: false

Il existe également une syntaxe compacte, dite « flow » :

server: { host: 127.0.0.1, port: 8080 }

Utilisez la syntaxe en blocs pour la plupart des configurations. La syntaxe flow est utile pour les valeurs courtes qui tiennent naturellement sur une seule ligne.

Séquences

Les séquences sont des listes ordonnées. Chaque élément commence par un tiret suivi d’un espace.

languages:
  - French
  - English
  - YAML

Une séquence peut contenir des associations :

services:
  - name: website
    port: 8080
  - name: api
    port: 3000

Elle peut également utiliser la syntaxe flow compacte :

languages: [French, English, YAML]

Valeurs scalaires et guillemets

Une valeur scalaire est une valeur unique : une chaîne, un nombre, un booléen, une valeur nulle, une date ou toute autre valeur reconnue par le parseur.

name: Arthak
age: 37
enabled: true
empty: null

Placez les chaînes entre guillemets lorsque leur type peut être ambigu ou lorsqu’elles contiennent des caractères ayant une signification syntaxique.

version: '1.0'
answer: 'true'
channel: '#general'
time: '12:30'

Les apostrophes conservent la plupart des caractères littéralement. Pour inclure une apostrophe, doublez-la :

message: 'C''est du YAML valide'

Les guillemets doubles prennent en charge les séquences d’échappement comme \n, \t et les échappements Unicode.

message: "Première ligne\nDeuxième ligne"

YAML 1.1 contre YAML 1.2

Les anciens parseurs YAML 1.1 peuvent interpréter des valeurs comme yes, no, on et off comme des booléens. YAML 1.2 limite les booléens de son schéma principal à true et false.

Pour une configuration portable, utilisez true et false, et placez entre guillemets les mots qui doivent rester des chaînes.

legacy_answer: 'yes'
modern_answer: true

Chaînes multilignes

Utilisez | lorsque les retours à la ligne ont une importance :

description: |
  Première ligne.
  Deuxième ligne.

Utilisez > lorsque plusieurs lignes doivent devenir un seul paragraphe :

description: >
  Ce texte est écrit sur plusieurs lignes
  mais il est normalement chargé comme un seul paragraphe.

Les indicateurs de chomping contrôlent les retours à la ligne finaux :

keep_all: |+
  Text

strip_all: |-
  Text

+ conserve les retours à la ligne finaux. - les supprime. Sans indicateur, YAML conserve un unique retour à la ligne final.

Plusieurs documents

Un flux YAML peut contenir plusieurs documents. Trois tirets commencent un nouveau document. Trois points peuvent terminer explicitement un document.

---
name: first
---
name: second
...

De nombreux outils attendent exactement un document par fichier. N’utilisez donc les flux que lorsque l’application qui les consomme indique clairement les prendre en charge.

Ancres, alias et clés de fusion

Les ancres marquent des nœuds réutilisables avec &. Les alias y font référence avec *.

defaults: &defaults
  retries: 3
  timeout: 10

production:
  settings: *defaults

La syntaxe des clés de fusion est largement implémentée et souvent utilisée pour étendre des associations :

defaults: &defaults
  retries: 3
  timeout: 10

production:
  <<: *defaults
  timeout: 30

Les ancres et les alias font partie de YAML. La clé de fusion << vient d’un type indépendant du langage défini pour YAML 1.1 et ne fait pas partie de la spécification principale de YAML 1.2. Sa prise en charge varie selon les parseurs. Préférez une configuration explicite lorsque l’interopérabilité est importante.

Balises et types explicites

Les balises identifient le type d’un nœud. Les balises standard commencent par !!.

integer: 123
string: !!str 123
float: !!float 123

Les applications peuvent définir des balises personnalisées :

release: !version 2.4.0

Les balises personnalisées dépendent de l’application. Un parseur YAML générique peut les conserver ou les rejeter s’il ne sait pas construire l’objet cible.

Les variables n’existent pas en YAML

YAML ne possède aucun système natif de variables ou d’interpolation.

Cette syntaxe n’a de sens que si l’application qui charge le fichier l’implémente :

home: ${HOME}

Les variables d’environnement, les templates, les inclusions et les expressions appartiennent aux outils construits autour de YAML, pas à YAML lui-même. Docker Compose, GitHub Actions, Ansible, Helm et d’autres systèmes ajoutent chacun leur propre sémantique.

Ne supposez pas qu’une fonctionnalité prise en charge par un outil basé sur YAML existe dans un autre.

Erreurs courantes

Tabulations

Les tabulations ne constituent pas une indentation valide. Configurez votre éditeur pour insérer des espaces.

Espace manquant après un deux-points

# Incorrect ou interprété de façon inattendue
port:8080

# Correct
port: 8080

Commentaires involontaires

# La valeur devient « dark »
theme: dark # experimental

# Le dièse fait partie de la valeur
channel: '#design'

Clés dupliquées

port: 8080
port: 3000

Les clés d’une association doivent être uniques. Certains parseurs rejettent les doublons, tandis que d’autres conservent silencieusement une seule valeur. Traitez les doublons comme des erreurs.

Faire confiance aux types implicites

Placez entre guillemets les identifiants, versions, dates et valeurs commençant par des zéros lorsqu’ils doivent rester des chaînes.

postal_code: '01230'
release: '2026-07-17'
version: '1.20'

Analyser dangereusement du YAML non fiable

Certaines bibliothèques peuvent construire des objets applicatifs à partir de balises. Lorsque vous chargez du contenu non fiable, utilisez le mode de chargement sécurisé du parseur et désactivez la construction arbitraire d’objets.

Valider avec le véritable consommateur

Un fichier peut être un YAML valide tout en étant invalide pour l’application qui l’utilise.

La validation comporte trois niveaux :

1. Syntaxe : un parseur YAML peut-il le lire ?
2. Schéma : contient-il les clés et les types de valeurs attendus ?
3. Application : l’outil cible accepte-t-il les options et la sémantique utilisées ?

Utilisez le même parseur et la même version en développement, dans les tests et en production. Ajoutez une validation de schéma lorsque la configuration devient suffisamment importante pour pouvoir casser un déploiement.

YAML ou autre chose ?

Utilisez YAML lorsque des humains modifient régulièrement une configuration structurée et que les commentaires sont utiles.

Utilisez JSON lorsque l’interopérabilité stricte, une syntaxe plus réduite ou les outils natifs du navigateur sont prioritaires.

Utilisez TOML pour des configurations relativement peu imbriquées, lorsque les types explicites et une analyse prévisible sont prioritaires.

Utilisez un langage de programmation lorsque la configuration nécessite des conditions complexes, des boucles, des imports ou de la logique réutilisable. Recréer un langage dans YAML rend généralement le système plus difficile à comprendre.

Liste de vérification pratique

• Enregistrer en UTF-8.
• Indenter uniquement avec des espaces.
• Conserver une indentation cohérente.
• Préférer les associations et séquences en blocs.
• Placer les chaînes ambiguës entre guillemets.
• Utiliser true, false et null pour des valeurs de base portables.
• Éviter les clés dupliquées.
• Ne pas attendre de YAML qu’il fournisse lui-même des variables ou des templates.
• Vérifier la prise en charge des ancres, des clés de fusion et des balises par le parseur cible.
• Valider la syntaxe, le schéma et le comportement de l’application.
• Utiliser un chargement sécurisé pour les entrées non fiables.

Sources et lectures complémentaires

• Spécification YAML 1.2.2
• Index des ressources YAML
• Suite de tests YAML
• Dépôt original Introduction to YAML
• Organisation YAML sur GitHub