What is YAML?

YAML (YAML Ain't Markup Language — yes, a recursive acronym) is a human-friendly data serialization format. Where JSON uses braces and brackets, YAML uses indentation and minimal punctuation, making it easier to read and write by hand. It is the format of choice for configuration files: Docker Compose, Kubernetes manifests, GitHub Actions, and Ansible playbooks are all YAML.

YAML vs JSON at a glance

The same data in both formats:

name: Alice Martin
age: 28
active: true
roles:
  - admin
  - editor
address:
  city: Paris
  country: France

{
  "name": "Alice Martin",
  "age": 28,
  "active": true,
  "roles": ["admin", "editor"],
  "address": {
    "city": "Paris",
    "country": "France"
  }
}

YAML is a superset of JSON — every valid JSON document is also valid YAML. Conversely, YAML supports features JSON does not: comments, multi-line strings, anchors, and aliases.

YAML syntax essentials

Scalars

string_bare: hello world          # no quotes needed for simple strings
string_quoted: "must quote: this" # quotes needed when value contains : or #
number: 42
float: 3.14
boolean_true: true                # also: yes, on, True, TRUE (be careful!)
boolean_false: false              # also: no, off, False, FALSE
null_value: null                  # also: ~
date: 2026-01-15                  # bare dates are parsed as dates, not strings

Sequences (lists)

# Block style (most common in config files)
fruits:
  - apple
  - banana
  - cherry

# Flow style (looks like JSON)
fruits: [apple, banana, cherry]

Mappings (objects)

# Block style
server:
  host: localhost
  port: 8080

# Flow style
server: { host: localhost, port: 8080 }

Multi-line strings

# Literal block (|) — preserves newlines
message: |
  Line one.
  Line two.
  Line three.

# Folded block (>) — newlines become spaces, blank lines become newlines
description: >
  This long sentence is split across
  multiple lines for readability but
  will be joined into one line.

Comments

# This is a comment — JSON does not support comments, YAML does
port: 8080  # inline comment

Anchors and aliases

YAML lets you define a value once and reuse it, which is useful in large config files:

defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults   # merge anchor — inherits timeout and retries
  host: prod.example.com

staging:
  <<: *defaults
  host: staging.example.com

Common YAML gotchas

The Norway problem

In YAML 1.1 (used by many parsers), country codes like NO, yes, on, and off are parsed as booleans. Norway's ISO code NO silently becomes false, which breaks country lists. Always quote these values:

# Wrong — NO becomes false in YAML 1.1
countries: [GB, FR, NO, DE]

# Correct — quote the ambiguous value
countries: [GB, FR, "NO", DE]

YAML 1.2 (the current standard) fixes this — only true and false are booleans.

Tabs are forbidden

YAML uses only spaces for indentation — never tabs. A tab character anywhere in the indentation is a syntax error. Most editors can be configured to insert spaces when you press Tab in YAML files.

Implicit type coercion

YAML parsers infer types from bare values. 1.0 becomes a float, 0x1A becomes an integer (26), 1_000 becomes 1000, and ISO dates become date objects. Quote values you want treated as strings:

version: "1.0"     # string, not float
zip: "01234"       # string, not integer (leading zero stripped otherwise)

When to use YAML

• Configuration files — Docker Compose, Kubernetes, GitHub Actions, Helm charts, Ansible.
• Human-edited files — when humans write and maintain the file and comments are valuable.
• CI/CD pipelines — virtually every CI platform (GitHub Actions, GitLab CI, CircleCI) uses YAML.

For machine-generated data or API responses, JSON is usually better — it is simpler, has fewer gotchas, and is natively supported by every language. See the JSON vs YAML comparison guide for a full breakdown of when to choose each.