Vollständige YAML 1.2-Syntaxreferenz mit Beispielen. Behandelt Skalare, Sequenzen, Mappings, Anchors, mehrzeilige Strings, Tags und häufige Fallstricke.
Plain unquoted string — most common
name: John Doe
Single-quoted: no variable or escape processing
path: '/usr/bin/node'
Double-quoted: supports escape sequences (\n, \t, etc.)
message: "Hello\nWorld"
Whole number (base 10)
port: 8080
Floating point number
threshold: 0.95
Boolean value — use only true/false (YAML 1.2)
debug: false
Null / absence of value
response: null
ISO 8601 date format
created: 2024-01-15T10:30:00Z
Single-line comment. No multi-line comment syntax.
# This is a comment key: value # inline comment
Force value to be treated as a specific type
port: !!str 8080 # string '8080' not int
Key-value pairs — indented block style
app: name: myapp port: 3000
Inline map — equivalent to block style
env: {NODE_ENV: prod, PORT: 8080}List of items — block style with dash+space
fruits: - apple - banana - cherry
Inline list — equivalent to block style
ports: [80, 443, 8080]
List where each item is a map
users:
- name: Alice
role: admin
- name: Bob
role: userArbitrarily deep nesting
database:
primary:
host: db1.example.com
port: 5432Merge the keys of a referenced mapping into current map
defaults: &defaults color: blue button: <<: *defaults text: Submit
Preserves newlines exactly as written
script: | #!/bin/bash echo "hello" exit 0
Newlines folded into spaces (great for long descriptions)
description: > This is a very long description that will be joined into one line.
Literal block, strip all trailing newlines
prompt: |- Enter value:
Literal block, keep all trailing newlines
template: |+ line1
Folded block, strip trailing newlines
message: >- This folds into one line no trailing newline
Assigns an anchor (label) to the current node
base: &base image: node:18 restart: always
References (copies) an anchored node
service1: <<: *base name: api service2: <<: *base name: worker
Anchor a scalar value to reuse it
read_timeout: &rto 30 write_timeout: *rto connect_timeout: *rto
Anchor a list
primary_colors: &colors - red - blue text_colors: *colors
Explicitly declare YAML version (optional, rarely needed)
%YAML 1.2 --- name: myapp
Marks the start of a YAML document. Required if using directives.
--- kind: Deployment --- kind: Service
Marks the end of a YAML document. Optional but useful.
--- debug: true ...
Multiple YAML docs in one file (stream)
Used in Kubernetes multi-resource files
Base64-encoded binary data
icon: !!binary | iVBORw0KGgo=
Indentation MUST use spaces only — never tabs
# WRONG: parent: \tchild: value # RIGHT: parent: child: value
Values containing ': ' (colon+space) must be quoted
# WRONG: url: http://example.com # RIGHT: url: "http://example.com"
1.0 parses as float! Quote or tag it to keep as string
version: '1.0' # string version: 1.0 # float
YAML 1.1 parses yes/no/on/off as booleans — quote to use strings
# YAML 1.1 (PyYAML): on: true # 'on' is boolean true! # Safe: always quote on: 'on'
Trailing spaces in keys are included in the key string
"key " (with space) != "key" — trim carefully
Duplicate keys — behavior is parser-specific (usually last wins). Treat as error.
Use a YAML linter to detect duplicate keys
| Funktion | YAML | JSON |
|---|---|---|
| Kommentare | Yes: # comment | Nicht unterstützt |
| Anführungszeichen erforderlich | Optional für Zeichenketten | Erforderlich für Zeichenketten |
| Anchors/aliases | Yes: &anchor / *alias | Nicht unterstützt |
| Mehrzeilige Zeichenketten | Yes: | and > blocks | Escaped \n only |
| Tabulatoren für Einrückungen | Nur Leerzeichen | Beides |
| Ist Obermenge von JSON | Jedes JSON ist gültiges YAML | - |
| Menschenlesbarkeit | Sehr hoch | Mittel |
| Parser-Verfügbarkeit | Hoch | Sehr hoch |
Wichtig: Viele YAML-Parser verwenden standardmäßig noch YAML 1.1 (Pythons PyYAML, Rubys Psych in einigen Versionen).
YAML ist eine Obermenge von JSON — jedes gültige JSON ist auch gültiges YAML. YAML ist darauf ausgelegt, für Menschen lesbarer zu sein, mit Unterstützung für Kommentare, mehrzeilige Zeichenketten und Anchors/Aliases. JSON ist strenger, schneller zu parsen und universell unterstützt. Verwenden Sie YAML für Konfigurationsdateien und JSON für APIs und Datenaustausch.
In YAML 1.1 (von vielen Parsern einschließlich PyYAML verwendet) sind 'on', 'off', 'yes', 'no' gültige Boole'sche Werte. Dies kann zu Fehlern führen, wenn sie als einfache Zeichenketten verwendet werden (z.B. in Ansible). YAML 1.2 hat dies behoben — nur 'true' und 'false' sind Booleans. Lösung: Setzen Sie diese Werte immer in Anführungszeichen ('yes', 'no'), wenn Sie sie als Zeichenketten verwenden möchten.
Verwenden Sie den Literal-Block-Skalar (|), um Zeilenumbrüche zu erhalten: Jede Zeile im Block wird zu einem tatsächlichen Zeilenumbruch in der Zeichenkette. Verwenden Sie den gefalteten Block-Skalar (>), um Zeilenumbrüche in Leerzeichen umzuwandeln: ideal für lange Absätze. Beide unterstützen optionale Chomping-Indikatoren (- zum Entfernen nachgestellter Zeilenumbrüche, + zum Behalten aller).
YAML verwendet Leerzeichen für Einrückungen — niemals Tabulatoren. Alle gleichrangigen Schlüssel müssen auf der gleichen Einrückungsebene stehen. Das Mischen von Tabulatoren und Leerzeichen führt immer zu Fehlern. Häufige Lösungen: Aktivieren Sie in Ihrem Editor die Einstellung 'Tabulatoren durch Leerzeichen ersetzen', verwenden Sie einen Linter (yamllint), stellen Sie konsistente Einrückungsbreite (2 oder 4 Leerzeichen) in der gesamten Datei sicher.