YAML-Validator: Compose-Dateien und Manifeste prüfen und Fehler finden

Ein Container startet nicht, weil docker compose up mit „yaml: line 4: mapping values are not allowed in this context“ abbricht. Ein Kubernetes-Deployment läuft, ignoriert aber die Ressourcengrenzen, weil ein Schlüssel eine Ebene zu tief steht. Ein CI-Workflow installiert Python 3.1 statt 3.10. Hinter all dem steckt YAML, das Format, in dem Docker Compose, Kubernetes, GitHub Actions und Ansible konfiguriert werden. Der YAML-Validator auf s-edv.com prüft Ihre Datei beim Tippen, zeigt die Fehlerstelle mit Zeilennummer, schlägt Korrekturen vor und macht sichtbar, wie der Parser die Datei tatsächlich versteht. Für Compose-Dateien prüft er zusätzlich typische Schwächen. Diese Anleitung richtet sich an Admins und Entwickler in KMU, die Container-Stacks pflegen oder Konfigurationen von Kollegen übernehmen.

Voraussetzungen

• Ein aktueller Browser mit JavaScript. Eingaben sind laut Tool auf 1 MB begrenzt.
• Die zu prüfende Datei, etwa compose.yaml, ein Kubernetes-Manifest oder einen Workflow unter .github/workflows/.
• Für die abschließende Prüfung auf dem Zielsystem: Docker mit Compose-Plugin für docker compose config, bei Kubernetes kubectl mit Zugriff auf einen Cluster.
• Grundwissen: Sie sollten wissen, was ein Compose-Service, ein Image-Tag und eine Port-Zuordnung sind. Die YAML-Regeln selbst erklärt diese Anleitung.

Für einen typischen Compose-Stack aus Webserver, Anwendung und Datenbank reicht ein Linux-Server mit 2 Kernen und 4 GB RAM.

Schritt 1: YAML-Grundregeln kennen und das Tool öffnen

YAML beschreibt Daten über Einrückung statt über Klammern. schlüssel: wert bildet ein Mapping, Zeilen mit - bilden eine Liste. Nach dem Doppelpunkt muss ein Leerzeichen folgen, eingerückt wird ausschließlich mit Leerzeichen, Tabulatoren sind in der Einrückung verboten. Wie weit Sie einrücken, ist frei, solange alle Einträge einer Ebene exakt gleich weit stehen. Üblich sind zwei Leerzeichen. Tückisch ist: Ein Einrückungsfehler macht eine Datei oft nicht ungültig, sondern verschiebt einen Schlüssel auf eine andere Ebene, wo das Programm ihn stillschweigend ignoriert.

Öffnen Sie den YAML-Validator. Links steht „YAML-Eingabe“ mit „Leeren“, dem Zähler „0 Zeichen · max. 1 MB“ und vier Vorlagen: „Docker Compose“, „Kubernetes-Deployment“, „GitHub-Actions-Workflow“ und „Beispiel mit Fehlern“. Rechts folgen „Ausgabe“ mit den Ansichten „Formatiert“, „JSON“ und „Struktur“, der Auswahl „Einrückung“ (2 oder 4 Leerzeichen), „Kopieren“ und „Herunterladen“ sowie der Bereich „Prüfung“.

Die Seite gibt an, dass alles im Browser läuft. Im Test kamen während der Prüfungen keine Netzwerkanfragen hinzu. Der Parser js-yaml wird als lokale Datei der Website geladen.

Verifizieren: Klicken Sie „Docker Compose“. Unter „Prüfung“ erscheinen Kennzahlen wie „DOKUMENTE 1“, „WURZEL Mapping 3 Schlüssel“ und „KNOTEN 35“, darunter „DOCKER-COMPOSE-PRÜFUNG · 3 SERVICES“ mit „Keine Auffälligkeiten: Images mit Versions-Tag, restart gesetzt, Ports eindeutig.“

Schritt 2: Datei einfügen und Fehlerstelle lesen

Fügen Sie Ihre Datei ein, die Prüfung startet beim Tippen. Bei einem Syntaxfehler erscheint „Fehlerstelle“ mit einer deutschen Überschrift samt Zeile und Spalte, einer Erklärung, der Originalmeldung unter „Meldung des Parsers“ und einem Ausschnitt mit Zeilennummern und Markierung. Mit „Im Eingabefeld zeigen“ springen Sie an die Stelle. Diese Fehler haben wir im Test provoziert:

