Skip to content

YAML Aide-mémoire

Standard de sérialisation de données lisible humain pour les fichiers de configuration.

01

Premiers pas

Structure de base

YAML utilise l'indentation (espaces, pas tabulations) pour l'imbrication. Les mappings utilisent cle: valeur, les séquences - element. La syntaxe inline utilise [] pour les listes et {} pour les maps. Les commentaires utilisent #.

yaml
# YAML uses indentation for structure
# Comments start with #

# Key-value pairs (mappings)
name: Alice
age: 30

# Nested mappings (use consistent indentation)
person:
  name: Bob
  age: 25
  address:
    city: NYC
    zip: 10001

# Sequences (lists)
hobbies:
  - reading
  - coding
  - music

# Inline syntax
numbers: [1, 2, 3]
coords: {x: 10, y: 20}

Commentaires

Les commentaires commencent par # et doivent être précédés d'une espace ou du début de ligne. Dans les scalaires de bloc (| et >), # est du contenu littéral, pas un commentaire. Pas de syntaxe de commentaire multi-lignes — chaque ligne exige son propre #.

yaml
# Full-line comment
key: value  # Inline comment (whitespace before # required)

# Comments can appear anywhere
# - before documents
# - inside sequences
list:
  - a  # first item
  - b  # second item

# Block scalar headers DO accept comments
text: |  # literal block
  line one

# But the content of block scalars is literal,
# so # inside is NOT a comment:
literal: |
  # this is part of the string, not a comment

Règles d'indentation

YAML interdit strictement les tabulations pour l'indentation — seuls les espaces sont autorisés. L'indentation doit être cohérente au sein d'un niveau mais n'a pas besoin d'être un nombre fixe. Le - des séquences fait partie de l'indentation. Mélanger tabulations et espaces lève une erreur du parseur.

yaml
# Use SPACES only — tabs are forbidden for indentation
# 2 spaces is the most common convention

mapping:
  nested:
    deeply_nested: value

# Sequences can be indented at the same level as the key
items:
  - one
  - two

# Or indented further (both are valid)
items2:
    - one
    - two

# WRONG: tab characters cause parser errors
# bad:	value   (tab before value)

# Hyphen counts as indentation start
- item1
- item2

Début et fin de document

--- marque le début d'un document YAML ; ... la fin. Un fichier peut contenir plusieurs documents séparés par --- (un flux de documents). Pour des fichiers de config à document unique, un --- initial est optionnel mais recommandé comme indice aux parseurs.

yaml
# --- separates documents in a stream
# ... ends a document (optional)

---
name: first document
value: 1
...
---
name: second document
value: 2
...

# A single document needs no markers
key: value

# But --- is recommended at the start of files
# to disambiguate from plain text
---
apiVersion: v1
kind: ConfigMap

Pièges courants

Les deux-points exigent une espace suivante pour être un séparateur de mapping. YAML 1.1 vs 1.2 diffèrent sur yes/no/on/off (booléens en 1.1, chaînes en 1.2) et sur les littéraux octaux. Les valeurs vides sont null, distinctes des chaînes vides. Beaucoup de parseurs (PyYAML) suivent encore les règles 1.1.

yaml
# Colon needs a space after it
key:value      # WRONG: parsed as a single string "key:value"
key: value     # correct

# Yes/No/On/Off are NOT booleans in YAML 1.2
# (they WERE in YAML 1.1 — common gotcha)
answer: yes    # YAML 1.1: true; YAML 1.2: "yes" string

# Numbers with leading zeros
version: 010   # YAML 1.1: octal 8; YAML 1.2: string "010"

# Unquoted strings with special chars
url: example.com/path   # OK
url: example.com:8080   # WRONG: parsed as mapping with key example.com

# Empty values
empty:       # null
empty2: ~    # explicit null
empty3: ""   # empty string (different from null)

YAML vs JSON

YAML 1.2 a été conçu pour que JSON en soit un sous-ensemble strict — tout fichier JSON est du YAML valide. YAML ajoute commentaires, structure de bloc, ancres, chaînes multi-lignes et tags. JSON exige de quoter toutes les clés et valeurs de chaînes, ce que YAML relâche pour les scalaires simples.

yaml
# JSON is a strict subset of YAML 1.2
# Every valid JSON document is valid YAML

# JSON:
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}

# Equivalent YAML:
name: Alice
age: 30
hobbies:
  - a
  - b

# YAML adds: comments, multi-line strings, anchors,
# relaxed quoting, tags, multiple documents

# YAML removes: mandatory quotes around strings,
# commas, braces (in block style)

# YAML is a superset of JSON — not the other way.
# Comments and anchors are not valid JSON.
02

Scalaires (chaînes, nombres, booléens, null)

Chaînes simples et quotées

Les chaînes simples n'exigent pas de guillemets sauf si elles ressemblent à des nombres, booléens, null ou dates. Les guillemets simples n'échappent que ' en doublant ('') ; aucun autre échappement. Les doubles guillemets supportent les séquences d'échappement complètes (\n, \t, \uXXXX). Quoter force le type chaîne.

yaml
# Plain strings (no quotes) — most common
name: Alice
path: /usr/local/bin
url: https://example.com

# Single-quoted — escape ' by doubling
msg: 'it''s fine'

# Double-quoted — supports escapes
greeting: "Hello\nWorld"
unicode: "\u03B1"   # Greek alpha
tab: "col1\tcol2"

# Multi-word plain strings are fine
description: This is a plain string with spaces

# Strings that look like other types must be quoted
version: "1.0"      # string, not float
notBool: "true"     # string, not boolean
notNull: "null"     # string, not null
date: "2024-01-01"  # string, not date

Nombres

YAML 1.2 utilise 0o pour l'octal (YAML 1.1 utilisait un 0 initial nu). Les underscores dans les nombres sont permis pour la lisibilité. .inf et .nan sont des littéraux flottants spéciaux. Quotter toute valeur qui devrait être une chaîne mais paraît numérique (versions, téléphones, IDs).

yaml
# Integers
int: 42
negative: -17
positive: +100
underscored: 1_000_000   # readable grouping (YAML 1.2)

# Octal & hex (YAML 1.2 prefixes)
octal: 0o17     # = 15 decimal
hex: 0xFF       # = 255 decimal
binary: 0b1010  # = 10 decimal

# Floats
pi: 3.14159
exp: 1.0e+3     # 1000.0
neg_exp: -2.5e-4

# Special float values (IEEE 754)
infinity: .inf
neg_infinity: -.inf
not_a_number: .nan

# To force a string that looks numeric:
version: "1.0"
phone: "555-1234"

Booléens

YAML 1.2 a restreint les booléens à true/false (et True/False, TRUE/FALSE). YAML 1.1 (utilisé par PyYAML) traite yes/no/on/off/y/n comme booléens — une source célèbre de bugs (ex. le 'no' norvégien → false). Quotter toujours ces chaînes si vous les voulez littérales.

yaml
# YAML 1.2 — only these are booleans:
enabled: true
disabled: false

# YAML 1.1 ALSO accepts (common gotcha):
# yes, no, on, off, y, n, Y, N
# These are strings in 1.2 but booleans in 1.1

# To force a string:
answer: "yes"      # always a string
option: "on"
flag: "y"

# PyYAML (1.1 rules) parses these as booleans:
# yes -> True, no -> False, on -> True, off -> False
# This breaks "no" as an answer or country code!

# Safe practice: quote if you mean the literal string
country: "no"   # Norway country code, not False

Valeurs null

YAML accepte null, Null, NULL, ~ et une valeur vide comme null. Une valeur vide (clé sans rien après les deux-points) est null, distincte d'une chaîne vide "". Les parseurs mappent le null YAML vers la valeur null du langage hôte (None, null, nil).

yaml
# All of these represent null/None/null
key1: null
key2: Null
key3: NULL
key4: ~
key5:             # empty value

# Distinguish null from empty string
empty_string: ""
null_value: null

# In sequences
list:
  - value
  - null         # explicit null item
  - another

# In nested structures
config:
  timeout: null   # explicitly unset
  retries: 3

# Parsers convert to language-specific null:
# Python -> None, JavaScript -> null, Go -> nil

Dates et timestamps

Les dates et timestamps ISO 8601 se reconnaissent comme types natifs par la plupart des parseurs. Un YYYY-MM-DD nu devient une date ; avec l'heure un datetime. Quotter la valeur pour la garder en chaîne. Les désignateurs de fuseau (Z, +08:00) sont supportés.

yaml
# Date (ISO 8601)
date: 2024-01-15

# Datetime (ISO 8601)
datetime: 2024-01-15T14:30:00
datetime_tz: 2024-01-15T14:30:00Z
datetime_offset: 2024-01-15T14:30:00+08:00
datetime_space: 2024-01-15 14:30:00

# To force string (not a date):
not_a_date: "2024-01-15"
not_a_date2: '2024-01-15'

# Parsers typically return datetime objects
# Python: datetime.date / datetime.datetime
# JavaScript: Date (depending on library)

Inférence de types

Le système de types de YAML résout les scalaires non quotés via un schéma. Le schéma Failsafe traite tout comme chaînes ; les schémas JSON et Core infèrent int, float, bool, null, date. Utilisez des guillemets ou des tags explicites (!!str, !!int) pour surcharger la résolution au besoin.

yaml
# YAML infers types from unquoted scalars
str: hello             # string
int: 42                # integer
float: 3.14            # float
bool: true             # boolean
null_val: null         # null
date: 2024-01-01       # date
list: [1, 2, 3]        # sequence

# Force string type with quotes
str_version: "42"
str_date: "2024-01-01"
str_bool: "true"

# Or with the !!str tag
forced: !!str 42        # string "42"
forced_int: !!int "42"  # integer 42

# Resolution depends on the schema
# Failsafe: everything is a string
# JSON/Core: numbers, bools, null inferred
03

Mappings

Mapping simple

Un mapping est des paires cle: valeur où les clés sont typiquement des chaînes. Les clés peuvent être tout scalaire (nombre, bool, même null). Les clés dupliquées sont déconseillées et le comportement varie selon le parseur (souvent le dernier gagne). Utilisez un linter pour attraper les doublons accidentels.

yaml
# A mapping is a set of key: value pairs
name: Alice
age: 30
email: [email protected]

# Keys can be any scalar type (string, number, bool)
"string key": value
123: numeric key
true: boolean key

# Duplicate keys are technically discouraged
# but some parsers allow them (last wins)
key: first
key: second   # overrides "first" in many parsers

# Values can be any type
mixed:
  string: text
  number: 42
  list: [1, 2, 3]
  nested:
    deep: value

Mappings imbriqués

Les mappings imbriqués se créent en indentant les clés enfants. L'indentation doit être cohérente au sein d'un niveau. Pas de taille d'indentation fixe, mais 2 espaces est le standard de facto. L'imbrication profonde nuit à la lisibilité — considérez aplatir les structures très profondes.

yaml
# Nest mappings with consistent indentation
server:
  host: localhost
  port: 8080
  ssl:
    enabled: true
    cert: /etc/ssl/cert.pem
    key: /etc/ssl/key.pem

database:
  primary:
    host: db1.example.com
    port: 5432
  replica:
    host: db2.example.com
    port: 5432

# Indentation level is up to you — just be consistent
# 2 spaces is the most common convention

Mapping de séquences

Mappings et séquences se composent librement. Un pattern courant est une séquence de mappings (une liste d'enregistrements), où chaque - démarre un élément et les clés alignées appartiennent à cet élément. L'indentation des clés suivantes doit s'aligner avec la première clé après le -.

yaml
# Values in a mapping can be sequences
servers:
  - web1.example.com
  - web2.example.com
  - web3.example.com

# Sequence of mappings (very common)
users:
  - name: Alice
    age: 30
  - name: Bob
    age: 25

# Each - starts a new item; aligned keys form one mapping
services:
  - name: api
    port: 8080
    env:
      - dev
      - prod
  - name: web
    port: 3000

# Mixed: mapping containing sequence containing mapping
config:
  endpoints:
    - path: /health
      method: GET
    - path: /users
      method: POST

Clés complexes

YAML autorise tout scalaire ou collection comme clé via l'indicateur ? cle. Rare dans les fichiers de config mais utile pour des tables de lookup (ex. tarification par région+instance). Les clés complexes sont maladroites à lire — la plupart des fichiers de config restent sur des clés de chaînes simples.

yaml
# Keys can be complex objects using ? notation
? key1
: value1

# A mapping as a key
? host: localhost
  port: 8080
: connection1

# A sequence as a key
? [a, b, c]
: indexed_value

# Practical (rare) use: matrix lookup
? [us-east-1, t2.micro]
: 0.0116
? [us-east-1, t2.small]
: 0.023

# In flow style:
{[a, b]: value, {x: 1}: other}

# Most config files just use plain string keys
simple: value

Mappings inline (flow)

Le style flow utilise {} pour les mappings et [] pour les séquences, semblable à JSON. Utile pour des données courtes et compactes sur une ligne. Contrairement à JSON, YAML n'autorise pas les virgules finales. Mêlez librement styles flow et bloc, mais préférez le bloc pour la lisibilité dans les fichiers de config.

yaml
# Flow style mapping (like JSON)
point: {x: 10, y: 20}
config: {host: localhost, port: 8080}

# Nested flow mappings
nested: {a: {b: {c: value}}}

# Mixed flow and block
block_key:
  flow_value: {x: 1, y: 2}
  another: value

# Flow with sequences
mixed: {nums: [1, 2, 3], name: test}

# Quoting still works in flow style
quoted: {"key with space": "value", count: 3}

# Trailing comma is NOT allowed in YAML flow
bad: {a: 1, b: 2,}   # parse error

Ordre et style des clés

YAML préserve lui-même l'ordre des mappings dans la spécification, mais les objets du langage hôte peuvent ne pas le faire (bien que la plupart des dicts modernes le fassent). Pour la lisibilité de config, groupez les clés liées, utilisez un nommage cohérent (snake_case ou camelCase) et ajoutez des commentaires pour délimiter les sections.

yaml
# YAML mappings are ORDERED (unlike JSON spec, though
# most JSON parsers preserve insertion order too)
# But language objects may not preserve order:
# Python dict (3.7+): preserves order
# Ruby Hash: preserves order
# JSON object: technically unordered

# Consistent key style improves readability
config:
  server:
    host: localhost      # snake_case
    port: 8080
    max_connections: 100
  database:
    host: db.example.com
    port: 5432
    connection_pool: 10

# Group related keys together
# Use comments to delineate sections
app:
  # networking
  host: 0.0.0.0
  port: 3000
  # limits
  timeout: 30
  retries: 3
04

Séquences

Séquences en bloc

Les séquences en bloc utilisent - (tiret + espace) avant chaque élément. Les éléments peuvent être de tout type : scalaires, mappings ou séquences imbriquées. Le - compte comme partie de l'indentation, donc les clés suivantes d'un élément mapping s'alignent avec la première clé après le tiret.

yaml
# A sequence (list) uses - followed by space
fruits:
  - apple
  - banana
  - cherry

# Sequence as top-level document
- item1
- item2
- item3

# Empty sequence
empty: []
or_with_marker: []

# Sequence with mixed types
mixed:
  - string
  - 42
  - true
  - null
  - key: value   # a mapping as an item

Séquences imbriquées

Les séquences imbriquées se forment en indentant d'autres niveaux -. Elles deviennent dures à lire au-delà de 2 niveaux — passez au style flow pour les séquences internes. Les structures d'arbres (séquence de mappings avec children) sont plus lisibles que des séquences pures imbriquées.

yaml
# Sequence of sequences
matrix:
  - - 1
    - 2
    - 3
  - - 4
    - 5
    - 6

# More readable with flow style for inner
matrix2:
  - [1, 2, 3]
  - [4, 5, 6]

# Deeply nested
tree:
  - name: root
    children:
      - name: child1
        children:
          - name: grandchild1
      - name: child2

# 3D: sequence of sequence of sequence
cube:
  - - [1, 2]
    - [3, 4]
  - - [5, 6]
    - [7, 8]]

