Plain unquoted string — most common
name: John Doe
Single-quoted: no variable or escape processing
path: '/usr/bin/node'
Double-quoted: supports escape sequences (\n, \t, etc.)
message: "Hello\nWorld"
Whole number (base 10)
port: 8080
Floating point number
threshold: 0.95
Boolean value — use only true/false (YAML 1.2)
debug: false
Null / absence of value
response: null
ISO 8601 date format
created: 2024-01-15T10:30:00Z
Single-line comment. No multi-line comment syntax.
# This is a comment key: value # inline comment
Force value to be treated as a specific type
port: !!str 8080 # string '8080' not int
Key-value pairs — indented block style
app: name: myapp port: 3000
Inline map — equivalent to block style
env: {NODE_ENV: prod, PORT: 8080}List of items — block style with dash+space
fruits: - apple - banana - cherry
Inline list — equivalent to block style
ports: [80, 443, 8080]
List where each item is a map
users:
- name: Alice
role: admin
- name: Bob
role: userArbitrarily deep nesting
database:
primary:
host: db1.example.com
port: 5432Merge the keys of a referenced mapping into current map
defaults: &defaults color: blue button: <<: *defaults text: Submit
Preserves newlines exactly as written
script: | #!/bin/bash echo "hello" exit 0
Newlines folded into spaces (great for long descriptions)
description: > This is a very long description that will be joined into one line.
Literal block, strip all trailing newlines
prompt: |- Enter value:
Literal block, keep all trailing newlines
template: |+ line1
Folded block, strip trailing newlines
message: >- This folds into one line no trailing newline
Assigns an anchor (label) to the current node
base: &base image: node:18 restart: always
References (copies) an anchored node
service1: <<: *base name: api service2: <<: *base name: worker
Anchor a scalar value to reuse it
read_timeout: &rto 30 write_timeout: *rto connect_timeout: *rto
Anchor a list
primary_colors: &colors - red - blue text_colors: *colors
Explicitly declare YAML version (optional, rarely needed)
%YAML 1.2 --- name: myapp
Marks the start of a YAML document. Required if using directives.
--- kind: Deployment --- kind: Service
Marks the end of a YAML document. Optional but useful.
--- debug: true ...
Multiple YAML docs in one file (stream)
Used in Kubernetes multi-resource files
Base64-encoded binary data
icon: !!binary | iVBORw0KGgo=
Indentation MUST use spaces only — never tabs
# WRONG: parent: \tchild: value # RIGHT: parent: child: value
Values containing ': ' (colon+space) must be quoted
# WRONG: url: http://example.com # RIGHT: url: "http://example.com"
1.0 parses as float! Quote or tag it to keep as string
version: '1.0' # string version: 1.0 # float
YAML 1.1 parses yes/no/on/off as booleans — quote to use strings
# YAML 1.1 (PyYAML): on: true # 'on' is boolean true! # Safe: always quote on: 'on'
Trailing spaces in keys are included in the key string
"key " (with space) != "key" — trim carefully
Duplicate keys — behavior is parser-specific (usually last wins). Treat as error.
Use a YAML linter to detect duplicate keys
| Fonctionnalité | YAML | JSON |
|---|---|---|
| Commentaires | Yes: # comment | Non pris en charge |
| Guillemets requis | Optionnel pour les chaînes | Requis pour les chaînes |
| Anchors/aliases | Yes: &anchor / *alias | Non pris en charge |
| Chaînes multi-lignes | Yes: | and > blocks | Escaped \n only |
| Tabulations pour l'indentation | Espaces uniquement | L'un ou l'autre |
| Est un sur-ensemble de JSON | Tout JSON est du YAML valide | - |
| Lisibilité humaine | Très élevée | Moyen |
| Disponibilité des parseurs | Élevée | Très élevée |
Important : De nombreux parseurs YAML utilisent encore YAML 1.1 par défaut (PyYAML de Python, Psych de Ruby dans certaines versions).
YAML a deux styles multilignes :
Bloc littéral (|) — préserve les retours à la ligne :
description: |
This is line one.
This is line two.
This is line four (after blank line).
Bloc replié (>) — joint les lignes avec des espaces :
description: >
This is a long paragraph
that will be folded into
a single line.
Ajoutez - pour supprimer les retours à la ligne finaux (|-, >-) ou + pour les conserver (|+, >+).
Un seul fichier YAML peut contenir plusieurs documents séparés par --- :
---
# Document 1: Config
apiVersion: v1
kind: ConfigMap
---
# Document 2: Service
apiVersion: v1
kind: Service
Ceci est couramment utilisé dans les manifestes Kubernetes.
Deux espaces est la convention la plus courante, utilisée par Kubernetes, Docker Compose, GitHub Actions et la plupart des outils DevOps. Certains projets utilisent quatre espaces. La règle clé est la cohérence au sein d'un fichier — ne mélangez jamais les niveaux d'indentation.
Oui, YAML supporte les commentaires sur une seule ligne avec #. Il n'y a pas de syntaxe de commentaire multiligne. Les commentaires sont supprimés lors du parsing et ne sont pas disponibles dans la structure de données chargée.
YAML est un sur-ensemble de JSON — tout JSON valide est du YAML valide. YAML est conçu pour être plus lisible par les humains avec la prise en charge des commentaires, des chaînes multi-lignes et des ancres/alias. JSON est plus strict, plus rapide à analyser et universellement pris en charge. Utilisez YAML pour les fichiers de configuration et JSON pour les API et l'échange de données.
Dans YAML 1.1 (utilisé par de nombreux parseurs dont PyYAML), 'on', 'off', 'yes', 'no' sont des valeurs booléennes valides. Cela peut causer des bugs lorsqu'ils sont utilisés comme chaînes simples (par ex. dans Ansible). YAML 1.2 a corrigé cela — seuls 'true' et 'false' sont des booléens. Solution : toujours mettre entre guillemets ces valeurs ('yes', 'no') si vous voulez les traiter comme des chaînes.
Utilisez le scalaire de bloc littéral (|) pour préserver les sauts de ligne : chaque ligne du bloc devient un saut de ligne littéral dans la chaîne. Utilisez le scalaire de bloc replié (>) pour convertir les sauts de ligne en espaces : idéal pour les longs paragraphes. Les deux prennent en charge les indicateurs de chomping optionnels (- pour supprimer les sauts de ligne finaux, + pour les conserver tous).
YAML utilise des espaces pour l'indentation — jamais des tabulations. Toutes les clés sœurs doivent être au même niveau d'indentation. Mélanger tabulations et espaces causera toujours des erreurs. Solutions courantes : activez le paramètre 'remplacer les tabulations par des espaces' de votre éditeur, utilisez un linter (yamllint), assurez une largeur d'indentation cohérente (2 ou 4 espaces) dans tout le fichier.