YAML block style

Block style uses indentation to show structure. There are two block collections, the sequence and the mapping, and any node inside them can be written in block or flow style.

Indentation

Indentation is a number of space characters at the start of a line. Tabs cannot be used for it. A node’s content is indented further than its parent, by at least one space; the amount is free, and the only requirement is that the entries of one collection line up.

server:
  host: example.com
  ports:
    - 80
    - 443
  tls: true
timeout: 30

Each level is indented further than the one above it

A tab can separate tokens on a line, as in key: value, and can follow the indentation in front of a scalar. It cannot stand in for indentation, and a block collection cannot start after one.

Block sequences

Each entry of a block sequence starts with a dash, the - indicator, and white space or a line break must follow it. The entries line up in one column.

- red
- green
- blue

A block sequence

A sequence inside a mapping can be indented or can sit at the same column as its key. These two are equal:

indented:
  - one
  - two
level:
- one
- two

A sequence need not be indented under its key

This exception holds only under a mapping key. A sequence inside a sequence must be indented further.

Compact forms

A block sequence or mapping can start on the same line as a parent - or ?. The column where it starts becomes its indentation.

- - nested
  - sequence
- name: first
  size: 2

A sequence in a sequence, and a mapping in a sequence

Block mappings

Each entry is a key and a value separated by a colon. The colon must be followed by white space or a line break, so a:b is one plain value but a: b is a mapping entry.

name: Example
tags:
  - one
owner:
  id: 7
empty:
"quoted key": 1
? [complex, key]
: value

A value can be on the key’s line or the lines below it, or absent

A key with nothing after its colon has an empty value. That value resolves to null.

Implicit keys

A key written without ? is called an implicit key. Three rules apply to it, and they apply to every key written that way:

It must be on a single line.
It must be at most 1024 Unicode characters, including anything before the colon.
It cannot be a block collection or a block scalar.

A value on the same line as an implicit key cannot itself be a block mapping or a block sequence. a: b: c is an error, while a block collection on the lines below, or a flow collection, is fine.

Explicit keys

The ? indicator introduces an explicit key: any node, in any style, on any number of lines. Its value follows on a line starting with : at the same indentation. If no such line is there, the value is empty.

? |
  a block
  key
: - one
  - two
? another key

A block scalar as a key, and an explicit key with no value

Duplicate keys

The keys of a mapping must be unique. The specification says that a mapping with a repeated key is invalid. In practice many readers accept it and keep the last value, and others raise an error.

Properties on block nodes

Tags and anchors are written before a node. The position decides what they apply to:

&m
a: 1            # &m is on the mapping, because it is on a line of its own
&k b: 2          # &k is on the key b
seq: !!seq
  - x           # the tag is on the sequence
c: &v [1, 2]    # &v is on the flow sequence value

An anchor or tag on its own line applies to the collection that follows

A block sequence or mapping cannot start on the same line as its own tag or anchor.

Specification

These rules are in section 8.2 of YAML 1.2.2, and indentation is in section 6.1.

.YAML File Format – Block style