• „Tabulator in der Einrückung“ mit der Parsermeldung tab characters must not be used in indentation,
• „Falsche Einrückung oder Doppelpunkt an unerwarteter Stelle“ bei einem Schlüssel mit drei statt vier Leerzeichen, dazu unter „HINWEISE ZUR STRUKTUR“ die gefundenen Einrückungsweiten,
• „Doppelter Schlüssel“, wenn etwa image zweimal im selben Service steht,
• „Unerwarteter Inhalt“ mit dem Hinweis, dass nach dem Doppelpunkt vermutlich ein Leerzeichen fehlt (port:8080),
• „Doppeltes Anführungszeichen nicht geschlossen“.

Der doppelte Schlüssel verdient Aufmerksamkeit: PyYAML akzeptierte dieselbe Datei in unserer Gegenprobe ohne Meldung und übernahm einfach den letzten Wert. Je nach Werkzeug läuft also stillschweigend ein anderes Image als gedacht. Der Validator macht das sichtbar.

Verifizieren: Prüfen Sie die Datei zusätzlich mit einem zweiten Parser. Auf vielen Linux-Systemen ist PyYAML für das System-Python installiert:

python3 -c 'import sys, yaml; yaml.safe_load(open(sys.argv[1])); print("OK")' compose.yaml

Schritt 3: Korrekturvorschlag übernehmen

Ein häufiger Fehler ist ein vergessener Doppelpunkt, etwa image nginx:latest. Der Parser liest die Zeile dann als Fortsetzung eines Textes und stolpert oft erst eine Zeile später. Das Tool sucht oberhalb der gemeldeten Stelle nach solchen Zeilen, ergänzt den Doppelpunkt und prüft erneut. Ist das Ergebnis gültig, erscheint „So ist es richtig (Doppelpunkt in Zeile 4 ergänzt)“ mit der korrigierten Fassung und der Schaltfläche „Korrektur übernehmen“.

Probieren Sie das mit der Vorlage „Beispiel mit Fehlern“. Das Tool meldet „Fehlender Doppelpunkt“ für Zeile 4 und erklärt, dass Parser solche Fehler oft erst eine Zeile später melden. Nach „Korrektur übernehmen“ ist die Datei gültig, und erst jetzt läuft die Compose-Prüfung aus Schritt 5.

Verifizieren: Nach der Übernahme verschwindet der Kasten „Fehlerstelle“, und unter „Prüfung“ stehen Kennzahlen. Vergleichen Sie die korrigierte Zeile mit Ihrer Originaldatei, bevor Sie diese ersetzen.

Schritt 4: Formatiert, JSON und Struktur nutzen

Bei gültigem YAML zeigt „Formatiert“ eine bereinigte Fassung mit einheitlicher Einrückung. Beachten Sie den Hinweis unter der Ausgabe: „Formatieren entfernt Kommentare und löst Anker (&name, *name) auf.“ Im Test wurde aus einem Compose-Anker <<: *common der ausgeschriebene Inhalt, Ports wurden in einfache Anführungszeichen gesetzt und leere Werte als null geschrieben. Behalten Sie deshalb Ihre Originaldatei.

„JSON“ zeigt die Daten so, wie Programme sie sehen. Das ist die beste Kontrolle gegen Einrückungsfehler: Steht environment plötzlich als Liste von Objekten statt als Objekt da, sehen Sie es sofort. Mehrere Dokumente, getrennt durch ---, gibt das Tool in der JSON-Ansicht laut seiner Hilfe als Array aus. „Struktur“ zeigt einen aufklappbaren Baum mit Typ und Anzahl der Schlüssel je Ebene.

„Herunterladen“ speichert die aktuelle Ansicht, im Test als formatiert.yaml bzw. daten.json. Mit „Einrückung“ wählen Sie 2 oder 4 Leerzeichen. Bei 4 Leerzeichen schreibt das Tool Listeneinträge mit Mappings so, dass der Bindestrich allein in einer Zeile steht. Das ist gültiges YAML, aber ungewohnt. Für Compose-Dateien bleiben Sie besser bei 2.

Verifizieren: Vergleichen Sie die JSON-Ansicht mit der Ausgabe eines zweiten Parsers:

python3 -c 'import sys, json, yaml; print(json.dumps(yaml.safe_load(open(sys.argv[1])), indent=2))' compose.yaml

Schritt 5: Docker-Compose-Prüfung auswerten

Enthält die Datei einen Abschnitt services:, erscheint „DOCKER-COMPOSE-PRÜFUNG“ mit der Zahl der Services. Für das korrigierte Fehlerbeispiel meldete das Tool im Test:

• das veraltete Feld version, das aktuelle Docker-Compose-Versionen ignorieren,
• „Image mit „:latest““ und ein Image „ohne Tag“, bei denen die laufende Version vom Zeitpunkt des Pulls abhängt,
• environment als Liste mit Einträgen der Form - KEY: wert, richtig wäre - KEY=wert oder die Map-Form ohne Bindestriche,
• Services ohne restart, die nach einem Neustart des Hosts nicht automatisch starten,
• Ports ohne Anführungszeichen und den Hinweis, dass ein YAML-1.1-Parser 22:22 als Zahl 1342 liest,
• einen mehrfach belegten Host-Port 8080.

