Was ist eine YAML-Datei? Syntax, Beispiele und häufige Fehler

 Eine YAML-Datei ist eine reine Textdatei, die Einstellungen und andere strukturierte Informationen in einem Format speichert, das sowohl Menschen als auch Programme lesen können. Sie nutzt Einrückungen und einfache Satzzeichen wie Doppelpunkte und Bindestriche, um zu zeigen, wie Informationen zueinander in Beziehung stehen.

Du wirst meist mit YAML in Berührung kommen, wenn ein Tool dich auffordert, es zu konfigurieren: eine Deployment-Pipeline, eine Container-Einrichtung oder eine Hosting-Plattform. Dieser Leitfaden erklärt, wie YAML aufgebaut ist, führt dich durch konkrete Beispiele und behandelt die wenigen Fehler, die hinter den meisten fehlerhaften YAML-Dateien stecken.

Wofür wird YAML verwendet?

Das Wichtigste auf einen Blick: YAML ist eines der gängigsten Formate für Konfigurationsdateien in Entwicklungstools, da man es ohne spezielle Software lesen und bearbeiten kann.

Der Name ist ein rekursiver Witz: YAML steht für „YAML Ain’t Markup Language“. Der springende Punkt ist, dass YAML Daten wie Einstellungen, Listen und Optionen beschreibt, anstatt ein Dokument so zu formatieren, wie es HTML tut.

YAML-Dateien findest du in vielen Tools, die Entwickler täglich nutzen:

Konfigurationsdateien werden viel häufiger von Menschen gelesen und geändert, als dass sie von Grund auf neu geschrieben werden – und genau hier zahlt sich ein lesbares Format aus. YAML-Dateien befinden sich oft neben anderen Konfigurationsdateien in einem Projekt, wie zum Beispiel einer .env-Datei, die Geheimnisse enthält. Unser Leitfaden „Was ist .env?“ behandelt genau das.

Grundlagen der YAML-Syntax mit einem Beispiel

Das Wichtigste auf einen Blick: Fast jede YAML-Datei besteht aus Schlüssel-Wert-Paaren, Einrückungen zur Verschachtelung und Bindestrichen für Listen.

Hier ist eine kurze YAML-Datei für eine fiktive Web-App. Jeder Teil davon wird im Folgenden erklärt.

# Settings for a small web app
app_name: recipe-finder
port: 8080
debug: false

database:
  host: localhost
  name: recipes

features:
  - search
  - favorites
  - shopping-list

welcome_message: |
  Welcome to Recipe Finder.
  Search by ingredient to get started.

Text benötigt normalerweise keine Anführungszeichen, aber du kannst jeden Wert in einfache oder doppelte Anführungszeichen setzen. Mit Anführungszeichen teilst du YAML mit, etwas als Text zu behandeln, wenn es wie eine Zahl oder ein Schalter aussieht (siehe den Abschnitt „Fehler“ weiter unten).

Die Einrückung bestimmt die Struktur. Eine Zeile, die unter einem Schlüssel eingerückt ist, gehört zu diesem Schlüssel, und Zeilen mit derselben Einrückung sind gleichrangig. Die genaue Anzahl der Leerzeichen bleibt dir überlassen, solange jede Ebene einheitlich ist. Zwei Leerzeichen pro Ebene sind eine gängige Wahl.

YAML vs. JSON

Das Wichtigste auf einen Blick: YAML und JSON können dieselben Informationen enthalten. YAML ist für Menschen leichter zu lesen und zu bearbeiten, während JSON strenger ist und häufiger für den Datenaustausch zwischen Programmen verwendet wird.

JSON ist ein weiteres Textformat für strukturierte Daten, das vor allem von Websites und APIs intensiv genutzt wird. Hier ist dieselbe App-Konfiguration wie oben, geschrieben als JSON:

{
  "app_name": "recipe-finder",
  "port": 8080,
  "debug": false,
  "database": {
    "host": "localhost",
    "name": "recipes"
  },
  "features": ["search", "favorites", "shopping-list"],
  "welcome_message": "Welcome to Recipe Finder.\nSearch by ingredient to get started.\n"
}

