Skip to content

YAML Spickzettel

Menschenfreundlicher Datenserialisierungs-Standard für Config-Dateien.

01

Erste Schritte

Grundstruktur

YAML nutzt Einrückung (Leerzeichen, keine Tabs) für Verschachtelung. Mappings nutzen key: value, Sequenzen - item. Die Inline-Syntax nutzt [] für Listen und {} für Maps. Kommentare nutzen #.

yaml
# YAML uses indentation for structure
# Comments start with #

# Key-value pairs (mappings)
name: Alice
age: 30

# Nested mappings (use consistent indentation)
person:
  name: Bob
  age: 25
  address:
    city: NYC
    zip: 10001

# Sequences (lists)
hobbies:
  - reading
  - coding
  - music

# Inline syntax
numbers: [1, 2, 3]
coords: {x: 10, y: 20}

Kommentare

Kommentare beginnen mit # und müssen von Whitespace oder Zeilenanfang vorangestellt sein. Innerhalb von Blockskalaren (| und >) ist # literaler Inhalt, kein Kommentar. Es gibt keine Mehrzeilen-Kommentarsyntax — jede Zeile braucht ihr eigenes #.

yaml
# Full-line comment
key: value  # Inline comment (whitespace before # required)

# Comments can appear anywhere
# - before documents
# - inside sequences
list:
  - a  # first item
  - b  # second item

# Block scalar headers DO accept comments
text: |  # literal block
  line one

# But the content of block scalars is literal,
# so # inside is NOT a comment:
literal: |
  # this is part of the string, not a comment

Einrückungsregeln

YAML verbietet Tabs für die Einrückung strikt — nur Leerzeichen sind erlaubt. Die Einrückung muss innerhalb einer Ebene konsistent sein, muss aber keine fixe Zahl sein. Das - in Sequenzen zählt zur Einrückung. Tabs und Leerzeichen zu mischen wirft einen Parserfehler.

yaml
# Use SPACES only — tabs are forbidden for indentation
# 2 spaces is the most common convention

mapping:
  nested:
    deeply_nested: value

# Sequences can be indented at the same level as the key
items:
  - one
  - two

# Or indented further (both are valid)
items2:
    - one
    - two

# WRONG: tab characters cause parser errors
# bad:	value   (tab before value)

# Hyphen counts as indentation start
- item1
- item2

Dokumentanfang & -ende

--- markiert den Anfang eines YAML-Dokuments; ... das Ende. Eine Datei kann mehrere durch --- getrennte Dokumente enthalten (ein Dokumentstrom). Für Ein-Dokument-Config-Dateien ist ein führendes --- optional, aber als Hinweis an Parser empfohlen.

yaml
# --- separates documents in a stream
# ... ends a document (optional)

---
name: first document
value: 1
...
---
name: second document
value: 2
...

# A single document needs no markers
key: value

# But --- is recommended at the start of files
# to disambiguate from plain text
---
apiVersion: v1
kind: ConfigMap

Häufige Fallstricke

Der Doppelpunkt braucht ein folgendes Leerzeichen, um ein Mapping-Trenner zu sein. YAML 1.1 vs. 1.2 unterscheiden sich bei yes/no/on/off (Booleans in 1.1, Strings in 1.2) und bei Oktalliteralen. Leere Werte sind null, unterscheiden sich also vom leeren String. Viele Parser (PyYAML) folgen weiterhin den 1.1-Regeln.

yaml
# Colon needs a space after it
key:value      # WRONG: parsed as a single string "key:value"
key: value     # correct

# Yes/No/On/Off are NOT booleans in YAML 1.2
# (they WERE in YAML 1.1 — common gotcha)
answer: yes    # YAML 1.1: true; YAML 1.2: "yes" string

# Numbers with leading zeros
version: 010   # YAML 1.1: octal 8; YAML 1.2: string "010"

# Unquoted strings with special chars
url: example.com/path   # OK
url: example.com:8080   # WRONG: parsed as mapping with key example.com

# Empty values
empty:       # null
empty2: ~    # explicit null
empty3: ""   # empty string (different from null)

YAML vs. JSON

YAML 1.2 wurde so entworfen, dass JSON eine strenge Teilmenge ist — jede JSON-Datei ist gültiges YAML. YAML ergänzt Kommentare, Blockstruktur, Anker, mehrzeilige Strings und Tags. JSON verlangt die Quotierung aller Schlüssel und String-Werte, was YAML für plain Skalare lockert.

yaml
# JSON is a strict subset of YAML 1.2
# Every valid JSON document is valid YAML

# JSON:
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}

# Equivalent YAML:
name: Alice
age: 30
hobbies:
  - a
  - b

# YAML adds: comments, multi-line strings, anchors,
# relaxed quoting, tags, multiple documents

# YAML removes: mandatory quotes around strings,
# commas, braces (in block style)

# YAML is a superset of JSON — not the other way.
# Comments and anchors are not valid JSON.
02

Skalare (Strings, Zahlen, Booleans, Null)

Plain- & quotierte Strings

Plain-Strings brauchen keine Anführungszeichen, außer sie sehen aus wie Zahlen, Booleans, null oder Daten. Einfache Anführungszeichen escapen nur ' durch Verdopplung (''); keine anderen Escapes. Doppelte unterstützen volle Escape-Sequenzen (\n, \t, \uXXXX). Quotieren erzwingt den String-Typ.

yaml
# Plain strings (no quotes) — most common
name: Alice
path: /usr/local/bin
url: https://example.com

# Single-quoted — escape ' by doubling
msg: 'it''s fine'

# Double-quoted — supports escapes
greeting: "Hello\nWorld"
unicode: "\u03B1"   # Greek alpha
tab: "col1\tcol2"

# Multi-word plain strings are fine
description: This is a plain string with spaces

# Strings that look like other types must be quoted
version: "1.0"      # string, not float
notBool: "true"     # string, not boolean
notNull: "null"     # string, not null
date: "2024-01-01"  # string, not date

Zahlen

YAML 1.2 nutzt 0o für Oktal (YAML 1.1 nutzte ein nacktes führendes 0). Unterstriche in Zahlen sind zur Lesbarkeit erlaubt. .inf und .nan sind besondere Float-Literale. Jeden Wert quoten, der ein String sein soll, aber numerisch aussieht (Versionen, Telefonnummern, IDs).

yaml
# Integers
int: 42
negative: -17
positive: +100
underscored: 1_000_000   # readable grouping (YAML 1.2)

# Octal & hex (YAML 1.2 prefixes)
octal: 0o17     # = 15 decimal
hex: 0xFF       # = 255 decimal
binary: 0b1010  # = 10 decimal

# Floats
pi: 3.14159
exp: 1.0e+3     # 1000.0
neg_exp: -2.5e-4

# Special float values (IEEE 754)
infinity: .inf
neg_infinity: -.inf
not_a_number: .nan

# To force a string that looks numeric:
version: "1.0"
phone: "555-1234"

Booleans

YAML 1.2 verengte Booleans auf true/false (und True/False, TRUE/FALSE). YAML 1.1 (von PyYAML genutzt) behandelt yes/no/on/off/y/n als Booleans — eine berühmte Bugquelle (z. B. Norwegen 'no' → false). Diese Strings immer quoten, wenn sie wörtlich gemeint sind.

yaml
# YAML 1.2 — only these are booleans:
enabled: true
disabled: false

# YAML 1.1 ALSO accepts (common gotcha):
# yes, no, on, off, y, n, Y, N
# These are strings in 1.2 but booleans in 1.1

# To force a string:
answer: "yes"      # always a string
option: "on"
flag: "y"

# PyYAML (1.1 rules) parses these as booleans:
# yes -> True, no -> False, on -> True, off -> False
# This breaks "no" as an answer or country code!

# Safe practice: quote if you mean the literal string
country: "no"   # Norway country code, not False

Null-Werte

YAML akzeptiert null, Null, NULL, ~ und einen leeren Wert als null. Ein leerer Wert (Schlüssel ohne Inhalt nach dem Doppelpunkt) ist null, unterschieden vom leeren String "". Parser mappen YAML-null auf den null-Wert der Hostsprache (None, null, nil).

yaml
# All of these represent null/None/null
key1: null
key2: Null
key3: NULL
key4: ~
key5:             # empty value

# Distinguish null from empty string
empty_string: ""
null_value: null

# In sequences
list:
  - value
  - null         # explicit null item
  - another

# In nested structures
config:
  timeout: null   # explicitly unset
  retries: 3

# Parsers convert to language-specific null:
# Python -> None, JavaScript -> null, Go -> nil

Daten & Zeitstempel

ISO-8601-Daten und -Zeitstempel werden von den meisten Parsern als native Typen erkannt. Ein nacktes YYYY-MM-DD wird ein Datum; mit Zeit ein datetime. Den Wert quoten, um ihn als String zu behalten. Zeitzonenbezeichner (Z, +08:00) werden unterstützt.

yaml
# Date (ISO 8601)
date: 2024-01-15

# Datetime (ISO 8601)
datetime: 2024-01-15T14:30:00
datetime_tz: 2024-01-15T14:30:00Z
datetime_offset: 2024-01-15T14:30:00+08:00
datetime_space: 2024-01-15 14:30:00

# To force string (not a date):
not_a_date: "2024-01-15"
not_a_date2: '2024-01-15'

# Parsers typically return datetime objects
# Python: datetime.date / datetime.datetime
# JavaScript: Date (depending on library)

Typableitung

YAMLs Typsystem löst unquotierte Skalare über ein Schema auf. Das Failsafe-Schema behandelt alles als Strings; die JSON- und Core-Schemata leiten int, float, bool, null, date ab. Anführungszeichen oder explizite Tags (!!str, !!int) nutzen, um die Auflösung bei Bedarf zu überschreiben.

yaml
# YAML infers types from unquoted scalars
str: hello             # string
int: 42                # integer
float: 3.14            # float
bool: true             # boolean
null_val: null         # null
date: 2024-01-01       # date
list: [1, 2, 3]        # sequence

# Force string type with quotes
str_version: "42"
str_date: "2024-01-01"
str_bool: "true"

# Or with the !!str tag
forced: !!str 42        # string "42"
forced_int: !!int "42"  # integer 42

# Resolution depends on the schema
# Failsafe: everything is a string
# JSON/Core: numbers, bools, null inferred
03

Mappings

Einfaches Mapping

Ein Mapping ist eine Menge key: value-Paare, deren Schlüssel typisch Strings sind. Schlüssel können jeder Skalar sein (Zahl, bool, sogar null). Doppelte Schlüssel sind unüblich, und das Verhalten variiert je Parser (oft gewinnt der letzte). Einen Linter nutzen, um versehentliche Duplikate zu erwischen.

yaml
# A mapping is a set of key: value pairs
name: Alice
age: 30
email: [email protected]

# Keys can be any scalar type (string, number, bool)
"string key": value
123: numeric key
true: boolean key

# Duplicate keys are technically discouraged
# but some parsers allow them (last wins)
key: first
key: second   # overrides "first" in many parsers

# Values can be any type
mixed:
  string: text
  number: 42
  list: [1, 2, 3]
  nested:
    deep: value

Verschachtelte Mappings

Verschachtelte Mappings entstehen, indem Kind-Schlüssel eingerückt werden. Die Einrückung muss innerhalb einer Ebene konsistent sein. Es gibt keine feste Einrückungsgröße, aber 2 Leerzeichen sind der De-facto-Standard. Tiefe Verschachtelung senkt die Lesbarkeit — sehr tiefe Strukturen zu flachen erwägen.

yaml
# Nest mappings with consistent indentation
server:
  host: localhost
  port: 8080
  ssl:
    enabled: true
    cert: /etc/ssl/cert.pem
    key: /etc/ssl/key.pem

database:
  primary:
    host: db1.example.com
    port: 5432
  replica:
    host: db2.example.com
    port: 5432

# Indentation level is up to you — just be consistent
# 2 spaces is the most common convention

Mapping von Sequenzen

Mappings und Sequenzen komponieren frei. Ein übliches Muster ist eine Sequenz von Mappings (eine Liste von Datensätzen), bei der jedes - einen Eintrag startet und ausgerichtete Schlüssel zu diesem Eintrag gehören. Die Einrückung nachfolgender Schlüssel muss mit dem ersten Schlüssel nach dem - fluchten.

yaml
# Values in a mapping can be sequences
servers:
  - web1.example.com
  - web2.example.com
  - web3.example.com

# Sequence of mappings (very common)
users:
  - name: Alice
    age: 30
  - name: Bob
    age: 25

# Each - starts a new item; aligned keys form one mapping
services:
  - name: api
    port: 8080
    env:
      - dev
      - prod
  - name: web
    port: 3000

# Mixed: mapping containing sequence containing mapping
config:
  endpoints:
    - path: /health
      method: GET
    - path: /users
      method: POST

Komplexe Schlüssel

YAML erlaubt jeden Skalar oder jede Collection als Schlüssel über den ?-Schlüsselindikator. In Config-Dateien selten, aber nützlich für Lookup-Tabellen (z. B. Preise nach Region+Instanz). Komplexe Schlüssel sind umständlich zu lesen — die meisten Config-Dateien bleiben bei plain String-Schlüsseln.

yaml
# Keys can be complex objects using ? notation
? key1
: value1

# A mapping as a key
? host: localhost
  port: 8080
: connection1

# A sequence as a key
? [a, b, c]
: indexed_value

# Practical (rare) use: matrix lookup
? [us-east-1, t2.micro]
: 0.0116
? [us-east-1, t2.small]
: 0.023

# In flow style:
{[a, b]: value, {x: 1}: other}

# Most config files just use plain string keys
simple: value

Inline-(Flow-)Mappings

Der Flow-Stil nutzt {} für Mappings und [] für Sequenzen, ähnlich JSON. Nützlich für kurze, kompakte Daten auf einer Zeile. Anders als JSON erlaubt YAML keine nachgestellten Kommas. Flow- und Blockstil frei mischen, aber in Config-Dateien den Block für Lesbarkeit bevorzugen.

yaml
# Flow style mapping (like JSON)
point: {x: 10, y: 20}
config: {host: localhost, port: 8080}

# Nested flow mappings
nested: {a: {b: {c: value}}}

# Mixed flow and block
block_key:
  flow_value: {x: 1, y: 2}
  another: value

# Flow with sequences
mixed: {nums: [1, 2, 3], name: test}

# Quoting still works in flow style
quoted: {"key with space": "value", count: 3}

# Trailing comma is NOT allowed in YAML flow
bad: {a: 1, b: 2,}   # parse error

Schlüsselreihenfolge & Stil

YAML selbst erhält die Mapping-Reihenfolge in der Spezifikation, aber Hostsprachen-Objekte tun es womöglich nicht (die meisten modernen Dicts allerdings schon). Für Config-Lesbarkeit verwandte Schlüssel gruppieren, konsistente Benennung nutzen (snake_case oder camelCase) und Kommentare zur Abgrenzung von Sektionen ergänzen.

