YAML Reference

The literal block scalar (|) preserves all newlines exactly as written, making it ideal for shell scripts, code blocks, or preformatted text embedded in YAML. The folded block scalar (>) replaces single newlines with spaces, joining lines into paragraphs, while double newlines (blank lines) are preserved as actual line breaks. This makes folded blocks useful for long descriptions or documentation strings that should wrap naturally.

Anchors (&name) mark a value for reuse, and aliases (*name) reference that stored value elsewhere in the document. Combined with the merge key (<<: *name), you can define default settings once and inherit them in multiple places, overriding only the fields that differ. For example, you can anchor database defaults and merge them into development, staging, and production configs, changing just the host and credentials per environment.

YAML strictly requires spaces for indentation because tab width is not standardized across editors and terminals (it can be 2, 4, or 8 spaces). Mixing tabs and spaces would cause inconsistent parsing, where a file that looks correctly indented in one editor breaks in another. Using spaces only ensures that the visual structure always matches the logical structure, preventing subtle hierarchy errors in configuration files.

YAML supports three ways to express null: the explicit keyword null, the tilde shorthand ~, and an empty value (a key with no value after the colon). All three parse to the same null/nil/None value in the target programming language. The empty-value form is commonly used for optional configuration fields that should default to nothing, while explicit null is preferred for clarity in complex documents.

Block style uses indentation to denote structure, with items on separate lines (e.g., sequences use "- item" and mappings use "key: value" on individual lines). Flow style uses JSON-like inline notation with brackets for sequences ([a, b, c]) and braces for mappings ({x: 1, y: 2}). Block style is more readable for complex, nested structures, while flow style is concise for short, simple collections that fit on one line.

Plain (unquoted) strings work for most values but fail when the value contains special YAML characters like colons, brackets, or leading special characters. Single quotes preserve all characters literally except that single quotes are escaped by doubling them. Double quotes support escape sequences like \n for newlines, \t for tabs, and \x or \u for Unicode. Use !!str to force a numeric-looking value to be treated as a string.

The --- marker begins a new YAML document within a single file, allowing multiple independent documents to be concatenated. The ... marker optionally signals the end of a document. This is commonly used in Kubernetes, where a single file contains multiple resource definitions separated by ---. Parsers process each document independently, and a missing --- at the start of the first document is implicitly assumed.

YAML supports decimal integers (42), negative integers (-17), floating-point numbers (3.14), scientific notation (1.0e+5), hexadecimal with 0x prefix (0xFF = 255), and octal with 0o prefix (0o77 = 63). Underscores can be used as visual separators in large numbers (1_000_000). Special float values .inf, -.inf, and .nan are also supported for representing infinity and not-a-number.