Beides hängt eng zusammen. YAML 1.2, die aktuelle Version der YAML-Spezifikation, wurde so konzipiert, dass JSON gültiges YAML ist. Deshalb akzeptieren manche Tools für dieselbe Datei beide Formate.

Warum dein YAML nicht funktioniert: häufige Fehler und wie man sie behebt

Das Wichtigste auf einen Blick: Die meisten YAML-Probleme sind Einrückungs- oder Leerzeichenfehler, und die schlimmsten davon lösen überhaupt keinen Fehler aus. Die Datei wird geladen, bedeutet aber etwas anderes als das, was du geschrieben hast.

Es gibt zwei Arten von YAML-Fehlern. Manche verhindern das Laden der Datei und zeigen eine Fehlermeldung an – das ist zwar ärgerlich, aber leicht zu erkennen. Andere werden ohne Probleme geladen und ändern still und leise deine Einstellungen, sodass die App mit Werten läuft, die du gar nicht festlegen wolltest. Wo es hilfreich ist, wird bei jedem der folgenden Fehler zuerst die fehlerhafte Version gezeigt, dann die Korrektur.

1. Tabulatoren statt Leerzeichen verwenden

YAML erlaubt keine Tabulatorzeichen zur Einrückung. Ein einziger Tabulator, der oft vom Editor hinzugefügt wird, ohne dass du es merkst, führt dazu, dass die gesamte Datei nicht geladen werden kann.

Lösung: Stelle deinen Editor so ein, dass beim Drücken der Tabulatortaste Leerzeichen eingefügt werden. Die meisten Code-Editoren verfügen über diese Einstellung, und viele wenden sie automatisch auf YAML-Dateien an.

2. Eine Zeile auf die falsche Ebene einrücken

Wenn eine Zeile eine Ebene zu weit links steht, gehört sie nicht mehr zur darüberliegenden Gruppe. YAML interpretiert sie als eigenständige Einstellung, ohne dass ein Fehler auftritt.

# Broken: name is no longer part of database
database:
  host: localhost
name: recipes

# Fixed
database:
  host: localhost
  name: recipes

Eine Zeile, die um ein Leerzeichen zu weit eingerückt ist, führt in der Regel zu einem Fehler, der oft mit „Mapping-Werte sind hier nicht erlaubt“ formuliert wird. Wenn du diese Meldung siehst, überprüfe die Einrückung der Zeile, auf die sie sich bezieht, sowie der Zeile darüber.

3. Das Leerzeichen nach einem Doppelpunkt oder Bindestrich vergessen

YAML benötigt ein Leerzeichen nach dem Doppelpunkt bei „Schlüssel: Wert“ und nach dem Bindestrich in einem Listenelement. Ohne dieses Leerzeichen interpretiert YAML den Text als normalen Text.

# Broken: read as one line of text, not a list
features:
  -search
  -favorites

# Fixed
features:
  - search
  - favorites

4. Verwendung eines Doppelpunkts innerhalb eines Werts

Ein Doppelpunkt, gefolgt von einem Leerzeichen innerhalb eines Werts, verwirrt YAML, da es wie der Beginn einer neuen Einstellung aussieht.

# Broken: fails to load
message: Note: restart the app after changes

# Fixed
message: "Note: restart the app after changes"

5. Werte, die YAML als etwas anderes interpretiert

YAML versucht zu erraten, welche Art von Wert du meinst, und manchmal liegt es dabei falsch. Das sind die klassischen Überraschungen:

Lösung: Setze Anführungszeichen um jeden Wert, der als Text erhalten bleiben soll, z. B. version: „1.10“ oder country: „NO“. Lass die Anführungszeichen bei Werten weg, die ein Tool als reelle Zahlen oder als „true“- und „false“-Schalter erwartet, wie z. B. eine Portnummer.

6. Wiederholung eines Schlüssels

Wenn derselbe Schlüssel zweimal auf derselben Ebene vorkommt, behalten viele Tools den letzten Wert bei und ignorieren den ersten, ohne dich darüber zu informieren. Strengere Tools brechen stattdessen mit einer Fehlermeldung ab.

port: 8080
# ...many lines later
port: 9090