yaml
# YAML mappings are ORDERED (unlike JSON spec, though
# most JSON parsers preserve insertion order too)
# But language objects may not preserve order:
# Python dict (3.7+): preserves order
# Ruby Hash: preserves order
# JSON object: technically unordered

# Consistent key style improves readability
config:
  server:
    host: localhost      # snake_case
    port: 8080
    max_connections: 100
  database:
    host: db.example.com
    port: 5432
    connection_pool: 10

# Group related keys together
# Use comments to delineate sections
app:
  # networking
  host: 0.0.0.0
  port: 3000
  # limits
  timeout: 30
  retries: 3
04

Sequenzen

Block-Sequenzen

Block-Sequenzen nutzen - (Bindestrich + Leerzeichen) vor jedem Eintrag. Einträge können jeden Typ haben: Skalare, Mappings oder verschachtelte Sequenzen. Das - zählt als Teil der Einrückung, nachfolgende Schlüssel eines Mapping-Eintrags fluchten also mit dem ersten Schlüssel nach dem Bindestrich.

yaml
# A sequence (list) uses - followed by space
fruits:
  - apple
  - banana
  - cherry

# Sequence as top-level document
- item1
- item2
- item3

# Empty sequence
empty: []
or_with_marker: []

# Sequence with mixed types
mixed:
  - string
  - 42
  - true
  - null
  - key: value   # a mapping as an item

Verschachtelte Sequenzen

Verschachtelte Sequenzen entstehen durch weiter eingerückte -Ebenen. Jenseits von 2 Ebenen werden sie schwer lesbar — für innere Sequenzen zum Flow-Stil wechseln. Baumstrukturen (Sequenz von Mappings mit Kindern) sind lesbarer als reine verschachtelte Sequenzen.

yaml
# Sequence of sequences
matrix:
  - - 1
    - 2
    - 3
  - - 4
    - 5
    - 6

# More readable with flow style for inner
matrix2:
  - [1, 2, 3]
  - [4, 5, 6]

# Deeply nested
tree:
  - name: root
    children:
      - name: child1
        children:
          - name: grandchild1
      - name: child2

# 3D: sequence of sequence of sequence
cube:
  - - [1, 2]
    - [3, 4]
  - - [5, 6]
    - [7, 8]]

Sequenz von Mappings

Eine Sequenz von Mappings ist das häufigste YAML-Muster (Listen von Datensätzen). Jedes - startet einen neuen Eintrag; nachfolgende Schlüssel gleicher Einrückung gehören zu diesem Eintrag. Schlüssel nach dem - ausrichten für Lesbarkeit. Ein leerer Mapping-Eintrag wird als {} geschrieben.

yaml
# Most common pattern: list of records
users:
  - name: Alice
    email: [email protected]
    roles:
      - admin
      - user
  - name: Bob
    email: [email protected]
    roles:
      - user

# Each - starts a new mapping; aligned keys belong
# to that item. Indent the first key after - by 2 spaces.
servers:
  - host: web1.example.com
    port: 8080
    healthy: true
  - host: web2.example.com
    port: 8080
    healthy: false

# Empty mapping item
list:
  - {}
  - name: real

Inline-(Flow-)Sequenzen

Flow-Sequenzen nutzen [] und sind äquivalent zu Block-Sequenzen. Nützlich für kurze Listen auf einer Zeile. Flow-Sequenzen dürfen sich zur Lesbarkeit über mehrere Zeilen erstrecken. Anders als JSON verbietet YAML nachgestellte Kommas. Flow-Sequenzen frei mit Block-Mappings mischen.

yaml
# Flow sequence (JSON-like)
numbers: [1, 2, 3]
names: [Alice, Bob, Charlie]

# Nested flow sequences
matrix: [[1, 2], [3, 4]]

# Flow sequence of flow mappings
points: [{x: 1, y: 2}, {x: 3, y: 4}]

# Mixed: block mapping with flow sequence value
config:
  ports: [80, 443, 8080]
  hosts: [web1, web2, web3]

# Spread across multiple lines (still flow style)
long_list: [
  item1,
  item2,
  item3
]

# NO trailing comma allowed
bad: [1, 2, 3,]   # error

Gemischte & heterogene Inhalte

YAML erlaubt völlig heterogene Inhalte in Sequenzen und Mappings — jeder Eintrag kann jeden Typ haben. Diese Flexibilität ist mächtig, bedeutet aber, dass die Anwendung die Struktur validieren muss. Für strenge Validierung ein Schema nutzen (JSON Schema, Cue usw.).

yaml
# Sequences can mix types freely
mixed:
  - string
  - 42
  - true
  - null
  - [1, 2, 3]            # nested sequence
  - key: value           # mapping
    another: value2
  - - nested
    - sequence

# Heterogeneous mapping values
config:
  string_val: text
  int_val: 42
  list_val: [a, b, c]
  map_val: {x: 1, y: 2}
  null_val: null
  bool_val: true

# YAML has no schema enforcing uniformity —
# the application must validate structure

Sequenz-Einrückungsmuster

Sequenzen unter einem Schlüssel können eingerückt sein (Muster 1) oder auf derselben Ebene stehen (Muster 2, da das - zur Einrückung zählt). Beide sind gültig; eines wählen und konsistent bleiben. In Sequenzen von Mappings müssen alle Schlüssel eines Eintrags mit dem ersten Schlüssel nach dem - fluchten.

yaml
# Pattern 1: sequence indented under key
items:
  - a
  - b

# Pattern 2: sequence at same level as key
# (the - is treated as indentation)
items:
- a
- b

# Both are valid and produce the same result.
# Pick one and be consistent (most style guides prefer #1).

# Mapping item alignment — both keys align with first
users:
  - name: Alice
    age: 30
  - name: Bob
    age: 25

# WRONG: misaligned keys cause parse errors
# users:
#   - name: Alice
#    age: 30    # one space off — error
05

Mehrzeilige Strings (Folded & Literal)

Literaler Blockskalar (|)

Der literale Blockskalar | erhält jeden Zeilenumbruch exakt wie geschrieben. Die Einrückung (der Betrag über das | hinaus) wird von jeder Zeile gestrippt. Standard-Chomping (clip) behält einen nachgestellten Zeilenumbruch. Genutzt für Skripte, Code, Gedichte, ASCII-Kunst — überall, wo literale Zeilenumbrüche zählen.

yaml
# | preserves newlines as-is
script: |
  #!/bin/bash
  echo "Hello"
  echo "World"

# Output string:
# #!/bin/bash\necho "Hello"\necho "World"\n

poem: |
  Roses are red,
  Violets are blue,
  YAML is clean,
  And JSON is too.

# Trailing newline is kept by default (clip mode)
# Use |- to strip, |+ to keep all trailing newlines

Gefalteter Blockskalar (>)

Der gefaltete Blockskalar > wandelt einzelne Zeilenumbrüche in Leerzeichen um und verbindet Zeilen zu Absätzen. Leere Zeilen werden zu literalen Zeilenumbrüchen. Stärker eingerückte Zeilen als der Blockinhalt bleiben literal erhalten (praktisch für Codebeispiele innerhalb von Prosa).

yaml
# > folds newlines into spaces (paragraphs)
description: >
  This is a long paragraph that
  spans multiple lines in the YAML
  but will be joined into one line
  when parsed.

# Output: "This is a long paragraph that spans multiple
# lines in the YAML but will be joined into one line when
# parsed.\n"

# Blank lines preserve a newline
paragraphs: >
  First paragraph here.

  Second paragraph here.

  Third paragraph here.

# More indented lines are preserved literally
example: >
  This is folded.
    This line is more indented — kept literal.

Chomping-Indikatoren (+/-)

Chomping steuert nachgestellte Zeilenumbrüche: clip (Standard, ohne Indikator) behält einen; strip (-) entfernt alle; keep (+) erhält alle. Der Indikator steht direkt hinter | oder > (z. B. |-, |+, >-, >+). Strippen ist nützlich für Strings, die inline genutzt werden; keepen ist selten, aber entspricht exakt der Quelle.

yaml
# Default (clip): single trailing newline
text: |
  line1
  line2
# Result: "line1\nline2\n"

# Strip (-): remove ALL trailing newlines
text_strip: |-
  line1
  line2
# Result: "line1\nline2"

# Keep (+): keep ALL trailing newlines
text_keep: |+
  line1
  line2


# Result: "line1\nline2\n\n\n"

# Same applies to folded scalars
folded_keep: >+
  folded
  text

Einrückungsindikator

Beginnt Blockskalar-Inhalt mit Whitespace, musst du die Inhaltseinrückung explizit mit einer Ziffer angeben (z. B. |2). Die Ziffer gibt an, wie viele Leerzeichen der Einrückung zur Struktur vs. zum Inhalt gehören. Mit Chomping kombinieren: |2-, >4+ usw. Selten nötig, aber essenziell, wenn doch.

yaml
# When the first line starts with spaces, you must
# tell YAML the content indentation explicitly

# Without indicator (ambiguous):
# content:
#   indented_line   # is the leading space content or not?

# With explicit indentation indicator (digit after | or >)
literal: |2
    hello
      world
# The "2" means: content is indented 2 spaces past the indicator
# So 4 spaces of indentation = 2 content + 2 extra

# Combined with chomping (order: indent then chomp)
text: |2-
    no trailing newline

# Folded with explicit indent
folded: >4
    paragraph with
    explicit indent

# Most of the time you don't need this — only when
# content legitimately starts with spaces

Plain mehrzeilige Strings

Plain- und quotierte Skalare dürfen sich über mehrere Zeilen erstrecken, wobei Zeilenumbrüche zu Leerzeichen gefaltet werden (ähnlich >, aber implizit). Das ist zerbrechlich, weil Zeilenumbrüche vom Kontext und Sonderzeichen abhängen. Für nicht-trivialen mehrzeiligen Text lieber explizite | (literal) oder > (folded) Blockskalare.

yaml
# Plain (unquoted) scalars can span lines
# Newlines are folded to spaces (like > but no indicator)
message: this is
  a long message
  on multiple lines
# Result: "this is a long message on multiple lines"

# Quotes are required if the string contains special chars
quoted: "this is also
  a long message
  on multiple lines"
# Result: "this is also a long message on multiple lines"

# Plain multi-line breaks at certain chars
# (colons, etc.) — usually fold cleanly
# but be careful with leading colons

# Plain is fragile for multi-line — prefer | or >
safe_literal: |
  Use literal block for
  predictable multi-line text

Folded vs. Literal wählen

Faustregel: | nutzen, wenn Zeilenumbrüche bedeutsam sind (Skripte, Config-Dateien, Code); > nutzen, wenn du lesbaren mehrzeiligen Quelltext, aber einen verbundenen Absatz willst (Beschreibungen, Dokumentation). |- nutzen, um den nachgestellten Zeilenumbruch zu strippen, wenn der String inline genutzt wird.

yaml
# Use | (literal) when newlines matter:
script: |
  #!/bin/bash
  set -e
  echo "Step 1"
  echo "Step 2"

config_file: |
  [default]
  region=us-east-1
  output=json

# Use > (folded) when you want readable source
# but a single paragraph string:
description: >
  This service handles user authentication
  and session management. It talks to the
  PostgreSQL database and Redis cache.

# Use |- or >- to strip trailing newline
# (useful for inline string usage):
inline_script: |-
  echo hello

# Use plain single-line for short strings
short: hello world
06

Anker & Aliasse

Anker definieren (&)

&name definiert einen Anker an einem Knoten (Mapping, Sequenz oder Skalar). Der Anker ändert den Wert an dieser Stelle nicht — er labelt den Knoten nur zur Wiederverwendung. Aliasse (*name) referenzieren den verankerten Knoten beim Namen. Anker müssen vor der Nutzung im Dokument definiert sein.

yaml
# &name defines an anchor on a node
defaults: &defaults
  adapter: postgres
  host: localhost
  port: 5432

# The anchor marks the node so it can be reused
# The value is still assigned normally
production:
  database: *defaults
  # *defaults is an alias — references the anchored node

# Anchors on scalars
version: &ver "1.0.0"
current: *ver

# Anchors on sequences
colors: &colors
  - red
  - green
  - blue
primary: *colors

Aliasse nutzen (*)

*name ist ein Alias, der einen zuvor verankerten Knoten referenziert. Aliasse teilen die Identität mit dem Original (dasselbe Objekt in den meisten Parsern). Anker/Aliasse sind dokumentbezogen — sie dürfen nicht über ---Dokumentgrenzen hinweg referenzieren. Mit << (merge key) kombinieren, um Overrides zu schichten.

yaml
# Define once, reuse by alias
base: &base
  image: nginx:1.25
  restart: always

web:
  <<: *base
  ports:
    - "80:80"

api:
  <<: *base
  ports:
    - "8080:8080"
  environment:
    - DEBUG=true

# Aliases reference the SAME object (by identity)
# In most parsers, mutating one mutates the other
# (though YAML itself is read-only)

# Aliases can't span documents
# Each document has its own anchor namespace

Anker-Scope

Anker sind auf ihr Dokument begrenzt und müssen vor jeder Alias-Referenz definiert sein (keine Vorwärtsreferenzen). Mehrere Aliasse dürfen denselben Anker referenzieren. Einen Alias zu aliasen funktioniert — er löst sich transitiv auf. Dokumentübergreifende Referenzen sind ein Fehler.

yaml
# Anchors are scoped to a single document
---
# Document 1
shared: &shared
  key: value
use: *shared   # works
...
---
# Document 2 — &shared is NOT visible here
other: *shared   # ERROR: unknown anchor

# Anchors must be defined before the alias
# (forward references are not allowed)
bad: *later      # ERROR
later: &later value

# Multiple aliases to the same anchor are fine
template: &tpl
  timeout: 30
use1: *tpl
use2: *tpl
use3: *tpl

# Aliasing an alias is allowed
a: &a value
b: &b *a
c: *b   # resolves to "value"

Verankerte Werte überschreiben

Ein Alias (*name) ersetzt den ganzen Knoten — teilweise Überschreiben geht nicht. Um einzelne Schlüssel eines verankerten Mappings zu überschreiben, den merge key << nutzen, um das verankerte Mapping zu verschmelzen und dann Schlüssel zu ergänzen oder zu überschreiben. Das kanonische Muster für Konfigurationskomposition.

yaml
# Aliases themselves can't be partially overridden —
# an alias replaces the whole node. Use << (merge)
# to combine an anchored mapping with overrides.
defaults: &defaults
  timeout: 30
  retries: 3
  log_level: info

production:
  <<: *defaults
  log_level: warn      # override
  host: prod.example.com   # add

# Result:
# production:
#   timeout: 30
#   retries: 3
#   log_level: warn
#   host: prod.example.com

# Without <<, an alias replaces the whole node:
wrong:
  thing: *defaults
  # thing is the FULL defaults mapping — can't override