Séquence de mappings

Une séquence de mappings est le pattern YAML le plus courant (listes d'enregistrements). Chaque - démarre un nouvel élément ; les clés suivantes à la même indentation appartiennent à cet élément. Alignez les clés après le - pour la lisibilité. Un élément mapping vide s'écrit {}.

yaml
# Most common pattern: list of records
users:
  - name: Alice
    email: [email protected]
    roles:
      - admin
      - user
  - name: Bob
    email: [email protected]
    roles:
      - user

# Each - starts a new mapping; aligned keys belong
# to that item. Indent the first key after - by 2 spaces.
servers:
  - host: web1.example.com
    port: 8080
    healthy: true
  - host: web2.example.com
    port: 8080
    healthy: false

# Empty mapping item
list:
  - {}
  - name: real

Séquences inline (flow)

Les séquences flow utilisent [] et équivalent aux séquences en bloc. Utiles pour des listes courtes sur une ligne. Elles peuvent s'étendre sur plusieurs lignes pour la lisibilité. Contrairement à JSON, YAML interdit les virgules finales. Mêlez librement séquences flow et mappings en bloc.

yaml
# Flow sequence (JSON-like)
numbers: [1, 2, 3]
names: [Alice, Bob, Charlie]

# Nested flow sequences
matrix: [[1, 2], [3, 4]]

# Flow sequence of flow mappings
points: [{x: 1, y: 2}, {x: 3, y: 4}]

# Mixed: block mapping with flow sequence value
config:
  ports: [80, 443, 8080]
  hosts: [web1, web2, web3]

# Spread across multiple lines (still flow style)
long_list: [
  item1,
  item2,
  item3
]

# NO trailing comma allowed
bad: [1, 2, 3,]   # error

Contenu mixte et hétérogène

YAML autorise un contenu complètement hétérogène dans les séquences et mappings — tout élément peut être de tout type. Cette flexibilité est puissante mais signifie que l'application doit valider la structure. Utilisez un schéma (JSON Schema, Cue, etc.) pour une validation stricte.

yaml
# Sequences can mix types freely
mixed:
  - string
  - 42
  - true
  - null
  - [1, 2, 3]            # nested sequence
  - key: value           # mapping
    another: value2
  - - nested
    - sequence

# Heterogeneous mapping values
config:
  string_val: text
  int_val: 42
  list_val: [a, b, c]
  map_val: {x: 1, y: 2}
  null_val: null
  bool_val: true

# YAML has no schema enforcing uniformity —
# the application must validate structure

Patterns d'indentation des séquences

Les séquences sous une clé peuvent être indentées (Pattern 1) ou au même niveau (Pattern 2, puisque le - compte comme indentation). Les deux sont valides ; choisissez-en un et restez cohérent. Dans les séquences de mappings, toutes les clés d'un élément doivent s'aligner avec la première clé après le -.

yaml
# Pattern 1: sequence indented under key
items:
  - a
  - b

# Pattern 2: sequence at same level as key
# (the - is treated as indentation)
items:
- a
- b

# Both are valid and produce the same result.
# Pick one and be consistent (most style guides prefer #1).

# Mapping item alignment — both keys align with first
users:
  - name: Alice
    age: 30
  - name: Bob
    age: 25

# WRONG: misaligned keys cause parse errors
# users:
#   - name: Alice
#    age: 30    # one space off — error
05

Chaînes multi-lignes (folded et literal)

Scalaire de bloc littéral (|)

Le scalaire de bloc littéral | préserve chaque retour à la ligne exactement comme écrit. L'indentation (la quantité au-delà du |) se retire de chaque ligne. Le chomping par défaut (clip) garde un retour à la ligne final. Utilisé pour scripts, code, poésie, ASCII art — partout où les retours littéraux comptent.

yaml
# | preserves newlines as-is
script: |
  #!/bin/bash
  echo "Hello"
  echo "World"

# Output string:
# #!/bin/bash\necho "Hello"\necho "World"\n

poem: |
  Roses are red,
  Violets are blue,
  YAML is clean,
  And JSON is too.

# Trailing newline is kept by default (clip mode)
# Use |- to strip, |+ to keep all trailing newlines

Scalaire de bloc folded (>)

Le scalaire de bloc folded > convertit les retours à la ligne simples en espaces, joignant les lignes en paragraphes. Les lignes vides deviennent des retours littéraux. Les lignes plus indentées que le contenu du bloc se préservent littéralement (utile pour des échantillons de code dans la prose).

yaml
# > folds newlines into spaces (paragraphs)
description: >
  This is a long paragraph that
  spans multiple lines in the YAML
  but will be joined into one line
  when parsed.

# Output: "This is a long paragraph that spans multiple
# lines in the YAML but will be joined into one line when
# parsed.\n"

# Blank lines preserve a newline
paragraphs: >
  First paragraph here.

  Second paragraph here.

  Third paragraph here.

# More indented lines are preserved literally
example: >
  This is folded.
    This line is more indented — kept literal.

Indicateurs de chomping (+/-)

Le chomping contrôle les retours finaux : clip (défaut, sans indicateur) en garde un ; strip (-) les retire tous ; keep (+) les préserve tous. L'indicateur vient juste après | ou > (ex. |-, |+, >-, >+). Le strip sert aux chaînes utilisées inline ; le keep est rare mais matche exactement la source.

yaml
# Default (clip): single trailing newline
text: |
  line1
  line2
# Result: "line1\nline2\n"

# Strip (-): remove ALL trailing newlines
text_strip: |-
  line1
  line2
# Result: "line1\nline2"

# Keep (+): keep ALL trailing newlines
text_keep: |+
  line1
  line2


# Result: "line1\nline2\n\n\n"

# Same applies to folded scalars
folded_keep: >+
  folded
  text

Indicateur d'indentation

Quand le contenu d'un scalaire de bloc commence par des espaces, il faut spécifier explicitement l'indentation du contenu avec un chiffre (ex. |2). Le chiffre indique combien d'espaces d'indentation appartiennent à la structure vs au contenu. Combinez au chomping : |2-, >4+, etc. Rarement requis mais essentiel quand il l'est.

yaml
# When the first line starts with spaces, you must
# tell YAML the content indentation explicitly

# Without indicator (ambiguous):
# content:
#   indented_line   # is the leading space content or not?

# With explicit indentation indicator (digit after | or >)
literal: |2
    hello
      world
# The "2" means: content is indented 2 spaces past the indicator
# So 4 spaces of indentation = 2 content + 2 extra

# Combined with chomping (order: indent then chomp)
text: |2-
    no trailing newline

# Folded with explicit indent
folded: >4
    paragraph with
    explicit indent

# Most of the time you don't need this — only when
# content legitimately starts with spaces

Chaînes multi-lignes simples

Les scalaires simples et quotés peuvent s'étendre sur plusieurs lignes, les retours se pliant en espaces (semblable à > mais implicite). Fragile car les ruptures de ligne dépendent du contexte et des caractères spéciaux. Pour tout texte multi-lignes non trivial, préférez les scalaires de bloc explicites | (littéral) ou > (folded).

yaml
# Plain (unquoted) scalars can span lines
# Newlines are folded to spaces (like > but no indicator)
message: this is
  a long message
  on multiple lines
# Result: "this is a long message on multiple lines"

# Quotes are required if the string contains special chars
quoted: "this is also
  a long message
  on multiple lines"
# Result: "this is also a long message on multiple lines"

# Plain multi-line breaks at certain chars
# (colons, etc.) — usually fold cleanly
# but be careful with leading colons

# Plain is fragile for multi-line — prefer | or >
safe_literal: |
  Use literal block for
  predictable multi-line text

Choisir fold vs literal

Règle empirique : utilisez | quand les retours à la ligne sont significatifs (scripts, fichiers de config, code), utilisez > quand vous voulez une source multi-lignes lisible mais un paragraphe joint (descriptions, documentation). Utilisez |- pour retirer le retour final quand la chaîne s'utilise inline.

yaml
# Use | (literal) when newlines matter:
script: |
  #!/bin/bash
  set -e
  echo "Step 1"
  echo "Step 2"

config_file: |
  [default]
  region=us-east-1
  output=json

# Use > (folded) when you want readable source
# but a single paragraph string:
description: >
  This service handles user authentication
  and session management. It talks to the
  PostgreSQL database and Redis cache.

# Use |- or >- to strip trailing newline
# (useful for inline string usage):
inline_script: |-
  echo hello

# Use plain single-line for short strings
short: hello world
06

Ancres et alias

Définir des ancres (&)

&nom définit une ancre sur un nœud (mapping, séquence ou scalaire). L'ancre ne change pas la valeur à cet endroit — elle étiquette juste le nœud pour réutilisation. Les alias (*nom) référencent le nœud ancré par nom. Les ancres doivent se définir avant usage dans le document.

yaml
# &name defines an anchor on a node
defaults: &defaults
  adapter: postgres
  host: localhost
  port: 5432

# The anchor marks the node so it can be reused
# The value is still assigned normally
production:
  database: *defaults
  # *defaults is an alias — references the anchored node

# Anchors on scalars
version: &ver "1.0.0"
current: *ver

# Anchors on sequences
colors: &colors
  - red
  - green
  - blue
primary: *colors

Utiliser des alias (*)

*nom est un alias référençant un nœud ancré précédemment. Les alias partagent l'identité avec l'original (même objet dans la plupart des parseurs). Ancres et alias se délimitent au document — ils ne peuvent référencer au-delà des frontières de ---. Combinez à << (clé de fusion) pour superposer des surcharges.

yaml
# Define once, reuse by alias
base: &base
  image: nginx:1.25
  restart: always

web:
  <<: *base
  ports:
    - "80:80"

api:
  <<: *base
  ports:
    - "8080:8080"
  environment:
    - DEBUG=true

# Aliases reference the SAME object (by identity)
# In most parsers, mutating one mutates the other
# (though YAML itself is read-only)

# Aliases can't span documents
# Each document has its own anchor namespace

Portée des ancres

Les ancres se délimitent à leur document et doivent se définir avant toute référence d'alias (pas de références avant). Plusieurs alias peuvent référencer la même ancre. Aliaser un alias marche — il résout transitivement. Les références inter-documents sont une erreur.

yaml
# Anchors are scoped to a single document
---
# Document 1
shared: &shared
  key: value
use: *shared   # works
...
---
# Document 2 — &shared is NOT visible here
other: *shared   # ERROR: unknown anchor

# Anchors must be defined before the alias
# (forward references are not allowed)
bad: *later      # ERROR
later: &later value

# Multiple aliases to the same anchor are fine
template: &tpl
  timeout: 30
use1: *tpl
use2: *tpl
use3: *tpl

# Aliasing an alias is allowed
a: &a value
b: &b *a
c: *b   # resolves to "value"

Surcharger des valeurs ancrées

Un alias (*nom) remplace tout le nœud — impossible de le surcharger partiellement. Pour surcharger des clés individuelles d'un mapping ancré, utilisez la clé de fusion << pour fusionner le mapping ancré puis ajouter ou surcharger des clés. C'est le pattern canonique de composition de configuration.

yaml
# Aliases themselves can't be partially overridden —
# an alias replaces the whole node. Use << (merge)
# to combine an anchored mapping with overrides.
defaults: &defaults
  timeout: 30
  retries: 3
  log_level: info

production:
  <<: *defaults
  log_level: warn      # override
  host: prod.example.com   # add

# Result:
# production:
#   timeout: 30
#   retries: 3
#   log_level: warn
#   host: prod.example.com

# Without <<, an alias replaces the whole node:
wrong:
  thing: *defaults
  # thing is the FULL defaults mapping — can't override

Ancres dans les séquences

Les ancres peuvent étiqueter des séquences entières, des éléments de séquence individuels ou des mappings dans une séquence. Le pattern de fusion << est particulièrement utile dans des séquences d'enregistrements similaires (ex. définitions de services) pour partager des champs communs. Ancrez les éléments individuels avec - &nom valeur.

yaml
# Anchors work on sequence items too
common: &common
  enabled: true
  log: stdout

services:
  - name: web
    <<: *common
    port: 80
  - name: api
    <<: *common
    port: 8080
  - name: worker
    <<: *common
    queue: jobs

# Anchoring a whole sequence
endpoints: &endpoints
  - /health
  - /metrics
  - /ready

monitoring:
  checks: *endpoints

# Anchoring individual sequence items
list:
  - &first one
  - two
  - *first   # "one" again

Précautions des ancres

Les ancres ont des précautions : les alias partagent l'identité (muter l'un affecte toutes les références dans les parseurs mutables), ils ajoutent une charge cognitive, et la plupart des sérialiseurs (y compris la sortie JSON) les expandent en copies simples. Utilisez les ancres pour de la vraie réutilisation (templates, défauts), pas de la micro-optimisation.

