Qu’est-ce que YAML ? Comprendre les bases, la syntaxe et les cas d’usage

Au fil des ans, j’ai manipulé d’innombrables fichiers de configuration, et YAML s’est imposé par sa simplicité et sa lisibilité. Qu’il s’agisse de configurer des workflows dans Kubernetes, de définir des services dans Docker ou de structurer des requêtes d’API, YAML rend les configurations complexes plus gérables. Sa structure claire, basée sur l’indentation, évite l’encombrement de formats comme XML tout en restant flexible.

Dans ce guide, je vous présente la syntaxe, la structure, les fonctionnalités avancées et les bonnes pratiques de YAML pour que vous puissiez l’utiliser en toute confiance. 

Qu’est-ce que YAML ?

YAML (Yet Another Markup Language / YAML Ain’t Markup Language) est un format de sérialisation de données qui privilégie la lisibilité et la facilité d’utilisation. Alors que XML utilise des balises imbriquées proches du HTML et que JSON emploie des accolades et des guillemets, comme les dictionnaires Python, YAML est plus concis et s’appuie sur l’indentation pour définir la structure, ce qui le rend plus lisible pour les humains.

YAML prend en charge plusieurs types de données, notamment les scalaires (chaînes, nombres, booléens), les séquences (listes) et les mappings (paires clé-valeur). Il est largement utilisé dans les fichiers de configuration, l’automatisation d’infrastructure et l’échange de données, en particulier avec des outils comme Kubernetes, Docker et Ansible.

De plus, YAML est un sur-ensemble de JSON, ce qui signifie que des fichiers JSON valides peuvent être analysés comme YAML. Les fichiers YAML portent généralement l’extension .yaml ou .yml.

Vous pouvez aussi en savoir plus sur YAML sur son site !

Syntaxe et structure de YAML

Cette section présente les principes fondamentaux de la syntaxe YAML, notamment les paires clé-valeur, les listes, les données imbriquées et les commentaires.

Règles de base

Voici quelques règles syntaxiques essentielles pour YAML :

• L’indentation par espaces définit la structure, évitez donc les tabulations ! 
• Les paires clé-valeur suivent la structure clé: valeur, comme dans d’autres langages. 
• Un tiret au début d’une ligne indique un élément de liste. 
• Le signe # introduit des lignes de commentaire.

# Voici un exemple de YAML
name: John Doe
age: 30
skills:
  - Python
  - YAML

Paires clé-valeur

YAML représente les données sous forme de paires clé-valeur, à la manière des dictionnaires en Python. Cela sert souvent à transmettre des informations à différents fichiers et paramètres de configuration. Il n’est pas nécessaire d’entourer les chaînes ou les clés de guillemets : indiquez simplement la clé et la valeur souhaitées :

location: New York
country: USA
security-level: user

Listes en YAML

Les listes sont représentées avec des tirets (-). Cela vous permet d’énumérer plusieurs éléments sous une même clé. Dans des éditeurs de balisage, elles apparaissent souvent sous forme de puces.

fruits:
  - Apple
  - Banana
  - Cherry

Données imbriquées

Les structures imbriquées permettent de représenter des données hiérarchiques via l’indentation. Imaginez-les comme des dictionnaires imbriqués. En utilisant l’indentation, vous indiquez quelles clés sont des sous-ensembles d’autres.

person:
  name: Alice
  details:
    age: 25
    city: London

Commentaires

Les commentaires commencent par # et sont ignorés par les parseurs YAML. Il s’agit de commentaires sur une seule ligne.

# Ceci est un commentaire
username: admin
password: secret

Fonctionnalités avancées de YAML

YAML propose des fonctionnalités puissantes comme les chaînes multilignes, les types de données et les ancres, qui rendent les documents plus efficaces et mieux structurés. Dans cette section, nous allons les explorer avec des exemples concrets.

Chaînes multilignes

YAML prend en charge les chaînes multilignes via | (bloc littéral) ou > (bloc plié). 

• Le bloc littéral | crée un retour à la ligne \n à chaque saut de ligne. 
• Le bloc plié > ne crée un retour à la ligne que pour les sauts consécutifs.

literal: |
  This is a
  multi-line string.

folded: >
  This is another
  multi-line string.

On comprend mieux la différence en regardant la sortie.

• Pour le | (bloc littéral) :

This is a
multi-line string.

• Pour le > (bloc plié) :

This is another multi-line string.

Types de données dans YAML

YAML prend en charge divers types de données, notamment les chaînes, les nombres, les booléens et les valeurs nulles. Il détecte automatiquement les types selon le formatage, mais autorise aussi des déclarations explicites.

