YAML-Grundlagen

Einrückung ist die Syntax

In YAML ist Leerraum keine Dekoration – er ist die gesamte Struktur. Ein Mapping besteht aus einem Schlüssel, einem Doppelpunkt, einem Leerzeichen und dann dem Wert; ein verschachtelter Wert steht in der nächsten Zeile, weiter eingerückt, und zwei Zeilen mit derselben Einrückung sind Geschwister. Tabs sind kategorisch verboten: Der Standard kann sich nicht festlegen, wie breit ein Tab ist, also lehnen Parser sie ab, statt zu raten. Editoren fügen beim Kopieren und Einfügen gern Tabs ein – deshalb sehen so viele Dateien perfekt aus und wollen trotzdem nicht parsen.

Die Konvention sind zwei Leerzeichen pro Ebene. Vier oder sechs sind genauso gültig – der Standard verbietet nur Tabs –, aber zwei verwenden Kubernetes und Compose, zwei erwartet jeder Linter, und zwei hält tiefe Manifeste davon ab, seitlich wegzuscrollen. Mischen Sie Breiten innerhalb einer Datei, entstehen Einrückungsfehler; entscheiden Sie sich für zwei und lassen Sie den Editor das durchsetzen.

• Eine Ebene = eine feste Leerzeichenanzahl; zwei ist die Konvention.
• Tabs in der Einrückung werden von Parsern abgelehnt, nicht umgewandelt.
• Ein Sequenzeintrag darf auf der Einrückung seines übergeordneten Schlüssels liegen – der Strich ist das Markierungszeichen.
• Werte lassen sich auch inline im Flow-Stil schreiben: ports: [8080].

services:
  web:
    image: nginx:1.27
    ports:
      - "8080:80"
  cache:
    image: redis:7

services
├─ web
│  ├─ image: "nginx:1.27"
│  └─ ports: ["8080:80"]
└─ cache
   └─ image: "redis:7"

Skalare und das Norwegen-Problem

Werte in Anführungszeichen sind immer Zeichenketten. Werte ohne Anführungszeichen werden per Inferenz typisiert, und genau diese Inferenz hat YAMLs Ruf begründet: Ein nacktes 8080 wird zur Zahl 8080, ein leerer Wert wird zu null – praktisch, bis die Inferenz etwas typisiert, das Sie als Text gemeint haben, etwa einen Ländercode oder eine Versionszeichenkette.

Der klassische Ausfall ist eine Liste von ISO-Ländercodes, in der NO – Norwegen – als boolesch false geparst wird: das Norwegen-Problem, lustig, bis es still und leise ein Deployment-Flag deaktiviert. Version 1.1 ging deutlich weiter, wie die Tabelle zeigt. Das 1.2-Core-Schema löst nur true und false als boolesche Werte auf und liest alles Übrige in der Tabelle unten als schlichte Zeichenketten oder Dezimalzahlen – doch weil so viel eingesetzte Software weiterhin nach 1.1-Regeln arbeitet, lautet die defensive Gewohnheit: alles quoten, was eine Zeichenkette bleiben muss.

Anführungszeichen und Blockskalare

YAML bietet drei Wege, eine Zeichenkette zu schreiben. Ohne Anführungszeichen ist der Standard und für die meisten Werte in Ordnung. Einfache Anführungszeichen sind literal – das einzige Escape ist das Verdoppeln eines Apostrophs ('it''s fine'). Doppelte Anführungszeichen unterstützen Backslash-Escapes wie \n und \t, den Stil, den JSON verwendet. Die defensive Regel gilt hier genauso: Enthält ein Wert etwas, das man für Struktur halten könnte – Doppelpunkte, Rauten, reservierte Wörter –, setzen Sie ihn gezielt in Anführungszeichen.