Die Prüfung ersetzt nicht den Test mit Docker. Erst docker compose config löst Variablen aus der .env auf und prüft gegen die Compose-Spezifikation. Kubernetes-Felder kennt das Tool nicht, dafür nutzen Sie kubectl apply --dry-run=server.

Verifizieren: Auf dem Server im Projektordner:

docker compose config --quiet && echo "Compose-Datei OK"
kubectl apply --dry-run=server -f deployment.yaml

Typische Fehler

Versionen und Zahlen verändern sich

python-version: 3.10 wird zur Zahl 3.1, das Tool zeigt in der formatierten Ausgabe genau das. Setzen Sie Versionsnummern immer in Anführungszeichen: "3.10".

Werte wie no, on oder 12:30 bedeuten je nach Parser etwas anderes

Der Validator nutzt js-yaml nach YAML 1.2, dort sind no und 12:30 gewöhnliche Texte. PyYAML nach YAML 1.1 las in unserer Gegenprobe land: no als False, zeit: 12:30 als 750 und den Schlüssel on als True. Eine Datei kann im Tool also gültig sein und in einem anderen Werkzeug trotzdem anders verstanden werden. Anführungszeichen lösen das für alle Parser.

Kommentar schneidet den Wert ab

Ab einem Leerzeichen mit # beginnt ein Kommentar. kennung: abc #1 ergibt nur abc. Schreiben Sie kennung: "abc #1".

Kein Ergebnis bei leerem Feld

Ohne Eingabe steht unter „Prüfung“ nur „Kennzahlen erscheinen, sobald gültiges YAML vorliegt.“ Das gilt auch bei jedem Syntaxfehler. Die Compose-Prüfung läuft erst, wenn die Datei fehlerfrei ist.

Häufige Fragen

Ist das Prüfen fremder Dateien sicher?

Laut Tool wird die Datei nur im Browser gelesen, js-yaml 4 erzeugt ausschließlich Daten und führt keinen Code aus. Gegen Dateien, die sich über Anker aufblähen, begrenzt das Tool die Zahl der aufgelösten Knoten. Passwörter in Compose-Dateien gehören trotzdem in Secrets oder eine .env, nicht in geteilte Dateien.

Was bedeuten &, * und <<?

&name legt einen Anker an, *name verweist darauf, <<: *name übernimmt dessen Schlüssel. In Compose-Dateien kombiniert man das gern mit Erweiterungsfeldern wie x-common, die Docker Compose auf oberster Ebene ignoriert.

Kann ich mehrere Dokumente prüfen?

Ja. Die Vorlage „Kubernetes-Deployment“ enthält Deployment und Service, das Tool meldet „2 Dokumente, getrennt durch ---.“

Wo lege ich die Compose-Datei auf einem Synology NAS ab?

Im Container Manager als Projekt. Prüfen Sie die Datei vorher im Validator, dann sehen Sie Syntaxfehler mit Zeilenangabe, bevor das NAS das Projekt ablehnt.

Testumfang

Wir haben den Validator am 1. Oktober 2026 mit allen vier Vorlagen sowie mit gezielt fehlerhaften Dateien geprüft: Tabulatoren, falsche Einrückung, doppelte Schlüssel, fehlende Leerzeichen und offene Anführungszeichen. Ergebnisse und Fehlerstellen haben wir mit PyYAML auf einem Linux-Host gegengeprüft. Die Abweichungen zwischen YAML 1.1 und 1.2 traten dabei genau so auf, wie das Tool sie beschreibt. Einen Test mit Docker selbst haben wir nicht durchgeführt.

Fazit

Der YAML-Validator findet Syntaxfehler schneller als die oft kryptischen Meldungen von Docker oder kubectl, erklärt sie auf Deutsch und behebt den häufigsten Fehler auf Knopfdruck. Die JSON-Ansicht entlarvt Einrückungsfehler, die Compose-Prüfung erinnert an feste Image-Tags, restart und Port-Konflikte. Für die endgültige Freigabe bleiben docker compose config und kubectl --dry-run auf dem Zielsystem Pflicht.

Weiterführende Anleitungen und Quellen

• Docker Compose: Multi-Container-Stacks aufbauen
• Docker Compose absichern: Secrets, Healthchecks, Non-Root
• Container Manager auf dem Synology NAS: Compose-Projekt anlegen
• k3s: Leichtgewichtiges Kubernetes einrichten
• YAML-Spezifikation 1.2.2
• Docker-Doku: Compose file reference
• Docker-Doku: docker compose config
• js-yaml auf GitHub