yaml
# Caveat 1: shared identity can surprise you
defaults: &defaults
  list: [1, 2, 3]

a: *defaults
b: *defaults
# In mutable parsers, a.list and b.list are the SAME list.
# Editing a.list also changes b.list.

# Caveat 2: anchors add cognitive overhead
# Overuse makes YAML hard to read and trace.

# Caveat 3: not all tools preserve anchors on output
# Many serializers expand aliases to plain copies.

# Caveat 4: JSON output loses anchors entirely
# (JSON has no anchor concept).

# Caveat 5: anchors don't work across documents
---
doc1: &x value
use1: *x
---
doc2: *x   # ERROR

# Prefer anchors for genuine reuse, not micro-optimization.
07

Clés de fusion (<<)

Fusion de base (<<)

La clé de fusion << prend un mapping (habituellement un alias) et fusionne ses paires clé-valeur dans le mapping courant. Les clés explicitement réglées dans le mapping courant surchargent les fusionnées. C'est le pattern canonique d'héritage de configuration en YAML.

yaml
# << merges a referenced mapping into the current one
defaults: &defaults
  adapter: postgres
  pool: 5
  timeout: 5000

development:
  <<: *defaults
  database: myapp_dev
  host: localhost

production:
  <<: *defaults
  database: myapp_prod
  host: db.example.com
  pool: 20      # override

# Result for development:
# adapter: postgres
# pool: 5
# timeout: 5000
# database: myapp_dev
# host: localhost

Fusions multiples

<< peut fusionner plusieurs mappings en passant une séquence flow d'alias ([*a, *b, *c]). Les fusions s'appliquent de gauche à droite ; les fusions ultérieures surchargent les antérieures pour les clés dupliquées. Les clés explicites du mapping gagnent toujours sur toute clé fusionnée. Plusieurs entrées << sont aussi autorisées.

yaml
# << can merge multiple mappings (sequence value)
base: &base
  logging: info
  retries: 3

security: &security
  auth: required
  tls: true

service: &service
  port: 8080
  host: 0.0.0.0

# Merge multiple in one go
production:
  <<: [*base, *security, *service]
  environment: prod
  port: 80        # override service.port

# Later merges override earlier ones for the same key.
# Explicit keys always win over merges.

# You can also have multiple << entries:
combined:
  <<: *base
  <<: *security
  custom: value

Surcharge et précédence

La précédence de fusion : les clés explicites du mapping gagnent toujours. Parmi les mappings fusionnés, les ultérieurs de la séquence surchargent les antérieurs pour la même clé. Utilisez cela pour superposer proprement défauts → spécifique-au-rôle → spécifique-à-l'instance.

yaml
# Explicit keys override merged keys
template: &template
  port: 8080
  log: info
  timeout: 30

instance:
  <<: *template
  port: 9090        # overrides template.port
  log: debug        # overrides template.log
  host: example.com # added

# Final: {port: 9090, log: debug, timeout: 30, host: example.com}

# Precedence: explicit > later merge > earlier merge
a: &a
  k: from_a
  x: 1
b: &b
  k: from_b
  y: 2

result:
  <<: [*a, *b]
  k: explicit   # wins over both a and b
# Final: {k: explicit, x: 1, y: 2}

Pattern de fusion avec ancres

Le pattern fusion+ancre est le pain quotidien de Docker Compose et fichiers de config similaires : définissez une ancre de défauts, puis chaque service la fusionne et surcharge des champs individuels. Cela garde les configs DRY sans sacrifier la personnalisation par service.

yaml
# Common pattern: anchor templates, merge + override
defaults: &defaults
  image: nginx:1.25
  restart: always
  logging:
    driver: json-file

services:
  web:
    <<: *defaults
    ports: ["80:80"]
  api:
    <<: *defaults
    image: node:20      # override
    ports: ["8080:8080"]
    environment:
      NODE_ENV: production
  worker:
    <<: *defaults
    image: worker:latest
    command: ["./run.sh"]

# This is the bread-and-butter of Docker Compose files
# — share base config, override per service.

Limites de la fusion

La clé de fusion << ne marche que pour les mappings — séquences et scalaires ne fusionnent pas. La fusion est superficielle : un mapping imbriqué dans le nœud courant REMPLACE entièrement le fusionné (pas de fusion profonde). Pour une fusion profonde, restructurez les données ou faites-le dans le code applicatif.

yaml
# << only works for MAPPINGS, not sequences or scalars
list_template: &list [1, 2, 3]

# This does NOT merge list items:
combined:
  <<: *list      # WRONG: *list is a sequence, not a mapping
  extra: value   # parse error or unexpected behavior

# Deep merge is NOT supported
parent: &parent
  nested:
    a: 1
    b: 2

child:
  <<: *parent
  nested:
    c: 3   # REPLACES parent.nested entirely
# Result: {nested: {c: 3}}  — NOT {nested: {a:1, b:2, c:3}}

# To deep-merge, you must do it in application code
# or restructure the data.

Statut et dépréciation de la clé de fusion

La clé de fusion << était une extension YAML 1.1 retirée de la spécification cœur YAML 1.2. En pratique, la plupart des parseurs la supportent encore (PyYAML, js-yaml, ruamel, SnakeYAML), mais les parseurs 1.2 stricts la rejettent. Utilisez-la aujourd'hui, mais sachez qu'elle est non standard ; pour les nouveaux formats, considérez des langages de config avec vraie héritage (Cue, Jsonnet, Dhall).

yaml
# IMPORTANT: the << merge key was REMOVED in YAML 1.2
# It was a YAML 1.1 feature.

# In practice, many parsers still support it:
# - PyYAML: supports (1.1 mode)
# - js-yaml: supports (opt-in)
# - ruamel.yaml: supports
# - SnakeYAML: supports
# - LibYAML: supports

# But strict YAML 1.2 parsers reject it:
# new_yaml_1_2_strict:
#   <<: *template    # ERROR in strict 1.2

# Recommendation:
# - Use << for now (widely supported)
# - Document that your files rely on it
# - For new formats, consider composition in code
#   or a config language with proper inheritance
#   (e.g. Dhall, Cue, Jsonnet)

# Alternative without <<:
# just duplicate or use application-level templating
08

Tags de types

Tags intégrés

Les tags intégrés utilisent le préfixe !! (raccourci de tag:yaml.org,2002:). Ils forcent un type précis quelle que soit l'inférence du schéma. Tags courants : !!str, !!int, !!float, !!bool, !!null, !!binary, !!map, !!seq, !!omap, !!set, !!timestamp. Utiles quand l'inférence devinerait faux.

yaml
# YAML tags use !! prefix for built-in types
# (the long form is tag:yaml.org,2002:)

# Common built-in tags
str: !!str hello
int: !!int 42
float: !!float 3.14
bool: !!bool true
null: !!null null
binary: !!binary "SGVsbG8="
map: !!map {a: 1}
seq: !!seq [1, 2]
omap: !!omap
  - a: 1
  - b: 2
set: !!set
  ? item1
  ? item2
timestamp: !!timestamp 2024-01-01T00:00:00Z
merge: !!merge "<<"   # the merge key tag

# Tags force a specific type regardless of inference
forced_str: !!str 42        # "42" string
forced_int: !!int "42"      # 42 integer
forced_bool: !!bool "yes"   # true

Forcer les types

Les tags forcent un type précis, surchargeant l'inférence du schéma. L'usage le plus courant est !!str pour empêcher des chaînes ressemblant à nombres/booléens/dates d'être coercées. !!int et !!float peuvent parser des chaînes numériques. Les tags sont essentiels quand l'application hôte exige un type précis.

yaml
# Without tags, type depends on schema inference
value: 42          # integer (Core schema)
value: "42"        # string (quoted)
value: !!str 42    # string (forced by tag)

# Common forcing scenarios
version: !!str 1.0       # "1.0" string, not float
phone: !!str 5551234     # string, not int
answer: !!str yes        # string, not bool (1.1)
region: !!str no         # string "no", not False (1.1)

# Force numeric parsing from strings
count: !!int "100"       # 100 integer
ratio: !!float "0.5"     # 0.5 float

# Force bool from strings
enabled: !!bool "yes"    # true
enabled: !!bool "off"    # false

# Force null
empty: !!null ""         # null
empty: !!null "~"        # null

Tags personnalisés

Les tags custom utilisent un préfixe ! simple et se définissent au niveau applicatif. L'application hôte doit enregistrer un constructeur pour chaque tag. Les loaders sûrs (recommandés) rejettent les tags inconnus par défaut — il faut explicitement opter. Les tags propres à des bibliothèques (comme python/object de PyYAML) peuvent être dangereux et sont désactivés par les loaders sûrs.

yaml
# Application-specific tags use ! prefix
# The application's YAML loader must handle them

# Custom tag (application-defined)
person: !person
  name: Alice
  age: 30

# Tag with arguments
color: !color rgb(255, 0, 0)
point: !point [10, 20]

# Library-specific tags (PyYAML example)
# python/object/apply:module.func args
sorted_set: !!python/object/apply:sorted
  args:
    - [3, 1, 2]

# Ruby-specific (Psych)
# !ruby/object:ClassName

# Custom tags require custom constructors in code.
# Unknown tags usually cause errors in safe loaders.

Tags locaux et verbatim