Mehrzeiligen Text bringen Blockskalare unter. Ein literaler Block, geschrieben als |, behält jeden Zeilenumbruch exakt so, wie er getippt wurde – die richtige Form für Shell-Skripte und Zertifikate. Ein gefalteter Block, geschrieben als >, fügt die Zeilen zu einem durchlaufenden Absatz zusammen – die richtige Form für eine lange Beschreibung. Beide akzeptieren eine Chomping-Angabe: |- entfernt den letzten Zeilenumbruch, |+ behält alle abschließenden, und ein schlichtes | behält genau einen.

script: |
  set -e
  make build
  make deploy

summary: >
  Deploys finish
  in under a minute.

script:   "set -e\nmake build\nmake deploy\n"
summary:  "Deploys finish in under a minute.\n"

Anker, Aliasse und Wiederverwendung

YAML erlaubt einem Knoten, einen Namen zu tragen, auf den andere Knoten verweisen. Schreiben Sie &name hinter einen Schlüssel, um dessen Wert zu ankern; schreiben Sie *name an einer beliebigen anderen Stelle, um ihn zu aliasieren, und der Parser setzt eine Kopie des verankerten Knotens ein. Jobs, die sich eine Retry-Policy teilen, verweisen dann auf eine einzige Definition, und die Änderung landet genau einmal.

Zwei Erweiterungen setzen auf diesem Mechanismus auf. Merge-Keys, geschrieben als <<: *name, fügen alle Schlüssel eines verankerten Mappings in das aktuelle ein – verbreitet in Compose- und Ansible-Dateien, und eine Konvention aus der 1.1-Ära, die nie Eingang in die 1.2-Core-Grammatik fand. Anker lassen sich auch missbrauchen: Aliasse, die in Aliassen verschachtelt sind, lassen zehn Definitionen zu einer Million Knoten anwachsen – der Billion-Laughs-Angriff –, deshalb budgetieren Parser, denen Sie vertrauen, die Expansion und melden die Obergrenze, statt sich aufzuhängen.

defaults: &base
  retries: 3
  timeout: 30s

staging:
  retries: 3
  timeout: 30s
  log: *base

defaults:  { retries: 3, timeout: "30s" }
log alias: { retries: 3, timeout: "30s" }   (staging.log)

Kommentare und mehrere Dokumente

Kommentare beginnen mit # und reichen bis zum Zeilenende; eine Raute innerhalb einer quotierten Zeichenkette zählt nicht. Das ist YAMLs größter ergonomischer Vorsprung gegenüber JSON, das Kommentare mit Absicht gestrichen hat, und der Grund, warum von Hand gepflegte Konfiguration hierher driftet: Die Datei erklärt sich inline selbst, und in Reviews stehen eine Zeile und ihr Kommentar gemeinsam in einem Diff-Hunk.

Eine Datei darf auch mehrere Dokumente enthalten, getrennt durch Zeilen mit drei Strichen; ein führendes --- ist die optionale Startmarkierung, und ... beendet ein Dokument. So trägt ein einziges Artefakt eine Staging-Konfiguration und eine Produktivkonfiguration nebeneinander her. Die Konverter dieser Website parsen jedes Dokument und arbeiten auf dem letzten – wie gängige CLIs es auch tun.

env: staging
region: eu-1
---
env: production
region: us-2

env: production
region: us-2   (the last document)

Was die Konverter dieser Website akzeptieren

Jeder YAML-Parser ist ein Parser einer Teilmenge – die vollständige 1.2-Grammatik ist notorisch groß –, und ein Konverter gewinnt Vertrauen, indem er seine Teilmenge benennt, statt Sie beim Scheitern darüber aufklären zu lassen. Die YAML-Bibliothek dieser Website implementiert das 1.2-Core-Schema über die Block- und Flow-Konstrukte, die in echten Konfigurationsdateien vorkommen, mit bewussten Grenzen dort, wo der Standard unbegrenzte Arbeit erlaubt. Die Tabelle ist der Vertrag.