Anker in Sequenzen

Anker dürfen ganze Sequenzen, einzelne Sequenzeinträge oder Mappings innerhalb einer Sequenz labeln. Das <<-Mergemuster ist besonders nützlich in Sequenzen ähnlicher Datensätze (z. B. Service-Definitionen), um gemeinsame Felder zu teilen. Einzelne Einträge mit - &name value verankern.

yaml
# Anchors work on sequence items too
common: &common
  enabled: true
  log: stdout

services:
  - name: web
    <<: *common
    port: 80
  - name: api
    <<: *common
    port: 8080
  - name: worker
    <<: *common
    queue: jobs

# Anchoring a whole sequence
endpoints: &endpoints
  - /health
  - /metrics
  - /ready

monitoring:
  checks: *endpoints

# Anchoring individual sequence items
list:
  - &first one
  - two
  - *first   # "one" again

Anker-Vorbehalte

Anker haben Vorbehalte: Aliasse teilen die Identität (eine zu mutieren wirkt in veränderlichen Parsern auf alle Referenzen), sie ergänzen kognitive Last, und die meisten Serialisierer (inklusive JSON-Ausgabe) expandieren sie zu plain Kopien. Anker für echte Wiederverwendung nutzen (Templates, Defaults), nicht für Mikrooptimierung.

yaml
# Caveat 1: shared identity can surprise you
defaults: &defaults
  list: [1, 2, 3]

a: *defaults
b: *defaults
# In mutable parsers, a.list and b.list are the SAME list.
# Editing a.list also changes b.list.

# Caveat 2: anchors add cognitive overhead
# Overuse makes YAML hard to read and trace.

# Caveat 3: not all tools preserve anchors on output
# Many serializers expand aliases to plain copies.

# Caveat 4: JSON output loses anchors entirely
# (JSON has no anchor concept).

# Caveat 5: anchors don't work across documents
---
doc1: &x value
use1: *x
---
doc2: *x   # ERROR

# Prefer anchors for genuine reuse, not micro-optimization.
07

Merge-Schlüssel (<<)

Einfaches Mergen (<<)

Der merge key << nimmt ein Mapping (meist einen Alias) und verschmilzt seine Schlüssel-Wert-Paare in das aktuelle Mapping. Im aktuellen Mapping explizit gesetzte Schlüssel überschreiben gemergte. Das kanonische Muster für Konfigurationsvererbung in YAML.

yaml
# << merges a referenced mapping into the current one
defaults: &defaults
  adapter: postgres
  pool: 5
  timeout: 5000

development:
  <<: *defaults
  database: myapp_dev
  host: localhost

production:
  <<: *defaults
  database: myapp_prod
  host: db.example.com
  pool: 20      # override

# Result for development:
# adapter: postgres
# pool: 5
# timeout: 5000
# database: myapp_dev
# host: localhost

Mehrere Merges

<< darf mehrere Mappings verschmelzen, indem eine Flow-Sequenz von Aliassen übergeben wird ([*a, *b, *c]). Merges gelten von links nach rechts; spätere Merges überschreiben frühere bei doppelten Schlüsseln. Explizite Schlüssel im Mapping schlagen immer jeden gemergten. Mehrere <<-Einträge sind ebenfalls erlaubt.

yaml
# << can merge multiple mappings (sequence value)
base: &base
  logging: info
  retries: 3

security: &security
  auth: required
  tls: true

service: &service
  port: 8080
  host: 0.0.0.0

# Merge multiple in one go
production:
  <<: [*base, *security, *service]
  environment: prod
  port: 80        # override service.port

# Later merges override earlier ones for the same key.
# Explicit keys always win over merges.

# You can also have multiple << entries:
combined:
  <<: *base
  <<: *security
  custom: value

Override & Priorität

Merge-Priorität: Explizite Schlüssel im Mapping gewinnen immer. Unter gemergten Mappings überschreiben spätere in der Sequenz frühere für denselben Schlüssel. Damit Defaults → rollenspezifisch → instanzspezifisch sauber schichten.

yaml
# Explicit keys override merged keys
template: &template
  port: 8080
  log: info
  timeout: 30

instance:
  <<: *template
  port: 9090        # overrides template.port
  log: debug        # overrides template.log
  host: example.com # added

# Final: {port: 9090, log: debug, timeout: 30, host: example.com}

# Precedence: explicit > later merge > earlier merge
a: &a
  k: from_a
  x: 1
b: &b
  k: from_b
  y: 2

result:
  <<: [*a, *b]
  k: explicit   # wins over both a and b
# Final: {k: explicit, x: 1, y: 2}

Merge-Muster mit Anker

Das Merge+Anchor-Muster ist Brot und Butter von Docker Compose und ähnlichen Config-Dateien: einen Defaults-Anker definieren, dann lässt jeder Service ihn verschmelzen und überschreibt einzelne Felder. So bleiben Configs DRY, ohne Anpassung pro Service zu opfern.

yaml
# Common pattern: anchor templates, merge + override
defaults: &defaults
  image: nginx:1.25
  restart: always
  logging:
    driver: json-file

services:
  web:
    <<: *defaults
    ports: ["80:80"]
  api:
    <<: *defaults
    image: node:20      # override
    ports: ["8080:8080"]
    environment:
      NODE_ENV: production
  worker:
    <<: *defaults
    image: worker:latest
    command: ["./run.sh"]

# This is the bread-and-butter of Docker Compose files
# — share base config, override per service.

Merge-Grenzen

Der merge key << funktioniert nur für Mappings — Sequenzen und Skalare lassen sich nicht mergen. Mergen ist flach: Ein verschachteltes Mapping im aktuellen Knoten ERSETZT das gemergte vollständig (kein Deep Merge). Für tiefes Mergen die Daten umstrukturieren oder es im Anwendungscode machen.

yaml
# << only works for MAPPINGS, not sequences or scalars
list_template: &list [1, 2, 3]

# This does NOT merge list items:
combined:
  <<: *list      # WRONG: *list is a sequence, not a mapping
  extra: value   # parse error or unexpected behavior

# Deep merge is NOT supported
parent: &parent
  nested:
    a: 1
    b: 2

child:
  <<: *parent
  nested:
    c: 3   # REPLACES parent.nested entirely
# Result: {nested: {c: 3}}  — NOT {nested: {a:1, b:2, c:3}}

# To deep-merge, you must do it in application code
# or restructure the data.

Merge-Key-Status & Veraltung

Der merge key << war eine YAML-1.1-Erweiterung, die aus der YAML-1.2-Kernspezifikation entfernt wurde. In der Praxis unterstützen die meisten Parser ihn weiterhin (PyYAML, js-yaml, ruamel, SnakeYAML), strenge 1.2-Parser weisen ihn aber zurück. Heute nutzen, aber wissen: Er ist nicht standardkonform; für neue Formate Config-Sprachen mit echter Vererbung erwägen (Cue, Jsonnet, Dhall).

yaml
# IMPORTANT: the << merge key was REMOVED in YAML 1.2
# It was a YAML 1.1 feature.

# In practice, many parsers still support it:
# - PyYAML: supports (1.1 mode)
# - js-yaml: supports (opt-in)
# - ruamel.yaml: supports
# - SnakeYAML: supports
# - LibYAML: supports

# But strict YAML 1.2 parsers reject it:
# new_yaml_1_2_strict:
#   <<: *template    # ERROR in strict 1.2

# Recommendation:
# - Use << for now (widely supported)
# - Document that your files rely on it
# - For new formats, consider composition in code
#   or a config language with proper inheritance
#   (e.g. Dhall, Cue, Jsonnet)

# Alternative without <<:
# just duplicate or use application-level templating
08

Typ-Tags

Eingebaute Tags

Eingebaute Tags nutzen das !!-Präfix (Kurzform von tag:yaml.org,2002:). Sie erzwingen einen bestimmten Typ unabhängig von der Schema-Ableitung. Übliche Tags: !!str, !!int, !!float, !!bool, !!null, !!binary, !!map, !!seq, !!omap, !!set, !!timestamp. Nützlich, wenn die Ableitung falsch raten würde.

yaml
# YAML tags use !! prefix for built-in types
# (the long form is tag:yaml.org,2002:)

# Common built-in tags
str: !!str hello
int: !!int 42
float: !!float 3.14
bool: !!bool true
null: !!null null
binary: !!binary "SGVsbG8="
map: !!map {a: 1}
seq: !!seq [1, 2]
omap: !!omap
  - a: 1
  - b: 2
set: !!set
  ? item1
  ? item2
timestamp: !!timestamp 2024-01-01T00:00:00Z
merge: !!merge "<<"   # the merge key tag

# Tags force a specific type regardless of inference
forced_str: !!str 42        # "42" string
forced_int: !!int "42"      # 42 integer
forced_bool: !!bool "yes"   # true

Typen erzwingen

Tags erzwingen einen bestimmten Typ und überschreiben die Schema-Ableitung. Der häufigste Einsatz ist !!str, um Strings, die wie Zahlen/Booleans/Daten aussehen, vor erzwungener Konvertierung zu schützen. !!int und !!float können numerische Strings parsen. Tags sind essenziell, wenn die Hostanwendung einen bestimmten Typ braucht.

yaml
# Without tags, type depends on schema inference
value: 42          # integer (Core schema)
value: "42"        # string (quoted)
value: !!str 42    # string (forced by tag)

# Common forcing scenarios
version: !!str 1.0       # "1.0" string, not float
phone: !!str 5551234     # string, not int
answer: !!str yes        # string, not bool (1.1)
region: !!str no         # string "no", not False (1.1)

# Force numeric parsing from strings
count: !!int "100"       # 100 integer
ratio: !!float "0.5"     # 0.5 float

# Force bool from strings
enabled: !!bool "yes"    # true
enabled: !!bool "off"    # false

# Force null
empty: !!null ""         # null
empty: !!null "~"        # null

Eigene Tags

Eigene Tags nutzen ein einzelnes !-Präfix und sind anwendungsdefiniert. Die Hostanwendung muss für jedes Tag einen Konstruktor registrieren. Sichere Loader (empfohlen) weisen unbekannte Tags standardmäßig zurück — explizit einschalten musst du. Bibliotheksspezifische Tags (etwa PyYAMLs python/object) können gefährlich sein und werden von sicheren Loadern deaktiviert.

yaml
# Application-specific tags use ! prefix
# The application's YAML loader must handle them

# Custom tag (application-defined)
person: !person
  name: Alice
  age: 30

# Tag with arguments
color: !color rgb(255, 0, 0)
point: !point [10, 20]

# Library-specific tags (PyYAML example)
# python/object/apply:module.func args
sorted_set: !!python/object/apply:sorted
  args:
    - [3, 1, 2]

# Ruby-specific (Psych)
# !ruby/object:ClassName

# Custom tags require custom constructors in code.
# Unknown tags usually cause errors in safe loaders.

Lokale & verbatim Tags

!prefix ist für lokale Tags (anwendungsdefiniert), !! ist die Kurzform der globalen yaml.org-Tags, !<uri> ist verbatim (keine Auflösung), und !prefix!short nutzt %TAG-deklarierte Präfixe zur Kürze. Lokale Tags sind am häufigsten; verbatim Tags zählen bei toolübergreifenden Schemata.

yaml
# ! prefix — local tag (application-specific, no URI)
data: !myapp/data
  value: 42

# !! prefix — global built-in tag (resolved to yaml.org)
str: !!str hello

# !<full-uri> — verbatim tag (exact URI, no resolution)
binary: !<tag:example.com,2024:binary> "data"

# !tag!short — tag with prefix (resolved via %TAG directive)
%TAG !e! tag:example.com,2024:
data: !e!custom value
# resolves to tag:example.com,2024:custom

# %TAG directives declare prefixes
%TAG !yaml! tag:yaml.org,2002:
value: !yaml!str 42   # same as !!str

# Local tags are most common in app-specific YAML
# Verbatim tags are useful for cross-tool interoperability

Tag-Auflösung

Die Tag-Auflösung hängt vom Schema ab. Failsafe (minimal) behandelt alles als Strings, außer getaggt. Das JSON-Schema ergänzt int/float/bool/null. Das Core-Schema (YAML-1.2-Standard) erweitert JSON um toleranteres Matching. Explizite Tags (!!) überschreiben immer die Schema-Auflösung.

yaml
# Tags are resolved by the schema (Core, JSON, Failsafe)
# Without explicit tags, the schema infers types

# Failsafe schema — only str, map, seq (no inference)
# Everything is a string unless tagged
failsafe_value: 42       # str "42"
failsafe_tagged: !!int 42  # int 42

# JSON schema — str, int, float, bool, null, map, seq
json_value: 42           # int
json_str: "42"           # str

# Core schema (default for YAML 1.2) — like JSON but
# with more lenient parsing (yes/no not bool, etc.)
core_value: 42           # int
core_bool: true          # bool
core_str: hello          # str

# Explicit tags override schema resolution
forced: !!str true       # str "true" (even in Core)

Anwendungsspezifische Tags

Anwendungsspezifische Tags erlauben es, Domänenobjekte (Money, DateRange usw.) in YAML einzubetten. Der Loader muss für jedes Tag einen Konstruktor registrieren. Immer safe_loader nutzen, die unbekannte Tags standardmäßig zurückweisen — unvertrautem YAML nie erlauben, beliebige Konstruktoren aufzurufen (eine klassische Deserialisierungsschwachstelle).

yaml
# Define your own tags for domain objects
# Example: a config loader for a custom app

# Tag a node as a "Money" object
price: !money "USD 19.99"

# Tag a node as a "DateRange"
range: !dateRange
  start: 2024-01-01
  end: 2024-12-31

# Tag nodes for custom parsing/validation
settings: !strict
  host: localhost
  port: 8080

# PyYAML example: register a constructor
# class MoneyLoader:
#     def __init__(self, value):
#         self.currency, self.amount = value.split()
#         self.amount = float(self.amount)
#
# yaml.add_constructor('!money', lambda l, n:
#     MoneyLoader(l.construct_scalar(n)))

# Safe loaders reject unknown tags — opt-in explicitly
# to avoid processing untrusted input with side effects.
09

Dokumentmarker & Direktiven

Einzelnes Dokument

Ein einzelnes YAML-Dokument funktioniert auch ohne Marker gut. Ein führendes --- ist eine Konvention, um 'das ist YAML' zu signalisieren und von plain Text abzugrenzen. Der ...-Endmarker ist optional und wird bei Ein-Dokument-Dateien selten genutzt.

yaml
# A single YAML document needs no markers
key: value
list:
  - a
  - b

# But a leading --- is a common convention
# to mark "this is YAML, not plain text"
---
key: value

# The trailing ... (end marker) is optional
# for a single document
key: value
...

Mehrere Dokumente (Stream)

