Topolearn

Learn YAML

The indentation-based data format behind most configuration files

13 lessons · 2 hours · 4 levels · covers YAML YAML 1.2.2

YAML is a human-friendly data serialization format used for Kubernetes manifests, CI pipelines, Docker Compose, Ansible and countless app configs. Learn its few structures, its string and typing rules and its traps, and every YAML-configured tool becomes easier to read and debug.

Sign in free to track progressOfficial docs ↗

How deep do you want to go?

1. EssentialsRead and write simple code, do the everyday basics3 lessons · 26 min in total
2. PracticalUse it productively at work, with the usual idioms7 lessons · 1 hour in total
3. AdvancedThe less common features, performance and trade-offs10 lessons · 2 hours in total
4. ExpertInternals and the edge cases experts know13 lessons · 2 hours in total

The YAML tree

YAMLMappings, sequences and indentationMappings,sequences and ind…Scalars: strings, numbers, booleans, nullScalars: strings,numbers, booleans…Flow style and YAML as a superset of JSONFlow style and YAMLas a superset of JS…Multi-line strings: | and >Multi-line strings: |and >Quoting: plain, single and double quotesQuoting: plain, singleand double quotesAnchors, aliases and merge keysAnchors, aliases andmerge keysMultiple documents in one fileMultiple documentsin one file
Essentials and Practical shown (7 of 13 lessons); the full list is below. Click a lesson to read it.

All 13 lessons, in order

Structure

  1. Mappings, sequences and indentation · Essentials · 8 min

    YAML has two collections: mappings of key: value pairs and sequences of - items, nested by indentation with spaces.

  2. Scalars: strings, numbers, booleans, null · Essentials · 10 min

    Unquoted scalars are typed automatically: 42 is an int, 3.5 a float, true a boolean, null or ~ is null, and almost everything else is a string.

  3. Flow style and YAML as a superset of JSON · Essentials · 8 min

    Write compact inline collections with [a, b] and {k: v}, and know that (almost) any JSON document is already valid YAML.

Strings and scalars

  1. Multi-line strings: | and > · Practical · 12 min

    Write long text with literal | (keeps newlines) and folded > (joins lines), and control the final newline with chomping indicators - and +.

  2. Quoting: plain, single and double quotes · Practical · 10 min

    Know when a string must be quoted, and the difference between single quotes (no escapes, '' for a quote) and double quotes (backslash escapes).

Reuse and documents

  1. Anchors, aliases and merge keys · Practical · 10 min

    Define a node once with &name and reuse it with *name, and merge mappings with <<: to share default settings.

  2. Multiple documents in one file · Practical · 8 min

    Separate several YAML documents in one stream with ---, end one with ..., and load them all with a load_all style API.

YAML in practice

  1. Implicit typing traps: the Norway problem · Advanced · 12 min

    Why NO, on, 012, 1:30 and 1e3 may not be what you think, how YAML 1.1 and 1.2 parsers differ, and how to stay safe.

  2. Loading YAML safely in code · Advanced · 12 min

    Parse YAML with safe loaders (yaml.safe_load, not yaml.load with an unsafe Loader), limit alias expansion, and understand round-trip loaders.

  3. Linting and schema validation · Advanced · 10 min

    Catch YAML mistakes early with yamllint for syntax and style, and JSON Schema for structure and types, in the editor and in CI.

Spec corners

  1. Tags and explicit types · Expert · 12 min

    Use !!str, !!int and friends to force a type, understand local !tags used by tools like CloudFormation and Home Assistant, and how parsers map tags to types.

  2. Schemas: how plain scalars get their type · Expert · 12 min

    Understand YAML's representation model: nodes, tags, and the failsafe, JSON and core schemas that resolve untagged scalars, and why parsers disagree.

  3. Edge cases: complex keys, indentation, gotchas · Expert · 12 min

    The corners experts know: ? complex keys, non-string keys, indentation of block sequences, tabs, BOMs, long keys and string folding in plain scalars.