Formatierer

YAML-Grundlagen: Syntax, Einrückung, Listen und Objekte

Zuletzt aktualisiert am

YAML ist ein textbasiertes Datenformat für Konfigurationsdateien, etwa für Docker Compose, GitHub Actions oder Kubernetes. Die Syntax besteht aus wenigen Bausteinen: Schlüssel-Wert-Paare (Mappings), Listen (Sequenzen) und einfache Werte (Skalare). Die Struktur ergibt sich allein aus der Einrückung mit Leerzeichen. Dieser Ratgeber zeigt jeden Baustein mit Beispiel.

Ob deine Datei gültig und sauber eingerückt ist, siehst du im YAML-Formatierer: Er rückt neu ein und behält deine Kommentare. Wie die Daten als JSON aussehen, zeigt der YAML-zu-JSON-Konverter. Beide arbeiten komplett lokal im Browser, es wird nichts an einen Server gesendet.

Mappings: Schlüssel und Werte

Ein Mapping ist eine Sammlung von Schlüssel-Wert-Paaren, vergleichbar mit einem JSON-Objekt. Schlüssel und Wert trennt ein Doppelpunkt mit anschließendem Leerzeichen:

name: Ada
alter: 36
aktiv: true

Das entspricht diesem JSON:

{ "name": "Ada", "alter": 36, "aktiv": true }

Ohne Leerzeichen nach dem Doppelpunkt (name:Ada) ist es kein Mapping, sondern ein einzelner Text.

Verschachtelung durch Einrückung

Wo JSON geschweifte Klammern nutzt, nutzt YAML Einrückung. Alles, was unter einem Schlüssel weiter eingerückt steht, gehört zu ihm:

server:
  host: localhost
  port: 8080

Die Regeln:

  • Nur Leerzeichen, keine Tabs. Tabs sind in YAML zur Einrückung nicht erlaubt. Stelle deinen Editor so ein, dass die Tab-Taste Leerzeichen einfügt.
  • Die Tiefe ist frei wählbar, üblich sind zwei Leerzeichen. Entscheidend ist, dass Einträge auf derselben Ebene exakt gleich weit eingerückt sind.
  • Eine falsche Einrückung führt meist zu einem Fehler, manchmal aber still zu einer anderen Struktur: Rückst du port ganz an den Zeilenanfang, gehört es nicht mehr zu server, sondern steht auf der obersten Ebene. Typische Fehlermeldungen und ihre Lösung stehen im Ratgeber YAML-Fehler.

Listen (Sequenzen)

Ein Listeneintrag beginnt mit einem Bindestrich und einem Leerzeichen:

sprachen:
  - Deutsch
  - Englisch

In JSON: { "sprachen": ["Deutsch", "Englisch"] }. Listeneinträge können selbst Mappings sein. Dann beginnt das Mapping hinter dem Bindestrich, und die folgenden Schlüssel stehen bündig darunter:

nutzer:
  - name: Ada
    rolle: admin
  - name: Linus
    rolle: dev

Skalare und Anführungszeichen

Texte brauchen in YAML meist keine Anführungszeichen. Aus unquotierten Werten leitet ein Parser den Typ ab: true und false werden zu Booleans, null und ~ zu null, 42 und 3.14 zu Zahlen, der Rest zu Text.

Anführungszeichen setzt du, wenn ein Wert sonst falsch gelesen würde:

version: "3.10"      # Text; ohne Anführungszeichen wäre es die Zahl 3.1
plz: "01067"         # führende Null bleibt erhalten
titel: "Hallo: Welt" # Doppelpunkt mit Leerzeichen im Wert
  • Doppelte Anführungszeichen kennen Escape-Sequenzen wie \n, \t und \".
  • Einfache Anführungszeichen interpretieren nichts; ein einfaches Anführungszeichen im Text schreibst du doppelt: 'it''s'.

Achtung bei Wörtern wie yes, no, on und off: YAML 1.1 liest sie als Booleans, YAML 1.2 nicht mehr. Welche Version ein Programm umsetzt, unterscheidet sich je nach Bibliothek. Im Zweifel setzt du Anführungszeichen. Ein bekannter Fall steht im Ratgeber Norway-Problem. Mehrzeilige Texte mit | und > erklärt der Ratgeber Mehrzeilige Strings in YAML.

Kommentare

Ein Kommentar beginnt mit # und reicht bis zum Zeilenende. Hinter einem Wert muss vor dem # ein Leerzeichen stehen:

# Server-Einstellungen
port: 8080  # Standardport

Das ist ein großer Vorteil gegenüber JSON, das keine Kommentare kennt (siehe Kommentare in JSON). Beim Umwandeln nach JSON gehen Kommentare allerdings verloren, weil JSON sie nicht speichern kann.

Mehrere Dokumente in einer Datei

Drei Bindestriche --- trennen mehrere YAML-Dokumente in einer Datei. Kubernetes-Manifeste nutzen das oft:

---
kind: ConfigMap
metadata:
  name: a
---
kind: Service
metadata:
  name: b

Ein JSON-Dokument kann nur einen Wert enthalten. Wandle die Dokumente deshalb einzeln um, oder fasse sie selbst in einer Liste zusammen.

Anker und Aliase

Mit einem Anker &name markierst du einen Wert, mit einem Alias *name verwendest du ihn erneut. Das vermeidet Wiederholungen:

standard: &standard
  retries: 3
  timeout: 30

dienst_a: *standard
dienst_b:
  <<: *standard
  timeout: 60

dienst_a ist eine Kopie von standard. Der Merge-Key << übernimmt alle Einträge des Ankers in ein Mapping; Einträge, die du selbst angibst, überschreiben sie. Der Anker muss vor dem Alias stehen. Der Merge-Key stammt aus YAML 1.1 und ist nicht Teil der YAML-1.2-Kernspezifikation, wird aber von den meisten Bibliotheken unterstützt.

JSON hat nichts Vergleichbares. Der YAML-zu-JSON-Konverter löst Anker, Aliase und Merge-Keys deshalb auf und schreibt die Werte aus.

Flow-Stil: {} und []

YAML darf auch wie JSON geschrieben werden, mit geschweiften und eckigen Klammern:

punkt: { x: 1, y: 2 }
tags: [web, api, "v2"]

Das ist praktisch für kurze Einträge. Jedes gültige JSON ist (bis auf wenige Randfälle) zugleich gültiges YAML, die Umkehrung gilt nicht. Mehr dazu im Vergleich JSON vs. YAML.

Beispiel: Docker Compose

Alles zusammen in einer realistischen Datei:

x-defaults: &defaults
  restart: unless-stopped
  environment:
    TZ: Europe/Berlin

services:
  web:
    <<: *defaults
    image: nginx:1.27
    ports:
      - "8080:80"
  worker:
    <<: *defaults
    image: meine-app:latest
    command: ["node", "worker.js"]

Die Ports stehen in Anführungszeichen, wie es die Docker-Dokumentation empfiehlt: Ein Wert wie 22:22 wäre für einen YAML-1.1-Parser sonst eine Zahl zur Basis 60 (1342). Mit Anführungszeichen ist jeder Port sicher ein Text. Als JSON sieht dieselbe Datei so aus; die Merge-Keys sind aufgelöst:

{
  "x-defaults": {
    "restart": "unless-stopped",
    "environment": { "TZ": "Europe/Berlin" }
  },
  "services": {
    "web": {
      "restart": "unless-stopped",
      "environment": { "TZ": "Europe/Berlin" },
      "image": "nginx:1.27",
      "ports": ["8080:80"]
    },
    "worker": {
      "restart": "unless-stopped",
      "environment": { "TZ": "Europe/Berlin" },
      "image": "meine-app:latest",
      "command": ["node", "worker.js"]
    }
  }
}

Die Reihenfolge der Schlüssel nach dem Auflösen kann je nach Programm abweichen; inhaltlich ist das Ergebnis gleich.

Kurz gesagt

  • YAML besteht aus Mappings (schluessel: wert), Listen (- eintrag) und Skalaren; die Struktur entsteht durch Einrückung.
  • Rücke nur mit Leerzeichen ein, nie mit Tabs, und halte Einträge einer Ebene exakt bündig.
  • Setze Werte wie "3.10", "01067" oder Ports wie "22:22" in Anführungszeichen, wenn sie Text bleiben sollen.
  • # leitet Kommentare ein, --- trennt Dokumente, &, * und << vermeiden Wiederholungen.
  • Prüfe und formatiere deine Datei im YAML-Formatierer oder wandle sie mit dem YAML-zu-JSON-Konverter um.

Weiterlesen: JSON vs. YAML, YAML-Fehler, Mehrzeilige Strings in YAML. Einzelne Fehlermeldungen: „found character that cannot start any token“ und „could not find expected ':'“.