YAML-Syntax verstehen: Einrückung, Listen, Datentypen

YAML steht für “YAML Ain’t Markup Language” und wurde entworfen, um Konfigurationsdaten für Menschen gut lesbar zu machen. Statt geschweifter Klammern und Anführungszeichen wie bei JSON verwendet YAML Einrückung und einfache Zeichen. Das Ergebnis liest sich fast wie eine Notiz, hat aber eine strenge Struktur dahinter. Genau diese Mischung macht YAML angenehm zu lesen und gleichzeitig überraschend fehleranfällig, wenn du die Regeln nicht kennst.

In diesem Ratgeber gehst du Schritt für Schritt durch die Bausteine der YAML-Syntax: Einrückung, Schlüssel-Wert-Paare, Listen, verschachtelte Strukturen, Datentypen, mehrzeilige Strings sowie Anchor und Alias. Am Ende kennst du die häufigsten Stolperfallen und weißt, wie du sie vermeidest.

Das Grundprinzip: Einrückung

YAML gruppiert Daten über Einrückung. Was zusammengehört, steht auf der gleichen Einrückungsebene. Dabei gilt eine harte Regel: Du darfst ausschließlich Leerzeichen benutzen, niemals Tabs. Die YAML-Spezifikation verbietet Tabs zur Einrückung ausdrücklich, weil unterschiedliche Editoren Tabs verschieden breit darstellen und die Struktur dann mehrdeutig würde.

server:
  host: localhost
  port: 8080
  optionen:
    timeout: 30
    retries: 3

Hier siehst du drei Ebenen. Üblich sind zwei Leerzeichen pro Ebene, aber die genaue Anzahl ist dir überlassen, solange du innerhalb einer Struktur konsistent bleibst. Wichtig ist nur: Alle Schlüssel auf derselben Ebene brauchen exakt dieselbe Einrückung.

Schlüssel-Wert-Paare

Der grundlegende Baustein ist das Schlüssel-Wert-Paar (auf Englisch key-value pair). Es besteht aus einem Schlüssel, einem Doppelpunkt, einem Leerzeichen und dem Wert:

name: Anna Schmidt
alter: 34
aktiv: true

Das Leerzeichen nach dem Doppelpunkt ist Pflicht. Schreibst du alter:34 ohne Leerzeichen, interpretiert der Parser das nicht als Schlüssel-Wert-Paar, sondern als einen einzigen Textwert. Der Schlüssel steht dabei links, der Wert rechts vom Doppelpunkt.

Listen

Listen (auch Arrays oder Sequenzen genannt) schreibst du in YAML mit einem Bindestrich gefolgt von einem Leerzeichen. Jedes Element steht in einer eigenen Zeile:

sprachen:
  - Deutsch
  - Englisch
  - Polnisch

Es gibt auch eine kompakte Inline-Schreibweise mit eckigen Klammern, die genau wie in JSON aussieht:

sprachen: [Deutsch, Englisch, Polnisch]

Beide Varianten ergeben dasselbe Ergebnis. Die Bindestrich-Notation ist besser lesbar bei längeren oder verschachtelten Listen, die Inline-Variante spart Platz bei kurzen Aufzählungen. Eine Liste kann auch aus komplexen Objekten bestehen:

mitarbeiter:
  - name: Anna
    rolle: Entwicklerin
  - name: Ben
    rolle: Designer

Jeder Bindestrich beginnt hier ein neues Objekt. Die Schlüssel name und rolle gehören zum jeweiligen Listenelement, erkennbar an der Einrückung relativ zum Bindestrich.

Verschachtelte Strukturen

YAML lässt sich beliebig tief verschachteln. Du kombinierst dazu einfach Objekte und Listen über die Einrückung. Wenn du unsicher bist, wie sich diese Strukturen zu JSON verhalten, hilft dir der Ratgeber zu den JSON-Struktur-Grundlagen weiter, denn beide Formate bilden dieselben Datenmodelle ab.

projekt:
  name: Website-Relaunch
  team:
    - name: Anna
      aufgaben:
        - Design
        - Frontend
    - name: Ben
      aufgaben:
        - Backend
  budget:
    geplant: 50000
    verbraucht: 32000

