YAML mit JSON Schema validieren: das Sicherheitsnetz für Config-Dateien
Fazit: Eine YAML-Datei, die ohne Fehler parst, ist keine korrekte Datei: country: NO ist für einen YAML-1.1-Parser kein String, und version: 1.10 wird stillschweigend zur Gleitkommazahl 1.1. Dieser Guide erklärt, warum JSON Schema YAML validieren kann, die CLI- und Editor-Wege zur Einrichtung, wie ein Schema den echten Vorfall mit dem norwegischen Ländercode abgefangen hätte, und die drei Grenzen der Schema-Validierung.

Fazit: YAML 1.2 ist eine strikte Obermenge von JSON, daher validiert JSON Schema die Datenstruktur nach dem Parsen, nicht das Dateiformat — schreibe das Schema einmal, und es deckt sowohl JSON- als auch YAML-Daten ab. Genau deshalb kann es Vorfälle abfangen, bei denen ein Parser stillschweigend den Typ ändert.
Ein
yaml.safe_loadohne Fehler beweist nur, dass die Datei ein legaler YAML-Text ist. Es beweist nicht, dasscountry: NOnoch ein String ist — unter einem YAML-1.1-Parser ist es längstfalse, lange bevor dein Code die Datei sieht.
Eins: Parse ohne Fehler ≠ korrekte Konfiguration — zuerst ein echter Vorfall
Ein E-Commerce-Team hat Norwegen zu seinen Lieferländern hinzugefügt: eine Zeile, NO, in einer Liste in den Ansible group_vars. Reviewed, validiert, deployt. Eine Woche später: null norwegische Bestellungen — die JSON-Datei auf den Servern enthielt "DK", false, "SE". Ansible parst seine Variablendateien mit PyYAML, einem YAML-1.1-Parser: NO war schon beim Einlesen der Datei der Boolean false, und der to_json-Filter hat das treu geschrieben. Das Template renderte, das JSON war valide, niemand beschwerte sich — nur der Checkout-Service lehnte weiter jeden norwegischen Kunden ab, weil NO nicht in der Liste stand.
Den Vorfällen dieser Art ist gemeinsam: alle syntaxorientierten Tools stehen auf Grün, während die Datenschicht bereits falsch ist. Die folgende Tabelle zeigt den mit PyYAML 6.0.3 gemessenen Typ-Drift; YAML-1.2-Parser korrigieren nur einen Teil davon:
| Du schreibst | YAML 1.1 liest | YAML 1.2 liest | Gewollt |
|---|---|---|---|
country: NO |
false |
"NO" |
"NO" |
version: 1.10 |
Float 1.1 |
Float 1.1 |
"1.10" |
zip: 02134 |
Oktal 1116 |
Dezimal 2134 |
"02134" |
mode: 0755 |
Dezimal 493 |
Dezimal 755 |
493 oder "0755" |
ports: ["22:22"] |
Sexagesimal 1342 |
"22:22" |
"22:22" |
Das gründliche Mittel: jede Zeichenfolge, die nach Code aussieht, in Anführungszeichen setzen. Aber Anführungszeichen basieren auf menschlichem Gedächtnis; ein Schema basiert auf maschineller Prüfung — deshalb verdient YAML ein JSON Schema.
Zwei: warum JSON Schema YAML regieren kann
Die YAML-1.2-Spezifikation sagt es klar: Das Hauptziel von 1.2 war es, YAML zu einer strikten Obermenge von JSON zu machen, und ein 1.2-Parser liest gewöhnliches JSON unverändert. Beide Formate parsen in dieselben Datenstrukturen, daher hat die Dateiendung für einen Validator keine Bedeutung. Die ganze Pipeline sind drei Schritte:
- Die YAML-Datei in Objekte/Arrays parsen;
- Das JSON Schema laden;
- Die Daten gegen das Schema validieren — Fehler oder Durchlauf.
Beachte: Schritt eins verlangt nicht, das YAML zuerst in JSON-Text zu serialisieren und erneut zu parsen; die YAML-Bibliothek deiner Sprache übergibt die Struktur direkt an den Validator. Das Schema selbst lässt sich auch in YAML schreiben (yq -P schema.json > schema.yaml — ein Befehl), aber es als JSON zu halten ist die sicherere Wahl: bessere Tool-Kompatibilität, und alle Schemata des Katalogs schemastore.org sind JSON.
Drei: drei CLI-Wege, die heute schon funktionieren
Nimm eine config.yaml, in der das Schema name und version verlangt, eine Semver-Form vorschreibt und countries als Array zweibuchstabiger Großbuchstaben-Strings:
# 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);
Reine Pipeline (yq + ajv-cli):
yq -o=json config.yaml | ajv validate -s schema.json -d -
# Oder check-jsonschema, das YAML direkt konsumiert
pip install check-jsonschema
check-jsonschema --schemafile schema.json config.yaml
Die drei Wege unterscheiden sich nur im Parsing-Schritt: die ersten beiden sind explizit in zwei Zeilen, die Pipeline läuft in einem Strom, und check-jsonschema erledigt die YAML→JSON-Konvertierung intern. Die Schemadatei ist für alle drei dieselbe.
Vier: Validierung in Echtzeit im Editor: Modeline und SchemaStore
Die YAML-Erweiterung von Red Hat (basierend auf yaml-language-server) zählt rund 30 Millionen Installationen in VS Code und unterstützt JSON Schema draft-04/07/2019-09/2020-12. Drei Wege, sie anzubinden:
# Option 1: Modeline — die erste Zeile der Datei zeigt auf das Schema
# yaml-language-server: $schema=./schema.json
name: checkout
// Optionen 2 und 3: .vscode/settings.json, nach Dateiname oder Glob
{
"yaml.schemas": {
"./schema.json": ["config/*.yaml", "*.config.yaml"],
"https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml"
}
}
yaml.schemaStore.enable ist standardmäßig aktiv: gängige Dateien wie package.json, GitHub-Workflows oder docker-compose werden automatisch mit dem Katalog schemastore.org verknüpft, ganz ohne Konfiguration. Die description-Felder des Schemas werden zu Autovervollständigungs-Hilfen und Tooltips, fehlende required-Eigenschaften rot unterstrichen — Konfigurationsfehler wandern von „Debugging nach dem Deploy“ zu „in dem Moment, in dem du tippst“. Das erklärt auch, warum SchemaStore statt eines „YAML-Schema-Standards“: YAML hat keinen offiziellen Schema-Standard, und JSON Schema ist der De-facto-Standard.
Fünf: wie ein Schema das norwegische Problem abgefangen hätte
Zurück zum NO-Vorfall aus Abschnitt eins. Gib countries ein Schema auf Element-Ebene:
{
"type": "object",
"required": ["name", "version", "countries"],
"properties": {
"countries": {
"type": "array",
"items": { "type": "string", "pattern": "^[A-Z]{2}$" }
}
}
}
Das von PyYAML erzeugte false ist kein String, also scheitert type: string sofort; hätte ein Parser es sogar als "no" in Kleinbuchstaben gelesen, stoppt das pattern. Für tiefergehende Kontrolle ergänze eine enum-Whitelist. Dasselbe Schema läuft in CI über die CLI-Wege aus Abschnitt drei und im Editor über die Modeline aus Abschnitt vier — ein einziger Vertrag an beiden Enden.
Die Arbeitsteilung mit yamllint verdient einen Satz: die truthy-Regel von yamllint (nur true/false erlaubt, jede andere boolesche Schreibweise wird gemeldet) regiert den Schreibstil und fängt flag: yes auf der Lint-Ebene; JSON Schema regiert die Datenform, unabhängig vom Parser. Das Team aus dem Vorfall hat am Ende alle drei übernommen: Anführungszeichen auf Strings, yamllint truthy in der Pipeline und die Zwei-Buchstaben-Assertion im Template. Die zwei Verteidigungsebenen überlappen nicht — sie ergänzen sich.
Sechs: Batch-Validierung von Kubernetes-Manifesten
Die Kubernetes-API selbst ist in OpenAPI beschrieben, und das Projekt kubernetes-json-schema wandelt sie in Standard-JSON Schema um. Kubeconform nutzt dieses Register für Batch-Validierung: auf einem 4-Kern-Laptop laufen 35.139 Dateien und 50.714 Ressourcen mit kubeconform -ignore-missing-schemas -n 8 -summary in 6,7 Sekunden durch, gegenüber 35 Sekunden für kubeval bei derselben Aufgabe. Der Standard-Helm-Griff: erst rendern, dann validieren:
helm template my-app ./charts/my-app > rendered.yaml
kubeconform -strict -summary -kubernetes-version 1.28.0 rendered.yaml
-strict verwirft Felder, die das Schema nicht definiert (Tippfehler fallen früh auf); CRD-Ressourcen lassen sich mit -ignore-missing-schemas überspringen oder über -schema-location mit einem eigenen Register versorgen.
Sieben: was Schema-Validierung nicht kann: drei Grenzen
- Der Versions-Drift des Parsers passiert beim Parsing. Das Schema sieht das Parsing-Ergebnis: das von PyYAML gelesene
NOist bereitsfalse, und das Schema kann diesen falschen Wert nur mittype/patterneinfangen. Das gründliche Mittel bleiben Anführungszeichen; erwarte nicht, dass ein Schema einen Parser repariert. - Logische Fehler sind außerhalb des Perimeters. Ein Tippfehler im Selector oder ein K8s-Selector, der auf ein nicht existierendes Label zeigt — das Schema kennt Formen, nicht Semantik. Das ist Terrain von Admission Webhooks, OPA-Policies oder
kubectl apply --dry-run=server. - Doppelte Schlüssel gewinnen stillschweigend. Viele YAML-Parser akzeptieren doppelte Schlüssel ohne Warnung (der letzte gewinnt), das Schema erhält also Daten, die bereits einen Schlüssel verloren haben. Die
key-duplicates-Regel von yamllint oder Parsing-Hooks bleiben die Detektoren.
Checkliste vor dem Deploy: Anführungszeichen auf codeartige Strings → yamllint ausführen (truthy + key-duplicates) → JSON-Schema-Validierung sowohl in CI als auch im Editor → für Cluster-Ressourcen zusätzlich --dry-run=server. Mit diesen vier Schritten überlebt der norwegische Vorfall aus Abschnitt eins den zweiten Pipeline-Schritt nicht.
FAQ
Kann JSON Schema YAML-Dateien direkt validieren?
Ja — aber es validiert die Daten, in die die Datei parst, nicht die Datei selbst. YAML 1.2 ist eine strikte Obermenge von JSON, beide parsen in dieselben Strukturen, also dient ein Schema für JSON wie YAML. Wähle einen der vier Wege — Python, Node, die yq-Pipeline oder check-jsonschema — ganz ohne manuelle Formatkonvertierung.
Was ist SchemaStore und wie benutzt man ihn?
schemastore.org ist ein Katalog von JSON Schemas (catalog.json) mit Schemata für Hunderte gängiger Config-Dateien: package.json, GitHub-Workflows, docker-compose und mehr. Editoren mit YAML/JSON-Support verknüpfen Dateien automatisch mit dem Katalog, oder du mappst die URLs manuell in yaml.schemas. Auch das Schema deines eigenen Projekts kannst du einreichen.
Doppeln sich yamllint und JSON Schema?
Nein. yamllint prüft den Schreibstil (Einrückung, Zeilenlänge, truthy, doppelte Schlüssel) auf Textebene; JSON Schema prüft die Datenstruktur (Typen, required, enums, patterns) auf Datenebene. Die Fixliste des norwegischen Vorfalls nutzte beide: die truthy-Regel fängt Schreibweisen wie flag: yes, während das Schema ein false abfängt, das in einem String-Array gelandet ist.
Für Kubernetes: kubeconform oder kubectl dry-run?
Zwei verschiedene Gewerbe. Kubeconform arbeitet offline und stapelweise, ohne Cluster, sein Platz ist die CI für strukturelle Fehler; dry-run=server spricht mit einem echten API-Server und deckt Admission-Webhook- und Quota-Probleme auf, verlangt aber Cluster-Zugang. Die Standard-Kombination: kubeconform in der CI, dann ein Durchlauf --dry-run=server vor dem Deploy — halte beide Ebenen.
Wenn du dein Schema geschrieben hast, füge den aus deinem YAML konvertierten JSON in den JSON-Online-Validator ein, um Fehler zuerst zu sehen; zum Schreiben der Schema-Schlüsselwörter siehe den JSON-Schema-Guide; um das Schema in CI durch Tests bewacht zu halten, lies das JSON-Schema-Contract-Testing; für die alltägliche JSON↔YAML-Konvertierung nutze den JSON YAML XML Konverter.