JSON Toolkit

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.

Średniozaawansowany~6 min czytaniaOpublikowano 2026-11-13Zaktualizowano 2026-11-13
Schemat ilustrujący walidację plików konfiguracyjnych YAML za pomocą JSON Schema

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_load bez błędów dowodzi tylko, że plik to legalny YAML. Nie dowodzi, że country: NO to nadal ciąg — pod parserem YAML 1.1 to już false na 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:

  1. Sparsować plik YAML do obiektów/tablic;
  2. Wczytać JSON Schema;
  3. 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

  1. Dryf wersji parsera dzieje się przy parsowaniu. Schemat widzi wynik parsowania: NO odczytane przez PyYAML to już false, a schemat może jedynie zamknąć tę błędną wartość przez type/pattern. Radykalnym lekarstwem pozostają cudzysłowy; nie oczekuj od schematu naprawy parsera.
  2. 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.
  3. 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-duplicates yamllint 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.