Complete YAML syntax reference covering data types, strings, collections, anchors, and multi-document files. Bookmark this page for quick lookup when writing YAML configuration files.
Basic Types
Syntax
Description
name: John
String scalar (unquoted)
age: 30
Integer
price: 19.99
Float
hex: 0xFF
Hexadecimal integer (255)
octal: 0o77
Octal integer (63, YAML 1.2)
infinity: .inf
Positive infinity
not_a_number: .nan
NaN (not a number)
enabled: true
Boolean true (also True, TRUE)
debug: false
Boolean false (also False, FALSE)
value: null
Null value (also ~ or omitted)
empty:
Null (key with no value)
date: 2024-01-15
Date (ISO 8601)
timestamp: 2024-01-15T09:30:00Z
Datetime with timezone
Strings
Syntax
Description
plain: hello world
Plain (unquoted) string
single: 'hello world'
Single-quoted string (no escape sequences)
escape: 'it''s here'
Escaped single quote inside single quotes
double: "hello\nworld"
Double-quoted string (supports \n, \t, etc.)
unicode: "\u0041"
Unicode escape sequence (A)
literal: | line one line two
Literal block: preserves newlines exactly
folded: > long line continued
Folded block: joins lines with spaces
strip: |- no trailing newline
Literal block, strip trailing newline
keep: |+ keep trailing newlines
Literal block, keep all trailing newlines
indent: |2 indented text
Literal block with explicit indent indicator
folded_strip: >- text here
Folded block, strip trailing newline
Collections
Syntax
Description
- apple - banana - cherry
Sequence (list/array)
name: John age: 30
Mapping (dictionary/object)
person: name: John age: 30
Nested mapping (indent with 2 spaces)
users: - name: Alice - name: Bob
List of mappings
- - a - b - - c - d
Nested sequences (list of lists)
server: host: localhost ports: - 80 - 443
Mapping containing a sequence
- name: Alice skills: - Python - YAML
List of mappings with nested lists
Flow Style
Syntax
Description
colors: [red, green, blue]
Inline sequence (flow sequence)
person: {name: John, age: 30}
Inline mapping (flow mapping)
matrix: [[1, 2], [3, 4]]
Nested inline sequences
user: {name: Jo, tags: [a, b]}
Mixed flow: inline map with inline list
items: [1, "two", true, null]
Mixed types in a flow sequence
{? key: val}
Explicit key indicator (rarely used)
Advanced
Syntax
Description
defaults: &defaults timeout: 30 retries: 3
Anchor: define a reusable block named "defaults"
production: <<: *defaults host: prod.example.com
Alias + merge: inherit anchor values, add/override keys
other: *defaults
Alias: reference the anchored block by name
<<: *defaults
Merge key: merge mapping from anchor into current map
typed: !!str 123
Tag: force value to be a string ("123")
num: !!int "42"
Tag: force value to be an integer (42)
bin: !!binary aGVsbG8=
Binary data (base64 encoded)
set: !!set ? item1 ? item2
Set type (unique values only)
omap: !!omap - key1: val1 - key2: val2
Ordered mapping (preserves insertion order)
Multi-Document
Syntax
Description
---
Document start marker (begins a new document)
...
Document end marker (optional, ends current document)
--- doc: one --- doc: two
Multiple documents in one file
--- doc: one ... --- doc: two
Explicit end before next document start
%YAML 1.2 --- key: value
YAML version directive (before document start)
# comment --- key: value
Comments before document start are allowed
Common Gotchas
Syntax
Description
country: NO
Parsed as boolean false in YAML 1.1 (the "Norway problem")
country: "NO"
Fix: quote to force string interpretation
on: true / off: false
YAML 1.1 treats on/off/yes/no as booleans
version: 1.0
Parsed as float (1.0), not string "1.0"
version: "1.0"
Fix: quote to keep as string
time: 12:30:00
YAML 1.1 may parse as sexagesimal (base-60) number
# Use spaces only
Tabs are NOT allowed for indentation in YAML
# Indent consistently
Indentation must be consistent (2 spaces recommended)
key: { nested: value }
Flow mappings cannot span multiple lines (in strict parsers)
key: value # comment
Inline comments need a space before #
duplicate: first duplicate: second
Duplicate keys: last value wins (may cause silent bugs)