Die App läuft auf Port 9090, und die erste Zeile wird stillschweigend ignoriert. Suche in einer langen Datei nach dem Schlüssel, bevor du ihn hinzufügst.

So überprüfst du eine YAML-Datei, bevor du sie verwendest

Das Wichtigste: Lass deine YAML-Datei von einem Tool prüfen. Eine Editor-Erweiterung erkennt Fehler schon beim Tippen, und ein Validator überprüft die gesamte Datei, bevor du dich darauf verlässt.

Es gibt drei gängige Methoden, eine YAML-Datei zu überprüfen, von der einfachsten bis zur gründlichsten:

1. Verwende einen Editor, der YAML versteht. Editoren zum Programmieren wie Visual Studio Code verfügen über YAML-Erweiterungen, die Fehler während der Eingabe unterstreichen. Einige kennen auch das erwartete Layout bestimmter Dateien und schlagen dir beim Schreiben gültige Einstellungen vor.
2. Führe einen Linter aus. Ein Linter ist ein kleines Programm, das eine Datei ausliest und Probleme meldet. „yamllint“ ist eine kostenlose open source-Option für YAML, die sowohl Stilprobleme wie inkonsistente Einrückungen als auch eindeutige Fehler kennzeichnet.
3. Nutze den Checker, der zu deinem Tool gehört. Viele Tools können ihre eigenen Konfigurationsdateien überprüfen, wodurch Fehler erkannt werden, die ein allgemeiner YAML-Checker nicht findet, wie zum Beispiel eine Einstellung mit falschem Namen.

Online-YAML-Validatoren funktionieren ebenfalls, aber sei vorsichtig damit, was du dort einfügst. Konfigurationsdateien enthalten manchmal Passwörter oder interne Adressen, und diese sollten nicht auf einer Website landen, die du nicht kontrollierst.

Wenn ein KI-Assistent die Datei erstellt hat, überprüfe sie auf dieselbe Weise. Von KI generiertes YAML hat oft eine gültige Syntax, sodass es fehlerfrei geladen wird. Die Fehler liegen stattdessen meist im Inhalt: ein Einstellungsname, den das Tool nicht erkennt, eine Option aus einer älteren Version des Tools oder ein Wert auf der falschen Ebene. Der tool-eigene Checker (Option 3 oben) ist am ehesten in der Lage, diese Fehler zu erkennen.

YAML auf Upsun Cloud: Eine echte Konfigurationsdatei lesen

Das Wichtigste auf einen Blick: Upsun Cloud beschreibt ein gesamtes Projekt in einer einzigen YAML-Datei, .upsun/config.yaml, und sein Befehlszeilentool kann diese Datei vor dem Deployment überprüfen.

Auf der Upsun Cloud befinden sich die von dir ausgeführten Apps, die von ihnen genutzten Dienste (wie z. B. eine Datenbank) und die Webadressen, über die sie erreichbar sind, alle in einer einzigen YAML-Datei. Diese befindet sich in einem Ordner namens .upsun ganz oben in deinem Projekt. Mit dem Befehl „upsun project:init“ wird eine Startversion erstellt, die auf dem gefundenen Code basiert.

Hier ist ein kleines Beispiel: eine Node.js-App, die mit einer PostgreSQL-Datenbank verbunden ist.

applications:
  myapp:
    type: "nodejs:26"
    relationships:
      database:
    web:
      commands:
        start: "node index.js"

services:
  database:
    type: "postgresql:17"

routes:
  "https://{default}/":
    type: upstream
    upstream: "myapp:http"

Hier ist die Funktion der einzelnen Teile:

• Die Datei enthält drei Schlüssel auf oberster Ebene: „applications“, „services“ und „routes“ – genau die Struktur, die Upsun Cloud erwartet.
• Unter „applications“ läuft eine App namens „myapp“ auf Node.js 26 und wird mit dem Befehl „node index.js“ gestartet.
• Unter „services“ ist eine PostgreSQL-17-Datenbank mit dem Namen „database“ hinterlegt.
• Der Eintrag „relationships“ verbindet die App mit dieser Datenbank. Der Name „database“ muss an beiden Stellen übereinstimmen. Wenn einer falsch geschrieben ist, kann die App ihre Datenbank nicht finden.
• Unter „routes“ wird der Web-Traffic an die Adresse des Projekts an „myapp“ weitergeleitet.