!prefix est pour les tags locaux (définis par l'app), !! le raccourci des tags globaux yaml.org, !<uri> est verbatim (sans résolution), et !prefix!court utilise les préfixes déclarés %TAG par brièveté. Les tags locaux sont les plus courants ; les verbatim comptent pour les schémas inter-outils.

yaml
# ! prefix — local tag (application-specific, no URI)
data: !myapp/data
  value: 42

# !! prefix — global built-in tag (resolved to yaml.org)
str: !!str hello

# !<full-uri> — verbatim tag (exact URI, no resolution)
binary: !<tag:example.com,2024:binary> "data"

# !tag!short — tag with prefix (resolved via %TAG directive)
%TAG !e! tag:example.com,2024:
data: !e!custom value
# resolves to tag:example.com,2024:custom

# %TAG directives declare prefixes
%TAG !yaml! tag:yaml.org,2002:
value: !yaml!str 42   # same as !!str

# Local tags are most common in app-specific YAML
# Verbatim tags are useful for cross-tool interoperability

Résolution des tags

La résolution des tags dépend du schéma. Failsafe (minimal) traite tout comme chaînes sauf tag explicite. Le schéma JSON ajoute int/float/bool/null. Le schéma Core (défaut YAML 1.2) étend JSON avec un matching plus tolérant. Les tags explicites (!!) surchargent toujours la résolution du schéma.

yaml
# Tags are resolved by the schema (Core, JSON, Failsafe)
# Without explicit tags, the schema infers types

# Failsafe schema — only str, map, seq (no inference)
# Everything is a string unless tagged
failsafe_value: 42       # str "42"
failsafe_tagged: !!int 42  # int 42

# JSON schema — str, int, float, bool, null, map, seq
json_value: 42           # int
json_str: "42"           # str

# Core schema (default for YAML 1.2) — like JSON but
# with more lenient parsing (yes/no not bool, etc.)
core_value: 42           # int
core_bool: true          # bool
core_str: hello          # str

# Explicit tags override schema resolution
forced: !!str true       # str "true" (even in Core)

Tags spécifiques à l'application

Les tags spécifiques à l'application permettent d'embarquer des objets de domaine (Money, DateRange, etc.) dans le YAML. Le loader doit enregistrer un constructeur pour chaque tag. Utilisez toujours des safe_loaders rejetant les tags inconnus par défaut — ne laissez jamais un YAML non fiable invoquer des constructeurs arbitraires (une vulnérabilité classique de désérialisation).

yaml
# Define your own tags for domain objects
# Example: a config loader for a custom app

# Tag a node as a "Money" object
price: !money "USD 19.99"

# Tag a node as a "DateRange"
range: !dateRange
  start: 2024-01-01
  end: 2024-12-31

# Tag nodes for custom parsing/validation
settings: !strict
  host: localhost
  port: 8080

# PyYAML example: register a constructor
# class MoneyLoader:
#     def __init__(self, value):
#         self.currency, self.amount = value.split()
#         self.amount = float(self.amount)
#
# yaml.add_constructor('!money', lambda l, n:
#     MoneyLoader(l.construct_scalar(n)))

# Safe loaders reject unknown tags — opt-in explicitly
# to avoid processing untrusted input with side effects.
09

Marqueurs et directives de document

Document unique

Un document YAML unique marche très bien sans marqueurs. Un --- initial est une convention pour signaler « ceci est du YAML » et se désambiguïser du texte simple. Le marqueur de fin ... est optionnel et rarement utilisé pour les fichiers à document unique.

yaml
# A single YAML document needs no markers
key: value
list:
  - a
  - b

# But a leading --- is a common convention
# to mark "this is YAML, not plain text"
---
key: value

# The trailing ... (end marker) is optional
# for a single document
key: value
...

Documents multiples (flux)

Un flux YAML est une séquence de documents séparés par ---. Chaque document se parse indépendamment. Les flux sont courants dans Kubernetes (plusieurs objets par fichier), les générateurs de sites statiques et les logs. Utilisez load_all() ou équivalent dans votre parseur pour itérer les documents.

yaml
# A YAML stream is multiple documents separated by ---
---
name: first
value: 1
---
name: second
value: 2
---
name: third
value: 3

# Each document is independent — anchors don't cross
# Use a parser's load_all() / load_multi() to read them
# Python (PyYAML):
#   for doc in yaml.safe_load_all(stream):
#       print(doc)

# Common use cases:
# - Kubernetes: multiple objects in one file
# - Blog generators: front matter + content
# - Log files: one record per document
# - CI/CD: multi-step pipelines

Marqueur de fin de document (...)

Le marqueur ... termine explicitement un document. Optionnel dans la plupart des cas mais utile quand le contenu pourrait être ambigu (ex. un bloc littéral contenant ---). Il signale aussi la fin de document aux parseurs en streaming. Rare dans le YAML écrit à la main mais courant dans la sortie programmatique.

yaml
# ... explicitly ends a document
---
key: value
...
# Anything after ... is a new document or stream end

# Useful when a document's content might be ambiguous
# without an explicit end:
---
message: |
  Some content
  ---
  that looks like a separator
...
---
next: document

# Without ... the parser might think the ---
# inside the literal block is a document separator
# (though block scalars usually prevent this)

# ... is also useful in programmatic output to flush

Directives

Les directives apparaissent avant le contenu du document et configurent le parseur. %YAML règle la version ; %TAG déclare des raccourcis de préfixes de tags. Les directives se délimitent au document — elles ne s'appliquent qu'au document suivant. La plupart des fichiers de config omettent les directives et s'appuient sur les défauts du parseur (habituellement 1.1 ou 1.2 bimodal).

yaml
# Directives appear at the very top, before content
# %YAML — declare YAML version
%YAML 1.2
---
key: value

# %TAG — declare a tag prefix
%TAG !e! tag:example.com,2024:
---
data: !e!custom value

# Multiple directives are allowed
%YAML 1.2
%TAG !e! tag:example.com,2024:
%TAG !yaml! tag:yaml.org,2002:
---
value: !yaml!str hello

# Directives are document-scoped — they apply to the
# next document only and must be repeated for each.
# Most config files omit directives and use defaults.

Exemples de flux de documents

Les flux de documents sont largement utilisés. Kubernetes les utilise pour regrouper plusieurs objets (Namespace, Deployment, Service) en un fichier. Les templates Helm, les logs CI et les générateurs de sites statiques (front matter + contenu) utilisent aussi des flux. Chaque document est indépendant et peut porter ses propres directives.

yaml
# Kubernetes multi-object file
---
apiVersion: v1
kind: Namespace
metadata:
  name: production
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: production
spec:
  replicas: 3
---
apiVersion: v1
kind: Service
metadata:
  name: api
  namespace: production
spec:
  ports:
    - port: 80

# Helm chart templates: stream of objects
# CI logs: one event per document
# Static site generator: front matter + body

Pièges de frontière

Une ligne commençant par --- en colonne 0 est toujours un séparateur de document (hors scalaires de bloc). Dans les scalaires de bloc (|, >), --- est du contenu littéral. Pour inclure --- en colonne 0 dans une valeur, indentez le bloc ou terminez d'abord le document avec ... Un --- avec du contenu sur la même ligne est un marqueur de début de document, pas un séparateur.

yaml
# A line starting with --- is ALWAYS a document separator
# (when at column 0). This can surprise you:

---
script: |
  echo hello
  ---  # this is INSIDE the block scalar — safe
next: value

# But this is NOT safe:
---
content: |
  line1
---
mistaken: this is a NEW document, not part of content!

# Inside block scalars, --- is literal (good).
# Outside, --- at column 0 always separates documents.

# Workaround for content that must contain --- at col 0:
# indent the block, or use ... to end the doc first.

# Also: a bare --- line with content on the same line
# is the document start marker, NOT a separator
--- key: value   # this is one document
10

Style flow

Séquences flow

Les séquences flow utilisent [ ] et se comportent comme des tableaux JSON. Espaces et retours à la ligne à l'intérieur sont flexibles. Contrairement à JSON, les virgules finales ne sont PAS autorisées. Utile pour des listes courtes et denses. Quotter les éléments contenant des caractères spéciaux (virgules, crochets, deux-points).

yaml
# Flow sequences use [item1, item2, ...]
numbers: [1, 2, 3]
names: [Alice, Bob, Charlie]

# Empty
empty: []

# Nested flow sequences
matrix: [[1, 2], [3, 4]]

# Flow sequence of mappings
points: [{x: 1, y: 2}, {x: 3, y: 4}]

# Multi-line flow sequence (whitespace is flexible)
long: [
  alpha,
  beta,
  gamma
]

# Quoting inside flow
mixed: ["hello", 'world', 42, true]

# NO trailing comma
bad: [1, 2, 3,]   # parse error

Mappings flow

Les mappings flow utilisent { } et se comportent comme des objets JSON. Les clés peuvent se quoter quand elles contiennent des caractères spéciaux. Les espaces sont flexibles. Virgules finales interdites (contrairement à JSON). Utilisez les mappings flow pour des données courtes et denses ; le style bloc est plus lisible pour les structures plus grandes.

yaml
# Flow mappings use {key: value, ...}
point: {x: 10, y: 20}
config: {host: localhost, port: 8080}

# Empty mapping
empty: {}

# Nested flow mappings
nested: {a: {b: {c: value}}}

# Quoted keys (needed for special chars)
quoted: {"key with space": value, "weird:key": 1}

# Multi-line flow mapping
config: {
  host: localhost,
  port: 8080,
  debug: true
}

# Flow mapping with flow sequence value
mixed: {nums: [1, 2, 3], name: test}

# NO trailing comma
bad: {a: 1, b: 2,}   # parse error

Mélanger flow et bloc

Les styles flow et bloc peuvent se mélanger librement dans un document. La règle pragmatique : style bloc pour les éléments structuraux (meilleure lisibilité avec l'indentation) et style flow pour les valeurs inline courtes (listes de scalaires, petites maps). Évitez le flow profondément imbriqué — il devient illisible vite.

yaml
# Mix flow and block styles freely
config:
  name: myapp
  ports: [80, 443]        # flow sequence in block mapping
  endpoints: {api: /v1, web: /}  # flow mapping in block

# Block inside flow (less common but valid)
flow_with_block: [{name: Alice, roles: [admin, user]}, {name: Bob}]

# Flow at top level
[top, level, flow]

# Block at top level
- block
- sequence

# Pragmatic rule:
# - Block for structure (readability)
# - Flow for short inline values
# - Avoid deeply nested flow — it becomes unreadable

Flow imbriqué

Le style flow peut s'imbriquer arbitrairement profondément, mais chaque niveau ajoute des crochets/accolades devenant durs à lire. Après 1 à 2 niveaux d'imbrication, passez au style bloc pour la lisibilité. L'équivalent en bloc d'un flow profondément imbriqué est presque toujours plus clair pour les mainteneurs humains.

yaml
# Flow can nest arbitrarily
data: {users: [{name: Alice, tags: [a, b]}, {name: Bob}]}

# Equivalent block:
# data:
#   users:
#     - name: Alice
#       tags:
#         - a
#         - b
#     - name: Bob

# Multi-line nested flow (rare but valid)
matrix: {
  rows: [
    [1, 2, 3],
    [4, 5, 6]
  ],
  cols: 3
}

# Recommendation: switch to block style after 1-2 levels
# of nesting — flow becomes a "wall of brackets".

Quand utiliser le style flow

Utilisez le style flow pour les courtes listes de scalaires, petites maps de lookup, enregistrements mono-ligne et sorties compatibles JSON. Évitez le flow pour les longues listes (dures à balayer), les structures profondément imbriquées (mur de crochets) ou tout ce qui exige des commentaires inline. Dans le doute, préférez le style bloc pour la lisibilité.

yaml
# Good uses of flow style:

# 1. Short lists of scalars
ports: [80, 443, 8080]
colors: [red, green, blue]

# 2. Small lookup maps
codes: {200: OK, 404: NotFound, 500: Error}

# 3. Single-line records in a sequence
coordinates:
  - {x: 1, y: 2}
  - {x: 3, y: 4}
  - {x: 5, y: 6}

# 4. JSON-compatible output (flow is JSON-compatible)

# Bad uses of flow style:

# 1. Long lists (use block)
#   ports: [80, 443, 8080, 8443, 9000, 9090, 9091, ...]  # hard to read

# 2. Deeply nested (use block)
#   {a: {b: {c: {d: {e: value}}}}}  # unreadable

# 3. Anything with comments (flow doesn't allow inline comments well)

Précautions du style flow

Le style flow a des précautions : caractères spéciaux (virgules, deux-points, crochets) à quoter ; pas de virgules finales ; commentaires maladroits ; pas de scalaires de bloc | ou > (utilisez \n dans les chaînes double-quotées) ; et les changements mono-ligne sont plus durs à diff. Le style bloc est plus friendly pour la config sous gestion de version.

yaml
# Caveat 1: special characters need quotes in flow
flow: [a, b, "c,d", "d:e"]   # commas and colons need quoting
block:
  - a
  - b
  - c,d      # no quotes needed in block style
  - d:e      # no quotes needed in block style

# Caveat 2: no trailing commas
bad: [1, 2, 3,]   # error

# Caveat 3: comments are awkward in flow
config: {
  host: localhost,  # comment allowed but clunky
  port: 8080
}

# Caveat 4: flow style has no multi-line strings
# (no | or > inside flow)
# You can use \n escapes in double quotes:
text: "line1\nline2"

# Caveat 5: flow is harder to diff in version control
# (one-line changes vs whole-block changes)
11

Conversion YAML et JSON

JSON est du YAML valide

YAML 1.2 a été conçu pour que JSON en soit un sous-ensemble strict — tout document JSON est du YAML valide. La plupart des parseurs YAML lisent le JSON avec plaisir. L'inverse est faux : les fonctionnalités YAML comme les commentaires, ancres, flux multi-documents et scalaires de bloc ne sont pas du JSON valide.

yaml
# JSON is a strict subset of YAML 1.2
# Any JSON file is valid YAML

# This is valid YAML (it's JSON):
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}

# So is this multi-line JSON:
{
  "name": "Alice",
  "age": 30,
  "hobbies": ["a", "b"]
}

# Parsers usually accept JSON files as YAML
# Python: yaml.safe_load(json_string)  # works
# JS:     YAML.load(json_string)       # works
# Go:     yaml.Unmarshal(json_bytes, &v)  # works (yaml.v3)

# But the reverse is NOT always true:
# YAML with comments, anchors, multi-docs is NOT valid JSON

Représentations équivalentes

JSON, YAML bloc et YAML flow peuvent tous représenter les mêmes données. JSON est le plus portable (chaque langage a un parseur JSON). Le YAML bloc est le plus lisible pour l'humain. Le YAML flow est un compromis compact. Choisissez selon votre audience : outils (JSON) vs humains (YAML bloc).

yaml
# JSON:
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}

# YAML block:
name: Alice
age: 30
hobbies:
  - a
  - b

# YAML flow (closest to JSON):
{name: Alice, age: 30, hobbies: [a, b]}

# YAML with quotes (JSON-compatible):
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}

# All four parse to the same data structure.
# Pick the style that fits your use case:
# - JSON for interop and strict tools
# - YAML block for human-edited config
# - YAML flow for compact inline data

Conversion JSON vers YAML

Convertissez JSON en YAML en parsant le JSON puis en déversant en YAML avec default_flow_style=False (style bloc). Les guillemets obligatoires du JSON se retirent là où YAML n'en a pas besoin. Attention aux clés ressemblant à des nombres/booléens — elles peuvent exiger un quoting en YAML pour préserver le type chaîne.

yaml
# Convert JSON to YAML using a parser
# Python:
# import json, yaml
# data = json.loads(json_string)
# yaml_str = yaml.safe_dump(data, default_flow_style=False, sort_keys=False)
#
# JS:
# const data = JSON.parse(jsonString)
# const yamlStr = yaml.dump(data)

# Example input JSON:
# {"server": {"host": "localhost", "port": 8080}, "debug": true}

# Output YAML:
# server:
#   host: localhost
#   port: 8080
# debug: true

# Conversion considerations:
# - JSON keys are always quoted -> YAML usually unquotes them
# - JSON arrays -> YAML block sequences (with default_flow_style=False)
# - JSON strings with special chars may need quoting
# - JSON null -> YAML null (or ~)
# - JSON booleans/numbers preserved

Conversion YAML vers JSON

Convertissez YAML en JSON en parsant puis sérialisant en JSON. Précautions : commentaires et tags se perdent ; les ancres s'expansent en copies simples ; les flux multi-documents doivent devenir un tableau JSON ; les dates YAML peuvent devenir des chaînes. Des outils comme yq rendent cela facile en ligne de commande.

yaml
# Convert YAML to JSON
# Python:
# import json, yaml
# data = yaml.safe_load(yaml_string)
# json_str = json.dumps(data, indent=2)

# JS:
# const data = yaml.load(yamlString)
# const jsonStr = JSON.stringify(data, null, 2)

# Command-line tools:
# yq -o=json '.config' file.yaml        # mikefarah/yq
# ruby -ryaml -rjson -e 'puts JSON.generate(YAML.load(STDIN.read))' < file.yaml
# python -c 'import json,sys,yaml; print(json.dumps(yaml.safe_load(sys.stdin)))'

# Caveats when converting YAML to JSON:
# - YAML comments are LOST (JSON has no comments)
# - YAML anchors are EXPANDED to plain copies
# - YAML multi-doc streams become a JSON array (or fail)
# - YAML tags (!!) are lost or cause errors
# - YAML dates may become strings (JSON has no date type)

Sous-ensemble compatible JSON

Le sous-ensemble compatible JSON du YAML évite commentaires, ancres, multi-docs, tags, scalaires de bloc et chaînes simples ressemblant à d'autres types. Rester dans ce sous-ensemble garantit des aller-retours propres vers JSON. Utile quand des consommateurs YAML et JSON lisent les mêmes données, ou quand la préservation stricte des types compte.

yaml
# To produce YAML that round-trips to JSON cleanly,
# stay within the JSON-compatible subset:

# 1. No comments
# 2. No anchors/aliases
# 3. No multi-doc streams
# 4. No tags
# 5. No block scalars (|, >) — use \n in double-quoted strings
# 6. Quote all string keys (JSON requires this)
# 7. No plain strings that look like other types

# JSON-compatible YAML:
{"name": "Alice", "age": 30, "active": true}
{"items": ["a", "b", "c"]}
{"nested": {"key": "value"}}

