JSON Toolkit

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.

Středně pokročilý~6 min čteníPublikováno 2026-11-13Aktualizováno 2026-11-13
Diagram znázorňující validaci YAML konfiguračních souborů pomocí JSON Schema

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_load bez chyb dokazuje jen to, že soubor je legální YAML. Nedokazuje, že country: NO je stále řetězec — pod parserem YAML 1.1 je to už false dlouho 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:

  1. Sparsit YAML soubor do objektů/polí;
  2. Načíst JSON Schema;
  3. 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í

  1. Drift verze parsera nastává při parsování. Schema vidí výsledek parsování: NO přečtené PyYAML je už false a schema může jen uzavřít tuto špatnou hodnotu přes type/pattern. Zásadní lékem zůstávají uvozovky; nečekejte, že schema parser opraví.
  2. 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.
  3. 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-duplicates yamllint 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.