Walidacja YAML za pomocą JSON Schema: siatka bezpieczeństwa plików konfiguracyjnych
Podsumowanie: Plik YAML, który parsuje się bez błędów, nie jest plikiem poprawnym: country: NO nie jest ciągiem dla parsera YAML 1.1, a version: 1.10 po cichu zamienia się w liczbę 1.1. Ten przewodnik wyjaśnia, dlaczego JSON Schema może walidować YAML, działające sposoby CLI i edytorowe, jak schemat przechwyciłby prawdziwy incydent z norweskim kodem kraju, oraz trzy ograniczenia walidacji przez schemat.

Wniosek: YAML 1.2 to ścisłe nadzbioru JSON, więc JSON Schema waliduje strukturę danych po parsowaniu, a nie format pliku — napisz schemat raz, a obejmie zarówno dane JSON, jak i YAML. Właśnie dlatego potrafi przechwycić incydenty, gdy parser po cichu zmienia typ.
yaml.safe_loadbez błędów dowodzi tylko, że plik to legalny YAML. Nie dowodzi, żecountry: NOto nadal ciąg — pod parserem YAML 1.1 to jużfalsena długo zanim twój kod zobaczy plik.
Jeden: parsowanie bez błędów ≠ poprawna konfiguracja — najpierw prawdziwy incydent
Zespół e-commerce dodał Norwegię do krajów dostawy: jedna linijka, NO, na liście w group_vars Ansible. Zreviewowane, zwalidowane, wdrożone. Tydzień później: zero norweskich zamówień — plik JSON na serwerach zawierał "DK", false, "SE". Ansible parsuje pliki zmiennych przez PyYAML, parser YAML 1.1: NO stało się wartością logiczną false już przy czytaniu pliku, a filtr to_json wiernie to zapisał. Szablon się wyrenderował, JSON był poprawny, nikt nie narzekał — tylko serwis checkout dalej odrzucał każdego norweskiego klienta, bo NO nie było na liście.
Wspólne dla takich incydentów: wszystkie narzędzia składniowe świecą na zielono, podczas gdy warstwa danych jest już błędna. Poniższa tabela pokazuje zmierzony na PyYAML 6.0.3 dryf typów; parsery YAML 1.2 poprawiają tylko część:
| Piszesz | YAML 1.1 czyta | YAML 1.2 czyta | Chciałeś |
|---|---|---|---|
country: NO |
false |
"NO" |
"NO" |
version: 1.10 |
liczba 1.1 |
liczba 1.1 |
"1.10" |
zip: 02134 |
ósemkowo 1116 |
dziesiętnie 2134 |
"02134" |
mode: 0755 |
dziesiętnie 493 |
dziesiętnie 755 |
493 lub "0755" |
ports: ["22:22"] |
sześćdziesiątkowo 1342 |
"22:22" |
"22:22" |
Radykalne lekarstwo: brać w cudzysłowy każdy ciąg, który wygląda jak kod. Ale cudzysłowy opierają się na ludzkiej pamięci; schemat opiera się na maszynowej weryfikacji — dlatego YAML zasługuje na JSON Schema.
Dwa: dlaczego JSON Schema może rządzić YAML-em
Specyfikacja YAML 1.2 mówi to wprost: głównym celem 1.2 było uczynienie YAML-a ścisłym nadzbiorem JSON, a parser 1.2 czyta zwykły JSON bez zmian. Oba formaty parsują do tych samych struktur danych, więc rozszerzenie pliku nie znaczy nic dla walidatora. Cały pipeline to trzy kroki:
- Sparsować plik YAML do obiektów/tablic;
- Wczytać JSON Schema;
- Zwalidować dane względem schematu — błędy albo zaliczenie.
Zauważ, że krok pierwszy nie wymaga serializacji YAML do tekstu JSON i ponownego parsowania; biblioteka YAML twojego języka przekazuje strukturę walidatorowi bezpośrednio. Sam schemat też można pisać w YAML-u (yq -P schema.json > schema.yaml to jedna komenda), ale trzymanie go w JSON to najbezpieczniejszy wybór: kompatybilność narzędzi jest lepsza, a wszystkie schematy katalogu schemastore.org są w JSON.
Trzy: trzy sposoby CLI, które działają już dziś
Weźmy config.yaml, w którym schemat wymaga name i version, narzuca formę semver oraz countries jako tablicę ciągów z dwóch wielkich liter:
# 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);
Czysty pipeline (yq + ajv-cli):
yq -o=json config.yaml | ajv validate -s schema.json -d -
# Albo check-jsonschema, który przyjmuje YAML bezpośrednio
pip install check-jsonschema
check-jsonschema --schemafile schema.json config.yaml
Trzy sposoby różnią się tylko krokiem parsowania: pierwsze dwa są jawne, w dwóch linijkach, pipeline płynie jednym strumieniem, a check-jsonschema robi konwersję YAML→JSON wewnętrznie. Plik schematu jest ten sam dla wszystkich trzech.
Cztery: walidacja w czasie rzeczywistym w edytorze: modeline i SchemaStore
Rozszerzenie YAML od Red Hat (oparte na yaml-language-server) ma około 30 milionów instalacji w VS Code i wspiera JSON Schema draft-04/07/2019-09/2020-12. Trzy sposoby podłączenia:
# Opcja 1: modeline — pierwsza linijka pliku wskazuje na schemat
# yaml-language-server: $schema=./schema.json
name: checkout
// Opcje 2 i 3: .vscode/settings.json, po nazwie pliku lub glob
{
"yaml.schemas": {
"./schema.json": ["config/*.yaml", "*.config.yaml"],
"https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml"
}
}
yaml.schemaStore.enable jest domyślnie włączone: znane pliki takie jak package.json, workflow GitHub czy docker-compose są automatycznie wiązane z katalogiem schemastore.org, bez żadnej konfiguracji. Pola description schematu stają się podpowiedziami autouzupełniania i dymkami, a brakujące właściwości required podkreślane są na czerwono — błędy konfiguracji przenoszą się z „debugowania po wdrożeniu” do „momentu, w którym piszesz”. To wyjaśnia też, czemu SchemaStore, a nie „standard schematów dla YAML”: YAML nie ma oficjalnego standardu schematów, a JSON Schema jest standardem de facto.
Pięć: jak schemat przechwyciłby norweski problem
Wróćmy do incydentu z NO z pierwszej sekcji. Dajmy countries schemat na poziomie elementów:
{
"type": "object",
"required": ["name", "version", "countries"],
"properties": {
"countries": {
"type": "array",
"items": { "type": "string", "pattern": "^[A-Z]{2}$" }
}
}
}
false wyprodukowane przez PyYAML nie jest ciągiem, więc type: string pada natychmiast; nawet gdyby parser odczytał to jako "no" małymi literami, pattern by zatrzymał. Idąc dalej, dodaj białą listę enum. Ten sam schemat kręci się w CI przez sposoby CLI z sekcji trzeciej i w edytorze przez modeline z sekcji czwartej — jeden kontrakt na obu końcach.
Podział pracy z yamllint zasługuje na zdanie: reguła truthy yamllint (akceptowane tylko true/false, każde inne logiczne zapisanie jest sygnalizowane) rządzi stylem pisania i przechwytuje flag: yes na poziomie lintu; JSON Schema rządzi kształtem danych, niezależnie od parsera. Zespół z incydentu przyjął ostatecznie wszystkie trzy: cudzysłowy na ciągach, yamllint truthy w pipeline i asercję dwuliterowych ciągów w szablonie. Dwie warstwy obrony się nie nakładają — one się uzupełniają.
Sześć: walidacja wsadowa manifestów Kubernetes
Samo API Kubernetes jest opisane w OpenAPI, a projekt kubernetes-json-schema konwertuje je na standardowy JSON Schema. Kubeconform używa tego rejestru do walidacji wsadowej: na laptopie z 4 rdzeniami 35 139 plików i 50 714 zasobów z kubeconform -ignore-missing-schemas -n 8 -summary kończy się w 6,7 sekundy, wobec 35 sekund kubeval na tym samym zadaniu. Standardowy gest Helm: najpierw render, potem walidacja:
helm template my-app ./charts/my-app > rendered.yaml
kubeconform -strict -summary -kubernetes-version 1.28.0 rendered.yaml
-strict odrzuca pola niezdefiniowane w schemacie (literówki widać wcześnie); zasoby CRD można pominąć przez -ignore-missing-schemas albo podpiąć własny rejestr przez -schema-location.
Siedem: czego walidacja przez schemat nie potrafi: trzy ograniczenia
- Dryf wersji parsera dzieje się przy parsowaniu. Schemat widzi wynik parsowania:
NOodczytane przez PyYAML to jużfalse, a schemat może jedynie zamknąć tę błędną wartość przeztype/pattern. Radykalnym lekarstwem pozostają cudzysłowy; nie oczekuj od schematu naprawy parsera. - Błędy logiczne są poza perimetrem. Literówka w selectorze albo K8s-selector wskazujący na nieistniejący label — schemat zna kształty, nie semantykę. To teren admission webhooks, polityk OPA albo
kubectl apply --dry-run=server. - Zduplikowane klucze wygrywają po cichu. Wiele parserów YAML przyjmuje duplikaty kluczy bez ostrzeżenia (wygrywa ostatni), więc schemat dostaje dane, które już straciły klucz. Reguła
key-duplicatesyamllint albo hooki parsowania pozostają detektorami.
Checklista przed wdrożeniem: cudzysłowy na ciągach przypominających kod → uruchomić yamllint (truthy + key-duplicates) → walidacja JSON Schema i w CI, i w edytorze → dla zasobów klastrowych dodatkowo --dry-run=server. Z tymi czterema krokami norweski incydent z sekcji pierwszej nie dożywa drugiego kroku pipeline.
FAQ
Czy JSON Schema może walidować pliki YAML bezpośrednio?
Tak — ale waliduje dane, do których plik się parsuje, a nie sam plik. YAML 1.2 to ścisłe nadzbioru JSON, oba parsują do tych samych struktur, więc jeden schemat służy dla JSON i YAML. Wybierz jeden z czterech sposobów — Python, Node, pipeline yq albo check-jsonschema — bez ręcznej konwersji formatów.
Czym jest SchemaStore i jak go używać?
schemastore.org to katalog JSON Schema (catalog.json) zbierający schematy setek popularnych plików konfiguracyjnych: package.json, workflow GitHub, docker-compose i in. Edytory ze wsparciem YAML/JSON automatycznie wiążą pliki z tym katalogiem, albo możesz zmapować URL-e ręcznie w yaml.schemas. Schemat własnego projektu też możesz zgłosić do katalogu.
Czy yamllint i JSON Schema się dublują?
Nie. yamllint sprawdza styl pisania (wcięcia, długość linii, truthy, duplikaty kluczy) na poziomie tekstu; JSON Schema sprawdza strukturę danych (typy, required, enum, pattern) na poziomie danych. Lista poprawek norweskiego incydentu użyła obu: reguła truthy przechwytuje zapisy typu flag: yes, podczas gdy schemat przechwytuje false, który wylądował w tablicy ciągów.
Dla Kubernetes: kubeconform czy kubectl dry-run?
Dwa różne rzemiosła. Kubeconform działa offline i wsadowo, bez klastra, jego miejsce jest w CI na błędy strukturalne; dry-run=server rozmawia z prawdziwym serwerem API i ujawnia problemy admission webhook i limitów, ale wymaga dostępu do klastra. Standardowa kombinacja: kubeconform w CI, potem przebieg --dry-run=server przed wdrożeniem — trzymaj obie warstwy.
Po napisaniu schematu wklej JSON skonwertowany z twojego YAML do walidatora JSON online, by najpierw zobaczyć błędy; żeby pisać słowa kluczowe schematu, zobacz przewodnik po JSON Schema; żeby trzymać schemat pod strażą testów w CI, przeczytaj testowanie kontraktów JSON Schema; do codziennej konwersji JSON↔YAML użyj konwertera JSON YAML XML.