Validace YAML pomocí JSON Schema: pojistka konfiguračních souborů
Shrnutí: YAML soubor, který se parsuje bez chyb, není správný soubor: country: NO není pro parser YAML 1.1 řetězec a version: 1.10 se potichu změní na číslo 1.1. Tato příručka vysvětluje, proč může JSON Schema validovat YAML, funkční CLI a editor postupy, jak by schema zachytilo skutečný incident s norským kódem země, a tři omezení validace podle schématu.

Závěr: YAML 1.2 je úplná nadmnožina JSON, takže JSON Schema validuje datovou strukturu po parsování, nikoli formát souboru — napište schema jednou a pokryje data JSON i YAML. Právě proto dokáže zachytit incidenty, kdy parser potichu změní typ.
yaml.safe_loadbez chyb dokazuje jen to, že soubor je legální YAML. Nedokazuje, žecountry: NOje stále řetězec — pod parserem YAML 1.1 je to užfalsedlouho předtím, než ho váš kód uvidí.
Jedna: parsování bez chyb ≠ správná konfigurace — nejdřív skutečný incident
Tým e-commerce přidal Norsko mezi země dodání: jediný řádek, NO, v seznamu v group_vars Ansible. Zrecenzováno, zvalidováno, nasazeno. O týden později: nula norských objednávek — JSON soubor na serverech obsahoval "DK", false, "SE". Ansible parsuje soubory proměnných přes PyYAML, parser YAML 1.1: NO se stalo logickou hodnotou false už při čtení souboru a filtr to_json to věrně zapsal. Šablona se vyrenderovala, JSON byl validní, nikdo si nestěžoval — jen služba checkout dál odmítala každého norského zákazníka, protože NO nebylo v seznamu.
Společné pro tyto incidenty: všechny syntaktické nástroje svítí zeleně, zatímco datová vrstva je už špatná. Tabulka níže ukazuje drift typů naměřený na PyYAML 6.0.3; parsery YAML 1.2 opraví jen část:
| Napíšete | YAML 1.1 přečte | YAML 1.2 přečte | Chtěli jste |
|---|---|---|---|
country: NO |
false |
"NO" |
"NO" |
version: 1.10 |
číslo 1.1 |
číslo 1.1 |
"1.10" |
zip: 02134 |
osmičkově 1116 |
desítkově 2134 |
"02134" |
mode: 0755 |
desítkově 493 |
desítkově 755 |
493 nebo "0755" |
ports: ["22:22"] |
šedesátkově 1342 |
"22:22" |
"22:22" |
Zásadní lék: dát do uvozovek každý řetězec, který vypadá jako kód. Ale uvozovky stojí na lidské paměti; schema stojí na strojové kontrole — proto YAML zasluhuje JSON Schema.
Dva: proč může JSON Schema vládnout YAML
Specifikace YAML 1.2 říká jasně: hlavním cílem 1.2 bylo učinit z YAML úplnou nadmnožinu JSON a parser 1.2 čte běžný JSON beze změn. Oba formaty se parsují do stejných datových struktur, takže přípona souboru pro validátor neznamená nic. Celý pipeline jsou tři kroky:
- Sparsit YAML soubor do objektů/polí;
- Načíst JSON Schema;
- Validovat data proti schématu — chyby nebo průchod.
Všimněte si, že krok první nevyžaduje serializovat YAML do JSON textu a parsovat znovu; YAML knihovna vašeho jazyka předá strukturu validátoru přímo. Samotné schema lze psát i v YAML (yq -P schema.json > schema.yaml převede jedním příkazem), ale držet ho v JSON je bezpečnější volba: kompatibilita nástrojů je lepší a všechna schemata katalogu schemastore.org jsou v JSON.
Tři: tři CLI postupy, které fungují už dnes
Vezměme config.yaml, kde schema vyžaduje name a version, nařizuje tvar semver a countries jako pole řetězců ze dvou velkých písmen:
# 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);
Čistý pipeline (yq + ajv-cli):
yq -o=json config.yaml | ajv validate -s schema.json -d -
# Nebo check-jsonschema, který přijímá YAML přímo
pip install check-jsonschema
check-jsonschema --schemafile schema.json config.yaml
Tři postupy se liší jen v kroku parsování: první dva jsou explicitní, na dva řádky, pipeline teče jedním proudem a check-jsonschema dělá konverzi YAML→JSON uvnitř. Soubor schematu je pro všechny tři stejný.
Čtyři: validace v reálném čase v editoru: modeline a SchemaStore
Rozšíření YAML od Red Hat (založené na yaml-language-server) má v VS Code zhruba 30 milionů instalací a podporuje JSON Schema draft-04/07/2019-09/2020-12. Tři způsoby připojení:
# Varianta 1: modeline — první řádek souboru ukazuje na schema
# yaml-language-server: $schema=./schema.json
name: checkout
// Varianty 2 a 3: .vscode/settings.json, podle názvu souboru nebo glob
{
"yaml.schemas": {
"./schema.json": ["config/*.yaml", "*.config.yaml"],
"https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml"
}
}
yaml.schemaStore.enable je zapnuté ve výchozím stavu: běžné soubory jako package.json, GitHub workflowy nebo docker-compose se automaticky vážou ke katalogu schemastore.org, bez jakékoli konfigurace. Pole description schématu se stávají nápovědami doplňování a tooltipy a chybějící vlastnosti required se podtrhávají červeně — chyby konfigurace se stěhují z „ladění po nasazení“ do „okamžiku, kdy píšete“. To vysvětluje i to, proč SchemaStore a ne „standard schémat pro YAML“: YAML nemá oficiální standard schémat a JSON Schema je de facto standardem.
Pět: jak by schema zachytilo norský problém
Vraťme se k incidentu s NO z první sekce. Dejme countries schema na úrovni prvků:
{
"type": "object",
"required": ["name", "version", "countries"],
"properties": {
"countries": {
"type": "array",
"items": { "type": "string", "pattern": "^[A-Z]{2}$" }
}
}
}
false vyprodukované PyYAML není řetězec, takže type: string padá okamžitě; i kdyby ho parser přečetl jako "no" malými písmeny, pattern by zastavil. Pro hlubší kontrolu přidejte whitelist enum. Totožné schema běží v CI přes CLI postupy sekce tři a v editoru přes modeline sekce čtyři — jedna smlouva na obou koncích.
Dělení práce s yamllint stojí za větu: pravidlo truthy yamllint (přijímány jen true/false, jakékoli jiné logické hláskování je signalizováno) vládne stylu psaní a zachytí flag: yes na úrovni lintu; JSON Schema vládne tvaru dat, nezávisle na parseru. Tým z incidentu nakonec přijal všechny tři: uvozovky na řetězcích, yamllint truthy v pipeline a kontrolu dvoupísmenných řetězců v šabloně. Dvě obranné vrstvy se nepřekrývají — doplňují se.
Šest: dávková validace manifestů Kubernetes
Samotné API Kubernetes je popsáno v OpenAPI a projekt kubernetes-json-schema ho konvertuje na standardní JSON Schema. Kubeconform používá tento registr pro dávkovou validaci: na notebooku se 4 jádry 35 139 souborů a 50 714 zdrojů s kubeconform -ignore-missing-schemas -n 8 -summary skončí za 6,7 sekundy, oproti 35 sekundám kubeval na stejném úkolu. Standardní Helmový úchop: nejdřív render, potom validace:
helm template my-app ./charts/my-app > rendered.yaml
kubeconform -strict -summary -kubernetes-version 1.28.0 rendered.yaml
-strict odmítá pole, která schema nedefinuje (překlepy se vidí brzy); CRD zdroje lze přeskočit přes -ignore-missing-schemas nebo napojit vlastní registr přes -schema-location.
Sedm: co validace podle schématu nedokáže: tři omezení
- Drift verze parsera nastává při parsování. Schema vidí výsledek parsování:
NOpřečtené PyYAML je užfalsea schema může jen uzavřít tuto špatnou hodnotu přestype/pattern. Zásadní lékem zůstávají uvozovky; nečekejte, že schema parser opraví. - Logické chyby jsou mimo obvod. Překlep v selectoru nebo K8s selector mířící na neexistující label — schema zná tvary, ne sémantiku. To je terén admission webhooks, politik OPA nebo
kubectl apply --dry-run=server. - Duplicitní klíče vyhrávají potichu. Mnoho YAML parserů přijímá duplikáty klíčů bez varování (vyhrává poslední), takže schema dostává data, která už o klíč přišla. Pravidlo
key-duplicatesyamllint nebo hooky parsování zůstávají detektory.
Checklist před nasazením: uvozovky na řetězcích typu kód → spustit yamllint (truthy + key-duplicates) → validace JSON Schema jak v CI, tak v editoru → pro clusterové zdroje navíc --dry-run=server. S těmito čtyřmi kroky norský incident z sekce jedna nepřežije druhý krok pipeline.
FAQ
Může JSON Schema validovat YAML soubory přímo?
Ano — ale validuje data, do kterých se soubor parsuje, ne samotný soubor. YAML 1.2 je úplná nadmnožina JSON, oba se parsují do stejných struktur, takže jedno schema poslouží pro JSON i YAML. Vyberte jeden ze čtyř postupů — Python, Node, pipeline yq nebo check-jsonschema — bez ruční konverze formátů.
Co je SchemaStore a jak se používá?
schemastore.org je katalog JSON Schema (catalog.json), který sdružuje schemata stovek běžných konfiguračních souborů: package.json, GitHub workflowy, docker-compose apod. Editory s podporou YAML/JSON vážou soubory k tomuto katalogu automaticky, nebo si URL můžete namapovat ručně v yaml.schemas. Schema vlastního projektu můžete do katalogu také podat.
Překrývají se yamllint a JSON Schema?
Ne. yamllint kontroluje styl psaní (odsazení, délku řádků, truthy, duplicitní klíče) na úrovni textu; JSON Schema kontroluje strukturu dat (typy, required, enum, pattern) na úrovni dat. Seznam oprav norského incidentu použil obojí: pravidlo truthy zachytí hláskování jako flag: yes, zatímco schema zachytí false, který skončil v poli řetězců.
Pro Kubernetes: kubeconform nebo kubectl dry-run?
Dva rozdílné řemesla. Kubeconform pracuje offline a dávkově, bez clusteru, jeho místo je v CI na strukturální chyby; dry-run=server mluví s opravdovým API serverem a odhalí problémy admission webhook a kvót, ale vyžaduje přístup k clusteru. Standardní kombinace: kubeconform v CI, pak průchod --dry-run=server před nasazením — držte obě vrstvy.
Až napíšete schema, vložte JSON konvertovaný z vašeho YAML do online validátoru JSON, abyste chyby viděli nejdřív; k psaní klíčových slov schématu slouží průvodce JSON Schema; abyste schema nechali hlídat testy v CI, čtěte kontraktní testování JSON Schema; pro každodenní konverzi JSON↔YAML použijte konvertor JSON YAML XML.