YAML (YAML Ain't Markup Language) has become the default choice for configuration files in modern software development. From Docker Compose and Kubernetes manifests to GitHub Actions workflows and Ansible playbooks, YAML is everywhere. Its human-readable syntax is both its greatest strength and the source of some of the most frustrating bugs developers encounter.
This guide covers YAML syntax from basics to advanced features, the critical gotchas that trip up even experienced developers, comparison with JSON and TOML, and best practices for writing maintainable YAML in production environments.
What is YAML and Why Was It Created?
YAML was created in 2001 as an alternative to XML for configuration files and data serialization. The name originally stood for "Yet Another Markup Language" but was later retroactively changed to "YAML Ain't Markup Language" to emphasize that it's a data serialization language, not a document markup language.
The design goals were:
- Human readability: Use indentation and natural syntax instead of XML's verbose tags
- Language-native data structures: Map directly to lists, dictionaries, and scalars in every programming language
- Superset of JSON: Any valid JSON document is also valid YAML (YAML 1.2+)
YAML is used in:
- Container orchestration: Kubernetes manifests, Docker Compose
- CI/CD: GitHub Actions, GitLab CI, CircleCI, Drone
- Configuration management: Ansible, Puppet, SaltStack
- Application config: Spring Boot, Ruby on Rails, Symfony
- Static site generators: Jekyll, Hugo, Gatsby frontmatter
YAML Syntax Fundamentals
YAML documents use indentation for structure (spaces only — no tabs). Here are the key building blocks:
Scalars (strings, numbers, booleans, null):
name: Alice # string (no quotes needed)
age: 30 # integer
price: 9.99 # float
active: true # boolean
nothing: null # null (also: ~)
multiline: | # literal block (preserves newlines)
Line 1
Line 2
folded: > # folded block (newlines become spaces)
This is a long
sentence that wrapsMappings (key-value pairs, like JSON objects):
person:
name: Alice
age: 30
address:
city: Shanghai
zip: "200000" # quotes force string typeSequences (lists, like JSON arrays):
fruits:
- apple
- banana
- cherry
# Inline (flow) style:
fruits: [apple, banana, cherry]Comments: Use # for single-line comments (JSON doesn't support comments):
# This is a configuration for the web server
server:
port: 8080 # default HTTP portYAML Data Types and the Norway Problem
YAML's automatic type inference is convenient but can cause surprising bugs. The most infamous is the "Norway Problem":
countries:
- GB # → string "GB"
- US # → string "US"
- NO # → boolean false!!! (YAML 1.1 parsed "NO" as false)YAML 1.1 (used by many older parsers) treated NO, no, Yes, YES, on, Off etc. as booleans. YAML 1.2 fixed this — only true and false (case-insensitive) are booleans.
Common type gotchas:
version: 1.0 # float → 1.0 (not string "1.0"!)
port: 8080 # integer
zip_code: 01234 # integer 1234 (leading zero stripped!)
hex: 0x1A # integer 26
octal: 0o17 # integer 15 (YAML 1.2), or 017 in YAML 1.1
# Always quote values that look like numbers but should be strings:
zip_code: "01234" # string "01234" ✓
version: "1.0" # string "1.0" ✓
api_key: "0123456" # string ✓The "boolean strings" issue in Docker/Kubernetes:
env:
DEBUG: true # parsed as boolean true, but env vars are strings!
DEBUG: "true" # correct — string "true"Advanced YAML: Anchors, Aliases, and Merges
YAML provides powerful features for eliminating repetition in large configuration files.
**Anchors (&) and aliases (*)** allow you to define a value once and reference it multiple times:
defaults: &defaults
timeout: 30
retries: 3
log_level: info
production:
<<: *defaults # merge all keys from defaults
log_level: warning # override specific keys
host: prod.example.com
staging:
<<: *defaults
host: staging.example.comMultiple documents in a single file (separated by ---):
--- # Document 1
name: Alice
--- # Document 2
name: BobExplicit typing with YAML tags:
integer: !!int "42"
float: !!float "3.14"
string: !!str 42 # force integer to string
binary: !!binary |
R0lGODlh... # base64 encoded binary dataYAML vs JSON vs TOML: When to Use Each
YAML:
✓ Best readability for complex nested structures
✓ Supports comments
✓ Multi-line strings
✓ Anchors and aliases for DRY configuration
✗ Whitespace-sensitive (tabs cause errors)
✗ Implicit type coercion causes bugs
✗ Parsing is complex (many edge cases)
→ Best for: Kubernetes, CI/CD, Ansible, application config
JSON:
✓ Universal — every language can parse it
✓ No ambiguity — explicit types via delimiters
✓ Superset of YAML 1.2
✗ No comments
✗ Verbose for deeply nested data
✗ No multi-line strings
→ Best for: API responses, package.json, data interchange
TOML:
✓ Very readable for flat or two-level configuration
✓ Explicit types — no ambiguity
✓ Supports comments
✗ Poor support for deeply nested structures (gets verbose)
✗ Smaller ecosystem than YAML/JSON
→ Best for: Rust (Cargo.toml), Python (pyproject.toml), simple app config
# Cargo.toml example
[package]
name = "my-app"
version = "1.0.0"
[dependencies]
serde = { version = "1.0", features = ["derive"] }YAML in Kubernetes and Docker Compose
Kubernetes and Docker Compose are the most common places developers encounter YAML professionally.
Kubernetes Deployment example:
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
labels:
app: my-app
spec:
replicas: 3
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: my-app
image: my-app:1.2.3
ports:
- containerPort: 8080
env:
- name: DATABASE_URL
valueFrom:
secretKeyRef:
name: db-secret
key: url
resources:
requests:
memory: "64Mi"
cpu: "250m"
limits:
memory: "128Mi"
cpu: "500m"Docker Compose example:
version: "3.9"
services:
web:
image: nginx:alpine
ports:
- "80:80"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
depends_on:
- api
api:
build: .
environment:
- NODE_ENV=production
- DB_HOST=postgres
depends_on:
postgres:
condition: service_healthy
postgres:
image: postgres:16
environment:
POSTGRES_DB: myapp
POSTGRES_USER: admin
POSTGRES_PASSWORD: ${DB_PASSWORD} # from .env file
healthcheck:
test: ["CMD-SHELL", "pg_isready -U admin"]
interval: 10s
timeout: 5s
retries: 5YAML Best Practices and Common Mistakes
Always use spaces, never tabs: YAML strictly forbids tabs for indentation. Configure your editor to display tabs and convert them to spaces automatically.
Quote strings that look like other types:
# Risky — type depends on parser version:
enabled: yes # boolean in YAML 1.1, string in 1.2
# Safe:
enabled: "yes" # always a string
enabled: true # always a booleanValidate YAML before deploying: Use yamllint for linting and kubeval (for Kubernetes) to catch structural errors:
yamllint config.yaml
kubeval deployment.yamlUse explicit document separators in multi-document files:
---
kind: Deployment
# ...
---
kind: Service
# ...Avoid deeply nested anchors: While anchors reduce repetition, overly complex anchor hierarchies make files hard to understand. Consider splitting into multiple files instead.
Use a YAML-aware editor: VS Code with the YAML extension (Red Hat) provides schema validation, autocomplete, and hover documentation for Kubernetes, Docker Compose, and GitHub Actions.