Ein YAML-Stream ist eine Folge von durch --- getrennten Dokumenten. Jedes Dokument wird unabhängig geparst. Streams sind üblich in Kubernetes (mehrere Objekte pro Datei), statischen Site-Generatoren und Logdateien. load_all() oder Äquivalent in deinem Parser nutzen, um Dokumente zu iterieren.

yaml
# A YAML stream is multiple documents separated by ---
---
name: first
value: 1
---
name: second
value: 2
---
name: third
value: 3

# Each document is independent — anchors don't cross
# Use a parser's load_all() / load_multi() to read them
# Python (PyYAML):
#   for doc in yaml.safe_load_all(stream):
#       print(doc)

# Common use cases:
# - Kubernetes: multiple objects in one file
# - Blog generators: front matter + content
# - Log files: one record per document
# - CI/CD: multi-step pipelines

Dokumentend-Marker (...)

Der ...-Marker beendet ein Dokument explizit. Er ist in den meisten Fällen optional, aber nützlich, wenn der Inhalt mehrdeutig sein könnte (z. B. ein literaler Block, der --- enthält). Er signalisiert Streaming-Parsern zudem das Dokumentende. Selten in handgeschriebenem YAML, aber üblich in programmatischer Ausgabe.

yaml
# ... explicitly ends a document
---
key: value
...
# Anything after ... is a new document or stream end

# Useful when a document's content might be ambiguous
# without an explicit end:
---
message: |
  Some content
  ---
  that looks like a separator
...
---
next: document

# Without ... the parser might think the ---
# inside the literal block is a document separator
# (though block scalars usually prevent this)

# ... is also useful in programmatic output to flush

Direktiven

Direktiven erscheinen vor dem Dokumentinhalt und konfigurieren den Parser. %YAML setzt die Version; %TAG deklariert Tag-Präfix-Kurzbefehle. Direktiven sind dokumentbezogen — sie gelten nur für das nächste Dokument. Die meisten Config-Dateien lassen Direktiven weg und verlassen sich auf Parser-Defaults (meist 1.1- oder 1.2-bimodal).

yaml
# Directives appear at the very top, before content
# %YAML — declare YAML version
%YAML 1.2
---
key: value

# %TAG — declare a tag prefix
%TAG !e! tag:example.com,2024:
---
data: !e!custom value

# Multiple directives are allowed
%YAML 1.2
%TAG !e! tag:example.com,2024:
%TAG !yaml! tag:yaml.org,2002:
---
value: !yaml!str hello

# Directives are document-scoped — they apply to the
# next document only and must be repeated for each.
# Most config files omit directives and use defaults.

Dokumentstrom-Beispiele

Dokumentströme sind weit verbreitet. Kubernetes nutzt sie, um mehrere Objekte (Namespace, Deployment, Service) in einer Datei zu bündeln. Helm-Templates, CI-Logs und statische Site-Generatoren (front matter + Inhalt) nutzen ebenfalls Ströme. Jedes Dokument ist unabhängig und darf eigene Direktiven haben.

yaml
# Kubernetes multi-object file
---
apiVersion: v1
kind: Namespace
metadata:
  name: production
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: production
spec:
  replicas: 3
---
apiVersion: v1
kind: Service
metadata:
  name: api
  namespace: production
spec:
  ports:
    - port: 80

# Helm chart templates: stream of objects
# CI logs: one event per document
# Static site generator: front matter + body

Grenzen-Fallstricke

Eine Zeile, die mit --- an Spalte 0 beginnt, ist immer ein Dokumenttrenner (außerhalb von Blockskalaren). Innerhalb von Blockskalaren (|, >) ist --- literaler Inhalt. Um --- an Spalte 0 in einem Wert zu haben, den Block einrücken oder das Dokument zuerst mit ... beenden. Ein --- mit Inhalt auf derselben Zeile ist ein Dokumentanfangs-Marker, kein Trenner.

yaml
# A line starting with --- is ALWAYS a document separator
# (when at column 0). This can surprise you:

---
script: |
  echo hello
  ---  # this is INSIDE the block scalar — safe
next: value

# But this is NOT safe:
---
content: |
  line1
---
mistaken: this is a NEW document, not part of content!

# Inside block scalars, --- is literal (good).
# Outside, --- at column 0 always separates documents.

# Workaround for content that must contain --- at col 0:
# indent the block, or use ... to end the doc first.

# Also: a bare --- line with content on the same line
# is the document start marker, NOT a separator
--- key: value   # this is one document
10

Flow-Stil

Flow-Sequenzen

Flow-Sequenzen nutzen [ ] und verhalten sich wie JSON-Arrays. Whitespace und Zeilenumbrüche darin sind flexibel. Anders als JSON sind nachgestellte Kommas NICHT erlaubt. Nützlich für kurze, dichte Listen. Einträge quoten, die Sonderzeichen enthalten (Kommas, Klammern, Doppelpunkte).

yaml
# Flow sequences use [item1, item2, ...]
numbers: [1, 2, 3]
names: [Alice, Bob, Charlie]

# Empty
empty: []

# Nested flow sequences
matrix: [[1, 2], [3, 4]]

# Flow sequence of mappings
points: [{x: 1, y: 2}, {x: 3, y: 4}]

# Multi-line flow sequence (whitespace is flexible)
long: [
  alpha,
  beta,
  gamma
]

# Quoting inside flow
mixed: ["hello", 'world', 42, true]

# NO trailing comma
bad: [1, 2, 3,]   # parse error

Flow-Mappings

Flow-Mappings nutzen { } und verhalten sich wie JSON-Objekte. Schlüssel dürfen quotiert sein, wenn sie Sonderzeichen enthalten. Whitespace ist flexibel. Nachgestellte Kommas sind verboten (anders als JSON). Flow-Mappings für kurze, dichte Daten nutzen; Blockstil ist bei größeren Strukturen lesbarer.

yaml
# Flow mappings use {key: value, ...}
point: {x: 10, y: 20}
config: {host: localhost, port: 8080}

# Empty mapping
empty: {}

# Nested flow mappings
nested: {a: {b: {c: value}}}

# Quoted keys (needed for special chars)
quoted: {"key with space": value, "weird:key": 1}

# Multi-line flow mapping
config: {
  host: localhost,
  port: 8080,
  debug: true
}

# Flow mapping with flow sequence value
mixed: {nums: [1, 2, 3], name: test}

# NO trailing comma
bad: {a: 1, b: 2,}   # parse error

Gemischter Flow & Block

Flow- und Blockstile lassen sich innerhalb eines Dokuments frei mischen. Die pragmatische Regel: Blockstil für strukturelle Elemente (bessere Lesbarkeit durch Einrückung) und Flow-Stil für kurze Inline-Werte (Skalar-Listen, kleine Maps). Tief verschachtelten Flow vermeiden — er wird schnell unlesbar.

yaml
# Mix flow and block styles freely
config:
  name: myapp
  ports: [80, 443]        # flow sequence in block mapping
  endpoints: {api: /v1, web: /}  # flow mapping in block

# Block inside flow (less common but valid)
flow_with_block: [{name: Alice, roles: [admin, user]}, {name: Bob}]

# Flow at top level
[top, level, flow]

# Block at top level
- block
- sequence

# Pragmatic rule:
# - Block for structure (readability)
# - Flow for short inline values
# - Avoid deeply nested flow — it becomes unreadable

Verschachtelter Flow

Der Flow-Stil darf beliebig tief verschachteln, aber jede Ebene ergänzt Klammern, die schwer zu lesen werden. Nach 1-2 Verschachtelungsebenen für Lesbarkeit zum Blockstil wechseln. Das Blockäquivalent tief verschachtelten Flows ist für menschliche Pfleger fast immer klarer.

yaml
# Flow can nest arbitrarily
data: {users: [{name: Alice, tags: [a, b]}, {name: Bob}]}

# Equivalent block:
# data:
#   users:
#     - name: Alice
#       tags:
#         - a
#         - b
#     - name: Bob

# Multi-line nested flow (rare but valid)
matrix: {
  rows: [
    [1, 2, 3],
    [4, 5, 6]
  ],
  cols: 3
}

# Recommendation: switch to block style after 1-2 levels
# of nesting — flow becomes a "wall of brackets".

Wann Flow-Stil

Flow-Stil für kurze Skalar-Listen, kleine Lookup-Maps, Einzeilen-Datensätze und JSON-kompatible Ausgabe nutzen. Flow bei langen Listen vermeiden (schwer zu überstreichen), tief verschachtelten Strukturen (Klammerwand) oder allem, das Inline-Kommentare braucht. Im Zweifel Blockstil für Lesbarkeit bevorzugen.

yaml
# Good uses of flow style:

# 1. Short lists of scalars
ports: [80, 443, 8080]
colors: [red, green, blue]

# 2. Small lookup maps
codes: {200: OK, 404: NotFound, 500: Error}

# 3. Single-line records in a sequence
coordinates:
  - {x: 1, y: 2}
  - {x: 3, y: 4}
  - {x: 5, y: 6}

# 4. JSON-compatible output (flow is JSON-compatible)

# Bad uses of flow style:

# 1. Long lists (use block)
#   ports: [80, 443, 8080, 8443, 9000, 9090, 9091, ...]  # hard to read

# 2. Deeply nested (use block)
#   {a: {b: {c: {d: {e: value}}}}}  # unreadable

# 3. Anything with comments (flow doesn't allow inline comments well)

Flow-Stil-Vorbehalte

Der Flow-Stil hat Vorbehalte: Sonderzeichen (Kommas, Doppelpunkte, Klammern) brauchen Quotierung; keine nachgestellten Kommas; Kommentare sind umständlich; keine | oder > Blockskalare (\n in doppelquotierten Strings nutzen); und Einzelzeilen-Änderungen lassen sich schwerer diffen. Blockstil ist freundlicher für versionierte Config.

yaml
# Caveat 1: special characters need quotes in flow
flow: [a, b, "c,d", "d:e"]   # commas and colons need quoting
block:
  - a
  - b
  - c,d      # no quotes needed in block style
  - d:e      # no quotes needed in block style

# Caveat 2: no trailing commas
bad: [1, 2, 3,]   # error

# Caveat 3: comments are awkward in flow
config: {
  host: localhost,  # comment allowed but clunky
  port: 8080
}

# Caveat 4: flow style has no multi-line strings
# (no | or > inside flow)
# You can use \n escapes in double quotes:
text: "line1\nline2"

# Caveat 5: flow is harder to diff in version control
# (one-line changes vs whole-block changes)
11

YAML- & JSON-Konvertierung

JSON ist gültiges YAML

YAML 1.2 wurde so entworfen, dass JSON eine strenge Teilmenge ist — jedes JSON-Dokument ist gültiges YAML. Die meisten YAML-Parser lesen JSON gern. Umgekehrt gilt das nicht: YAML-Features wie Kommentare, Anker, Mehrdokument-Ströme und Blockskalare sind kein gültiges JSON.

yaml
# JSON is a strict subset of YAML 1.2
# Any JSON file is valid YAML

# This is valid YAML (it's JSON):
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}

# So is this multi-line JSON:
{
  "name": "Alice",
  "age": 30,
  "hobbies": ["a", "b"]
}

# Parsers usually accept JSON files as YAML
# Python: yaml.safe_load(json_string)  # works
# JS:     YAML.load(json_string)       # works
# Go:     yaml.Unmarshal(json_bytes, &v)  # works (yaml.v3)

# But the reverse is NOT always true:
# YAML with comments, anchors, multi-docs is NOT valid JSON

Äquivalente Repräsentationen

JSON, YAML-Block und YAML-Flow können dieselben Daten repräsentieren. JSON ist am portabelsten (jede Sprache hat einen JSON-Parser). YAML-Block ist für Menschen am lesbarsten. YAML-Flow ist ein kompakter Mittelweg. Nach Publikum wählen: Tools (JSON) vs. Menschen (YAML-Block).

yaml
# JSON:
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}

# YAML block:
name: Alice
age: 30
hobbies:
  - a
  - b

# YAML flow (closest to JSON):
{name: Alice, age: 30, hobbies: [a, b]}

# YAML with quotes (JSON-compatible):
{"name": "Alice", "age": 30, "hobbies": ["a", "b"]}

# All four parse to the same data structure.
# Pick the style that fits your use case:
# - JSON for interop and strict tools
# - YAML block for human-edited config
# - YAML flow for compact inline data

JSON zu YAML konvertieren

JSON zu YAML konvertieren, indem JSON geparst und dann als YAML mit default_flow_style=False (Blockstil) gedumpt wird. JSONs Pflicht-Anführungszeichen fallen weg, wo YAML sie nicht braucht. Auf Schlüssel achten, die wie Zahlen/Booleans aussehen — sie brauchen in YAML womöglich Quotierung, um den String-Typ zu erhalten.

yaml
# Convert JSON to YAML using a parser
# Python:
# import json, yaml
# data = json.loads(json_string)
# yaml_str = yaml.safe_dump(data, default_flow_style=False, sort_keys=False)
#
# JS:
# const data = JSON.parse(jsonString)
# const yamlStr = yaml.dump(data)

# Example input JSON:
# {"server": {"host": "localhost", "port": 8080}, "debug": true}

# Output YAML:
# server:
#   host: localhost
#   port: 8080
# debug: true

# Conversion considerations:
# - JSON keys are always quoted -> YAML usually unquotes them
# - JSON arrays -> YAML block sequences (with default_flow_style=False)
# - JSON strings with special chars may need quoting
# - JSON null -> YAML null (or ~)
# - JSON booleans/numbers preserved

YAML zu JSON konvertieren

YAML zu JSON konvertieren, indem geparst und dann JSON-serialisiert wird. Vorbehalte: Kommentare und Tags gehen verloren; Anker werden zu plain Kopien expandiert; Mehrdokument-Ströme müssen zu einem JSON-Array werden; YAML-Daten können zu Strings werden. Tools wie yq machen das auf der Befehlszeile leicht.

yaml
# Convert YAML to JSON
# Python:
# import json, yaml
# data = yaml.safe_load(yaml_string)
# json_str = json.dumps(data, indent=2)

# JS:
# const data = yaml.load(yamlString)
# const jsonStr = JSON.stringify(data, null, 2)

# Command-line tools:
# yq -o=json '.config' file.yaml        # mikefarah/yq
# ruby -ryaml -rjson -e 'puts JSON.generate(YAML.load(STDIN.read))' < file.yaml
# python -c 'import json,sys,yaml; print(json.dumps(yaml.safe_load(sys.stdin)))'

# Caveats when converting YAML to JSON:
# - YAML comments are LOST (JSON has no comments)
# - YAML anchors are EXPANDED to plain copies
# - YAML multi-doc streams become a JSON array (or fail)
# - YAML tags (!!) are lost or cause errors
# - YAML dates may become strings (JSON has no date type)

JSON-kompatible Teilmenge

