YAML Tutorial: Read and Write It Without Fear
YAML runs your deploys: Kubernetes, GitHub Actions, docker-compose, Ansible. It optimizes for human eyes — and punishes imprecision. This tutorial teaches the structure and the three pitfalls behind virtually every broken pipeline.
In short
YAML represents data with two structures — indentation-based mappings (key: value) and dash-prefixed lists — using spaces only, never tabs, for nesting. Most strings need no quotes, but three pitfalls break real pipelines: illegal tabs, silent indentation drift that reattaches a key to the wrong parent, and implicit typing (YAML 1.1's 'Norway problem', where NO becomes false). Anchors (&) and aliases (*) let you reuse blocks without repeating them.
Mappings, lists, and nesting
Two structures compose everything. Mappings: key: value, one per line (note the mandatory space after the colon). Lists: lines starting with a dash. Nesting is indentation — spaces only, tabs are illegal — and consistency matters more than the amount; two spaces is the universal convention.
service:
name: checkout
replicas: 3
ports:
- 8080
- 8443
env:
- name: LOG_LEVEL
value: infoStrings, quoting, and multi-line text
Most strings need no quotes — name: Ada Lovelace just works. Quote when the value could be misread: contains a colon-space, starts with a special character, or matches a keyword (more below). Multi-line text has two block styles: | preserves line breaks (literal), > folds them into spaces — invaluable for embedded scripts and certificates.
script: |
#!/bin/sh
echo "line breaks preserved"
exit 0
summary: >
These lines fold
into one paragraph.The three pitfalls that break pipelines
Tabs — invisible, illegal, and the first thing to suspect when a file 'looks right' but won't parse. Indentation drift — one extra space silently attaches a key to the wrong parent: the config loads fine and your option is just… ignored. Implicit typing — unquoted yes/no/on/off may become booleans (the infamous Norway problem: country: NO → false), version: 1.20 becomes the number 1.2, and 08:30 can surprise you. The cure for all typing surprises is one character: quotes.
Because two of the three failures are silent, validating before committing isn't paranoia — it's the workflow. Our YAML Validator reports the exact line and column, and the tree view shows which parent each key REALLY attached to.
| Pitfall | What happens | Fix |
|---|---|---|
| Tabs | The parser rejects the file — tabs are illegal for indentation | Use spaces only, two per level |
| Indentation drift | A key silently attaches to the wrong parent | Validate and check the tree view |
| Implicit typing | NO → false, 1.20 → 1.2, 08:30 → unexpected values | Quote ambiguous scalars |
Anchors: do-not-repeat-yourself YAML
An anchor (&name) labels a node; an alias (*name) reuses it; <<: merges it into a mapping. CI matrices and Kubernetes bases use this constantly. When converting YAML to JSON, anchors are resolved — every alias expands to a full copy, since JSON has no reference syntax.
defaults: &defaults
retries: 3
timeout: 30
production:
<<: *defaults
timeout: 60 # overrides the merged valueSources
Frequently asked questions
Why does YAML forbid tabs for indentation?
Because tab width is presentation, not data — your editor's 4-space tab is someone else's 8. Since indentation IS the structure in YAML, it must be unambiguous, so the spec allows only spaces. The error appears constantly because tabs are invisible.
What is the 'Norway problem'?
In YAML 1.1, unquoted no parses as boolean false — so country: NO (Norway's code) silently became country: false in countless configs. YAML 1.2 fixed it, but older parsers linger; quoting country codes, versions, and anything ambiguous remains the safe habit.
Do I need quotes around YAML strings?
Usually not — that's the point of YAML. Quote when the value could be misread as another type (yes, 1.20, null), contains a colon-space or starts with a special character. When in doubt, quotes never hurt; missing ones occasionally do.
Paste any YAML into the YAML Validator — full 1.2 parsing, exact error positions, and a tree view that exposes indentation mistakes instantly.
Validate your YAMLKeep working
Related tools
YAML Validator
Full YAML 1.2 validation with the exact line and column of every error — catch the indent bug before your pipeline does.
YAML Formatter
Normalize any YAML to clean, consistent style — uniform indentation, canonical quoting, validation built in.
YAML to JSON
Full YAML 1.2 parsing — anchors resolved, types preserved, errors pinpointed — straight into clean JSON.
JSON to YAML
Re-express JSON as clean, human-friendly YAML — smart quoting, two-space indentation, list dashes done right.
YAML Parser
See exactly what your tooling sees — full YAML 1.2 parsing with typed scalars, resolved anchors, and precise errors, shown as the JSON value it becomes.
YAML Viewer
Explore any YAML document as an interactive tree — mappings, lists, and counts at a glance, anchors resolved.
YAML Diff
Two YAML documents side by side with syntax highlighting, so an indentation change reads as a structural change rather than as moved whitespace.
YAML to XML
From indentation to angle brackets — YAML parsed with full 1.2 semantics and rendered as well-formed XML.
YAML to CSV
YAML record lists in, spreadsheet-ready CSV out — flattened columns, RFC 4180 quoting, no manual reshaping.
YAML URL Encode
YAML through URLs without corruption — validated, percent-encoded, and restored to clean formatting on decode.