L’exemple suivant illustre l’usage des types de base en YAML :

string_implicit: Hello, YAML!  # Pas besoin de guillemets sauf si nécessaire
string_double_quoted: "Supports escape sequences like \n and \t"
string_single_quoted: 'Raw text, no escape sequences'

integer: 42  # Nombres entiers
float: 3.14  # Nombres décimaux

boolean_true: true
boolean_false: false

null_value: null  # Valeur nulle
null_tilde: ~  # Autre manière de représenter null

YAML permet des déclarations de type explicites avec !!type si besoin :

explicit_string: !!str 123  # Force 123 à être une chaîne
explicit_integer: !!int "42"  # Force "42" à être un entier
explicit_float: !!float "3.14"  # Force "3.14" à être un flottant

Comme YAML est souvent utilisé pour des données structurées, il prend en charge :

• Les listes (séquences) :

fruits:
  - Apple
  - Banana
  - Cherry

• Les dictionnaires (mappings) :

person:
  name: Alice
  age: 30
  is_student: false

Ancres et alias

YAML vous permet de définir des valeurs réutilisables via des ancres (&) et de les référencer ensuite avec des alias (*). Cela réduit la redondance dans les fichiers de configuration, les rendant plus propres et plus faciles à maintenir.

defaults: &default_settings
  retries: 3
  timeout: 30

server1:
  host: example.com
  retries: *default_settings  # Réutilise la valeur retries depuis defaults

La syntaxe <<: permet de fusionner des paires clé-valeur d’une ancre dans un autre mapping. Si une clé existe dans les deux, la nouvelle valeur l’emporte.

defaults: &default_settings
  retries: 3
  timeout: 30

server1:
  <<: *default_settings  # Fusionne toutes les paires clé-valeur de default_settings
  host: example.com  # Cette clé est ajoutée aux données fusionnées

Voici la structure finale résolue :

server1:
  retries: 3
  timeout: 30
  host: example.com

Les ancres et alias sont particulièrement utiles dans les gros fichiers de configuration où répéter manuellement des valeurs serait inefficace. Ils aident à garder les fichiers YAML DRY (Don’t Repeat Yourself) et facilitent les mises à jour.

Cas d’usage courants de YAML

YAML est largement utilisé dans le développement logiciel, l’automatisation d’infrastructure et la gestion des APIs. Sa syntaxe lisible en fait un format privilégié pour les fichiers de configuration, la sérialisation de données et l’Infrastructure as Code (IaC). Voyons ses usages les plus courants.

Fichiers de configuration

YAML est très répandu pour la configuration d’applications comme Docker Compose, Kubernetes et les pipelines CI/CD. Sa facilité de lecture permet à toute personne de comprendre rapidement ce que font les fichiers YAML de configuration Docker.

version: '3'
services:
  web:
    image: nginx
    ports:
      - "80:80"
    environment:
      - NGINX_HOST=localhost
      - NGINX_PORT=80

La lisibilité de YAML et la prise en charge des ancres et alias réduisent les répétitions, ce qui le rend plus facile à maintenir que JSON ou XML.

Pour en savoir plus sur YAML et son usage avec Docker, découvrez ce cours Docker de niveau intermédiaire.

Sérialisation et transfert de données

YAML permet de sérialiser des données pour les APIs et les outils de gestion de configuration en convertissant des structures complexes en un format lisible par l’humain et facilement analysable par les machines. 

Par exemple, un corps de requête d’API formaté en YAML :

user:
  id: 123
  name: "John Doe"
  email: "johndoe@example.com"
  active: true

La structure basée sur l’indentation de YAML évite une syntaxe superflue, ce qui la rend plus légère, lisible et simple à modifier que JSON.

Infrastructure as Code (IaC)

Des outils de gestion de configuration comme Ansible et Kubernetes s’appuient sur YAML pour définir des états systèmes, automatiser des processus et garantir la cohérence entre environnements.

• Dans Ansible, YAML sert à écrire des playbooks décrivant des états, tâches et dépendances, pour configurer l’infrastructure de manière cohérente. 
• Kubernetes utilise des manifestes YAML pour définir des ressources comme des pods, services et déploiements, afin d’orchestrer automatiquement des applications conteneurisées.

Voici un exemple de configuration de Pod Kubernetes :

apiVersion: v1
kind: Pod
metadata:
  name: my-app
spec:
  containers:
    - name: app-container
      image: my-app:latest
      ports:
        - containerPort: 8080

Apprenez-en plus sur l’usage de YAML avec Kubernetes dans ce cours Introduction to Kubernetes.

Documentation d’API