# Useful when you need both YAML and JSON consumers
# for the same data, or want strict type preservation.

# Many YAML dumpers have a "json-compatible" mode.

Considérations d'aller-retour

L'aller-retour YAML (parser puis déverser) perd souvent commentaires, noms d'ancres, ordre des clés, style de quoting et formatage. ruamel.yaml (Python) a un mode round-trip qui préserve commentaires et ordre. Pour la config éditée par des humains, n'écrasez jamais aveuglément avec la sortie du dumper — diff soigneusement d'abord.

yaml
# Round-trip: YAML -> parse -> dump -> YAML
# Information that may be LOST:
# - Comments (most dumpers drop them)
# - Anchor names (dumpers may re-create or expand)
# - Key order (some dumpers sort keys)
# - Quoting style (dumpers choose their own)
# - Flow vs block style (dumpers usually pick one)
# - Whitespace and indentation amount
# - Multi-document structure (sometimes)
# - Tag prefixes and %TAG directives

# Tools that preserve style:
# - ruamel.yaml (Python): round-trip mode preserves comments/order
# - yaml.v3 (Go): preserves key order
# - prettier with yaml plugin: normalizes formatting

# For config files where humans edit:
# - Use ruamel.yaml round-trip mode
# - Or accept that dumps are "normalized"
# - Never overwrite human-edited files with dumper output
#   without diffing carefully
12

Schémas YAML

Schéma Failsafe

Le schéma Failsafe est le plus conservateur — il ne reconnaît que str, map et seq. Tous les scalaires sont des chaînes sauf tag explicite. Utile pour des entrées non fiables (pas de surprises de coercion implicite) ou comme base de schémas custom. La plupart des loaders de production utilisent un schéma un peu plus riche.

yaml
# Failsafe schema — the most conservative
# Recognizes ONLY three types: str, map, seq
# Everything else is a string

# Under Failsafe:
value: 42           # str "42" (NOT int)
flag: true          # str "true" (NOT bool)
empty: null         # str "null" (NOT null)
date: 2024-01-01    # str "2024-01-01" (NOT date)

# Use explicit tags to get other types
int_value: !!int 42
bool_value: !!bool true
null_value: !!null null

# When to use Failsafe:
# - Untrusted input (no implicit type coercion)
# - When you want strings only
# - As a base for custom schemas

# PyYAML: SafeLoader uses a schema close to Failsafe
# but with int/float/bool/null inference.

Schéma JSON

Le schéma JSON matche exactement le système de types de JSON : str, int, float, bool, null, map, seq. Plus strict que le schéma Core — pas de littéraux octal/binaire, pas de séparateurs underscore, seuls true/false comme booléens, pas d'inférence de date. À utiliser pour l'interop JSON ou un comportement de type strict.

yaml
# JSON schema — same type system as JSON
# Recognizes: str, int, float, bool, null, map, seq

# Under JSON schema:
int: 42             # int
float: 3.14         # float
str: hello          # str
bool: true          # bool
null_val: null      # null
list: [1, 2, 3]     # seq
map: {a: 1}         # map

# Differences from Core schema:
# - Stricter number parsing (no 0o octal, no _ separators)
# - Booleans are only true/false (no yes/no)
# - No date/timestamp inference

# When to use JSON schema:
# - Interop with JSON tools
# - Strict type behavior
# - When you want JSON's type semantics

Schéma Core

Le schéma Core est le défaut de YAML 1.2. Il étend JSON avec un parsing tolérant : hex (0x), octal (0o), binaire (0b), underscores dans les nombres, flottants .inf/.nan. Les booléens ne sont que true/false (pas yes/no). Les dates sont des chaînes (pas d'inférence). La plupart des parseurs modernes passent par défaut à Core ou une variante compatible 1.1.

yaml
# Core schema — the DEFAULT for YAML 1.2
# Extends JSON schema with more lenient scalar resolution

# Under Core schema:
int: 42             # int
neg: -17            # int
hex: 0xFF           # int (255)
oct: 0o17           # int (15)  [YAML 1.2 syntax]
bin: 0b1010         # int (10)
float: 3.14         # float
exp: 1.0e+3         # float
inf: .inf           # float
nan: .nan           # float
bool: true          # bool (only true/false, not yes/no)
null: null          # null (also ~, empty)
str: hello          # str
date: 2024-01-01    # str (Core does NOT infer dates)

# Differences from YAML 1.1:
# - yes/no/on/off are STRINGS (not booleans)
# - 017 is a string (octal is 0o17 in 1.2)
# - Dates are strings (no implicit inference)

# Most modern parsers default to Core or close to it.

YAML 1.1 vs 1.2

YAML 1.1 (défaut de PyYAML) traite yes/no/on/off comme booléens et les nombres à 0 initial comme octal — sources célèbres de bugs (le 'no' norvégien → false). YAML 1.2 (spécification courante) restreint les booléens à true/false et utilise 0o pour l'octal. Vérifiez toujours le défaut de votre parseur et quotter les chaînes ambiguës.

yaml
# YAML 1.1 (older, used by PyYAML by default)
bool_1_1: yes       # true (yes/no/on/off are booleans)
octal_1_1: 017      # 15 (leading 0 = octal)
sexagesimal: 1:30   # 90 (base-60!) - obscure feature

# YAML 1.2 (current spec)
bool_1_2: yes       # str "yes" (only true/false are bool)
octal_1_2: 0o17     # 15 (explicit 0o prefix)
no_sexagesimal: 1:30 # str "1:30"

# Practical impact:
# - "no" (Norway) becomes False in PyYAML (1.1)
# - "010" becomes 8 in PyYAML, "010" in 1.2
# - "on"/"off" become True/False in 1.1, strings in 1.2

# PyYAML: defaults to 1.1 behavior
# ruamel.yaml: defaults to 1.2 (with 1.1 compatibility options)
# js-yaml: defaults to 1.1 with 1.2 options
# Go yaml.v3: defaults to 1.2-ish

# Always check your parser's default schema!

Différences de résolution de types

La résolution de types diffère entre parseurs YAML 1.1 et 1.2 : yes/no/on/off, nombres à zéro initial et littéraux sexagésimaux se parsent différemment. Mitigez en quottant les chaînes ambiguës, épinglant la version avec %YAML, utilisant des tags explicites et testant contre tous les parseurs cibles.

yaml
# Same YAML, different parsers, different types:
value: yes

# PyYAML (1.1):        True (bool)
# js-yaml (1.1):       true (bool)
# ruamel (1.2):        "yes" (str)
# Go yaml.v3 (1.2):    "yes" (str)
# Strict 1.2:          "yes" (str)

value: 010

# PyYAML (1.1):        8 (int, octal)
# ruamel (1.2):        "010" (str)
# Go yaml.v3 (1.2):    "010" (str)

value: 1.0

# All:                 1.0 (float) - consistent

value: true

# All:                 true (bool) - consistent

# Mitigation strategies:
# 1. Quote strings that look like other types
# 2. Pin the YAML version with %YAML 1.2
# 3. Use explicit tags (!!) for critical values
# 4. Test against all target parsers

Choisir un schéma

Choisissez le schéma selon le cas d'usage : 1.2 Core pour les nouveaux projets (prévisible), 1.1 pour l'interop PyYAML (ou quotter les chaînes ambiguës), Failsafe/JSON pour les entrées non fiables, schéma JSON pour l'interop JSON. Pour les fichiers de config, 1.2 Core plus le quoting des chaînes ambiguës ("no", "010", etc.) est la combinaison la plus sûre.

yaml
# Recommendations for choosing a schema:

# 1. For NEW projects: use YAML 1.2 Core schema
#    - More predictable (no yes/no surprises)
#    - Modern parsers support it
#    - ruamel.yaml, Go yaml.v3 default to it

# 2. For INTEROP with existing PyYAML code:
#    - Either accept 1.1 semantics
#    - Or use ruamel.yaml with 1.2 + preserve 1.1 features
#    - Quote all ambiguous strings explicitly

# 3. For UNTRUSTED input: use Failsafe or JSON schema
#    - No implicit type coercion
#    - Smaller attack surface
#    - Predictable behavior

# 4. For CONFIG FILES: use 1.2 Core + quote ambiguous strings
#    - "no", "yes", "on", "off", "010", "1.0" should be quoted
#    - Document your schema choice
#    - Lint with yamllint

# 5. For JSON INTEROP: use JSON schema
#    - Same types as JSON
#    - Round-trips cleanly
13

Lint et validation YAML

yamllint

yamllint est le linter YAML standard (Python). Il attrape erreurs de syntaxe, soucis d'indentation, espaces finaux, marqueurs de document manquants et plus. À utiliser en CI et hooks pre-commit pour attraper tôt les soucis YAML. Le mode strict (-s) traite les avertissements comme erreurs.

yaml
# yamllint is the standard YAML linter
# Install: pip install yamllint

# Lint a file
# yamllint config.yaml

# Lint with strict mode (warnings = errors)
# yamllint -s config.yaml

# Output example:
# config.yaml
#   3:4       error    mapping values are not allowed here
#   5:1       error    syntax error: found character '	' that cannot start any token
#   8:3       warning  missing document start "---"
#   12:5      warning  comment is not indented like content

# Lint multiple files
# yamllint file1.yaml file2.yaml file3.yaml

# Lint a directory (recursive)
# yamllint -d path/to/dir

# Read from stdin
# cat config.yaml | yamllint -

Configuration du lint

Configurez yamllint avec .yamllint.yml. Étendez un profil (default ou strict) puis surchargez des règles individuelles : indentation, longueur de ligne, style de quoting, commentaires, espaces finaux, marqueurs de document. Réglez selon le style de votre équipe. Lancez en CI pour imposer de façon cohérente.

yaml
# .yamllint.yml — configuration file for yamllint
# Place in project root or ~/.config/yamllint/config

# Use a built-in profile
extends: default

# Or use a stricter profile
# extends: strict

# Override specific rules
rules:
  # Require document start marker
  document-start: disable
  # Enforce 2-space indentation
  indentation:
    spaces: 2
    indent-sequences: true
  # Max line length
  line-length:
    max: 120
    allow-non-breakable-words: true
  # Disallow trailing spaces
  trailing-spaces: enable
  # Require consistent quoting
  quoted-strings:
    quote-type: double
    required: only-when-needed
  # Disallow comments without space before #
  comments:
    require-starting-space: true
    min-spaces-from-content: 1

Erreurs de syntaxe courantes

Erreurs YAML courantes : tabulations pour l'indentation (seuls les espaces autorisés), deux-points sans espace suivante, chaînes non quotées avec deux-points (parsées comme mappings), virgules finales en style flow, indentation incohérente et clés dupliquées. Un linter attrape tout cela automatiquement.

yaml
# Error: tab characters for indentation
# bad:
# 	key: value   <- tab not allowed
# Fix: use spaces only

# Error: colon without space
# bad:  key:value
# good: key: value

# Error: unquoted special characters
# bad:  url: http://example.com:8080   <- parsed as mapping
# good: url: "http://example.com:8080"

# Error: trailing comma in flow
# bad:  list: [1, 2, 3,]
# good: list: [1, 2, 3]

# Error: inconsistent indentation
# bad:
#   key1: value
#    key2: value   <- one extra space
# good:
#   key1: value
#   key2: value

# Error: duplicate keys (some parsers warn)
# bad:
#   key: first
#   key: second
# good: rename one

Erreurs tabulation vs espace

Les tabulations sont strictement interdites pour l'indentation structurelle YAML — la cause n°1 des erreurs de parsing. Les tabulations dans les valeurs de chaînes (scalaires de bloc, chaînes quotées) vont bien. Configurez votre éditeur pour utiliser des espaces (expandtab) pour les fichiers YAML. Détectez les lignes fautives avec grep -P '\t'.

yaml
# YAML FORBIDS tabs for indentation.
# This is the #1 cause of YAML parse errors.

# Symptom: parser error like
# "found character '\t' that cannot start any token"
# or "while scanning for the next token, found tab"

# Tabs are allowed INSIDE string values:
script: |
  #!/bin/bash
  if [ -f file ]; then   # this is fine (literal content)
  \techo found           # \t inside block scalar is OK

# But tabs for STRUCTURAL indentation are forbidden:
# bad:
# services:
# \tweb:
# \t\timage: nginx

# Fix: convert tabs to spaces
# Configure your editor to use spaces for YAML files
# VS Code: "editor.insertSpaces": true, "editor.tabSize": 2
# Vim: set expandtab shiftwidth=2

# Detect tabs:
# grep -P '\t' file.yaml   (finds offending lines)

Détection des clés dupliquées

Les clés dupliquées dans un mapping sont déconseillées et une source courante de bugs (surcharge silencieuse dernier-gagnant). yamllint les détecte avec la règle key-duplicates (active par défaut). Causes courantes : erreurs de copier-coller et mauvaise résolution de conflits de fusion. Lint toujours en CI pour les attraper tôt.

yaml
# Duplicate keys are technically discouraged
# but YAML 1.2 doesn't strictly forbid them.
# Behavior varies by parser (usually last-wins).

config:
  host: localhost
  port: 8080
  host: prod.example.com   # silent override!

# yamllint catches these:
#   4:3  error  duplication of key "host" in mapping

# Enable in .yamllint.yml:
# rules:
#   key-duplicates: enable

# Other tools that detect duplicates:
# - kubeval (for Kubernetes YAML)
# - yq (programmatic checks)
# - Custom schema validation (JSON Schema)

# Common cause: copy-paste errors, merge conflicts
# resolved incorrectly. Always lint in CI to catch.

Validation de schéma

Validez la structure YAML avec JSON Schema (marche car YAML est un sur-ensemble de JSON). Pour Kubernetes, utilisez kubeval ou kubectl --dry-run. Pour la config générale, utilisez yamllint (syntaxe/style) plus jsonschema (structure) ou Cue (langage de schéma). Branchez la validation dans les hooks pre-commit et la CI.

yaml
# Validate YAML against a JSON Schema
# (JSON Schema works on YAML since YAML is a JSON superset)

# Python example with jsonschema + PyYAML:
# import json, yaml, jsonschema
# with open('schema.json') as f: schema = json.load(f)
# with open('config.yaml') as f: doc = yaml.safe_load(f)
# jsonschema.validate(doc, schema)

# Tools for Kubernetes YAML:
# kubeval            - validate against K8s schemas
# kubectl apply --dry-run=client -f file.yaml
# conftest           - policy-based validation (OPA)

# Tools for general YAML:
# yamllint           - syntax + style
# jsonschema-cli     - JSON Schema validation
# cue                - schema + validation language
# dataladen          - config validation

# Pre-commit hook example (.pre-commit-config.yaml):
# repos:
#   - repo: https://github.com/adrienverge/yamllint
#     rev: v1.32.0
#     hooks:
#       - id: yamllint
#         args: [-s]
14

YAML Docker Compose

Définition de service

Les fichiers Docker Compose définissent des apps multi-conteneurs. Les clés de premier niveau sont version, services, volumes, networks, configs, secrets. Chaque service définit image/build, ports, volumes, environment, depends_on, politique de restart. Les volumes déclarés au premier niveau sont nommés et persistés.

yaml
# docker-compose.yml — multi-container apps
version: "3.9"   # compose file format version

services:
  web:
    image: nginx:1.25
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./html:/usr/share/nginx/html:ro
    restart: unless-stopped
    depends_on:
      - api

  api:
    build:
      context: ./api
      dockerfile: Dockerfile
    environment:
      - NODE_ENV=production
      - DB_URL=postgres://db:5432/app
    ports:
      - "8080:8080"
    restart: always

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - db_data:/var/lib/postgresql/data
    restart: always

volumes:
  db_data:

Volumes et réseaux

Les volumes Compose sont des bind mounts (hote:conteneur), nommés (déclarés dans les volumes de premier niveau) ou anonymes. Le suffixe :ro rend les montages en lecture seule. Les réseaux isolent les services ; internal: true bloque l'accès externe. Les volumes nommés persistent les données entre recréations de conteneurs.

yaml
services:
  web:
    image: nginx
    volumes:
      # Bind mount: host:container
      - ./html:/usr/share/nginx/html:ro
      # Named volume: name:container
      - shared_data:/data
      # Anonymous volume
      - /tmp/cache
    networks:
      - frontend
      - backend

  db:
    image: postgres
    volumes:
      - db_data:/var/lib/postgresql/data
    networks:
      - backend

volumes:
  db_data:
    driver: local
  shared_data:
    driver: nfs
    driver_opts:
      type: nfs
      device: ":/path/to/share"

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true   # no external access

Variables d'environnement

Compose supporte trois styles de variables d'env : liste (CLE=valeur), map (CLE: valeur) et env_file. ${VAR} s'interpole depuis le shell hôte ou le fichier .env au parsing ; ${VAR:-defaut} fournit des défauts. Utilisez $$ pour échapper un $ littéral. Le fichier .env à la racine du projet se charge automatiquement.

yaml
services:
  api:
    image: myapi
    # Method 1: list of KEY=value
    environment:
      - NODE_ENV=production
      - LOG_LEVEL=info
    # Method 2: map (cleaner)
    environment:
      NODE_ENV: production
      LOG_LEVEL: info
    # Method 3: file
    env_file:
      - .env
      - .env.production
    # Interpolation from host environment
    environment:
      - API_KEY=${API_KEY}     # from shell
      - PORT=${PORT:-8080}      # default 8080

# .env file (auto-loaded by docker compose):
# API_KEY=abc123
# PORT=8080
# DB_URL=postgres://...

# Compose substitutes ${VAR} from host shell or .env
# Use $$ to escape (literal $):
# - TOKEN=price_$$5   # produces price_$5

Depends, healthchecks et restart

depends_on avec condition: service_healthy attend que le healthcheck d'une dépendance passe avant de démarrer. Les healthchecks utilisent test (CMD ou CMD-SHELL), interval, timeout, retries, start_period. Politiques de restart : no, always, unless-stopped (survit aux redémarrages mais respecte l'arrêt manuel), on-failure.