Die JSON-kompatible Teilmenge von YAML vermeidet Kommentare, Anker, Mehrdokumente, Tags, Blockskalare und plain Strings, die wie andere Typen aussehen. In dieser Teilmenge zu bleiben garantiert saubere JSON-Rundtrips. Nützlich, wenn sowohl YAML- als auch JSON-Konsumenten dieselben Daten lesen oder strenge Typerhaltung zählt.

yaml
# To produce YAML that round-trips to JSON cleanly,
# stay within the JSON-compatible subset:

# 1. No comments
# 2. No anchors/aliases
# 3. No multi-doc streams
# 4. No tags
# 5. No block scalars (|, >) — use \n in double-quoted strings
# 6. Quote all string keys (JSON requires this)
# 7. No plain strings that look like other types

# JSON-compatible YAML:
{"name": "Alice", "age": 30, "active": true}
{"items": ["a", "b", "c"]}
{"nested": {"key": "value"}}

# Useful when you need both YAML and JSON consumers
# for the same data, or want strict type preservation.

# Many YAML dumpers have a "json-compatible" mode.

Rundtrip-Überlegungen

YAML-Rundtrips (parsen, dann dumpen) verlieren oft Kommentare, Ankernamen, Schlüsselreihenfolge, Quotierungsstil und Formatierung. ruamel.yaml (Python) hat einen Rundtrip-Modus, der Kommentare und Reihenfolge erhält. Bei menschlich editierter Config niemals blind mit Dumper-Ausgabe überschreiben — zuerst sorgfältig diffen.

yaml
# Round-trip: YAML -> parse -> dump -> YAML
# Information that may be LOST:
# - Comments (most dumpers drop them)
# - Anchor names (dumpers may re-create or expand)
# - Key order (some dumpers sort keys)
# - Quoting style (dumpers choose their own)
# - Flow vs block style (dumpers usually pick one)
# - Whitespace and indentation amount
# - Multi-document structure (sometimes)
# - Tag prefixes and %TAG directives

# Tools that preserve style:
# - ruamel.yaml (Python): round-trip mode preserves comments/order
# - yaml.v3 (Go): preserves key order
# - prettier with yaml plugin: normalizes formatting

# For config files where humans edit:
# - Use ruamel.yaml round-trip mode
# - Or accept that dumps are "normalized"
# - Never overwrite human-edited files with dumper output
#   without diffing carefully
12

YAML-Schemata

Failsafe-Schema

Das Failsafe-Schema ist das konservativste — es erkennt nur str, map und seq. Alle Skalare sind Strings, außer explizit getaggt. Nützlich für unvertraute Eingaben (keine impliziten Konvertierungs-Überraschungen) oder als Basis eigener Schemata. Die meisten Produktionsloader nutzen ein etwas reicheres Schema.

yaml
# Failsafe schema — the most conservative
# Recognizes ONLY three types: str, map, seq
# Everything else is a string

# Under Failsafe:
value: 42           # str "42" (NOT int)
flag: true          # str "true" (NOT bool)
empty: null         # str "null" (NOT null)
date: 2024-01-01    # str "2024-01-01" (NOT date)

# Use explicit tags to get other types
int_value: !!int 42
bool_value: !!bool true
null_value: !!null null

# When to use Failsafe:
# - Untrusted input (no implicit type coercion)
# - When you want strings only
# - As a base for custom schemas

# PyYAML: SafeLoader uses a schema close to Failsafe
# but with int/float/bool/null inference.

JSON-Schema

Das JSON-Schema entspricht exakt JSONs Typsystem: str, int, float, bool, null, map, seq. Strenger als das Core-Schema — keine Oktal-/Binärliterale, keine Unterstrich-Trenner, nur true/false als Booleans, keine Datenableitung. Für JSON-Interop oder strenges Typverhalten nutzen.

yaml
# JSON schema — same type system as JSON
# Recognizes: str, int, float, bool, null, map, seq

# Under JSON schema:
int: 42             # int
float: 3.14         # float
str: hello          # str
bool: true          # bool
null_val: null      # null
list: [1, 2, 3]     # seq
map: {a: 1}         # map

# Differences from Core schema:
# - Stricter number parsing (no 0o octal, no _ separators)
# - Booleans are only true/false (no yes/no)
# - No date/timestamp inference

# When to use JSON schema:
# - Interop with JSON tools
# - Strict type behavior
# - When you want JSON's type semantics

Core-Schema

Das Core-Schema ist der YAML-1.2-Standard. Er erweitert JSON um tolerantes Parsen: hex (0x), oktal (0o), binär (0b), Unterstriche in Zahlen, .inf/.nan-Floats. Booleans sind nur true/false (nicht yes/no). Daten sind Strings (keine Ableitung). Die meisten modernen Parser defaulted auf Core oder eine 1.1-kompatible Variante.

yaml
# Core schema — the DEFAULT for YAML 1.2
# Extends JSON schema with more lenient scalar resolution

# Under Core schema:
int: 42             # int
neg: -17            # int
hex: 0xFF           # int (255)
oct: 0o17           # int (15)  [YAML 1.2 syntax]
bin: 0b1010         # int (10)
float: 3.14         # float
exp: 1.0e+3         # float
inf: .inf           # float
nan: .nan           # float
bool: true          # bool (only true/false, not yes/no)
null: null          # null (also ~, empty)
str: hello          # str
date: 2024-01-01    # str (Core does NOT infer dates)

# Differences from YAML 1.1:
# - yes/no/on/off are STRINGS (not booleans)
# - 017 is a string (octal is 0o17 in 1.2)
# - Dates are strings (no implicit inference)

# Most modern parsers default to Core or close to it.

YAML 1.1 vs. 1.2

YAML 1.1 (PyYAML-Standard) behandelt yes/no/on/off als Booleans und führende-0-Zahlen als Oktal — berühmte Bugquellen (Norwegen 'no' → false). YAML 1.2 (aktuelle Spezifikation) beschränkt Booleans auf true/false und nutzt 0o für Oktal. Immer den Default deines Parsers prüfen und mehrdeutige Strings quoten.

yaml
# YAML 1.1 (older, used by PyYAML by default)
bool_1_1: yes       # true (yes/no/on/off are booleans)
octal_1_1: 017      # 15 (leading 0 = octal)
sexagesimal: 1:30   # 90 (base-60!) - obscure feature

# YAML 1.2 (current spec)
bool_1_2: yes       # str "yes" (only true/false are bool)
octal_1_2: 0o17     # 15 (explicit 0o prefix)
no_sexagesimal: 1:30 # str "1:30"

# Practical impact:
# - "no" (Norway) becomes False in PyYAML (1.1)
# - "010" becomes 8 in PyYAML, "010" in 1.2
# - "on"/"off" become True/False in 1.1, strings in 1.2

# PyYAML: defaults to 1.1 behavior
# ruamel.yaml: defaults to 1.2 (with 1.1 compatibility options)
# js-yaml: defaults to 1.1 with 1.2 options
# Go yaml.v3: defaults to 1.2-ish

# Always check your parser's default schema!

Typauflösungs-Unterschiede

Die Typauflösung unterscheidet sich zwischen YAML-1.1- und 1.2-Parsern: yes/no/on/off, führende-Null-Zahlen und sexagesimale Literale parsen unterschiedlich. Abmildern durch Quotieren mehrdeutiger Strings, Version mit %YAML pinnen, explizite Tags nutzen und gegen alle Ziel-Parser testen.

yaml
# Same YAML, different parsers, different types:
value: yes

# PyYAML (1.1):        True (bool)
# js-yaml (1.1):       true (bool)
# ruamel (1.2):        "yes" (str)
# Go yaml.v3 (1.2):    "yes" (str)
# Strict 1.2:          "yes" (str)

value: 010

# PyYAML (1.1):        8 (int, octal)
# ruamel (1.2):        "010" (str)
# Go yaml.v3 (1.2):    "010" (str)

value: 1.0

# All:                 1.0 (float) - consistent

value: true

# All:                 true (bool) - consistent

# Mitigation strategies:
# 1. Quote strings that look like other types
# 2. Pin the YAML version with %YAML 1.2
# 3. Use explicit tags (!!) for critical values
# 4. Test against all target parsers

Schema wählen

Schema nach Anwendungsfall wählen: 1.2 Core für neue Projekte (vorhersagbar), 1.1 für PyYAML-Interop (oder mehrdeutige Strings quoten), Failsafe/JSON für unvertraute Eingaben, JSON-Schema für JSON-Interop. Für Config-Dateien ist 1.2 Core plus Quotieren mehrdeutiger Strings ("no", "010" usw.) die sicherste Kombination.

yaml
# Recommendations for choosing a schema:

# 1. For NEW projects: use YAML 1.2 Core schema
#    - More predictable (no yes/no surprises)
#    - Modern parsers support it
#    - ruamel.yaml, Go yaml.v3 default to it

# 2. For INTEROP with existing PyYAML code:
#    - Either accept 1.1 semantics
#    - Or use ruamel.yaml with 1.2 + preserve 1.1 features
#    - Quote all ambiguous strings explicitly

# 3. For UNTRUSTED input: use Failsafe or JSON schema
#    - No implicit type coercion
#    - Smaller attack surface
#    - Predictable behavior

# 4. For CONFIG FILES: use 1.2 Core + quote ambiguous strings
#    - "no", "yes", "on", "off", "010", "1.0" should be quoted
#    - Document your schema choice
#    - Lint with yamllint

# 5. For JSON INTEROP: use JSON schema
#    - Same types as JSON
#    - Round-trips cleanly
13

YAML-Lint & Validierung

yamllint

yamllint ist der Standard-YAML-Linter (Python). Er findet Syntaxfehler, Einrückungsprobleme, nachgestellten Whitespace, fehlende Dokumentmarker und mehr. In CI und Pre-Commit-Hooks nutzen, um YAML-Probleme früh zu erwischen. Der strenge Modus (-s) behandelt Warnungen als Fehler.

yaml
# yamllint is the standard YAML linter
# Install: pip install yamllint

# Lint a file
# yamllint config.yaml

# Lint with strict mode (warnings = errors)
# yamllint -s config.yaml

# Output example:
# config.yaml
#   3:4       error    mapping values are not allowed here
#   5:1       error    syntax error: found character '	' that cannot start any token
#   8:3       warning  missing document start "---"
#   12:5      warning  comment is not indented like content

# Lint multiple files
# yamllint file1.yaml file2.yaml file3.yaml

# Lint a directory (recursive)
# yamllint -d path/to/dir

# Read from stdin
# cat config.yaml | yamllint -

Lint-Konfiguration

yamllint mit .yamllint.yml konfigurieren. Ein Profil erweitern (default oder strict), dann einzelne Regeln überschreiben: Einrückung, Zeilenlänge, Quotierungsstil, Kommentare, nachgestellte Leerzeichen, Dokumentmarker. An den Stil des Teams anpassen. In CI ausführen, um konsistent zu erzwingen.

yaml
# .yamllint.yml — configuration file for yamllint
# Place in project root or ~/.config/yamllint/config

# Use a built-in profile
extends: default

# Or use a stricter profile
# extends: strict

# Override specific rules
rules:
  # Require document start marker
  document-start: disable
  # Enforce 2-space indentation
  indentation:
    spaces: 2
    indent-sequences: true
  # Max line length
  line-length:
    max: 120
    allow-non-breakable-words: true
  # Disallow trailing spaces
  trailing-spaces: enable
  # Require consistent quoting
  quoted-strings:
    quote-type: double
    required: only-when-needed
  # Disallow comments without space before #
  comments:
    require-starting-space: true
    min-spaces-from-content: 1

Häufige Syntaxfehler

Häufige YAML-Fehler: Tabs für Einrückung (nur Leerzeichen erlaubt), Doppelpunkt ohne folgendes Leerzeichen, unquotierte Strings mit Doppelpunkten (als Mappings geparst), nachgestellte Kommas im Flow-Stil, inkonsistente Einrückung und doppelte Schlüssel. Ein Linter findet all das automatisch.

yaml
# Error: tab characters for indentation
# bad:
# 	key: value   <- tab not allowed
# Fix: use spaces only

# Error: colon without space
# bad:  key:value
# good: key: value

# Error: unquoted special characters
# bad:  url: http://example.com:8080   <- parsed as mapping
# good: url: "http://example.com:8080"

# Error: trailing comma in flow
# bad:  list: [1, 2, 3,]
# good: list: [1, 2, 3]

# Error: inconsistent indentation
# bad:
#   key1: value
#    key2: value   <- one extra space
# good:
#   key1: value
#   key2: value

# Error: duplicate keys (some parsers warn)
# bad:
#   key: first
#   key: second
# good: rename one

Tab-vs-Leerzeichen-Fehler

Tabs sind für YAML-strukturelle Einrückung streng verboten — die Ursache Nummer 1 für Parsefehler. Tabs innerhalb von String-Werten (Blockskalare, quotierte Strings) sind fein. Den Editor konfigurieren, für YAML-Dateien Leerzeichen zu nutzen (expandtab). Betroffene Zeilen mit grep -P '\t' finden.

yaml
# YAML FORBIDS tabs for indentation.
# This is the #1 cause of YAML parse errors.

# Symptom: parser error like
# "found character '\t' that cannot start any token"
# or "while scanning for the next token, found tab"

# Tabs are allowed INSIDE string values:
script: |
  #!/bin/bash
  if [ -f file ]; then   # this is fine (literal content)
  \techo found           # \t inside block scalar is OK

# But tabs for STRUCTURAL indentation are forbidden:
# bad:
# services:
# \tweb:
# \t\timage: nginx

# Fix: convert tabs to spaces
# Configure your editor to use spaces for YAML files
# VS Code: "editor.insertSpaces": true, "editor.tabSize": 2
# Vim: set expandtab shiftwidth=2

# Detect tabs:
# grep -P '\t' file.yaml   (finds offending lines)

Doppelschlüssel-Erkennung

Doppelte Schlüssel in einem Mapping sind unüblich und eine häufige Bugquelle (stilles Last-wins-Override). yamllint findet sie mit der key-duplicates-Regel (standardmäßig aktiv). Häufige Ursachen: Copy-Paste-Fehler und schlechte Merge-Konflikt-Auflösung. Immer in CI linten, um sie früh zu erwischen.

yaml
# Duplicate keys are technically discouraged
# but YAML 1.2 doesn't strictly forbid them.
# Behavior varies by parser (usually last-wins).

config:
  host: localhost
  port: 8080
  host: prod.example.com   # silent override!

# yamllint catches these:
#   4:3  error  duplication of key "host" in mapping

# Enable in .yamllint.yml:
# rules:
#   key-duplicates: enable

# Other tools that detect duplicates:
# - kubeval (for Kubernetes YAML)
# - yq (programmatic checks)
# - Custom schema validation (JSON Schema)

# Common cause: copy-paste errors, merge conflicts
# resolved incorrectly. Always lint in CI to catch.

Schema-Validierung

