Valider du YAML avec JSON Schema : le garde-fou des fichiers de config
L’essentiel : Un fichier YAML qui parse sans erreur n'est pas un fichier correct : country: NO n'est pas une chaîne pour un parseur YAML 1.1, et version: 1.10 devient silencieusement le flottant 1.1. Ce guide explique pourquoi JSON Schema peut valider le YAML, les voies CLI et éditeur pour le mettre en place, comment un schéma aurait intercepté le vrai incident du code pays norvégien, et les trois limites de la validation par schéma.

Conclusion : YAML 1.2 est un sur-ensemble strict de JSON, donc JSON Schema valide la structure de données après parsing, pas le format du fichier — écrivez le schéma une fois et il couvre les données JSON comme YAML. C'est exactement pourquoi il peut intercepter les incidents où le parseur change silencieusement un type.
Un
yaml.safe_loadsans erreur prouve que le fichier est du YAML légal. Il ne prouve pas quecountry: NOest encore une chaîne — sous un parseur YAML 1.1, c'est devenufalsebien avant que votre code ne le voie.
Un : parser sans erreur ≠ config correcte — un incident réel d'abord
Une équipe e-commerce a ajouté la Norvège à ses pays de livraison : une ligne, NO, ajoutée à une liste dans un group_vars Ansible. Revu, validé, déployé. Une semaine plus tard, zéro commande norvégienne — le fichier JSON sur les serveurs contenait "DK", false, "SE". Ansible parse ses fichiers de variables avec PyYAML, un parseur YAML 1.1 : NO était le booléen false dès la lecture du fichier, et le filtre to_json l'a fidèlement écrit. Le template s'est rendu, le JSON était valide, rien ne s'est plaint — seul le service checkout continuait de refuser chaque client norvégien car NO n'était pas dans la liste.
Le point commun de ces incidents : tous les outils syntaxiques sont au vert alors que la couche données est déjà fausse. Le tableau ci-dessous montre la dérive de types mesurée avec PyYAML 6.0.3 ; les parseurs YAML 1.2 n'en corrigent qu'une partie :
| Vous écrivez | YAML 1.1 lit | YAML 1.2 lit | Vous vouliez |
|---|---|---|---|
country: NO |
false |
"NO" |
"NO" |
version: 1.10 |
flottant 1.1 |
flottant 1.1 |
"1.10" |
zip: 02134 |
octal 1116 |
décimal 2134 |
"02134" |
mode: 0755 |
décimal 493 |
décimal 755 |
493 ou "0755" |
ports: ["22:22"] |
sexagésimal 1342 |
"22:22" |
"22:22" |
Le remède de fond est de mettre des guillemets autour de toute chaîne qui ressemble à du code. Mais les guillemets reposent sur la mémoire humaine ; un schéma repose sur la vérification par la machine — voilà pourquoi le YAML mérite un JSON Schema.
Deux : pourquoi JSON Schema peut gouverner le YAML
La spécification YAML 1.2 le dit clairement : le premier objectif de la 1.2 était de faire de YAML un sur-ensemble strict de JSON, et un parseur 1.2 lit le JSON ordinaire sans modification. Les deux formats parse dans les mêmes structures de données, donc l'extension du fichier est sans signification pour un validateur. Le pipeline entier tient en trois étapes :
- Parser le fichier YAML en objets/tableaux ;
- Charger le JSON Schema ;
- Valider les données contre le schéma — erreurs ou passage.
Notez que l'étape un n'exige pas de sérialiser le YAML en texte JSON puis de le parser à nouveau ; la bibliothèque YAML de votre langage passe directement la structure au validateur. Le schéma lui-même peut aussi s'écrire en YAML (yq -P schema.json > schema.yaml convertit en une commande), mais le garder en JSON est le choix le plus sûr : la compatibilité des outils est meilleure et tous les schémas du catalogue schemastore.org sont en JSON.
Trois : trois voies CLI qui fonctionnent dès aujourd'hui
Prenons un config.yaml où le schéma exige name et version, impose une forme semver et des countries en tableau de chaînes de deux lettres majuscules :
# config.yaml
name: checkout
version: "1.4.2"
countries:
- DK
- NO
- SE
Python (jsonschema + PyYAML) :
import json, yaml
from jsonschema import validate
data = yaml.safe_load(open("config.yaml", encoding="utf-8"))
schema = json.load(open("schema.json", encoding="utf-8"))
validate(instance=data, schema=schema)
Node (js-yaml + Ajv) :
import Ajv from "ajv";
import yaml from "js-yaml";
import fs from "fs";
const schema = JSON.parse(fs.readFileSync("schema.json", "utf8"));
const data = yaml.load(fs.readFileSync("config.yaml", "utf8"));
const validate = new Ajv().compile(schema);
if (!validate(data)) console.error(validate.errors);
Pipeline pur (yq + ajv-cli) :
yq -o=json config.yaml | ajv validate -s schema.json -d -
# Ou check-jsonschema, qui consomme le YAML directement
pip install check-jsonschema
check-jsonschema --schemafile schema.json config.yaml
Les trois voies ne diffèrent qu'à l'étape de parsing : les deux premières sont explicites en deux lignes, le pipeline passe en un flux, et check-jsonschema fait la conversion YAML→JSON en interne. Le fichier de schéma est le même pour les trois.
Quatre : validation en temps réel dans l'éditeur : modeline et SchemaStore
L'extension YAML de Red Hat (basée sur yaml-language-server) compte environ 30 millions d'installations sur VS Code et supporte JSON Schema draft-04/07/2019-09/2020-12. Trois façons de la brancher :
# Option 1 : la modeline — la première ligne du fichier pointe vers le schéma
# yaml-language-server: $schema=./schema.json
name: checkout
// Options 2 et 3 : .vscode/settings.json, par nom de fichier ou glob
{
"yaml.schemas": {
"./schema.json": ["config/*.yaml", "*.config.yaml"],
"https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml"
}
}
yaml.schemaStore.enable est actif par défaut : les fichiers courants comme package.json, les workflows GitHub ou docker-compose sont associés automatiquement au catalogue schemastore.org, sans aucune configuration. Les champs description du schéma deviennent des aides à la complétion et des infobulles, et les propriétés required manquantes sont soulignées en rouge — les erreurs de config passent de « débogage après déploiement » à « l'instant où vous tapez ». Cela explique aussi pourquoi c'est SchemaStore plutôt qu'une « norme de schéma YAML » : YAML n'a pas de standard officiel de schéma, et JSON Schema est le standard de facto.
Cinq : comment un schéma aurait intercepté le problème norvégien
Revenons à l'incident NO de la première section. Donnons à countries un schéma au niveau des éléments :
{
"type": "object",
"required": ["name", "version", "countries"],
"properties": {
"countries": {
"type": "array",
"items": { "type": "string", "pattern": "^[A-Z]{2}$" }
}
}
}
Le false produit par PyYAML n'est pas une chaîne, donc type: string échoue immédiatement ; même si un parseur l'avait lu comme "no" en minuscules, le pattern le bloque. Pour aller plus loin, ajoutez une liste blanche enum. Le même schéma tourne en CI via les voies CLI de la section trois et dans l'éditeur via la modeline de la section quatre — un seul contrat aux deux bouts.
La division du travail avec yamllint mérite une phrase : la règle truthy de yamllint (seuls true/false acceptés, toute orthographe booléenne signalée) gouverne le style d'écriture et intercepte flag: yes à la couche lint ; JSON Schema gouverne la forme des données, quel que soit le parseur. L'équipe de l'incident a fini par adopter les trois : guillemets sur les chaînes, yamllint truthy dans le pipeline, et assertion de chaînes à deux lettres dans le template. Les deux couches de défense ne se recouvrent pas ; elles se complètent.
Six : validation en lot des manifestes Kubernetes
L'API Kubernetes est elle-même décrite en OpenAPI, et le projet kubernetes-json-schema la convertit en JSON Schema standard. Kubeconform utilise ce registre pour la validation en lot : sur un portable 4 cœurs, 35 139 fichiers et 50 714 ressources avec kubeconform -ignore-missing-schemas -n 8 -summary terminent en 6,7 secondes, contre 35 secondes pour kubeval sur la même tâche. Le geste Helm standard est de rendre d'abord, valider ensuite :
helm template my-app ./charts/my-app > rendered.yaml
kubeconform -strict -summary -kubernetes-version 1.28.0 rendered.yaml
-strict rejette les champs non définis par le schéma (les coquilles se voient tôt) ; les ressources CRD peuvent être ignorées avec -ignore-missing-schemas ou servir d'un registre personnalisé via -schema-location.
Sept : ce que la validation par schéma ne peut pas faire : trois limites
- La dérive de version du parseur se produit au niveau du parsing. Le schéma voit le résultat du parsing : le
NOlu par PyYAML est déjàfalse, et le schéma ne peut qu'enfermer cette valeur erronée avectype/pattern. Le remède de fond reste les guillemets ; n'attendez pas d'un schéma qu'il répare un parseur. - Les erreurs logiques sont hors périmètre. Un selector mal orthographié ou un selector K8s pointant vers un label inexistant — le schéma connaît les formes, pas la sémantique. Cela relève des admission webhooks, des politiques OPA ou de
kubectl apply --dry-run=server. - Les clés dupliquées gagnent silencieusement. Beaucoup de parseurs YAML acceptent les clés dupliquées sans avertissement (la dernière gagne), donc le schéma reçoit des données qui ont déjà perdu une clé. La règle
key-duplicatesde yamllint ou des hooks de parsing restent les détecteurs.
Checklist avant déploiement : mettre des guillemets sur les chaînes de type code → lancer yamllint (truthy + key-duplicates) → validation JSON Schema à la fois en CI et dans l'éditeur → pour les ressources cluster, passer aussi --dry-run=server. Avec ces quatre étapes, l'incident norvégien de la section un ne survit pas à la deuxième étape du pipeline.
FAQ
JSON Schema peut-il valider directement des fichiers YAML ?
Oui — mais il valide les données dans lesquelles le fichier parse, pas le fichier lui-même. YAML 1.2 est un sur-ensemble strict de JSON, les deux parse dans les mêmes structures, donc un seul schéma sert au JSON comme au YAML. Choisissez l'une des quatre voies — Python, Node, le pipeline yq ou check-jsonschema — sans convertir les formats à la main.
Qu'est-ce que SchemaStore et comment l'utiliser ?
schemastore.org est un catalogue de JSON Schemas (catalog.json) regroupant les schémas de centaines de fichiers de config courants : package.json, workflows GitHub, docker-compose, etc. Les éditeurs avec support YAML/JSON associent automatiquement les fichiers à ce catalogue, ou vous pouvez mapper les URL manuellement dans yaml.schemas. Vous pouvez aussi soumettre le schéma de votre propre projet au catalogue.
yamllint et JSON Schema se recouvrent-ils ?
Non. yamllint vérifie le style d'écriture (indentation, longueur de ligne, truthy, clés dupliquées) au niveau texte ; JSON Schema vérifie la structure des données (types, required, enums, patterns) au niveau données. La liste de correctifs de l'incident norvégien a utilisé les deux : la règle truthy intercepte les orthographes comme flag: yes, tandis que le schéma intercepte un false qui s'est retrouvé dans un tableau de chaînes.
Pour Kubernetes : kubeconform ou kubectl dry-run ?
Deux métiers différents. Kubeconform est hors ligne et en lot, sans cluster, et a sa place en CI pour attraper les erreurs structurelles ; dry-run=server parle à un vrai serveur d'API et révèle les problèmes d'admission webhook et de quotas, mais exige l'accès au cluster. La combinaison standard : kubeconform en CI, puis un passage --dry-run=server avant le déploiement — gardez les deux couches.
Après avoir écrit votre schéma, collez le JSON converti depuis votre YAML dans l'outil de validation JSON en ligne pour voir les erreurs d'abord ; pour écrire les mots-clés du schéma, voir le guide JSON Schema ; pour garder un schéma surveillé par des tests en CI, lisez le test de contrat JSON Schema ; pour la conversion quotidienne JSON↔YAML, utilisez le convertisseur JSON YAML XML.