YAML Syntax Explained

YAML stores the same data as JSON using indentation instead of brackets. Here is how the syntax works and where it surprises people.

What YAML is for

YAML is a text format for structured data that people edit by hand: configuration files, deployment manifests, CI pipelines, and similar files. It describes the same kinds of data as JSON (maps, lists, strings, numbers, booleans, null) but uses indentation and line breaks instead of braces and commas. That makes it easy to read and also easy to get subtly wrong.

The three building blocks

A mapping is a set of key and value pairs, written key: value with a space after the colon. A sequence is an ordered list, written one item per line with a leading dash and a space. A scalar is a single value such as a string, number, boolean, or null. Mappings and sequences nest inside each other by indentation.

Here is a small document and the JSON that PyYAML's safe_load produced from it (the list and inner map are shown on one line to save space):

# Service settings
name: web
port: 8080
debug: false
ratio: 0.5
version: "1.10"
tags:
  - api
  - public
owner:
  team: platform
  email: null
{
  "name": "web",
  "port": 8080,
  "debug": false,
  "ratio": 0.5,
  "version": "1.10",
  "tags": ["api", "public"],
  "owner": {"team": "platform", "email": null}
}

The comment line disappears, because comments are not data. The unquoted 8080 and 0.5 became numbers, false became a boolean, null became null, and the quoted "1.10" stayed a string.

Indentation and comments

Indentation defines structure, and it must use spaces. Tab characters are not allowed for indentation; PyYAML rejects a tab-indented list with a ScannerError. The number of spaces is up to you, but items at the same level must line up exactly. Two spaces is a common choice. Comments start with # and run to the end of the line. Inside a value, a # only starts a comment when a space comes before it.

Quoting rules

Most strings need no quotes at all. Add quotes when a value would otherwise be read as something else, or when it contains characters that YAML treats specially, such as a leading *, &, !, {, [, or a : sequence in the middle.

  • Single quotes keep text exactly as written. The only escape is a doubled quote: 'it''s' loads as it's.
  • Double quotes support backslash escapes. "tab\tend" contains a real tab character, while 'tab\tend' keeps the backslash and the letter t.

Block scalars for multi-line text

For longer text, a block scalar avoids quoting entirely. The | indicator is literal and keeps line breaks. The > indicator is folded and joins lines with spaces. Both keep one final newline by default; adding - strips it.

literal: |
  line one
  line two
folded: >
  line one
  line two
strip: |-
  no trailing newline

PyYAML loads these as 'line one\nline two\n', 'line one line two\n', and 'no trailing newline'. The literal style suits shell scripts and certificates; the folded style suits long prose.

Anchors and aliases

An anchor, written &name, labels a node. An alias, written *name, reuses it elsewhere. Many tools also accept the merge key <<, which copies the keys of an aliased mapping into the current one, with local keys taking priority:

defaults: &defaults
  retries: 3
  timeout: 30
staging:
  <<: *defaults
  timeout: 60

PyYAML loads staging as {"retries": 3, "timeout": 60}. The merge key came from the YAML 1.1 type set and is not part of the YAML 1.2 core schema, so a strict 1.2 parser may not support it.

Multiple documents in one file

A line containing only --- starts a new document, so one file can hold several. A stream of ---, kind: a, ---, kind: b loads with safe_load_all as two separate maps. Kubernetes manifests often use this to keep related resources together.

YAML and JSON

YAML 1.2 was aligned with JSON so that JSON text is, with only rare edge cases, also valid YAML. Feeding the line {"name": "web", "ports": [80, 443], "tls": true} to PyYAML gives the same dict a JSON parser would. The flow style used there, with braces and brackets, is legal YAML anywhere. The reverse is not true: comments, anchors, block scalars, and unquoted strings have no JSON equivalent.

The Norway problem

YAML 1.1 treats a long list of plain words as booleans, including yes, no, on, and off in several capitalizations. The country code for Norway is NO, so a list of country codes can silently gain a false. PyYAML follows YAML 1.1 rules, and this input:

countries:
  - GB
  - NO
  - SE
enabled: yes
mode: off
quoted: "no"
version: 1.10

loads as:

{"countries": ["GB", false, "SE"], "enabled": true,
 "mode": false, "quoted": "no", "version": 1.1}

Three surprises appear at once: NO became false, yes and off became booleans, and the unquoted version 1.10 became the number 1.1. The YAML 1.2 core schema only treats true and false as booleans, but many parsers still use 1.1 rules, so the safe habit is to quote anything that should stay a string.

Before you commit a YAML file

  1. Check that no tab characters appear in the indentation.
  2. Quote country codes, version numbers, and values like yes, no, on, and off when you mean text.
  3. Quote strings that start with a special character or contain : .
  4. Pick | or > deliberately for multi-line text, and decide whether the trailing newline matters.
  5. Load the file with the same parser your tool uses and inspect the result, rather than trusting how the file looks.