Die oben genannten häufigen Fehler gelten auch hier. Eine falsch gesetzte Einrückung kann dazu führen, dass Beziehungen aus dem Bereich unter „myapp“ verschoben werden. Die Anführungszeichen in diesem Beispiel sind optional, aber es ist eine sichere Vorgehensweise, Werte, die Doppelpunkte oder geschweifte Klammern enthalten, in Anführungszeichen zu setzen.

Um die Datei vor dem Push zu überprüfen, führe „upsun app:config-validate“ in deinem Projektordner aus. Damit werden die Konfigurationsdateien deines Projekts validiert, sodass Fehler bereits auf deinem Rechner sichtbar werden, bevor eine Bereitstellung erfolgt. Wenn ein Programmier-Agent diese Datei für dich bearbeitet, weise ihn an, nach jeder Änderung denselben Befehl auszuführen. Unser Leitfaden „Was ist eine AGENTS.md-Datei?“ zeigt, wie du diese Anweisung einmal festlegst, damit jeder Agent sie befolgt. Du kannst deinen Editor auch mit dem veröffentlichten Schema von Upsun Cloud verbinden, sodass er dir während der Eingabe gültige Einstellungen vorschlägt und Fehler markiert. Im Upsun Developer Center wird erklärt, wie du das einrichtest.

Was die Datei alles enthalten kann, erfährst du unter „YAML auf Upsun cloud“ in der Upsun-Dokumentation.

Auf der Upsun Cloud beschreibt diese eine Datei dein gesamtes Projekt, und jede Umgebung wird darauf aufbauend erstellt. Du kannst 15 Tage lang kostenlos auf der Upsun Cloud bereitstellen, ganz ohne Kreditkarte, oder dir ansehen, wie Git-gesteuerte Automatisierung Konfigurationsänderungen in Bereitstellungen umsetzt.

Häufig gestellte Fragen (FAQ)

Wofür steht YAML?

YAML steht für „YAML Ain’t Markup Language“. Der Name verdeutlicht, dass YAML dazu dient, Daten wie Einstellungen und Listen zu beschreiben, und nicht dazu, Dokumente zu formatieren.

Was ist der Unterschied zwischen .yaml und .yml?

Gar nichts. Beide Dateiendungen bezeichnen dasselbe Format. Manche Tools erwarten die eine oder die andere Endung – verwende also die, die in der Dokumentation des Tools angegeben ist.

Kann man in YAML Tabulatoren verwenden?

Nein. YAML erlaubt nur Leerzeichen zur Einrückung. Stelle deinen Editor so ein, dass beim Drücken der Tabulatortaste Leerzeichen eingefügt werden.

Mit wie vielen Leerzeichen soll ich YAML einrücken?

Jede Anzahl ist in Ordnung, solange die Einrückung auf jeder Ebene einheitlich ist. Zwei Leerzeichen pro Ebene sind eine gängige Wahl.

Warum erscheint in meinem YAML die Meldung „Mapping-Werte sind hier nicht erlaubt“?

Dieser Fehler bedeutet normalerweise, dass eine Zeile anders eingerückt ist als die benachbarten Zeilen oder dass ein Wert einen Doppelpunkt gefolgt von einem Leerzeichen enthält. Überprüfe die Einrückung der Zeile, auf die der Fehler hinweist, und setze alle Werte, die einen Doppelpunkt enthalten, in Anführungszeichen.

Ist YAML besser als JSON?

Keines von beiden ist generell besser. YAML ist für Menschen leichter zu lesen und zu bearbeiten, was sich gut für Konfigurationsdateien eignet. JSON ist strenger und für Programme einfacher zu erzeugen, was sich gut für Daten eignet, die zwischen Systemen ausgetauscht werden.

Wie öffne ich eine YAML-Datei?

Jeder Texteditor kann sie öffnen, da eine YAML-Datei aus reinem Text besteht. Ein Editor zum Programmieren mit YAML-Unterstützung erleichtert das Lesen und das Erkennen von Fehlern.