yaml
services:
  api:
    image: myapi
    depends_on:
      db:
        condition: service_healthy   # wait for db healthy
      redis:
        condition: service_started
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

  db:
    image: postgres
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

# restart policies:
# no              - never restart (default)
# always          - always restart on stop
# unless-stopped  - restart unless manually stopped
# on-failure      - restart only on non-zero exit

Fichiers de surcharge

Compose fusionne les fichiers de surcharge au-dessus de la base. docker-compose.override.yml s'applique automatiquement. Les mappings fusionnent en profondeur (les surcharges gagnent) ; les séquences se remplissent habituellement (pas ajoutées) — attention aux ports/volumes. Utilisez les flags -f pour préciser l'ordre explicite des fichiers pour les configs spécifiques à l'environnement.

yaml
# docker-compose.yml — base
services:
  web:
    image: nginx
    ports:
      - "80:80"
    environment:
      - ENV=base

# docker-compose.override.yml — auto-applied on top
# (loaded automatically by 'docker compose up')
services:
  web:
    ports:
      - "8080:80"      # overrides "80:80"
    environment:
      - DEBUG=true     # added
      - ENV=override   # overrides ENV=base
    volumes:
      - ./dev.conf:/etc/nginx/conf.d/default.conf

# Multiple override files (-f flag):
# docker compose -f compose.yml -f compose.prod.yml -f compose.secrets.yml up

# Merge rules:
# - mappings: deep-merged (overrides win, others kept)
# - sequences: usually REPLACED (not appended) —
#   ports/depends_on/volumes are exceptions in some versions

# Use -f to specify explicit file order

Profils et fonctionnalités Compose

Les profils permettent d'activer des services (ex. debug, test, ci) avec le flag --profile. Autres fonctionnalités v3 : init (gestion correcte des signaux PID 1), extends (hériter d'un autre service), configs et secrets (montés comme fichiers), deploy (placement/réplicas/ressources Swarm). Les profils sont géniaux pour garder un fichier compose pour plusieurs environnements.

yaml
# Profiles — opt-in services
services:
  web:
    image: nginx
    # no profile: always started

  debug:
    image: busybox
    profiles: ["debug"]   # only with --profile debug

  loadtest:
    image: locust
    profiles: ["test", "ci"]

# Enable a profile:
# docker compose --profile debug up
# docker compose --profile test --profile ci up

# Compose file format features (v3.9+):
# - deploy: placement, replicas, resources (Swarm-only in v3)
# - configs: external config files
# - secrets: mounted secret files
# - extends: inherit from another service
# - init: run tini as PID 1

services:
  worker:
    image: worker
    init: true   # proper signal handling
    extends:
      service: base   # inherit fields
    configs:
      - config1
    secrets:
      - api_key

configs:
  config1:
    file: ./config.toml
secrets:
  api_key:
    file: ./api_key.txt
15

YAML Kubernetes

Structure d'objet

Tout objet Kubernetes a apiVersion, kind, metadata et spec. apiVersion est groupe/version (ex. apps/v1, v1 pour le cœur). metadata inclut name, namespace, labels, annotations. spec est l'état désiré — Kubernetes œuvre pour que la réalité matche le spec. status se règle par le système.

yaml
# Every Kubernetes object has the same 4 top-level fields
apiVersion: apps/v1        # API group + version
kind: Deployment           # object type
metadata:                  # identity
  name: my-app
  namespace: production
  labels:
    app: my-app
    tier: backend
  annotations:
    deployment.kubernetes.io/revision: "1"
spec:                      # desired state
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: app
          image: my-app:1.0.0
          ports:
            - containerPort: 8080

# apiVersion + kind + metadata + spec is the universal shape
# (some objects use status too, but you don't set it)

Labels et selectors

