YAML

YAML Ain’t Markup Language (from version 1.2) is a superset of JSON which adds a number of features:

Concise expression of lists and maps using "block style" multi-line syntax where whitespace becomes significant.
Multiple documents in a single file, delimited by the --- document seperator.
Automatic type detection allows forgoing quotes, save for a few exceptions.
Reuse of blocks with anchors and aliases.

Versions

There are three versions of the YAML specification:

1.0
1.1:
- Language Independent Types
1.2 is the version described below:
- New JSON schema.

Test suite

A conformance suite for YAML implementations has been available since 2016.

Types defined by schemas

Types are usually inferred from node values, though can be explicitly specified with !!<type> (itself shorthand for !<tag:yaml.org,2002:<type>>) annotations preceding nodes.

YAML schemas define tags (either specific, if annotated with types, or non-specific) which allow parsing syntax into a series of typed nodes. YAML types are commonly represented by multiple different syntaxes made available in different schemas. Some common schemas are outlined below.

Fail-safe

The fail-safe schema is guaranteed to work in any YAML document.

str describes flow strings (either unquoted or single (') and double (") quotes) and block strings.
seq defines both block and flow sequence.
map defines both block and flow map.

JSON

The JSON schema allows parsing JSON documents within YAML documents, providing compatibility and interoperability. This syntax is referred to as "flow syntax", or shorthand.

null is implemented.
bool represents true or false.
int represents canonical integers.
float represents canonical real numbers.

Core

The core tags provide human-readable presentation of the JSON types, and is the recommended default schema for YAML processors.

null represents empty values, null, Null, NULL and ~.
bool values are identified from true, True, TRUE and false, False, FALSE.
int additionally represents decimal, octal, and hexadecimal representations.
float additionally represents exponential, fixed, .inf, and .NaN representations.

Tag repository

The YAML tag repository is defined in the "Language Independent Types for YAML" specification. It defines the following types. Although linked to from the 1.2 specification, few implementations implement them due to asinine, non-obvious behaviour.

Scalar

Comparisons below relate to the core syntax.

binary represents binary text as base64-encoded strings.
bool represent boolean values as y, Y, yes, Yes, YES, true, True, TRUE, on, On, ON and n, N, no, No, NO, false, False, FALSE, off, Off, OFF.
float adds some aliases for infinity and NaN, and expression of numbers in base-60.
int adds expression of numbers in base-2, -8, -16, and -60.
merge specifies one or more maps to be merged into the map within which it's used; useful for providing default values.
null is extended to cover Null and NULL.
str is no different to the core syntax.
timestamp allows specifying dates in a range of syntaxes:
- Canonical: 2001-12-15T02:59:43.1Z
- ISO 8601: 2001-12-14t21:59:43.10-05:00
- Space separated: 2001-12-14 21:59:43.10 -5
- No time zone: 2001-12-15 2:59:43.10
- Date (at 00:00:00Z): 2002-12-14
value allows replacing the named value with a default, useful for evolving scalar values into collection values later.
yaml allows modelling values of unknown tags.

Collections

map is no different to the core syntax.
omap introduces an ordered sequence of key-value pairs, disallowing duplicate keys.
pairs introduces an unordered sequence of key-value pairs, allowing duplicate keys.
set introduces a new unordered set of unique values.
seq is no different to the core syntax.

Syntax

YAML syntax is made up of a series of tags (defining structure) and nodes (defining values).

Documents

YAML documents can be optionally preceded by --- and followed by .... Multiple documents in the same file or transmission can be delimited using ---.

In block structures whitespace denotes structure. Tab characters are not allowed.

Directives

Optionally, the %YAML directive can be used to specify the version of the YAML specification to apply to the file can be placed at the top of the file, which must be followed by ---.

%YAML 1.2
---
key: value
---
key: value

The %TAG directive defines shorthand prefixes that expand to larger names, e.g.:

%TAG !foo! tag:example.com,2012:world/

Comments

Comments are preceded by a #, and can follow a node provided there's a space between the value and the comment:

# comment
someKey: someValue # comment
otherKey: | # comment
    someValue

Strings

Strings can be expressed in either block or flow style:

Flow style nodes have explicit start and end delimiters. This syntax is commonly used for single-line strings.
Block style strings span multiple lines without explicit delimiters.

string: single line
quotedString: 'single line'
quotedString: "single line"

Handling of newlines in multi-line strings is dependent upon the indicator used following the name:

| preserves newlines.
> folds newlines into spaces, except where text within the string is further indented, where they're preserved.

multiLine: | # multi\nline
    multi
    line

singleLine: > # single line
    single
    line

mixed: > # single line\n  but wait\n  what is this
    single
    line
      but wait
      what is this

Sequences

Sequences can be expressed in block form:

sequence:
  - item 1
  - item 2

Or flow form:

sequence: ["item 1", "item 2"]

Maps

Maps can be expressed in block form:

map:
    a: 1
    b: 2