Hier findest du Objekte in Listen und Listen in Objekten, alles über konsistente Einrückung organisiert. Solange die Einrückung stimmt, bleibt die Struktur eindeutig.

Skalare Datentypen

Einzelne Werte nennt man in YAML Skalare. YAML erkennt den Typ eines Werts anhand seines Aussehens automatisch, ohne dass du ihn deklarierst. Das ist bequem, aber auch eine Quelle für Überraschungen (mehr dazu weiter unten).

text: Hallo Welt
ganzzahl: 42
kommazahl: 3.14
wahrheitswert: true
leer: null
datum: 2026-07-03
gequotet: "42"

Beachte die letzte Zeile: Setzt du einen Wert in Anführungszeichen, behandelt YAML ihn als Text, auch wenn er wie eine Zahl aussieht. gequotet ist also der String 42, nicht die Zahl 42. Sowohl einfache ('...') als auch doppelte ("...") Anführungszeichen sind erlaubt. Innerhalb doppelter Anführungszeichen kannst du Escape-Sequenzen wie \n verwenden, innerhalb einfacher nicht.

Die folgende Tabelle fasst die wichtigsten Skalar-Typen zusammen:

Typ	Beispielwerte	Hinweis
String	Hallo, "42", 'Text'	ohne Quotes oft ausreichend, Quotes bei Sonderfällen
Ganzzahl	42, -7, 0xFF	Dezimal, negativ oder hexadezimal
Kommazahl	3.14, -0.5, 1e3	Punkt als Dezimaltrenner
Boolean	true, false	in YAML 1.1 auch yes, no, on, off
null	null, ~, leerer Wert	steht für “kein Wert”
Datum	2026-07-03	ISO-8601-Format, wird als Zeitstempel erkannt

Mehrzeilige Strings

Für längere Textblöcke bietet YAML zwei Block-Scalar-Stile, die du an einem einzelnen Zeichen nach dem Schlüssel erkennst.

Der Literal-Stil mit dem senkrechten Strich (|) bewahrt alle Zeilenumbrüche genau so, wie du sie schreibst:

gedicht: |
  Rosen sind rot,
  Veilchen sind blau,
  YAML ist lesbar,
  das weiß ich genau.

Der Folded-Stil mit dem Größer-als-Zeichen (>) faltet einzelne Zeilenumbrüche zu Leerzeichen zusammen, sodass ein fortlaufender Absatz entsteht. Nur Leerzeilen erzeugen echte Umbrüche:

beschreibung: >
  Dieser Text wird zu einer
  einzigen langen Zeile
  zusammengefügt.

Bei beiden Stilen kannst du das Verhalten am Ende steuern. Ein angehängtes - (etwa |-) entfernt den abschließenden Zeilenumbruch, ein + (etwa |+) behält alle folgenden Leerzeilen. Die folgende Tabelle stellt die Stile gegenüber:

Stil	Zeichen	Zeilenumbrüche	typischer Einsatz
Literal	`	`	bleiben erhalten
Folded	>	werden zu Leerzeichen gefaltet	Fließtext, lange Beschreibungen
Literal ohne Endumbruch	|-	erhalten, letzter Umbruch entfernt	einzeilige Ausgabe ohne Zeilenende
Folded mit Endumbruch	>+	gefaltet, Endzeilen behalten	wenn abschließende Leerzeilen zählen

Anchor, Alias und Merge

YAML kann Wiederholungen vermeiden. Mit einem Anchor (&) markierst du einen Wert und mit einem Alias (*) verweist du später darauf. So schreibst du dieselben Daten nur einmal:

standard: &basis
  region: eu-central
  timeout: 30

server_a:
  <<: *basis
  host: a.example.de

server_b:
  <<: *basis
  host: b.example.de

Der Anchor &basis benennt das Objekt unter standard. Der Merge-Key (<<) zusammen mit dem Alias *basis fügt dessen Inhalt in server_a und server_b ein, wo du dann nur noch den abweichenden Wert host ergänzt. Anchor und Alias funktionieren auch für einzelne Skalare:

haupt-email: &kontakt info@example.de
antwort-an: *kontakt