YAML-Struktur mit JSON Schema validieren (funktioniert, weil YAML eine JSON-Obermenge ist). Für Kubernetes kubeval oder kubectl --dry-run nutzen. Für allgemeine Config yamllint (Syntax/Stil) plus jsonschema (Struktur) oder Cue (Schemasprache). Validierung in Pre-Commit-Hooks und CI verdrahten.

yaml
# Validate YAML against a JSON Schema
# (JSON Schema works on YAML since YAML is a JSON superset)

# Python example with jsonschema + PyYAML:
# import json, yaml, jsonschema
# with open('schema.json') as f: schema = json.load(f)
# with open('config.yaml') as f: doc = yaml.safe_load(f)
# jsonschema.validate(doc, schema)

# Tools for Kubernetes YAML:
# kubeval            - validate against K8s schemas
# kubectl apply --dry-run=client -f file.yaml
# conftest           - policy-based validation (OPA)

# Tools for general YAML:
# yamllint           - syntax + style
# jsonschema-cli     - JSON Schema validation
# cue                - schema + validation language
# dataladen          - config validation

# Pre-commit hook example (.pre-commit-config.yaml):
# repos:
#   - repo: https://github.com/adrienverge/yamllint
#     rev: v1.32.0
#     hooks:
#       - id: yamllint
#         args: [-s]
14

Docker-Compose-YAML

Service-Definition

Docker-Compose-Dateien definieren Mehrcontainer-Apps. Die Top-Level-Schlüssel sind version, services, volumes, networks, configs, secrets. Jeder Service definiert image/build, ports, volumes, environment, depends_on, Restart-Richtlinie. Auf Top-Level deklarierte Volumes sind benannt und persistiert.

yaml
# docker-compose.yml — multi-container apps
version: "3.9"   # compose file format version

services:
  web:
    image: nginx:1.25
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./html:/usr/share/nginx/html:ro
    restart: unless-stopped
    depends_on:
      - api

  api:
    build:
      context: ./api
      dockerfile: Dockerfile
    environment:
      - NODE_ENV=production
      - DB_URL=postgres://db:5432/app
    ports:
      - "8080:8080"
    restart: always

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - db_data:/var/lib/postgresql/data
    restart: always

volumes:
  db_data:

Volumes & Netzwerke

Compose-Volumes sind Bind-Mounts (host:container), benannt (in Top-Level-volumes deklariert) oder anonym. Das :ro-Suffix macht Mounts nur-lesend. Netzwerke isolieren Dienste; internal: true blockt externen Zugang. Benannte Volumes erhalten Daten über Container-Neuerzeugungen hinweg.

yaml
services:
  web:
    image: nginx
    volumes:
      # Bind mount: host:container
      - ./html:/usr/share/nginx/html:ro
      # Named volume: name:container
      - shared_data:/data
      # Anonymous volume
      - /tmp/cache
    networks:
      - frontend
      - backend

  db:
    image: postgres
    volumes:
      - db_data:/var/lib/postgresql/data
    networks:
      - backend

volumes:
  db_data:
    driver: local
  shared_data:
    driver: nfs
    driver_opts:
      type: nfs
      device: ":/path/to/share"

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true   # no external access

Umgebungsvariablen

Compose unterstützt drei Env-Var-Stile: Liste (KEY=value), Map (KEY: value) und env_file. ${VAR} wird zur Parse-Zeit aus der Host-Shell oder .env-Datei interpoliert; ${VAR:-default} liefert Defaults. $$ nutzen, um ein literales $ zu escapen. Die .env-Datei im Projektstamm wird automatisch geladen.

yaml
services:
  api:
    image: myapi
    # Method 1: list of KEY=value
    environment:
      - NODE_ENV=production
      - LOG_LEVEL=info
    # Method 2: map (cleaner)
    environment:
      NODE_ENV: production
      LOG_LEVEL: info
    # Method 3: file
    env_file:
      - .env
      - .env.production
    # Interpolation from host environment
    environment:
      - API_KEY=${API_KEY}     # from shell
      - PORT=${PORT:-8080}      # default 8080

# .env file (auto-loaded by docker compose):
# API_KEY=abc123
# PORT=8080
# DB_URL=postgres://...

# Compose substitutes ${VAR} from host shell or .env
# Use $$ to escape (literal $):
# - TOKEN=price_$$5   # produces price_$5

Depends, Healthchecks & Restart

depends_on mit condition: service_healthy wartet, bis der Healthcheck einer Dependency besteht, bevor gestartet wird. Healthchecks nutzen test (CMD oder CMD-SHELL), interval, timeout, retries, start_period. Restart-Richtlinien: no, always, unless-stopped (übersteht Reboots, respektiert aber manuelles Stoppen), on-failure.

yaml
services:
  api:
    image: myapi
    depends_on:
      db:
        condition: service_healthy   # wait for db healthy
      redis:
        condition: service_started
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

  db:
    image: postgres
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

# restart policies:
# no              - never restart (default)
# always          - always restart on stop
# unless-stopped  - restart unless manually stopped
# on-failure      - restart only on non-zero exit

Override-Dateien

Compose verschmilzt Override-Dateien über die Basis. docker-compose.override.yml wird automatisch angewendet. Mappings werden tief gemergt (Overrides gewinnen); Sequenzen werden meist ersetzt (nicht angehängt) — bei ports/volumes aufpassen. -f-Flags nutzen, um für umgebungsspezifische Konfigurationen eine explizite Dateireihenfolge anzugeben.

yaml
# docker-compose.yml — base
services:
  web:
    image: nginx
    ports:
      - "80:80"
    environment:
      - ENV=base

# docker-compose.override.yml — auto-applied on top
# (loaded automatically by 'docker compose up')
services:
  web:
    ports:
      - "8080:80"      # overrides "80:80"
    environment:
      - DEBUG=true     # added
      - ENV=override   # overrides ENV=base
    volumes:
      - ./dev.conf:/etc/nginx/conf.d/default.conf

# Multiple override files (-f flag):
# docker compose -f compose.yml -f compose.prod.yml -f compose.secrets.yml up

# Merge rules:
# - mappings: deep-merged (overrides win, others kept)
# - sequences: usually REPLACED (not appended) —
#   ports/depends_on/volumes are exceptions in some versions

# Use -f to specify explicit file order

Profile & Compose-Features

Profile erlauben es, sich für Dienste anzumelden (z. B. debug, test, ci) mit dem --profile-Flag. Weitere v3-Features: init (korrekte PID-1-Signalbehandlung), extends (von einem anderen Service erben), configs und secrets (als Dateien gemountet), deploy (Swarm-Platzierung/Replicas/Ressourcen). Profile sind super, um eine Compose-Datei für mehrere Umgebungen zu halten.

yaml
# Profiles — opt-in services
services:
  web:
    image: nginx
    # no profile: always started

  debug:
    image: busybox
    profiles: ["debug"]   # only with --profile debug

  loadtest:
    image: locust
    profiles: ["test", "ci"]

# Enable a profile:
# docker compose --profile debug up
# docker compose --profile test --profile ci up

# Compose file format features (v3.9+):
# - deploy: placement, replicas, resources (Swarm-only in v3)
# - configs: external config files
# - secrets: mounted secret files
# - extends: inherit from another service
# - init: run tini as PID 1

services:
  worker:
    image: worker
    init: true   # proper signal handling
    extends:
      service: base   # inherit fields
    configs:
      - config1
    secrets:
      - api_key

configs:
  config1:
    file: ./config.toml
secrets:
  api_key:
    file: ./api_key.txt
15

Kubernetes-YAML

Objektstruktur

Jedes Kubernetes-Objekt hat apiVersion, kind, metadata und spec. apiVersion ist group/version (z. B. apps/v1, v1 für Core). metadata umfasst name, namespace, labels, annotations. spec ist der gewünschte Zustand — Kubernetes arbeitet daran, die Realität an spec anzupassen. status wird vom System gesetzt.

yaml
# Every Kubernetes object has the same 4 top-level fields
apiVersion: apps/v1        # API group + version
kind: Deployment           # object type
metadata:                  # identity
  name: my-app
  namespace: production
  labels:
    app: my-app
    tier: backend
  annotations:
    deployment.kubernetes.io/revision: "1"
spec:                      # desired state
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: app
          image: my-app:1.0.0
          ports:
            - containerPort: 8080

# apiVersion + kind + metadata + spec is the universal shape
# (some objects use status too, but you don't set it)

Labels & Selectors

Labels identifizieren und gruppieren Objekte; Selectors fragen nach Labels ab. Gleichheitsbasierte (key=value) und mengenbasierte (In, NotIn, Exists, DoesNotExist) Selector werden beide unterstützt. Annotations halten nicht-identifizierende Metadaten (Beschreibungen, Kontaktinfos, Tooling-Konfiguration). Labels sind für Auswahl; Annotations für Zusatzinfo.

yaml
# Labels — identify and group objects
metadata:
  labels:
    app: my-app
    tier: backend
    env: production
    version: "1.0"

# Selectors — query objects by labels
# Equality-based
selector:
  matchLabels:
    app: my-app
    env: production

# Set-based
selector:
  matchExpressions:
    - {key: tier, operator: In, values: [backend, api]}
    - {key: env, operator: NotIn, values: [dev]}
    - {key: version, operator: Exists}

# kubectl commands:
# kubectl get pods -l app=my-app
# kubectl get pods -l 'tier in (backend,api),env!=dev'
# kubectl get pods -l app=my-app -l env=production

# Annotations — non-identifying metadata
metadata:
  annotations:
    description: "My app deployment"
    contact: "[email protected]"

Pod-Spec

Ein Pod-Spec definiert Container, deren Images, Ports, Env-Variablen (literal oder aus secrets/configmaps), Ressourcen (requests/limits), Probes (readiness/liveness), Volumes und volumeMounts. Pods sind die kleinste deploybare Einheit, aber man erzeugt sie üblicherweise via Deployments, nicht direkt.

yaml
apiVersion: v1
kind: Pod
metadata:
  name: my-pod
spec:
  containers:
    - name: app
      image: my-app:1.0
      ports:
        - containerPort: 8080
          name: http
      env:
        - name: LOG_LEVEL
          value: info
        - name: SECRET_KEY
          valueFrom:
            secretKeyRef:
              name: app-secrets
              key: secret-key
      resources:
        requests: {cpu: 100m, memory: 128Mi}
        limits: {cpu: 500m, memory: 512Mi}
      readinessProbe:
        httpGet: {path: /health, port: 8080}
        initialDelaySeconds: 5
        periodSeconds: 10
      volumeMounts:
        - name: config
          mountPath: /etc/config
  volumes:
    - name: config
      configMap:
        name: app-config
  restartPolicy: Always

Deployment

Ein Deployment verwaltet ReplicaSets und Pods. spec.replicas setzt die gewünschte Anzahl. strategy.type kann RollingUpdate (Standard, gesteuert durch maxSurge/maxUnavailable) oder Recreate sein. Das Pod-Template (spec.template) definiert, wie Pods erzeugt werden. Rollouts mit kubectl rollout status/undo/history verwalten.

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: app
          image: my-app:1.0.0
          ports:
            - containerPort: 8080
          resources:
            requests: {cpu: 100m, memory: 128Mi}
            limits: {cpu: 500m, memory: 512Mi}
          readinessProbe:
            httpGet: {path: /ready, port: 8080}
  # Rollback / history
  # kubectl rollout status deployment/my-app
  # kubectl rollout undo deployment/my-app
  # kubectl rollout history deployment/my-app

Service

Ein Service exponiert Pods als Netzwerkdienst. type ClusterIP (Standard) ist nur intern; NodePort exponiert auf jedem Knoten; LoadBalancer provisioniert eine Cloud-LB; ExternalName ist ein DNS-CNAME. selector routet Traffic zu passenden Pods. ports mappen den Service-Port auf den container-targetPort (Zahl oder benannt).

yaml
apiVersion: v1
kind: Service
metadata:
  name: my-app
spec:
  type: ClusterIP      # ClusterIP (default), NodePort, LoadBalancer, ExternalName
  selector:
    app: my-app        # routes to pods with these labels
  ports:
    - name: http
      port: 80         # service port
      targetPort: 8080 # container port (or named port)
      protocol: TCP
    - name: https
      port: 443
      targetPort: 8443

# NodePort: exposes on each node's IP at a static port (30000-32767)
# LoadBalancer: provisions a cloud LB
# ExternalName: CNAME to an external service

# Service types:
# ClusterIP    - internal cluster IP (default)
# NodePort     - exposes on node port + ClusterIP
# LoadBalancer - cloud LB + NodePort + ClusterIP
# ExternalName - DNS CNAME (no proxying)

ConfigMap & Secret

ConfigMaps halten nicht-sensible Konfiguration (Strings oder Dateien); Secrets halten sensible Daten (base64-kodiert in data, oder plain in stringData). Beide werden via Env-Variablen (valueFrom) konsumiert oder als Volumes gemountet. Secrets sind standardmäßig NICHT verschlüsselt — Verschlüsselung im Ruhezustand aktivieren und RBAC-Zugang beschränken.

yaml
# ConfigMap — non-sensitive configuration
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  log_level: info
  max_connections: "100"
  config.yaml: |
    server:
      host: 0.0.0.0
      port: 8080
---
# Secret — sensitive data (base64-encoded)
apiVersion: v1
kind: Secret
metadata:
  name: app-secrets
type: Opaque
data:
  # base64-encoded values
  api_key: c2VjcmV0LWtleS0xMjM=   # echo -n 'secret-key-123' | base64
  db_password: cGFzc3dvcmQ=
# Or use stringData for plain text (auto-encoded):
# stringData:
#   api_key: secret-key-123

# Consumed by pods:
# env:
#   - name: API_KEY
#     valueFrom:
#       secretKeyRef:
#         name: app-secrets
#         key: api_key
# volumes:
#   - name: config
#     configMap:
#       name: app-config
16

CI/CD-Konfiguration (GitHub Actions & GitLab CI)

GitHub-Actions-Workflow

GitHub-Actions-Workflows liegen in .github/workflows/. on: Trigger (push, PR, schedule, workflow_dispatch). jobs enthalten runs-on + steps. uses: referenziert Actions, run: führt Shell aus. Ausdrücke nutzen die ${{ }}-Syntax — innerhalb YAML-Template-Literalen als \${{ }} zu escapen.

yaml
# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm test
      - run: npm run build
        env:
          NODE_ENV: production

  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run lint

# ${{ }} is GitHub Actions expression syntax
# MUST be escaped as ${{ }} in YAML template literals
# (here we use literal text, no escaping needed)

GitLab-CI-Pipeline

GitLab CI liegt in .gitlab-ci.yml. stages definieren die Pipeline-Reihenfolge. Jobs haben stage, image, script und viele Optionen (only/except, rules, when, artifacts, environment). Variablen nutzen die $VAR-Syntax (in YAML-Blockskalaren kein Escaping nötig). when: manual verlangt einen Klick zum Deployen.

