Formateur YAML : formater, ré-indenter et valider du YAML

YAML est sensible aux espaces, donc une tabulation égarée ou une indentation incohérente ne fait pas que désordonner —— elle change le sens ou casse le parsing. Un formateur YAML corrige ça : il ré-indente ton YAML à une profondeur cohérente, normalise l'espacement, et (optionnellement) trie les clés, pour que le fichier soit lisible et produise des diffs propres. Ce guide explique ce que fait un formateur YAML, les règles d'indentation qu'il impose, les pièges de typage à surveiller, et quand formater du YAML versus le convertir en JSON.

Ce que fait un formateur YAML

Un formateur parse ton YAML en une structure de données et le re-sérialise avec un style cohérent. Les données ne changent pas —— seule la présentation est normalisée :

• Ré-indente chaque niveau à une largeur fixe (couramment 2 espaces) et remplace les tabulations par des espaces
• Normalise l'espacement autour des deux-points, des tirets de liste et des collections inline
• Trie optionnellement les clés pour un ordre canonique propice aux diffs
• Valide en effet de bord —— s'il ne peut pas parser, tu as une erreur de syntaxe à corriger d'abord

# Avant —— indentation mélangée, difficile à scanner
server:
    host: api.example.com
    ports:
    - 8080
    - 8443
database: {name: mydb, pool: 5}

# Après —— indent à 2 espaces, normalisé
server:
  host: api.example.com
  ports:
    - 8080
    - 8443
database:
  name: mydb
  pool: 5

Pourquoi formater YAML

• Lisibilité —— pipelines de CI, manifestes Kubernetes et fichiers Docker Compose sont profondément imbriqués ; une indentation cohérente les rend lisibles.
• Diffs et reviews propres —— une mise en forme normalisée (et des clés triées) veut dire qu'une pull request ne montre que les vrais changements, pas du bruit d'espaces.
• Détecter les erreurs tôt —— le formatage ne réussit que sur du YAML valide, donc un formateur sert aussi de check rapide de validité.
• Cohérence dans une équipe —— un seul style appliqué automatiquement, plutôt que les habitudes d'indentation de chaque auteur.

Les règles d'indentation qu'un formateur impose

La plupart des erreurs YAML sont des erreurs d'indentation, et c'est exactement ce qu'un formateur standardise :

• Espaces uniquement —— jamais de tabulations. YAML interdit les caractères tab pour l'indentation. Une seule tabulation est le bug YAML le plus commun du « pourquoi ça ne parse pas ? ».
• Profondeur cohérente. Les clés sœurs doivent être indentées du même nombre d'espaces par rapport à leur parent. Un formateur réécrit tout à une largeur fixe.
• Alignement des listes. Les éléments d'une séquence de bloc (-) s'alignent sous leur clé ; un formateur normalise si le tiret est indenté ou à fleur.

Pièges de typage à la reformatage

Le formatage préserve les données, mais l'inférence de types de YAML peut quand même te surprendre quand les valeurs ne sont pas entre guillemets —— à savoir avant de faire confiance à la sortie :

• Le « Norway problem ». Sans guillemets, NO, yes, on, off peuvent être lus comme des booléens, donc le code pays NO devient false. Mets des guillemets autour de ces valeurs pour les garder en chaînes.
• Zéros en tête et grands nombres.007 peut perdre ses zéros s'il est lu comme un nombre ; de très grands entiers peuvent perdre en précision. Mets des guillemets aux IDs qui doivent rester des chaînes.
• Dates et timestamps. Certains parsers convertissent les chaînes sans guillemets ressemblant à des dates en types timestamp. Mets des guillemets si tu veux la chaîne littérale.

Style bloc vs style flow

YAML a deux façons d'écrire des collections : bloc (indenté, orienté lignes) et flow (inline, façon JSON avec [] / {}) :

# bloc
ports:
  - 80
  - 443

# flow (mêmes données)
ports: [80, 443]

Les formateurs normalisent typiquement vers le style bloc pour la lisibilité. Le style flow est compatible JSON —— utile pour intégrer du YAML dans des outils qui ne parsent que du JSON —— mais plus difficile à lire quand l'imbrication grandit.

Anchors et alias : extraits réutilisables

& marque un anchor ; * le référence. Utile pour partager de la config entre services sans copier-coller, et les formateurs les préservent :

defaults: &defaults
  retries: 3
  timeout: 30
api:
  <<: *defaults
  url: https://api.example.com
worker:
  <<: *defaults
  url: https://worker.example.com

Note : les anchors et alias disparaissent quand tu convertis en JSON —— JSON n'a pas de type référence, donc les valeurs sont inlinées. Un round-trip YAML → JSON → YAML les perd.

Lint au-delà du parsing : yamllint

Un formateur normalise la forme ; yamllint impose un guide de style (longueur de ligne, ordre des clés, marqueurs de début de document, valeurs truthy, espacement de commentaires). Combine-les en CI : formate d'abord, puis lint avec les règles choisies par ton équipe.

Formater YAML vs convertir en JSON

Formater garde le fichier en YAML —— mieux quand des humains continueront à l'éditer. Convertir en JSON est pour quand un programme doit le consommer (la plupart des apps ne parsent que du JSON à l'exécution). Comme YAML 1.2 est un sur-ensemble strict de JSON, la conversion est sans perte pour les données ; voir Convertir YAML en JSON et JSON vs YAML pour quand utiliser chacun.

Formater et valider YAML dans ton navigateur

Colle ton YAML dans le validateur et formateur YAML de fixjson et clique sur Format YAML pour le ré-indenter et le normaliser, ou To JSON pour convertir. Il rapporte la ligne exacte de toute erreur de syntaxe, et tout tourne dans ton navigateur —— pas d'upload —— ce qui compte pour des fichiers de config qui contiennent des hosts, secrets ou paramètres internes.

Foire aux questions

Que fait un formateur YAML ?

Il parse ton YAML et le re-sérialise avec indentation et espacement cohérents (et optionnellement clés triées), pour que le fichier soit lisible et propice aux diffs. Les données ne changent pas —— seule la mise en forme est normalisée.

Pourquoi mon YAML échoue-t-il au parsing ?

Presque toujours l'indentation : un caractère tab (YAML interdit les tabs pour l'indentation) ou des clés sœurs à des profondeurs incohérentes. Un formateur réécrit tout à une largeur unique en espaces, ce qui fait remonter et corrige la plupart de ces cas.

Formater du YAML change-t-il mes données ?

Non —— il ne change que les espaces et l'ordre des clés. Attention aux valeurs sans guillemets : YAML peut inférer des types (le « Norway problem »), donc mets des guillemets autour des valeurs comme NO ou 007 qui doivent rester des chaînes.

Dois-je formater du YAML ou le convertir en JSON ?

Formate quand des humains continuent à éditer le fichier ; convertis en JSON quand un programme le consomme. Beaucoup d'équipes écrivent du YAML et convertissent en JSON au chargement.

Outils & guides liés

• Validateur & formateur YAML —— formate, valide et convertis du YAML dans ton navigateur
• Convertir YAML en JSON —— la conversion et les pièges d'indentation
• JSON vs YAML —— différences et quand utiliser chacun
• Comment formater du JSON —— l'équivalent JSON