Ein wichtiger Hinweis: JSON kennt weder Anchor noch Alias noch Merge-Keys. Wenn du solche YAML-Dateien nach JSON umwandelst, werden die Referenzen aufgelöst und dupliziert. Details und weitere Konvertierungs-Themen findest du im Ratgeber zu den Fallstricken bei der JSON-YAML-Konvertierung.

Kommentare und Dokument-Trenner

Kommentare beginnst du mit einem Rautezeichen (#). Alles danach bis zum Zeilenende ignoriert der Parser:

# Server-Konfiguration
port: 8080  # Standard-Port für HTTP-Alternative

Auch das ist ein deutlicher Unterschied zu JSON, das offiziell keine Kommentare erlaubt. Wer die Formate grundsätzlich vergleichen möchte, findet die Gegenüberstellung im Ratgeber JSON gegen YAML im Vergleich.

Mehrere YAML-Dokumente kannst du in einer einzigen Datei ablegen und mit drei Bindestrichen (---) trennen. Drei Punkte (...) markieren optional das Ende eines Dokuments:

---
umgebung: entwicklung
debug: true
---
umgebung: produktion
debug: false
...

Häufige Stolperfallen

YAML ist lesbar, aber es hat einige Fallen, in die fast jeder einmal tappt. Diese solltest du kennen.

Tabs sind verboten. Die häufigste Fehlerquelle überhaupt. Viele Editoren fügen beim Drücken der Tab-Taste ein echtes Tabulatorzeichen ein, das YAML strikt ablehnt. Stelle deinen Editor so ein, dass Tab automatisch Leerzeichen erzeugt.

Inkonsistente Einrückung. Mischst du innerhalb einer Struktur zwei und vier Leerzeichen, gerät die Zuordnung durcheinander oder der Parser bricht mit einem Fehler ab. Bleibe pro Datei bei einer Einrückungstiefe.

Ungequotete Sonderwerte werden zu Booleans. Nach der älteren, sehr verbreiteten YAML-1.1-Regel werden yes, no, on und off (ebenso true und false) automatisch zu Wahrheitswerten. Wenn du also ein Länderkürzel NO für Norwegen oder eine Antwort yes als Text meinst, wird daraus ungewollt ein Boolean. Die Lösung: Setze solche Werte in Anführungszeichen.

# ungewollt: wird zu Boolean false
antwort: no

# richtig: bleibt Text
antwort: "no"
land: "NO"

Doppelpunkt in Werten. Enthält ein Wert selbst einen Doppelpunkt gefolgt von einem Leerzeichen, kann der Parser ihn als neues Schlüssel-Wert-Paar missverstehen. Ein Uhrzeit- oder URL-artiger Wert braucht dann Anführungszeichen:

# problematisch
titel: Kapitel 1: Der Anfang

# sicher
titel: "Kapitel 1: Der Anfang"
zeit: "12:30"

Führende Nullen und Sonderzeichen. Ein Wert wie 08 kann je nach Parser als Oktalzahl fehlinterpretiert werden, und Werte, die mit @, ` oder % beginnen, sind ohne Quotes reserviert. Im Zweifel quotest du solche Werte.

So prüfst du deine YAML-Syntax live

Der schnellste Weg, diese Stolperfallen zu erkennen, ist Ausprobieren. Auf jsonyaml.de kannst du deine YAML-Datei einfügen und die Ausgabe live prüfen. Der Konverter läuft komplett lokal in deinem Browser, es wird also nichts hochgeladen. Bei einem Syntaxfehler bekommst du eine Meldung mit Zeilennummer, sodass du die fehlerhafte Einrückung oder das vergessene Anführungszeichen sofort findest. Gerade bei den Boolean- und Doppelpunkt-Fallen siehst du dann direkt, ob dein Wert als Text oder als Zahl beziehungsweise Wahrheitswert interpretiert wurde.

Wenn du die Grundregeln aus diesem Ratgeber verinnerlichst (nur Leerzeichen, konsistente Einrückung, Sonderwerte quoten), schreibst du YAML, das sowohl für Menschen als auch für Parser sauber lesbar ist.

Hast du einen Fehler entdeckt oder einen Quellen-Hinweis für uns? Schreib gern an info@akara-solutions.de.