yaml
# .gitlab-ci.yml
stages:
  - test
  - build
  - deploy

variables:
  NODE_ENV: production
  IMAGE_TAG: $CI_COMMIT_SHORT_SHA

test:
  stage: test
  image: node:20
  script:
    - npm ci
    - npm test
  artifacts:
    reports:
      junit: test-results.xml
  coverage: '/Lines.*:\s(\d+\.\d+)\%/'

build:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  script:
    - docker build -t myapp:$IMAGE_TAG .
    - docker push myapp:$IMAGE_TAG
  only:
    - main

deploy:production:
  stage: deploy
  script:
    - ./deploy.sh
  environment:
    name: production
  only:
    - main
  when: manual   # require manual trigger

Matrix-Builds

Matrix-Builds führen einen Job mehrfach mit verschiedenen Variablen aus. GitHub Actions nutzt strategy.matrix mit include/exclude. GitLab nutzt parallel.matrix. fail-fast: false verhindert, dass ein Fehlschlag Geschwister abbricht. Nützlich für plattformübergreifende, mehrversions-Tests. Die ${{ }}-Syntax muss in YAML-Literalen escapet werden.

yaml
# GitHub Actions matrix
jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node: [18, 20, 22]
        exclude:
          - os: windows-latest
            node: 18
        include:
          - os: ubuntu-latest
            node: 20
            experimental: true
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm ci
      - run: npm test

# GitLab CI matrix (parallel matrix):
# test:
#   image: node:${NODE_VERSION}
#   parallel:
#     matrix:
#       - NODE_VERSION: [18, 20, 22]
#         OS: [linux, macos]

Wiederverwendbare Workflows & Includes

Beide Systeme unterstützen Wiederverwendung. GitHub Actions nutzt wiederverwendbare Workflows (workflow_call-Trigger), aufgerufen mit uses:. GitLab nutzt include (project, local, template, remote). Wiederverwendung reduziert Duplizierung geteilter CI-Logik. Eingaben/Geheimnisse explizit übergeben, um Workflows komponierbar und prüfbar zu halten.

yaml
# GitHub Actions: reusable workflow
# .github/workflows/reusable.yml
on:
  workflow_call:
    inputs:
      node-version:
        required: true
        type: string
    secrets:
      token:
        required: true
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - run: npm ci
        env:
          TOKEN: ${{ secrets.token }}

# Caller:
# jobs:
#   build:
#     uses: ./.github/workflows/reusable.yml
#     with:
#       node-version: '20'
#     secrets:
#       token: ${{ secrets.MY_TOKEN }}

# GitLab CI: include
# include:
#   - project: 'ci/templates'
#     file: '/node.yml'
#   - local: '/.gitlab/extra.yml'
#   - template: Jobs/SAST.gitlab-ci.yml

Anker in CI-Konfigs

YAML-Anker reduzieren Duplizierung in CI-Konfigs. GitLab CI nutzt sie stark: einen versteckten Job (.template) mit &anchor definieren, dann <<: *anchor zum Mergen. GitHub Actions unterstützt Anker, rät aber über Jobs hinweg davon ab (wiederverwendbare Workflows bevorzugen). Anker machen Configs DRY, aber schwerer nachzuverfolgen — überlegt einsetzen.

yaml
# YAML anchors reduce duplication in CI configs
# GitLab CI commonly uses anchors

.default_template: &default_template
  image: node:20
  before_script:
    - npm ci
  cache:
    paths:
      - node_modules/

test:
  <<: *default_template
  script:
    - npm test

lint:
  <<: *default_template
  script:
    - npm run lint

build:
  <<: *default_template
  script:
    - npm run build
  artifacts:
    paths:
      - dist/

# GitHub Actions supports anchors too (since 2022):
# jobs:
#   base: &base
#     runs-on: ubuntu-latest
#     steps:
#       - uses: actions/checkout@v4
#   test:
#     uses: ./.github/workflows/reusable.yml
#   # Anchors across jobs are limited — prefer reusable workflows

Umgebungen & Geheimnisse

GitHub-Actions-Umgebungen schalten Deployments (Bestätigung verlangen, auf Branches beschränken) und halten umgebungsspezifische Geheimnisse. Geheimnisse werden via ${{ secrets.NAME }} referenziert. GitLab nutzt protected (branch-beschränkte) und masked (im Log verborgene) Variablen, definiert in der UI. Geheimnisse nie loggen — sie können in Fehlerausgaben entweichen.

yaml
# GitHub Actions: environments & secrets
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production        # requires approval if configured
      url: https://app.example.com
    steps:
      - uses: actions/checkout@v4
      - name: Deploy
        run: ./deploy.sh
        env:
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
          API_TOKEN: ${{ secrets.API_TOKEN }}
          ENV: production

# Secret scopes:
# - Repository secrets: available to all workflows
# - Environment secrets: only when job uses that environment
# - Organization secrets: shared across repos

# GitLab CI: protected/masked variables
# variables:
#   # defined in UI: Settings > CI/CD > Variables
#   # - Protected: only on protected branches/tags
#   # - Masked: hidden in job logs
# deploy:
#   script:
#     - ./deploy.sh
#   environment:
#     name: production
#   only:
#     - main
17

Sicherheitsaspekte

Deserialisierungsrisiken

YAML-Deserialisierung ist gefährlich, weil Tags wie !!python/object/apply beliebige Funktionen aufrufen können. PyYAMLs yaml.load() war vor 5.1 standardmäßig unsicher (Codeausführung aus unvertrauter Eingabe). Für unvertraute Eingaben immer yaml.safe_load() nutzen — er weist Objekt-Instanziierungs-Tags zurück. Andere Sprachen haben ähnliche Gefahren (SnakeYAML, Psych).

yaml
# YAML deserialization can be DANGEROUS.
# Some loaders let YAML instantiate arbitrary objects.

# DANGEROUS (PyYAML < 5.1, default was unsafe):
# data = yaml.load(untrusted_input)
# An attacker can craft YAML that runs arbitrary code:
# !!python/object/apply:os.system ["rm -rf /"]

# Other dangerous tags:
# !!python/object/apply:...     # call any Python function
# !!python/object/new:...       # instantiate any class
# !ruby/object:...               # Ruby object instantiation
# !java/object:...               # Java (SnakeYAML)

# Safe loaders reject these tags by default.
# Modern PyYAML (>= 5.1): yaml.load() requires a SafeLoader
# yaml.safe_load() is ALWAYS safe.

# Rule of thumb:
# - NEVER use yaml.load() on untrusted input
# - ALWAYS use yaml.safe_load() (or full_load on trusted files)
# - Or use a schema-validated loader

safe_load vs. load

Immer safe_load (Python), safe_load (Ruby Psych) oder Default-sichere Schemata nutzen (js-yaml, Go yaml.v3). PyYAML 5.1+ verlangt einen expliziten Loader für yaml.load(). full_load erlaubt Standardtags, aber keine beliebigen Objekte — nur für vertraute Dateien. Sichere Loader weisen alle Objekt-Instanziierungs-Tags zurück.

yaml
# Python (PyYAML) — the classic safe/unsafe distinction

# SAFE: safe_load rejects all custom tags
import yaml
data = yaml.safe_load(untrusted_yaml)   # ALWAYS use this

# SAFE: load with SafeLoader (explicit)
data = yaml.load(untrusted_yaml, Loader=yaml.SafeLoader)

# FULL (trusted files only): full_load allows standard tags
# but not arbitrary python objects
data = yaml.full_load(trusted_yaml)

# UNSAFE: UnsafeLoader allows !!python/object — DANGEROUS
data = yaml.load(untrusted_yaml, Loader=yaml.UnsafeLoader)  # NEVER on untrusted

# PyYAML 5.1+ requires Loader argument for yaml.load()
# (raises error without it) — safety improvement.

# Other languages:
# JS (js-yaml): yaml.load(str) uses DEFAULT_SAFE_SCHEMA
# Go (yaml.v3): no object instantiation (safe by design)
# Ruby (Psych): Psych.safe_load is the safe variant
# Java (SnakeYAML): SafeConstructor for safe loading

Lokale Tag-Exploits

Eigene Tags (!include, !env, !file, !exec, !template) lassen sich auch ohne !!python/object ausnutzen. Ein !include, der Dateien liest, kann per Pfad-Durchquerung dazu gebracht werden, /etc/passwd oder .ssh/id_rsa zu lesen. Jeden eigenen Konstruktor auditieren: Pfade gegen Allow-Listen validieren, absolute Pfade und ../ ablehnen, den Loader sandbox-en.

yaml
# Even non-builtin tags can be exploited if your loader
# registers constructors that have side effects.

# Example: a "harmless" custom tag
# yaml.add_constructor('!include', include_file)
#
# If !include reads files from disk, an attacker can
# craft YAML to read sensitive files:
# config: !include /etc/passwd
# or:
# config: !include /etc/shadow
# or:
# config: !include ../../../.ssh/id_rsa

# Mitigation:
# 1. Validate the included path against an allowlist
# 2. Restrict !include to a specific directory
# 3. Refuse absolute paths and ../ traversal
# 4. Run the loader in a sandbox

# Other "innocent" tags that can be exploited:
# !env VAR_NAME        -> leaks env vars
# !exec "command"      -> arbitrary command execution
# !file /path          -> file disclosure
# !template <% ... %>  -> code injection

# Audit every custom constructor for side effects.

Billion Laughs & DoS

Der Billion-Laughs-Angriff nutzt verschachtelte Aliasse, um ein winziges Dokument in Gigabytes Speicher zu expandieren (10 Aliasse pro Ebene, 5 Ebenen = 10^9 Referenzen). Abmildern mit Alias-Tiefengrenzen, Gesamtgrößengrenzen, Streaming-Parsern und dem Zurückweisen übermäßiger Verschachtelung. Auch auf tiefe Verschachtelung (Stack-Overflow) und riesige flache Collections achten.

yaml
# "Billion Laughs" attack — exponential expansion via aliases
a: &a ["lol","lol","lol","lol","lol","lol","lol","lol","lol","lol"]
b: &b [*a,*a,*a,*a,*a,*a,*a,*a,*a,*a]
c: &c [*b,*b,*b,*b,*b,*b,*b,*b,*b,*b]
d: &d [*c,*c,*c,*c,*c,*c,*c,*c,*c,*c]
e: &e [*d,*d,*d,*d,*d,*d,*d,*d,*d,*d]

# This 5-line document expands to ~10^9 string references
# consuming gigabytes of memory on parse.

# Mitigations:
# 1. Limit alias depth (some parsers do this)
# 2. Limit total parsed size / memory
# 3. Use a streaming parser for untrusted input
# 4. PyYAML has a limit but not all parsers do
# 5. Reject documents with excessive alias nesting

# Other DoS vectors:
# - Very deep nesting (parser stack overflow)
# - Huge flat sequences/mappings (memory)
# - Pathological number formats (regex backtracking)
# - Quadratic blowup via duplicate keys

# For untrusted input: set hard size + depth limits.

Eingabevalidierung

Geschichtete Validierung: (1) Größengrenze, (2) safe_load, um gefährliche Tags zurückzuweisen, (3) Typcheck (ein dict erwarten, keine Liste), (4) Schema-Validierung (JSON Schema, Pydantic, Cue), (5) Domänenvalidierung (Geschäftsregeln wie Portbereich). Jede Schicht fängt andere Angriffe. Struktur nie vertrauen — vor der Nutzung immer validieren.

yaml
# Layered defense for untrusted YAML input:

# 1. Size limit (reject oversized input)
MAX_SIZE = 1024 * 1024  # 1 MB
if len(input_text) > MAX_SIZE:
    raise ValueError("input too large")

# 2. Safe parser (rejects dangerous tags)
import yaml
try:
    data = yaml.safe_load(input_text)
except yaml.YAMLError as e:
    raise ValueError(f"invalid YAML: {e}")

# 3. Type check (expect a mapping, not a list)
if not isinstance(data, dict):
    raise ValueError("expected a mapping at top level")

# 4. Schema validation (JSON Schema, Pydantic, etc.)
from pydantic import BaseModel, ValidationError
class Config(BaseModel):
    host: str
    port: int = 8080
try:
    config = Config(**data)
except ValidationError as e:
    raise ValueError(f"schema validation failed: {e}")

# 5. Domain validation (business rules)
if config.port < 1 or config.port > 65535:
    raise ValueError("port out of range")

Bibliotheksempfehlungen

Standardmäßig sichere Bibliotheken wählen: PyYAML (safe_load), ruamel.yaml, js-yaml (Standard sicher), Go yaml.v3, Psych.safe_load, SnakeYAML mit SafeConstructor, serde_yaml. yaml.load ohne expliziten sicheren Loader vermeiden. Auf aktuelle Versionen pinnen für Sicherheitspatches. Eigene Konstruktoren auditieren. Die Sicherheitsdoku der Bibliothek lesen.

yaml
# Safe-by-default YAML libraries by language:

# Python:
#   - PyYAML >= 5.1 (yaml.safe_load)
#   - ruamel.yaml (safe by default, round-trip mode)
#   AVOID: yaml.load without explicit SafeLoader

# JavaScript/TypeScript:
#   - js-yaml (yaml.load uses DEFAULT_SAFE_SCHEMA)
#   AVOID: yaml.load with DEFAULT_FULL_SCHEMA on untrusted

# Go:
#   - gopkg.in/yaml.v3 (no object instantiation, safe)
#   AVOID: yaml.v2 has subtle differences, prefer v3

# Ruby:
#   - Psych (Psych.safe_load)
#   AVOID: YAML.load (uses unsafe loader in old Ruby)

# Java:
#   - SnakeYAML with SafeConstructor
#   AVOID: new Yaml() without SafeConstructor on untrusted
#   (SnakeYAML had CVEs from unsafe loading)

# Rust:
#   - serde_yaml (safe by design, no arbitrary types)

# General rule:
# - Read the library's security docs
# - Pin to a recent version (security patches)
# - Use safe_load / SafeConstructor / safe schema
# - Audit custom constructors for side effects
18

Best Practices

Konsistente Einrückung

Durchgängig 2 Leerzeichen nutzen (der De-facto-Standard), nie Tabs. Den Editor konfigurieren, für YAML Leerzeichen einzufügen. Formatierer (prettier, yamlfixer) und Linter (yamllint) nutzen, um Konsistenz zu erzwingen. Inkonsistente Einrückung ist der häufigste YAML-Fehler und bricht das Parsen.

yaml
# Use 2 spaces for indentation (most common)
# NEVER use tabs (YAML forbids them)

# GOOD
server:
  host: localhost
  port: 8080
  routes:
    - path: /api
      handler: apiHandler
    - path: /web
      handler: webHandler

# BAD (inconsistent)
# server:
#    host: localhost
#   port: 8080      # wrong indent

