YAML

1. Aufbau

Namen, Werte und Einrückung

# Ein Film, wie in der Filmdatenbank
title: Nosferatu
year: 1922
watched: true
rating: null
director:
  name: F. W. Murnau
  born: 1888

• Jede Zeile name: wert ist ein Eintrag. Nach dem Doppelpunkt kommt ein Leerzeichen.
• Was zu einem Eintrag gehört, ist eingerückt, hier name und born unter director. Die Einrückung ist die Struktur: Wie viele Leerzeichen, ist egal, aber alle Einträge einer Ebene stehen genau untereinander.
• Eingerückt wird nur mit Leerzeichen, nie mit Tab.
• # beginnt einen Kommentar bis zum Ende der Zeile.
• Texte brauchen meist keine Anführungszeichen. Zahlen, true, false und null (auch ~) erkennt YAML selbst.

Listen

genres:
  - Horror
  - Fantasy
cast:
  - name: Max Schreck
    role: Graf Orlok
  - name: Greta Schröder
    role: Ellen

Jeder Eintrag einer Liste beginnt mit -. Ein Eintrag kann selbst ein Objekt sein; seine weiteren Zeilen stehen dann unter dem ersten Namen (role unter name). Kurze Listen und Objekte gehen auch in einer Zeile, wie in JSON:

genres: [Horror, Fantasy]
director: {name: F. W. Murnau, born: 1888}

Texte und lange Texte

Anführungszeichen braucht ein Text, wenn er mit einem Zeichen beginnt, das YAML etwas bedeutet ([, {, -, *, &, !, %, @), wenn : oder # darin vorkommt, oder wenn er sonst als Zahl oder Wahrheitswert gelesen würde (siehe Fallen):

title: "Mein Film: Teil 2"
tag: "#horror"
version: "1.10"

Für Text über mehrere Zeilen gibt es zwei Zeichen:

gedicht: |
  Die Zeilenumbrüche
  bleiben, wie sie sind.
beschreibung: >
  Diese Zeilen werden
  zu einem Absatz zusammengefügt.

| behält jeden Zeilenumbruch, > macht aus einfachen Umbrüchen Leerzeichen; eine leere Zeile beginnt einen neuen Absatz.

YAML und JSON

YAML und JSON beschreiben dieselben Daten. Derselbe Film als JSON:

{ "title": "Nosferatu", "year": 1922, "genres": ["Horror", "Fantasy"] }

Jedes JSON ist auch gültiges YAML. YAML ist für Menschen gedacht, die eine Datei von Hand schreiben, mit Kommentaren und ohne Klammern und Kommas; JSON für Programme, die sich Daten schicken. Mehr dazu im Handbuch JSON.

2. Fallen

Wenn YAML etwas anderes liest

YAML errät, was ein Wert ist. Was du als Text meinst, ist manchmal eine Zahl oder ein Wahrheitswert, und verschiedene Programme raten verschieden. Ruby liest nach der älteren Version YAML 1.1, yq nach YAML 1.2:

Die Regel ist einfach: Was Text bleiben soll, steht in Anführungszeichen, sobald es aussieht wie eine Zahl, eine Uhrzeit oder ein Ja und Nein.

Zwei Fehler, bei denen das Lesen ganz abbricht:

3. Wo YAML vorkommt

Front Matter

Am Anfang einer Markdown-Datei steht bei Hugo und anderen Generatoren oft ein Block YAML zwischen zwei Zeilen ---, die Front Matter. Sie beschreibt die Seite; der Text danach ist ihr Inhalt:

---
title: Wie lange schwingt ein Pendel?
date: 2026-10-15
draft: false
tags: [physik, versuch]
---

Eine Kugel an einem Faden schwingt hin und her …

Ein Datum schreibt man wie oben, Jahr, Monat, Tag, mit Bindestrichen.

Außerdem stehen in YAML: die Einstellungen von Hugo (hugo.yaml), Abläufe in GitHub Actions (.github/workflows/*.yml) und GitLab CI (.gitlab-ci.yml), Docker Compose (compose.yaml) und die Pakete eines Flutter-Projekts (pubspec.yaml). .yml und .yaml bedeuten dasselbe.

4. Lesen und prüfen

yq

yq ist für YAML, was jq für JSON ist: Es liest eine Datei, meldet Fehler mit Zeile und Spalte und holt heraus, was du brauchst.

yq . film.yaml                    # prüfen und anzeigen
yq .title film.yaml               # ein Feld
yq '.genres[0]' film.yaml         # der erste Eintrag einer Liste
yq '.cast[].name' film.yaml       # ein Feld aus jedem Eintrag
yq -o json film.yaml              # als JSON
yq -o yaml film.json              # JSON als YAML
yq -i '.watched = true' film.yaml # in der Datei ändern

yq --front-matter=extract .title seite.md liest die Front Matter einer Markdown-Datei.

Ruby

require 'yaml'

film = YAML.load_file('film.yaml')
puts film['title']                 # Nosferatu
film['watched'] = true
File.write('film.yaml', film.to_yaml)

YAML.load_file macht aus Objekten Hashes, aus Listen Arrays, wie JSON.parse. Ist die Datei kaputt, wirft es einen Psych::SyntaxError mit Zeile und Spalte. Ruby liest nach YAML 1.1; die Fallen oben gelten hier besonders.