C'est quoi, un fichier YAML ? Syntaxe, exemples et erreurs courantes

 Un fichier YAML est un fichier en texte brut qui stocke des paramètres et d’autres informations structurées dans un format lisible à la fois par les humains et par les programmes. Il utilise l’indentation et une ponctuation simple, comme les deux-points et les tirets, pour montrer comment les éléments d’information s’articulent entre eux.

Tu rencontreras généralement le YAML lorsqu’un outil te demandera de le configurer : un pipeline de déploiement, une configuration de conteneur ou une plateforme d’hébergement. Ce guide explique comment le YAML est structuré, te présente des exemples concrets et passe en revue les quelques erreurs à l’origine de la plupart des fichiers YAML défectueux.

À quoi sert YAML ?

Point clé : YAML est l’un des formats les plus courants pour les fichiers de configuration dans les outils de développement, car on peut le lire et le modifier sans logiciel spécifique.

Son nom est un jeu de mots récursif : YAML signifie « YAML Ain't Markup Language » (YAML n'est pas un langage de balisage). L'idée, c'est que YAML décrit des données, comme des paramètres, des listes et des options, plutôt que de mettre en forme un document comme le fait le HTML.

Tu trouveras des fichiers YAML dans de nombreux outils que les développeurs utilisent au quotidien :

Les fichiers de configuration sont bien plus souvent lus et modifiés que créés à partir de zéro, c’est là qu’un format lisible prend tout son sens. Les fichiers YAML côtoient souvent d’autres fichiers de configuration dans un projet, comme un fichier .env qui contient des secrets. Notre guide « Qu’est-ce que .env ? » aborde ce sujet.

Les bases de la syntaxe YAML, avec un exemple

Point clé : presque tous les fichiers YAML sont constitués de paires clé-valeur, d’indentation pour l’imbrication et de tirets pour les listes.

Voici un petit fichier YAML pour une application web fictive. Chaque partie est expliquée ci-dessous.

# Settings for a small web app
app_name: recipe-finder
port: 8080
debug: false

database:
  host: localhost
  name: recipes

features:
  - search
  - favorites
  - shopping-list

welcome_message: |
  Welcome to Recipe Finder.
  Search by ingredient to get started.

En général, le texte n'a pas besoin de guillemets, mais tu peux en mettre (simples ou doubles) autour de n'importe quelle valeur. Les guillemets permettent d'indiquer à YAML de traiter un élément comme du texte alors qu'il ressemble à un nombre ou à un commutateur (voir la section « Erreurs » ci-dessous).

C'est l'indentation qui définit la structure. Une ligne en retrait sous une clé appartient à cette clé, et les lignes ayant le même niveau d'indentation sont des éléments frères. Tu peux choisir le nombre exact d'espaces, à condition que chaque niveau soit cohérent. On utilise souvent deux espaces par niveau.

YAML vs JSON

Point clé : YAML et JSON peuvent contenir les mêmes informations. YAML est plus facile à lire et à modifier pour les humains, tandis que JSON est plus strict et plus couramment utilisé pour les données échangées entre programmes.

JSON est un autre format texte pour les données structurées, très utilisé par les sites web et les API. Voici la même configuration d’application que ci-dessus, écrite en JSON :

{
  "app_name": "recipe-finder",
  "port": 8080,
  "debug": false,
  "database": {
    "host": "localhost",
    "name": "recipes"
  },
  "features": ["search", "favorites", "shopping-list"],
  "welcome_message": "Welcome to Recipe Finder.\nSearch by ingredient to get started.\n"
}

Ces deux aspects sont étroitement liés. YAML 1.2, la version actuelle de la spécification YAML, a été conçue pour que le JSON soit un YAML valide. C'est pourquoi certains outils acceptent les deux formats pour un même fichier.

Pourquoi ton YAML ne fonctionne pas : erreurs courantes et comment les corriger

Point clé : la plupart des problèmes YAML sont des erreurs d’indentation ou d’espacement, et les pires ne génèrent aucune erreur. Le fichier se charge, mais il interprète quelque chose de différent de ce que tu as écrit.

Il existe deux types d’erreurs YAML. Certaines empêchent le chargement du fichier et affichent un message d’erreur, ce qui est agaçant mais facile à repérer. D’autres se chargent sans problème et modifient discrètement tes paramètres, si bien que l’application fonctionne avec des valeurs que tu n’avais pas l’intention de définir. Dans la mesure du possible, chaque erreur ci-dessous présente d’abord la version erronée, puis la correction.

1. Utilisation de tabulations à la place d’espaces

YAML n’autorise pas les tabulations pour l’indentation. Une seule tabulation, souvent ajoutée par un éditeur sans que tu t’en rendes compte, empêche le chargement de tout le fichier.