# Configure your editor:
# VS Code: "[yaml]": {"editor.insertSpaces": true, "editor.tabSize": 2}
# Vim:     autocmd FileType yaml setlocal ts=2 sts=2 sw=2 expandtab
# Emacs:   (add-hook 'yaml-mode-hook
#           (lambda () (setq yaml-indent-offset 2)))

# Use a formatter:
# prettier (with yaml plugin) normalizes indentation
# yamllint checks it
# yamlfixer auto-fixes issues

Quotierungsstrategie

Strings quoten, die wie Zahlen, Booleans, null oder Daten aussehen; die Doppelpunkte/Kommas/Sonderzeichen enthalten; oder die mit Indikatoren beginnen (- ? : * & ! | > ' " % @). Sonst plain (unquotiert) für Lesbarkeit bevorzugen. Doppelte Anführungszeichen für Escape-Sequenzen (\n, \t), einfache für literale Strings mit Apostrophen.

yaml
# Quote strings when:
# 1. They look like another type (number, bool, null, date)
version: "1.0"        # string, not float
answer: "yes"         # string, not bool (1.1)
region: "no"          # string "no", not False (1.1)
date: "2024-01-01"    # string, not date
phone: "555-1234"     # string, not number

# 2. They contain special characters
url: "https://example.com:8080"   # colon
list: "a, b, c"                    # comma
expr: "value:with:colons"          # colons

# 3. They start with special indicators (-, ?, :, *, &, !, |, >, ', ", %, @, `)
flag: "-not-a-list"
key: "?not-a-complex-key"

# Don't quote otherwise — plain is more readable
name: Alice            # no quotes needed
path: /usr/local/bin   # no quotes needed

# Prefer double quotes for escapes (\n, \t)
# Prefer single quotes for literal strings with apostrophes
greeting: "Hello\nWorld"
possessive: 'Alice''s car'

Tabs & weitere Fallstricke vermeiden

Häufige Fallstricke vermeiden: Tabs (verboten — Leerzeichen nutzen), unquotierte yes/no/on/off (1.1-vs-1.2-Mehrdeutigkeit), unquotierte Strings mit Doppelpunkten, nachgestellter Whitespace, CRLF-Zeilenenden (LF nutzen), BOM (als UTF-8 ohne BOM speichern) und sehr lange Zeilen (mit Blockskalaren umbrechen). Ein Linter findet das meiste.

yaml
# Pitfall 1: tabs for indentation (FORBIDDEN)
# Configure editor to use spaces

# Pitfall 2: yes/no/on/off as strings (1.1 vs 1.2)
# Always quote: "yes", "no", "on", "off"

# Pitfall 3: unquoted strings with colons
# bad:  url: http://x:8080
# good: url: "http://x:8080"

# Pitfall 4: trailing whitespace
# Some parsers are strict; linters always flag it
key: value   # <- no trailing spaces

# Pitfall 5: Windows line endings (CRLF)
# Use LF (\n) only — CRLF can cause subtle issues
# .gitattributes: *.yaml text eol=lf

# Pitfall 6: BOM at start of file
# Save as UTF-8 without BOM

# Pitfall 7: very long lines
# Wrap with block scalars or flow style
description: >
  This is a long description that wraps
  across multiple lines for readability.

# Pitfall 8: inconsistent key ordering
# Group related keys, be consistent

Versionspin & Schema-Doku

Die YAML-Version mit %YAML 1.2 pinnen, wenn 1.1-vs-1.2-Unterschiede zählen. Dein Schema dokumentieren: Pflicht-/Optionalfelder, Typen, Defaults, Bereiche — in Kommentaren, einer JSON-Schema-Datei oder README. Schemaversionen im Code pinnen, damit Config-Validierung reproduzierbar ist. Das senkt Einarbeitungsreibung und Config-Fehler.

yaml
# Pin the YAML version if it matters
%YAML 1.2
---
key: value

# Document your schema expectations in comments:
# Required fields:
#   - host: string (hostname or IP)
#   - port: integer (1-65535)
# Optional fields:
#   - tls: boolean (default: false)
#   - cert: string (path, required if tls: true)

config:
  host: example.com
  port: 443
  tls: true
  cert: /etc/ssl/cert.pem

# Or use a JSON Schema file (config.schema.json)
# and reference it from your docs / CI:
# "Validated against schema v1.2; see config.schema.json"

# For libraries, document the schema in the README:
# ## Configuration
# The config.yaml file must contain:
# - host (str, required)
# - port (int, required, 1-65535)
# - tls (bool, optional, default: false)

# Pin schema versions in code:
# CONFIG_SCHEMA_VERSION = "1.2"
# validate(data, schema_v1_2)

Linten in CI

YAML-Linting in CI (GitHub Actions, GitLab CI) und Pre-Commit-Hooks verdrahten. yamllint für Syntax/Stil und prettier für Formatierung nutzen. Editor-Integration (VS-Code-YAML-Erweiterung, yaml-language-server) liefert Inline-Linting und Schema-Validierung. YAML-Fehler in CI zu erwischen ist weit billiger als in Produktion.

yaml
# .github/workflows/lint.yml
name: Lint YAML
on: [push, pull_request]
jobs:
  yamllint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install yamllint
        run: pip install yamllint
      - name: Lint
        run: yamllint -s .

# GitLab CI:
# yamllint:
#   image: python:3.12
#   script:
#     - pip install yamllint
#     - yamllint -s .

# Pre-commit hook (.pre-commit-config.yaml):
# repos:
#   - repo: https://github.com/adrienverge/yamllint
#     rev: v1.35.1
#     hooks:
#       - id: yamllint
#         args: [-s, --config-file, .yamllint.yml]
#   - repo: https://github.com/pre-commit/mirrors-prettier
#     rev: v3.1.0
#     hooks:
#       - id: prettier
#         types: [yaml]

# Editor integration:
# VS Code: install "YAML" extension (redhat)
#   + "yamllint" for inline linting
#   + schema validation via yaml-language-server

Struktur & Lesbarkeit

Verwandte Schlüssel mit Kommentar-Headern gruppieren. Verschachtelung flach halten (max. 3-4 Ebenen) — tief verschachteltes YAML ist schwer zu lesen. Anker für wirklich wiederverwendete Werte nutzen. Blockskalare für mehrzeilige Strings nutzen. Zeilen unter 120 Zeichen halten. Lesbarkeit zählt, weil Menschen YAML editieren.

yaml
# Group related keys; use comments to delineate sections
server:
  # Networking
  host: 0.0.0.0
  port: 8080
  tls:
    enabled: true
    cert: /etc/ssl/cert.pem

  # Limits
  timeout: 30
  max_connections: 100
  retries: 3

# Keep nesting shallow (3-4 levels max)
# Deeply nested YAML is hard to read and edit.

# If a value is reused, use an anchor:
defaults: &defaults
  timeout: 30
  retries: 3

prod:
  <<: *defaults
  env: production

staging:
  <<: *defaults
  env: staging

# Use block scalars for multi-line values
script: |
  #!/bin/bash
  set -e
  echo "deploying"

# Keep lines under 120 chars; wrap with block scalars or
# multi-line flow style.
19

Fortgeschrittene Features

Komplexe Mapping-Schlüssel

Der ?-Indikator markiert einen komplexen Schlüssel (ein als Schlüssel genutztes Mapping oder eine Sequenz). Nützlich für Lookup-Tabellen (z. B. Preise nach Region+Instanz). Vorbehalt: Viele Serialisierer erhalten komplexe Schlüssel nicht und stringifizieren sie bei der Ausgabe. Die meisten Config-Dateien bleiben aus Einfachheit und Tool-Kompatibilität bei plain String-Schlüsseln.

yaml
# Use ? to mark a complex (non-scalar) key
? apple
: red fruit

? orange
: orange fruit

# A mapping as a key
? host: localhost
  port: 8080
: connection_string

# A sequence as a key
? [us-east-1, t2.micro]
: 0.0116
? [us-east-1, t2.small]
: 0.023
? [us-west-2, t2.micro]
: 0.0125

# Useful for lookup tables
pricing:
  ? [production, large]
  : 100
  ? [production, small]
  : 50
  ? [development, large]
  : 20

# In flow style:
{[a, b]: value, {x: 1}: other}

# Caveat: many serializers don't preserve complex keys
# and may convert them to strings on output.

Sets (!!set)

Ein YAML-Set (!!set) ist ein Mapping, dessen Schlüssel die Elemente und dessen Werte null sind. Manche Parser mappen es auf einen nativen Set-Typ. Nutzen, um eindeutige Collections zu deklarieren (Rollen, Berechtigungen). Vorbehalt: JSON hat keinen Set-Typ, die JSON-Konvertierung ergibt also ein Objekt mit null-Werten. Nicht alle Serialisierer erhalten das !!set-Tag.

yaml
# A set is a mapping with null values
# Use the !!set tag for clarity
permissions: !!set
  ? read
  ? write
  ? execute

# Equivalent to:
permissions:
  read: null
  write: null
  execute: null

# Or in flow style:
flags: !!set { red, green, blue }

# Parsers may map this to a native Set type:
# Python: set() (PyYAML with !!set constructor)
# Ruby: Set (Psych)
# JavaScript: depends on library

# Use case: declare a unique collection
roles: !!set
  ? admin
  ? editor
  ? viewer

# Caveat: JSON has no Set type, so JSON conversion
# usually produces an object with null values.

Geordnete Mappings (!!omap)

!!omap (ordered mapping) ist eine Sequenz Ein-Schlüssel-Mappings, die die Einfügereihenfolge erhält. Nützlich für Zeitachsen, geordnete Präferenzen oder Stellen, wo Reihenfolge semantisch zählt. Moderne Parser erhalten die reguläre Mapping-Reihenfolge ohnehin (Python dict 3.7+, Ruby Hash), aber Go-Maps sind zufällig — !!omap macht die Reihenfolge dort explizit.

yaml
# An ordered mapping preserves key order
# Use !!omap tag
timeline: !!omap
  - 2024-01-01: event A
  - 2024-02-01: event B
  - 2024-03-01: event C

# Equivalent representation as a list of single-key mappings:
# timeline:
#   - 2024-01-01: event A
#   - 2024-02-01: event B
#   - 2024-03-01: event C

# Parsers may map this to:
# Python: list of tuples, or OrderedDict
# Ruby: Array of one-key hashes (or OrderedDict)
# Go: ordered map (with custom type)

# Use case: ordered key-value pairs where order matters
# - event timelines
# - ordered preferences
# - step-by-step configurations

# Caveat: regular YAML mappings DO preserve order in
# most modern parsers (Python dict 3.7+, Ruby Hash,
# Go map iteration is random though). !!omap makes the
# intent explicit and works even where maps are unordered.

Binärdaten (!!binary)

!!binary kodiert Binärdaten als base64 in YAML. Parser dekodieren sie zu nativen Bytes (Python bytes, Ruby ASCII-8BIT-String). Nützlich, um kleine Bilder oder Icons direkt einzubetten. Bei großen Binärdaten lieber per Pfad oder URL referenzieren. Mehrzeiliges base64 funktioniert mit gefalteten (>) oder literalen (|) Blockskalaren.

yaml
# Encode binary data as base64 with !!binary tag
image: !!binary "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9
  awAAAABJRU5ErkJggg=="

# Multi-line base64 (folded or literal works)
data: !!binary |
  iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42m
  k+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==

# Parsers decode to bytes:
# Python: bytes object
# Ruby: ASCII-8BIT string
# JavaScript: depends on library (often base64 string)

# Use case: embed small images, icons, or other binary
# directly in YAML config

# For larger binary data, prefer:
# - Reference by path:  image: /path/to/image.png
# - Reference by URL:   image: https://example.com/img.png
# - Store separately and link

# Verify with:
# python -c 'import yaml; d=yaml.safe_load(open("f.yaml")); print(len(d["image"]))'

Eigene Konstruktoren

Eigene Konstruktoren registrieren, um Tags (!money) auf native Objekte zu mappen. add_constructor mit einem SafeLoader-begrenzten Loader nutzen. Konstruktoren erhalten den Loader und den Knoten; construct_scalar/mapping/sequence nutzen, um den Knotenwert zu lesen. Konstruktoren immer auf Nebenwirkungen auditieren (Dateilesevorgänge, Subprocess-Aufrufe) — sie lassen sich via unvertrauter Eingabe ausnutzen.

yaml
# PyYAML: register a constructor for a custom tag
import yaml

class Money:
    def __init__(self, currency, amount):
        self.currency = currency
        self.amount = amount
    def __repr__(self):
        return f"Money({self.currency} {self.amount})"

def money_constructor(loader, node):
    value = loader.construct_scalar(node)  # "USD 19.99"
    currency, amount = value.split()
    return Money(currency, float(amount))

# Register the constructor (use SafeLoader scope)
yaml.add_constructor('!money', money_constructor, Loader=yaml.SafeLoader)

# Now this YAML parses to a Money object:
# price: !money "USD 19.99"
config = yaml.safe_load("price: !money \"USD 19.99\"")
print(config['price'])  # Money(USD 19.99)

# Multi-argument constructors use construct_mapping or
# construct_sequence depending on the node kind.

# SECURITY: audit every constructor for side effects.
# A constructor that calls open(), os.system(), or
# subprocess can be exploited via untrusted input.

YAML-1.2-Features & Zukunft

YAML 1.2 machte JSON zu einer strengen Teilmenge, beschränkte Booleans auf true/false und führte 0o für Oktal ein. Der merge key << wurde aus der Kernspezifikation entfernt, ist aber weiterhin weit unterstützt. YAML 1.2.2 (2021) klärte die Spezifikation; 1.3 ist in Entwicklung. Zukunftssicher durch Version pinnen, mehrdeutige Strings quoten und Cue/Dhall/Jsonnet für komplexe Config erwägen.

yaml
# YAML 1.2 (2009, current spec) key changes from 1.1:
# - JSON is a strict subset
# - Booleans: only true/false (not yes/no/on/off)
# - Octal: 0o prefix (not leading 0)
# - Removed sexagesimal numbers
# - Removed merge key << from core spec (still widely supported)

# YAML 1.3 (in development) aims to:
# - Clarify ambiguous parts of 1.2
# - Standardize error reporting
# - Improve interoperability between parsers
# - Possibly restore some 1.1 features as optional

# YAML 1.2.2 (2021 update, spec revision):
# - Clarified type resolution
# - Better-defined core schema
# - Improved examples
# - No breaking changes

# Recommended practices for future-proofing:
# 1. Pin %YAML 1.2 in critical files
# 2. Quote ambiguous strings (yes/no, leading-zero numbers)
# 3. Avoid relying on << merge key for new formats
#    (or document that you depend on it)
# 4. Use JSON-compatible subset when interop matters
# 5. Watch for YAML 1.3 adoption in your parser

# Some tools (Cue, Dhall, Jsonnet) extend/replace YAML
# for complex configuration — consider them for new
# projects with advanced needs.

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.