Les labels identifient et groupent les objets ; les selectors interrogent par labels. Les selectors par égalité (cle=valeur) et par ensemble (In, NotIn, Exists, DoesNotExist) sont tous deux supportés. Les annotations détiennent des métadonnées non identifiantes (descriptions, contacts, config d'outillage). Les labels servent à la sélection ; les annotations aux infos additionnelles.

yaml
# Labels — identify and group objects
metadata:
  labels:
    app: my-app
    tier: backend
    env: production
    version: "1.0"

# Selectors — query objects by labels
# Equality-based
selector:
  matchLabels:
    app: my-app
    env: production

# Set-based
selector:
  matchExpressions:
    - {key: tier, operator: In, values: [backend, api]}
    - {key: env, operator: NotIn, values: [dev]}
    - {key: version, operator: Exists}

# kubectl commands:
# kubectl get pods -l app=my-app
# kubectl get pods -l 'tier in (backend,api),env!=dev'
# kubectl get pods -l app=my-app -l env=production

# Annotations — non-identifying metadata
metadata:
  annotations:
    description: "My app deployment"
    contact: "[email protected]"

Spec de Pod

Un spec de Pod définit conteneurs, leurs images, ports, variables d'env (littérales ou depuis secrets/configmaps), ressources (requests/limits), probes (readiness/liveness), volumes et volumeMounts. Les Pods sont la plus petite unité déployable mais on les crée habituellement via des Deployments, pas directement.

yaml
apiVersion: v1
kind: Pod
metadata:
  name: my-pod
spec:
  containers:
    - name: app
      image: my-app:1.0
      ports:
        - containerPort: 8080
          name: http
      env:
        - name: LOG_LEVEL
          value: info
        - name: SECRET_KEY
          valueFrom:
            secretKeyRef:
              name: app-secrets
              key: secret-key
      resources:
        requests: {cpu: 100m, memory: 128Mi}
        limits: {cpu: 500m, memory: 512Mi}
      readinessProbe:
        httpGet: {path: /health, port: 8080}
        initialDelaySeconds: 5
        periodSeconds: 10
      volumeMounts:
        - name: config
          mountPath: /etc/config
  volumes:
    - name: config
      configMap:
        name: app-config
  restartPolicy: Always

Deployment

Un Deployment gère ReplicaSets et Pods. spec.replicas règle le compte désiré. strategy.type peut être RollingUpdate (défaut, contrôlé par maxSurge/maxUnavailable) ou Recreate. Le template de pod (spec.template) définit comment les pods se créent. Gérez les rollouts avec kubectl rollout status/undo/history.

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: app
          image: my-app:1.0.0
          ports:
            - containerPort: 8080
          resources:
            requests: {cpu: 100m, memory: 128Mi}
            limits: {cpu: 500m, memory: 512Mi}
          readinessProbe:
            httpGet: {path: /ready, port: 8080}
  # Rollback / history
  # kubectl rollout status deployment/my-app
  # kubectl rollout undo deployment/my-app
  # kubectl rollout history deployment/my-app

Service

Un Service expose les Pods comme service réseau. Le type ClusterIP (défaut) est interne seulement ; NodePort expose sur chaque nœud ; LoadBalancer provisionne un LB cloud ; ExternalName est un CNAME DNS. Le selector route le trafic vers les pods correspondants. Les ports mappent le port du service au targetPort du conteneur (nombre ou nommé).

yaml
apiVersion: v1
kind: Service
metadata:
  name: my-app
spec:
  type: ClusterIP      # ClusterIP (default), NodePort, LoadBalancer, ExternalName
  selector:
    app: my-app        # routes to pods with these labels
  ports:
    - name: http
      port: 80         # service port
      targetPort: 8080 # container port (or named port)
      protocol: TCP
    - name: https
      port: 443
      targetPort: 8443

# NodePort: exposes on each node's IP at a static port (30000-32767)
# LoadBalancer: provisions a cloud LB
# ExternalName: CNAME to an external service

# Service types:
# ClusterIP    - internal cluster IP (default)
# NodePort     - exposes on node port + ClusterIP
# LoadBalancer - cloud LB + NodePort + ClusterIP
# ExternalName - DNS CNAME (no proxying)

ConfigMap et Secret

Les ConfigMaps détiennent la config non sensible (chaînes ou fichiers) ; les Secrets les données sensibles (encodées base64 dans data, ou en clair dans stringData). Les deux se consomment via variables d'env (valueFrom) ou montés comme volumes. Les secrets ne sont PAS chiffrés par défaut — activez le chiffrement au repos et restreignez l'accès RBAC.

yaml
# ConfigMap — non-sensitive configuration
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  log_level: info
  max_connections: "100"
  config.yaml: |
    server:
      host: 0.0.0.0
      port: 8080
---
# Secret — sensitive data (base64-encoded)
apiVersion: v1
kind: Secret
metadata:
  name: app-secrets
type: Opaque
data:
  # base64-encoded values
  api_key: c2VjcmV0LWtleS0xMjM=   # echo -n 'secret-key-123' | base64
  db_password: cGFzc3dvcmQ=
# Or use stringData for plain text (auto-encoded):
# stringData:
#   api_key: secret-key-123

# Consumed by pods:
# env:
#   - name: API_KEY
#     valueFrom:
#       secretKeyRef:
#         name: app-secrets
#         key: api_key
# volumes:
#   - name: config
#     configMap:
#       name: app-config
16

Configuration CI/CD (GitHub Actions et GitLab CI)

Workflow GitHub Actions

Les workflows GitHub Actions vivent dans .github/workflows/. on: déclencheurs (push, PR, schedule, workflow_dispatch). Les jobs contiennent runs-on + steps. uses: référence des actions, run: exécute du shell. Les expressions utilisent la syntaxe ${{ }} — à échapper en \${{ }} dans les littéraux de template YAML.

yaml
# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm test
      - run: npm run build
        env:
          NODE_ENV: production

  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run lint

# ${{ }} is GitHub Actions expression syntax
# MUST be escaped as ${{ }} in YAML template literals
# (here we use literal text, no escaping needed)

Pipeline GitLab CI

GitLab CI vit dans .gitlab-ci.yml. Les stages définissent l'ordre du pipeline. Les jobs ont stage, image, script et beaucoup d'options (only/except, rules, when, artifacts, environment). Les variables utilisent la syntaxe $VAR (pas d'échappement requis dans les scalaires de bloc YAML). when: manual exige un clic pour déployer.

yaml
# .gitlab-ci.yml
stages:
  - test
  - build
  - deploy

variables:
  NODE_ENV: production
  IMAGE_TAG: $CI_COMMIT_SHORT_SHA

test:
  stage: test
  image: node:20
  script:
    - npm ci
    - npm test
  artifacts:
    reports:
      junit: test-results.xml
  coverage: '/Lines.*:\s(\d+\.\d+)\%/'

build:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  script:
    - docker build -t myapp:$IMAGE_TAG .
    - docker push myapp:$IMAGE_TAG
  only:
    - main

deploy:production:
  stage: deploy
  script:
    - ./deploy.sh
  environment:
    name: production
  only:
    - main
  when: manual   # require manual trigger

Builds matriciels

Les builds matriciels exécutent un job plusieurs fois avec des variables différentes. GitHub Actions utilise strategy.matrix avec include/exclude. GitLab utilise parallel.matrix. fail-fast: false empêche un échec d'annuler les frères. Utile pour les tests multi-plateformes et multi-versions. La syntaxe ${{ }} doit s'échapper dans les littéraux YAML.

yaml
# GitHub Actions matrix
jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node: [18, 20, 22]
        exclude:
          - os: windows-latest
            node: 18
        include:
          - os: ubuntu-latest
            node: 20
            experimental: true
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm ci
      - run: npm test

# GitLab CI matrix (parallel matrix):
# test:
#   image: node:${NODE_VERSION}
#   parallel:
#     matrix:
#       - NODE_VERSION: [18, 20, 22]
#         OS: [linux, macos]

Workflows réutilisables et includes

Les deux systèmes supportent la réutilisation. GitHub Actions utilise des workflows réutilisables (déclencheur workflow_call) invoqués avec uses:. GitLab utilise include (project, local, template, remote). La réutilisation réduit la duplication pour la logique CI partagée. Passez les inputs/secrets explicitement pour garder les workflows composables et auditables.

yaml
# GitHub Actions: reusable workflow
# .github/workflows/reusable.yml
on:
  workflow_call:
    inputs:
      node-version:
        required: true
        type: string
    secrets:
      token:
        required: true
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - run: npm ci
        env:
          TOKEN: ${{ secrets.token }}

# Caller:
# jobs:
#   build:
#     uses: ./.github/workflows/reusable.yml
#     with:
#       node-version: '20'
#     secrets:
#       token: ${{ secrets.MY_TOKEN }}

# GitLab CI: include
# include:
#   - project: 'ci/templates'
#     file: '/node.yml'
#   - local: '/.gitlab/extra.yml'
#   - template: Jobs/SAST.gitlab-ci.yml

Ancres dans les configs CI

Les ancres YAML réduisent la duplication dans les configs CI. GitLab CI les utilise fortement : définissez un job caché (.template) avec &ancre, puis <<: *ancre pour fusionner. GitHub Actions supporte les ancres mais les déconseille entre jobs (préférez les workflows réutilisables). Les ancres rendent les configs DRY mais plus dures à tracer — avec discernement.

yaml
# YAML anchors reduce duplication in CI configs
# GitLab CI commonly uses anchors

.default_template: &default_template
  image: node:20
  before_script:
    - npm ci
  cache:
    paths:
      - node_modules/

test:
  <<: *default_template
  script:
    - npm test

lint:
  <<: *default_template
  script:
    - npm run lint

build:
  <<: *default_template
  script:
    - npm run build
  artifacts:
    paths:
      - dist/

# GitHub Actions supports anchors too (since 2022):
# jobs:
#   base: &base
#     runs-on: ubuntu-latest
#     steps:
#       - uses: actions/checkout@v4
#   test:
#     uses: ./.github/workflows/reusable.yml
#   # Anchors across jobs are limited — prefer reusable workflows

Environnements et secrets

Les environnements GitHub Actions verrouillent les déploiements (approbation requise, restriction aux branches) et détiennent des secrets délimités à l'environnement. Les secrets se référencent via ${{ secrets.NAME }}. GitLab utilise des variables protégées (restreintes à des branches) et masquées (cachées des logs) définies dans l'UI. Ne loggez jamais de secrets — ils peuvent fuir dans la sortie d'erreur.

yaml
# GitHub Actions: environments & secrets
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production        # requires approval if configured
      url: https://app.example.com
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        run: ./deploy.sh
        env:
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
          API_TOKEN: ${{ secrets.API_TOKEN }}
          ENV: production

# Secret scopes:
# - Repository secrets: available to all workflows
# - Environment secrets: only when job uses that environment
# - Organization secrets: shared across repos

# GitLab CI: protected/masked variables
# variables:
#   # defined in UI: Settings > CI/CD > Variables
#   # - Protected: only on protected branches/tags
#   # - Masked: hidden in job logs
# deploy:
#   script:
#     - ./deploy.sh
#   environment:
#     name: production
#   only:
#     - main
17

Considérations de sécurité

Risques de désérialisation

La désérialisation YAML est dangereuse car des tags comme !!python/object/apply peuvent appeler des fonctions arbitraires. Le yaml.load() de PyYAML était non sûr par défaut avant 5.1 (exécution de code depuis une entrée non fiable). Utilisez toujours yaml.safe_load() pour les entrées non fiables — il rejette les tags d'instanciation d'objets. Les autres langages ont des dangers similaires (SnakeYAML, Psych).

yaml
# YAML deserialization can be DANGEROUS.
# Some loaders let YAML instantiate arbitrary objects.

# DANGEROUS (PyYAML < 5.1, default was unsafe):
# data = yaml.load(untrusted_input)
# An attacker can craft YAML that runs arbitrary code:
# !!python/object/apply:os.system ["rm -rf /"]

# Other dangerous tags:
# !!python/object/apply:...     # call any Python function
# !!python/object/new:...       # instantiate any class
# !ruby/object:...               # Ruby object instantiation
# !java/object:...               # Java (SnakeYAML)

# Safe loaders reject these tags by default.
# Modern PyYAML (>= 5.1): yaml.load() requires a SafeLoader
# yaml.safe_load() is ALWAYS safe.

# Rule of thumb:
# - NEVER use yaml.load() on untrusted input
# - ALWAYS use yaml.safe_load() (or full_load on trusted files)
# - Or use a schema-validated loader

safe_load vs load

Utilisez toujours safe_load (Python), safe_load (Ruby Psych) ou les schémas sûrs par défaut (js-yaml, Go yaml.v3). PyYAML 5.1+ exige un Loader explicite pour yaml.load(). full_load autorise les tags standard mais pas les objets arbitraires — seulement sur des fichiers de confiance. Les loaders sûrs rejettent tous les tags d'instanciation d'objets.

yaml
# Python (PyYAML) — the classic safe/unsafe distinction

# SAFE: safe_load rejects all custom tags
import yaml
data = yaml.safe_load(untrusted_yaml)   # ALWAYS use this

# SAFE: load with SafeLoader (explicit)
data = yaml.load(untrusted_yaml, Loader=yaml.SafeLoader)

# FULL (trusted files only): full_load allows standard tags
# but not arbitrary python objects
data = yaml.full_load(trusted_yaml)

# UNSAFE: UnsafeLoader allows !!python/object — DANGEROUS
data = yaml.load(untrusted_yaml, Loader=yaml.UnsafeLoader)  # NEVER on untrusted

# PyYAML 5.1+ requires Loader argument for yaml.load()
# (raises error without it) — safety improvement.

# Other languages:
# JS (js-yaml): yaml.load(str) uses DEFAULT_SAFE_SCHEMA
# Go (yaml.v3): no object instantiation (safe by design)
# Ruby (Psych): Psych.safe_load is the safe variant
# Java (SnakeYAML): SafeConstructor for safe loading

Exploits de tags locaux

Les tags custom (!include, !env, !file, !exec, !template) peuvent s'exploiter même sans !!python/object. Un !include lisant des fichiers peut se faire piéger pour lire /etc/passwd ou .ssh/id_rsa via du path traversal. Auditez chaque constructeur custom : validez les chemins contre des allowlists, refusez les chemins absolus et ../, sandboxez le loader.

yaml
# Even non-builtin tags can be exploited if your loader
# registers constructors that have side effects.

# Example: a "harmless" custom tag
# yaml.add_constructor('!include', include_file)
#
# If !include reads files from disk, an attacker can
# craft YAML to read sensitive files:
# config: !include /etc/passwd
# or:
# config: !include /etc/shadow
# or:
# config: !include ../../../.ssh/id_rsa

# Mitigation:
# 1. Validate the included path against an allowlist
# 2. Restrict !include to a specific directory
# 3. Refuse absolute paths and ../ traversal
# 4. Run the loader in a sandbox

# Other "innocent" tags that can be exploited:
# !env VAR_NAME        -> leaks env vars
# !exec "command"      -> arbitrary command execution
# !file /path          -> file disclosure
# !template <% ... %>  -> code injection

# Audit every custom constructor for side effects.

Billion Laughs et DoS

L'attaque Billion Laughs utilise des alias imbriqués pour expandre un minuscule document en gigaoctets de mémoire (10 alias par niveau, 5 niveaux = 10^9 références). Mitigez avec des limites de profondeur d'alias, des limites de taille totale, des parseurs en streaming et le rejet de l'imbrication excessive. Surveillez aussi l'imbrication profonde (débordement de pile) et les collections plates énormes.

yaml
# "Billion Laughs" attack — exponential expansion via aliases
a: &a ["lol","lol","lol","lol","lol","lol","lol","lol","lol","lol"]
b: &b [*a,*a,*a,*a,*a,*a,*a,*a,*a,*a]
c: &c [*b,*b,*b,*b,*b,*b,*b,*b,*b,*b]
d: &d [*c,*c,*c,*c,*c,*c,*c,*c,*c,*c]
e: &e [*d,*d,*d,*d,*d,*d,*d,*d,*d,*d]

# This 5-line document expands to ~10^9 string references
# consuming gigabytes of memory on parse.

# Mitigations:
# 1. Limit alias depth (some parsers do this)
# 2. Limit total parsed size / memory
# 3. Use a streaming parser for untrusted input
# 4. PyYAML has a limit but not all parsers do
# 5. Reject documents with excessive alias nesting

# Other DoS vectors:
# - Very deep nesting (parser stack overflow)
# - Huge flat sequences/mappings (memory)
# - Pathological number formats (regex backtracking)
# - Quadratic blowup via duplicate keys

# For untrusted input: set hard size + depth limits.

Validation des entrées

Validation en couches : (1) limite de taille, (2) safe_load pour rejeter les tags dangereux, (3) vérification de type (attendez un dict, pas une liste), (4) validation de schéma (JSON Schema, Pydantic, Cue), (5) validation de domaine (règles métier comme la plage de ports). Chaque couche attrape des attaques différentes. Ne faites jamais confiance à la structure — validez toujours avant usage.

yaml
# Layered defense for untrusted YAML input:

# 1. Size limit (reject oversized input)
MAX_SIZE = 1024 * 1024  # 1 MB
if len(input_text) > MAX_SIZE:
    raise ValueError("input too large")

# 2. Safe parser (rejects dangerous tags)
import yaml
try:
    data = yaml.safe_load(input_text)
except yaml.YAMLError as e:
    raise ValueError(f"invalid YAML: {e}")

# 3. Type check (expect a mapping, not a list)
if not isinstance(data, dict):
    raise ValueError("expected a mapping at top level")

# 4. Schema validation (JSON Schema, Pydantic, etc.)
from pydantic import BaseModel, ValidationError
class Config(BaseModel):
    host: str
    port: int = 8080
try:
    config = Config(**data)
except ValidationError as e:
    raise ValueError(f"schema validation failed: {e}")

# 5. Domain validation (business rules)
if config.port < 1 or config.port > 65535:
    raise ValueError("port out of range")

Recommandations de bibliothèques

Choisissez des bibliothèques sûres par défaut : PyYAML (safe_load), ruamel.yaml, js-yaml (sûr par défaut), Go yaml.v3, Psych.safe_load, SnakeYAML avec SafeConstructor, serde_yaml. Évitez yaml.load sans loader sûr explicite. Épinglez des versions récentes pour les correctifs de sécurité. Auditez les constructeurs custom. Lisez la doc de sécurité de la bibliothèque.

yaml
# Safe-by-default YAML libraries by language:

# Python:
#   - PyYAML >= 5.1 (yaml.safe_load)
#   - ruamel.yaml (safe by default, round-trip mode)
#   AVOID: yaml.load without explicit SafeLoader

# JavaScript/TypeScript:
#   - js-yaml (yaml.load uses DEFAULT_SAFE_SCHEMA)
#   AVOID: yaml.load with DEFAULT_FULL_SCHEMA on untrusted

# Go:
#   - gopkg.in/yaml.v3 (no object instantiation, safe)
#   AVOID: yaml.v2 has subtle differences, prefer v3

# Ruby:
#   - Psych (Psych.safe_load)
#   AVOID: YAML.load (uses unsafe loader in old Ruby)

# Java:
#   - SnakeYAML with SafeConstructor
#   AVOID: new Yaml() without SafeConstructor on untrusted
#   (SnakeYAML had CVEs from unsafe loading)

# Rust:
#   - serde_yaml (safe by design, no arbitrary types)

# General rule:
# - Read the library's security docs
# - Pin to a recent version (security patches)
# - Use safe_load / SafeConstructor / safe schema
# - Audit custom constructors for side effects
18

Bonnes pratiques

Indentation cohérente

Utilisez 2 espaces de façon cohérente (le standard de facto), jamais de tabulations. Configurez votre éditeur pour insérer des espaces pour le YAML. Utilisez des formateurs (prettier, yamlfixer) et des linters (yamllint) pour imposer la cohérence. Une indentation incohérente est l'erreur YAML la plus courante et casse le parsing.

yaml
# Use 2 spaces for indentation (most common)
# NEVER use tabs (YAML forbids them)

# GOOD
server:
  host: localhost
  port: 8080
  routes:
    - path: /api
      handler: apiHandler
    - path: /web
      handler: webHandler

# BAD (inconsistent)
# server:
#    host: localhost
#   port: 8080      # wrong indent

# Configure your editor:
# VS Code: "[yaml]": {"editor.insertSpaces": true, "editor.tabSize": 2}
# Vim:     autocmd FileType yaml setlocal ts=2 sts=2 sw=2 expandtab
# Emacs:   (add-hook 'yaml-mode-hook
#           (lambda () (setq yaml-indent-offset 2)))

# Use a formatter:
# prettier (with yaml plugin) normalizes indentation
# yamllint checks it
# yamlfixer auto-fixes issues

Stratégie de quoting

Quotter les chaînes ressemblant à des nombres, booléens, null ou dates ; contenant deux-points/virgules/caractères spéciaux ; ou commençant par des indicateurs (- ? : * & ! | > ' " % @). Sinon préférez le simple (non quoté) pour la lisibilité. Utilisez les doubles guillemets pour les séquences d'échappement (\n, \t), les simples pour les chaînes littérales avec apostrophes.

yaml
# Quote strings when:
# 1. They look like another type (number, bool, null, date)
version: "1.0"        # string, not float
answer: "yes"         # string, not bool (1.1)
region: "no"          # string "no", not False (1.1)
date: "2024-01-01"    # string, not date
phone: "555-1234"     # string, not number

# 2. They contain special characters
url: "https://example.com:8080"   # colon
list: "a, b, c"                    # comma
expr: "value:with:colons"          # colons

# 3. They start with special indicators (-, ?, :, *, &, !, |, >, ', ", %, @, `)
flag: "-not-a-list"
key: "?not-a-complex-key"

# Don't quote otherwise — plain is more readable
name: Alice            # no quotes needed
path: /usr/local/bin   # no quotes needed

# Prefer double quotes for escapes (\n, \t)
# Prefer single quotes for literal strings with apostrophes
greeting: "Hello\nWorld"
possessive: 'Alice''s car'

Éviter les tabulations et autres pièges

Évitez les pièges courants : tabulations (interdites — utilisez des espaces), yes/no/on/off non quotés (ambiguïté 1.1 vs 1.2), chaînes non quotées avec deux-points, espaces finaux, fins de ligne CRLF (utilisez LF), BOM (sauvegardez en UTF-8 sans BOM) et lignes très longues (repliez avec des scalaires de bloc). Un linter attrape la plupart.

yaml
# Pitfall 1: tabs for indentation (FORBIDDEN)
# Configure editor to use spaces

# Pitfall 2: yes/no/on/off as strings (1.1 vs 1.2)
# Always quote: "yes", "no", "on", "off"

# Pitfall 3: unquoted strings with colons
# bad:  url: http://x:8080
# good: url: "http://x:8080"

# Pitfall 4: trailing whitespace
# Some parsers are strict; linters always flag it
key: value   # <- no trailing spaces

# Pitfall 5: Windows line endings (CRLF)
# Use LF (\n) only — CRLF can cause subtle issues
# .gitattributes: *.yaml text eol=lf

# Pitfall 6: BOM at start of file
# Save as UTF-8 without BOM

# Pitfall 7: very long lines
# Wrap with block scalars or flow style
description: >
  This is a long description that wraps
  across multiple lines for readability.

# Pitfall 8: inconsistent key ordering
# Group related keys, be consistent

Épinglage de version et doc de schéma

Épinglez la version YAML avec %YAML 1.2 si les différences 1.1 vs 1.2 comptent. Documentez votre schéma : champs requis/optionnels, types, défauts, plages — dans les commentaires, un fichier JSON Schema ou un README. Épinglez les versions de schéma dans le code pour que la validation de config soit reproductible. Cela réduit la friction d'intégration et les erreurs de config.

yaml
# Pin the YAML version if it matters
%YAML 1.2
---
key: value

# Document your schema expectations in comments:
# Required fields:
#   - host: string (hostname or IP)
#   - port: integer (1-65535)
# Optional fields:
#   - tls: boolean (default: false)
#   - cert: string (path, required if tls: true)

config:
  host: example.com
  port: 443
  tls: true
  cert: /etc/ssl/cert.pem

# Or use a JSON Schema file (config.schema.json)
# and reference it from your docs / CI:
# "Validated against schema v1.2; see config.schema.json"

# For libraries, document the schema in the README:
# ## Configuration
# The config.yaml file must contain:
# - host (str, required)
# - port (int, required, 1-65535)
# - tls (bool, optional, default: false)

# Pin schema versions in code:
# CONFIG_SCHEMA_VERSION = "1.2"
# validate(data, schema_v1_2)

Lint en CI

Branchez le lint YAML dans la CI (GitHub Actions, GitLab CI) et les hooks pre-commit. Utilisez yamllint pour la syntaxe/style et prettier pour le formatage. L'intégration éditeur (extension YAML de VS Code, yaml-language-server) fournit lint inline et validation de schéma. Attraper les erreurs YAML en CI coûte bien moins qu'en production.

yaml
# .github/workflows/lint.yml
name: Lint YAML
on: [push, pull_request]
jobs:
  yamllint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install yamllint
        run: pip install yamllint
      - name: Lint
        run: yamllint -s .

# GitLab CI:
# yamllint:
#   image: python:3.12
#   script:
#     - pip install yamllint
#     - yamllint -s .

# Pre-commit hook (.pre-commit-config.yaml):
# repos:
#   - repo: https://github.com/adrienverge/yamllint
#     rev: v1.35.1
#     hooks:
#       - id: yamllint
#         args: [-s, --config-file, .yamllint.yml]
#   - repo: https://github.com/pre-commit/mirrors-prettier
#     rev: v3.1.0
#     hooks:
#       - id: prettier
#         types: [yaml]

# Editor integration:
# VS Code: install "YAML" extension (redhat)
#   + "yamllint" for inline linting
#   + schema validation via yaml-language-server

Structure et lisibilité

Groupez les clés liées avec des en-têtes de commentaires. Gardez l'imbrication peu profonde (3-4 niveaux max) — le YAML profondément imbriqué est dur à lire. Utilisez les ancres pour des valeurs réellement réutilisées. Utilisez les scalaires de bloc pour les chaînes multi-lignes. Gardez les lignes sous 120 caractères. La lisibilité compte car ce sont des humains qui éditent le YAML.

yaml
# Group related keys; use comments to delineate sections
server:
  # Networking
  host: 0.0.0.0
  port: 8080
  tls:
    enabled: true
    cert: /etc/ssl/cert.pem

  # Limits
  timeout: 30
  max_connections: 100
  retries: 3

# Keep nesting shallow (3-4 levels max)
# Deeply nested YAML is hard to read and edit.

# If a value is reused, use an anchor:
defaults: &defaults
  timeout: 30
  retries: 3

prod:
  <<: *defaults
  env: production

staging:
  <<: *defaults
  env: staging

# Use block scalars for multi-line values
script: |
  #!/bin/bash
  set -e
  echo "deploying"

# Keep lines under 120 chars; wrap with block scalars or
# multi-line flow style.
19

Fonctionnalités avancées

Clés de mapping complexes

L'indicateur ? marque une clé complexe (un mapping ou une séquence utilisée comme clé). Utile pour des tables de lookup (ex. tarification par région+instance). Précaution : beaucoup de sérialiseurs ne préservent pas les clés complexes et peuvent les stringifier en sortie. La plupart des fichiers de config restent sur des clés de chaînes simples pour la simplicité et la compatibilité des outils.

yaml
# Use ? to mark a complex (non-scalar) key
? apple
: red fruit

? orange
: orange fruit

# A mapping as a key
? host: localhost
  port: 8080
: connection_string

# A sequence as a key
? [us-east-1, t2.micro]
: 0.0116
? [us-east-1, t2.small]
: 0.023
? [us-west-2, t2.micro]
: 0.0125

# Useful for lookup tables
pricing:
  ? [production, large]
  : 100
  ? [production, small]
  : 50
  ? [development, large]
  : 20

# In flow style:
{[a, b]: value, {x: 1}: other}

# Caveat: many serializers don't preserve complex keys
# and may convert them to strings on output.

Sets (!!set)

Un set YAML (!!set) est un mapping où les clés sont les éléments et les valeurs null. Certains parseurs le mappent vers un type Set natif. À utiliser pour déclarer des collections uniques (rôles, permissions). Précaution : JSON n'a pas de type Set, donc la conversion JSON produit un objet avec valeurs null. Tous les sérialiseurs ne préservent pas le tag !!set.

yaml
# A set is a mapping with null values
# Use the !!set tag for clarity
permissions: !!set
  ? read
  ? write
  ? execute

# Equivalent to:
permissions:
  read: null
  write: null
  execute: null

# Or in flow style:
flags: !!set { red, green, blue }

# Parsers may map this to a native Set type:
# Python: set() (PyYAML with !!set constructor)
# Ruby: Set (Psych)
# JavaScript: depends on library

# Use case: declare a unique collection
roles: !!set
  ? admin
  ? editor
  ? viewer

# Caveat: JSON has no Set type, so JSON conversion
# usually produces an object with null values.

Mappings ordonnés (!!omap)

!!omap (mapping ordonné) est une séquence de mappings à clé unique qui préserve l'ordre d'insertion. Utile pour des timelines, préférences ordonnées ou quand l'ordre compte sémantiquement. Les parseurs modernes préservent de toute façon l'ordre des mappings ordinaires (dict Python 3.7+, Hash Ruby), mais les maps Go sont aléatoires — !!omap y rend l'ordre explicite.

yaml
# An ordered mapping preserves key order
# Use !!omap tag
timeline: !!omap
  - 2024-01-01: event A
  - 2024-02-01: event B
  - 2024-03-01: event C

# Equivalent representation as a list of single-key mappings:
# timeline:
#   - 2024-01-01: event A
#   - 2024-02-01: event B
#   - 2024-03-01: event C

# Parsers may map this to:
# Python: list of tuples, or OrderedDict
# Ruby: Array of one-key hashes (or OrderedDict)
# Go: ordered map (with custom type)

# Use case: ordered key-value pairs where order matters
# - event timelines
# - ordered preferences
# - step-by-step configurations

# Caveat: regular YAML mappings DO preserve order in
# most modern parsers (Python dict 3.7+, Ruby Hash,
# Go map iteration is random though). !!omap makes the
# intent explicit and works even where maps are unordered.

Données binaires (!!binary)

!!binary encode des données binaires en base64 dans le YAML. Les parseurs les décodent en octets natifs (bytes Python, chaîne ASCII-8BIT Ruby). Utile pour embarquer de petites images ou icônes directement. Pour les données binaires volumineuses, préférez référencer par chemin ou URL. Le base64 multi-lignes marche avec les scalaires de bloc folded (>) ou literal (|).

yaml
# Encode binary data as base64 with !!binary tag
image: !!binary "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9
  awAAAABJRU5ErkJggg=="

# Multi-line base64 (folded or literal works)
data: !!binary |
  iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42m
  k+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==

# Parsers decode to bytes:
# Python: bytes object
# Ruby: ASCII-8BIT string
# JavaScript: depends on library (often base64 string)

# Use case: embed small images, icons, or other binary
# directly in YAML config

# For larger binary data, prefer:
# - Reference by path:  image: /path/to/image.png
# - Reference by URL:   image: https://example.com/img.png
# - Store separately and link

# Verify with:
# python -c 'import yaml; d=yaml.safe_load(open("f.yaml")); print(len(d["image"]))'

Constructeurs personnalisés

Enregistrez des constructeurs custom pour mapper des tags (!money) vers des objets natifs. Utilisez add_constructor avec un loader de portée SafeLoader. Les constructeurs reçoivent le loader et le nœud ; utilisez construct_scalar/mapping/sequence pour lire la valeur du nœud. Auditez toujours les constructeurs pour leurs effets de bord (lectures de fichiers, appels de sous-processus) — ils peuvent s'exploiter via des entrées non fiables.

yaml
# PyYAML: register a constructor for a custom tag
import yaml

class Money:
    def __init__(self, currency, amount):
        self.currency = currency
        self.amount = amount
    def __repr__(self):
        return f"Money({self.currency} {self.amount})"

def money_constructor(loader, node):
    value = loader.construct_scalar(node)  # "USD 19.99"
    currency, amount = value.split()
    return Money(currency, float(amount))

# Register the constructor (use SafeLoader scope)
yaml.add_constructor('!money', money_constructor, Loader=yaml.SafeLoader)

# Now this YAML parses to a Money object:
# price: !money "USD 19.99"
config = yaml.safe_load("price: !money \"USD 19.99\"")
print(config['price'])  # Money(USD 19.99)

# Multi-argument constructors use construct_mapping or
# construct_sequence depending on the node kind.

# SECURITY: audit every constructor for side effects.
# A constructor that calls open(), os.system(), or
# subprocess can be exploited via untrusted input.

Fonctionnalités YAML 1.2 et futur

YAML 1.2 a fait de JSON un sous-ensemble strict, restreint les booléens à true/false et adopté 0o pour l'octal. La clé de fusion << a été retirée de la spécification cœur mais reste largement supportée. YAML 1.2.2 (2021) a clarifié la spécification ; 1.3 est en développement. Préparez le futur en épinglant la version, quottant les chaînes ambiguës et considérant Cue/Dhall/Jsonnet pour la config complexe.

yaml
# YAML 1.2 (2009, current spec) key changes from 1.1:
# - JSON is a strict subset
# - Booleans: only true/false (not yes/no/on/off)
# - Octal: 0o prefix (not leading 0)
# - Removed sexagesimal numbers
# - Removed merge key << from core spec (still widely supported)

# YAML 1.3 (in development) aims to:
# - Clarify ambiguous parts of 1.2
# - Standardize error reporting
# - Improve interoperability between parsers
# - Possibly restore some 1.1 features as optional

# YAML 1.2.2 (2021 update, spec revision):
# - Clarified type resolution
# - Better-defined core schema
# - Improved examples
# - No breaking changes

# Recommended practices for future-proofing:
# 1. Pin %YAML 1.2 in critical files
# 2. Quote ambiguous strings (yes/no, leading-zero numbers)
# 3. Avoid relying on << merge key for new formats
#    (or document that you depend on it)
# 4. Use JSON-compatible subset when interop matters
# 5. Watch for YAML 1.3 adoption in your parser

# Some tools (Cue, Dhall, Jsonnet) extend/replace YAML
# for complex configuration — consider them for new
# projects with advanced needs.

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.