Solution : configure ton éditeur pour qu’il insère des espaces quand tu appuies sur la touche Tab. La plupart des éditeurs de code proposent ce paramètre, et beaucoup l’appliquent automatiquement aux fichiers YAML.

2. Indenter une ligne au mauvais niveau

Si une ligne se retrouve un niveau trop à gauche, elle ne fait plus partie du groupe qui la précède. YAML l'interprète comme un paramètre distinct, sans signaler d'erreur.

# Broken: name is no longer part of database
database:
  host: localhost
name: recipes

# Fixed
database:
  host: localhost
  name: recipes

Une ligne indentée d’un espace de trop génère généralement une erreur, souvent formulée ainsi : « les valeurs de mappage ne sont pas autorisées ici ». Si tu vois ce message, vérifie l’indentation de la ligne en question et de celle du dessus.

3. Oublier l'espace après deux-points ou un tiret

YAML a besoin d'un espace après les deux-points dans « clé : valeur » et après le tiret dans un élément de liste. Sans ça, YAML considère ça comme du texte ordinaire.

# Broken: read as one line of text, not a list
features:
  -search
  -favorites

# Fixed
features:
  - search
  - favorites

4. Utiliser deux points à l’intérieur d’une valeur

Un deux-points suivi d’un espace à l’intérieur d’une valeur perturbe YAML, car cela ressemble au début d’un nouveau paramètre.

# Broken: fails to load
message: Note: restart the app after changes

# Fixed
message: "Note: restart the app after changes"

5. Les valeurs que YAML interprète différemment

YAML devine le type de valeur que tu veux dire, et il lui arrive parfois de se tromper. Voici les surprises classiques :

Solution : mets des guillemets autour de toute valeur qui doit rester sous forme de texte, comme version: « 1.10 » ou country: « NO ». N'utilise pas de guillemets pour les valeurs qu'un outil attend sous forme de nombres réels ou de booléens (true et false), comme un numéro de port.

6. Répéter une clé

Si la même clé apparaît deux fois au même niveau, de nombreux outils conservent la dernière valeur et ignorent la première sans te prévenir. Les outils plus stricts s'arrêtent alors en affichant une erreur.

port: 8080
# ...many lines later
port: 9090

L'application tourne sur le port 9090, et la première ligne est ignorée sans avertissement. Dans un fichier long, cherche la clé avant de l'ajouter.

Comment vérifier un fichier YAML avant de l’utiliser

Point clé : laisse un outil vérifier ton YAML. Une extension d’éditeur détecte les erreurs au fur et à mesure que tu tapes, et un validateur vérifie l’intégralité du fichier avant que tu ne t’en serves.

Il existe trois méthodes courantes pour vérifier un fichier YAML, de la plus simple à la plus approfondie :

1. Utilise un éditeur compatible avec YAML. Les éditeurs de code comme Visual Studio Code disposent d’extensions YAML qui soulignent les erreurs au fur et à mesure que tu tapes. Certains connaissent également la structure attendue de fichiers spécifiques et te suggèrent des configurations valides pendant que tu écris.
2. Lance un linter. Un linter est un petit programme qui lit un fichier et signale les problèmes. yamllint est une option gratuite et open source pour le YAML ; il signale les problèmes de style, comme une indentation incohérente, ainsi que les erreurs flagrantes.
3. Utilise le vérificateur fourni avec ton outil. De nombreux outils peuvent vérifier leurs propres fichiers de configuration, ce qui permet de détecter des erreurs qu’un vérificateur YAML général ne peut pas repérer, comme un paramètre portant un nom incorrect.

Les validateurs YAML en ligne fonctionnent aussi, mais fais attention à ce que tu y colles. Les fichiers de configuration contiennent parfois des mots de passe ou des adresses internes, et ceux-ci ne doivent pas être saisis sur un site web que tu ne contrôles pas.

Si le fichier a été rédigé par un assistant IA, vérifie-le de la même manière. Le YAML généré par l’IA a souvent une syntaxe valide, il se charge donc sans erreur. Les erreurs se trouvent plutôt dans le contenu : un nom de paramètre que l’outil ne reconnaît pas, une option issue d’une ancienne version de l’outil, ou une valeur placée au mauvais niveau. C’est le vérificateur propre à l’outil, l’option 3 ci-dessus, qui a le plus de chances de les détecter.

Le YAML sur Upsun Cloud : lecture d’un vrai fichier de configuration

Point clé : Upsun Cloud décrit l’intégralité d’un projet dans un seul fichier YAML, .upsun/config.yaml, et son outil en ligne de commande permet de vérifier ce fichier avant le déploiement.

