YAML collections: Sequences and mappings

Cover photo by Karen Vardazaryan on Unsplash.

Sequences

A sequence is a YAML node that contains an ordered list of zero to n YAML nodes (mappings, sequences, or scalars). Sequences are commonly known as arrays or lists in other languages.

Block collection style

A block sequence is a series of YAML nodes lead by a dash (-) indicator and white space.

integers:
  - 1
  - 2
  - 3
  - 4
  - 5
  - 6
  - 7
  - 8
  - 9
  - 10
colors:
  - red
  - green
  - blue
  - yellow
  - cyan
  - magenta
  - black
  - white

In JSON, this is

{
  "integers": [
    1,
    2,
    3,
    4,
    5,
    6,
    7,
    8,
    9,
    10
  ],
  "colors": [
    "red",
    "green",
    "blue",
    "yellow",
    "cyan",
    "magenta",
    "black",
    "white"
  ]
}

Flow collection style

A flow sequence is a series of YAML nodes contained in square brackets ([ and ]). Flow sequence entries are separated by a comma (,) with a trailing comma allowed but empty node entries disallowed.

integers: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
colors: [red, green, blue, yellow, cyan, magenta, black, white]

but also

integers: [
  1, 2,
3, 4, 5,
  6, 7, 8, 9,
10,
]
colors: [red, green, blue,
yellow, cyan, magenta, black, white]

or any other white space variation.

In JSON, this is

{
  "integers": [
    1,
    2,
    3,
    4,
    5,
    6,
    7,
    8,
    9,
    10
  ],
  "colors": [
    "red",
    "green",
    "blue",
    "yellow",
    "cyan",
    "magenta",
    "black",
    "white"
  ]
}

Mappings

A mapping is a YAML node that contains an unordered set of zero to n key-value pairs. A key and its value are separated by a colon (:). Keys must be unique. Both keys and values may be any kind of YAML node. Mappings are commonly known as hash maps or associative arrays in other languages.

Block collection style

A block mapping is a series of key-value pairs on separate lines.

integer: 3
color: blue

In JSON, this is

{
  "integer": 3,
  "color": "blue"
}

Flow collection style

A flow mapping is a series of key-value pairs contained in curly braces ({ and }). Flow mapping entries are separated by a comma (,) with a trailing comma allowed but empty node entries disallowed.

{ integer: 3, color: blue }

but also

{
  integer: 3,
color: blue,}

or any other white space variation.

In JSON, this is

{
  "integer": 3,
  "color": "blue"
}

Explicit mapping entries

A mapping key and value pair is optionally put on separate lines where the key is lead by a question mark (?) and the value is lead by a colon (:). This allows for special keys such as the empty node or complex non-scalar nodes.

? 
: My key is empty
? - 3
  - [blue]
  - { autocorrect: On }
: My key is a nested collection

The previous example is a mapping containing two key-value pairs where the values are strings. It has no equivalent JSON expression.