Des spécifications d’API comme OpenAPI et Swagger utilisent YAML pour définir les endpoints et structures de données de manière claire. YAML sert à décrire les méthodes de l’API, les paramètres des requêtes, les formats de réponse et les méthodes d’authentification.

Voici un exemple de spécification OpenAPI en YAML :

openapi: 3.0.0
info:
  title: User API
  version: "1.0"
paths:
  /users:
    get:
      summary: Retrieve a list of users
      responses:
        "200":
          description: Successful response

Les spécifications OpenAPI, par exemple, utilisent YAML pour documenter les APIs REST. Elles fournissent un plan clair pour générer des SDK clients, une documentation interactive et des tests automatisés. Ce format structuré garantit la cohérence entre implémentations d’API.

Travailler avec des fichiers YAML

YAML est largement utilisé pour les fichiers de configuration, l’automatisation et la sérialisation de données, mais puisqu’il repose sur l’indentation, un formatage correct est crucial. Voici comment lire, écrire, valider et éditer YAML efficacement.

Lire et écrire du YAML en Python

La bibliothèque Python PyYAML permet d’analyser et de générer du YAML.

Imaginez le fichier de configuration YAML suivant :

database:
  host: localhost
  port: 5432
  user: admin
  password: secret

Voici comment travailler ce fichier de configuration en Python :

import yaml

# Load YAML data
with open("config.yaml", "r") as file:
    data = yaml.safe_load(file)  # safe_load empêche l'exécution de code arbitraire

# Modify data (optional)
data["database"]["user"] = "new_user"

# Write YAML data
with open("output.yaml", "w") as file:
    yaml.dump(data, file, default_flow_style=False)

Si vous souhaitez travailler des données JSON en Python, consultez ce tutoriel complet Python JSON.

Valider des fichiers YAML

Pour garantir une structure correcte, utilisez des outils qui détectent l’usage de tabulations à la place des espaces ou des anomalies comme les caractères répétés, erreurs de syntaxe et espaces finaux.

Voici quelques validateurs YAML populaires :

• Outil CLI : yamllint (linter basé sur Python)
• Validateurs en ligne : YAML Lint, YAML Validator de JSON Formatter

Éditer du YAML

Vous pouvez écrire et modifier du YAML dans n’importe quel éditeur de texte, mais les outils de linting et la coloration syntaxique améliorent la lisibilité.

Quelques éditeurs que j’apprécie :

• VS Code (avec extensions YAML)
• PyCharm (prise en charge intégrée)
• Sublime Text (avec coloration YAML)

Erreurs courantes à éviter avec YAML

Malgré sa simplicité, il est facile de commettre des erreurs ou des fautes de frappe avec YAML. Cette section récapitule ces écueils et propose des bonnes pratiques pour écrire des fichiers propres et corrects. C’est aussi pourquoi je recommande d’utiliser un linter ou un éditeur adapté !

Mélanger tabulations et espaces

YAML repose sur les espaces pour l’indentation — ne mélangez jamais espaces et tabulations. Les tabulations casseront tout simplement votre script YAML. C’est un choix délibéré : différents systèmes interprètent les tabulations différemment, d’où la préférence pour les espaces afin de minimiser les problèmes.

Indentation incorrecte

Veillez à une indentation cohérente pour éviter les erreurs d’analyse. Puisque l’indentation est le seul moyen pour YAML d’indiquer la hiérarchie, une indentation incorrecte peut provoquer des problèmes. Il est facile de placer par erreur une paire clé: valeur au mauvais endroit : gardez donc un œil sur les retraits !

Oublier les guillemets pour les caractères spéciaux

Utilisez des guillemets pour les chaînes contenant des caractères spéciaux ou des espaces. Les éléments comme les antislashs, virgules, points d’exclamation, etc., ont besoin de guillemets pour être lus comme des chaînes.

path: "/home/user/documents"
message: "Hello, World!"

Avec une validation adéquate, un éditeur structurant et PyYAML en Python, vous pouvez travailler efficacement avec des fichiers YAML tout en évitant les pièges courants.

Conclusion

YAML est un format simple mais puissant, largement utilisé pour la configuration, la sérialisation de données et l’automatisation d’infrastructure. En maîtrisant sa syntaxe, sa structure et ses bonnes pratiques, vous pourrez l’employer efficacement dans de nombreux contextes.

Si vous souhaitez appliquer YAML dans des cas concrets :

• Découvrez comment YAML est utilisé dans les workflows CI/CD avec ce cours CI/CD for Machine Learning.
• Explorez comment les APIs utilisent YAML dans leurs spécifications avec ce cours Introduction to APIs in Python.
• Approfondissez la conteneurisation et l’automatisation d’infrastructure avec ce parcours Containerization and Virtualization.