Sur Upsun Cloud, les applications que tu exécutes, les services qu’elles utilisent (comme une base de données) et les adresses web qui y donnent accès sont tous regroupés dans un seul fichier YAML. Il se trouve dans un dossier appelé .upsun à la racine de ton projet. La commande upsun project:init crée une version de départ basée sur le code qu’elle détecte.

Voici un petit exemple : une application Node.js connectée à une base de données PostgreSQL.

applications:
  myapp:
    type: "nodejs:26"
    relationships:
      database:
    web:
      commands:
        start: "node index.js"

services:
  database:
    type: "postgresql:17"

routes:
  "https://{default}/":
    type: upstream
    upstream: "myapp:http"

Voici ce que fait chaque partie :

• Le fichier comporte trois clés de premier niveau : applications, services et routes, ce qui correspond à la structure attendue par Upsun Cloud.
• Sous « applications », une application appelée « myapp » s’exécute sur Node.js 26 et se lance avec la commande « node index.js ».
• Sous « services », une base de données PostgreSQL 17 porte le nom « database ».
• L’entrée « relationships » relie l’application à cette base de données. Le nom « database » doit correspondre aux deux endroits. Si l’un des deux est mal orthographié, l’application ne pourra pas trouver sa base de données.
• Sous « routes », le trafic web vers l’adresse du projet est redirigé vers « myapp ».

Les erreurs courantes mentionnées plus haut s’appliquent ici aussi. Une indentation mal placée peut faire sortir les relations de la section « myapp ». Les guillemets dans cet exemple sont facultatifs, mais mettre entre guillemets les valeurs contenant des deux-points ou des accolades est une bonne habitude à prendre.

Pour vérifier le fichier avant de le pousser, lance la commande `upsun app:config-validate` dans le dossier de ton projet. Ça valide les fichiers de configuration de ton projet, ce qui permet de repérer les erreurs sur ta machine avant le déploiement. Si un agent de codage modifie ce fichier pour toi, demande-lui d’exécuter la même commande après chaque modification. Notre guide « Qu’est-ce qu’un fichier AGENTS.md ? » explique comment rédiger cette instruction une seule fois pour que tous les agents la respectent. Tu peux également connecter ton éditeur au schéma publié par Upsun Cloud, afin qu’il te suggère des paramètres valides et signale les erreurs au fur et à mesure que tu tapes. Le Centre de développement Upsun explique comment configurer cela.

Pour connaître tout ce que ce fichier peut contenir, consulte la section « YAML sur Upsun Cloud » dans la documentation d’Upsun.

Sur Upsun Cloud, ce fichier unique décrit l’ensemble de ton projet, et chaque environnement est construit à partir de celui-ci. Tu peux déployer gratuitement sur Upsun Cloud pendant 15 jours, sans avoir besoin d’une carte bancaire, ou découvrir comment l’automatisation pilotée par Git transforme les modifications de configuration en déploiements.

Foire aux questions (FAQ)

Que signifie YAML ?

YAML signifie « YAML Ain't Markup Language ». Ce nom souligne le fait que YAML sert à décrire des données, telles que des paramètres et des listes, plutôt qu'à mettre en forme des documents.

Quelle est la différence entre .yaml et .yml ?

Aucune. Les deux extensions désignent le même format. Certains outils exigent l’une ou l’autre, alors utilise celle indiquée dans la documentation de l’outil.

Est-ce que YAML accepte les tabulations ?

Non. YAML n'autorise que les espaces pour l'indentation. Configure ton éditeur pour qu'il insère des espaces quand tu appuies sur la touche Tab.

Combien d'espaces dois-tu utiliser pour l'indentation en YAML ?

N'importe quel nombre convient, tant que chaque niveau est cohérent. Deux espaces par niveau est un choix courant.

Pourquoi mon fichier YAML affiche-t-il le message « mapping values are not allowed here » ?

Cette erreur signifie généralement qu’une ligne est indentée différemment de ses voisines, ou qu’une valeur contient un deux-points suivi d’un espace. Vérifie l’indentation de la ligne indiquée par l’erreur, et mets entre guillemets toute valeur contenant un deux-points.

Est-ce que YAML est meilleur que JSON ?

Aucun des deux n’est meilleur en général. Le YAML est plus facile à lire et à modifier pour les humains, ce qui convient bien aux fichiers de configuration. Le JSON est plus strict et plus simple à générer pour les programmes, ce qui convient bien aux données échangées entre les systèmes.

Comment ouvrir un fichier YAML ?

N'importe quel éditeur de texte peut l'ouvrir, car un fichier YAML est du texte brut. Un éditeur de code prenant en charge l'extension YAML facilite la lecture et permet de repérer plus facilement les erreurs.