YAML documents and directives

A YAML file is a stream of zero or more documents. Each document holds one node: a mapping, a sequence or a scalar. Two markers and two directives divide the stream and say how a document is to be read.

The stream

…Byte order mark optional, at the start of the stream or before a documentoptional
…Comments and blank linesany number
…Directives %YAML and %TAG lines for this documentoptional
…Directives end marker ---, needed after directives3 characters
…Content one nodevaries
…Document end marker ...optional
…More documents the same parts, repeatedany number

The parts of a YAML stream

An empty file, or one that holds only comments, is a stream with no documents.

Document markers

A marker must start at the first column of a line and be followed by white space or the end of the line.

Marker	Name	Meaning
`---`	Directives end	Ends the directives, if there are any, and starts a document. Content can follow on the same line: `--- text`
`...`	Document end	Ends a document. A comment can follow on the line; content cannot

The characters --- or ... at the start of a line are always a marker, wherever they appear, and they cannot be plain text or sit inside a multi-line string. A quoted string or a block scalar that needs them on a line must indent or escape them.

# A stream of three documents
---
name: first
...
---
name: second
--- # comment on the marker line
- third
- document

The ... is optional when a --- starts the next document

Bare and explicit documents

A document may start with --- (explicit) or with no marker at all (bare). The rules for what can come next are:

A bare document may be the first thing in a stream or follow a ....
After a document that was not ended by ..., the next document must start with ---. Plain content cannot simply carry on.
Directives can only come at the start of the stream or after a ....
A document can be empty. Nothing between two markers gives a null.

On a --- line the node can start straight away, but a block mapping or block sequence cannot: it needs its own line. --- key: value is an error.

Directives

A directive starts with % in the first column of a line. It applies to the next document only, and the directives must be followed by a --- line.

The %YAML directive

%YAML 1.2
---
value: 10

Declares the version the document is written for

It takes one parameter, a version of the form 1.2. At most one may appear in a document. A reader should handle a higher minor version with a warning and reject a higher major version. A document with no %YAML is read by the version the reader implements; see YAML 1.1 and 1.2.

The %TAG directive

%TAG !e! tag:example.com,2000:app/
---
!e!invoice
number: 34

Gives the handle !e! a prefix, so !e!invoice means tag:example.com,2000:app/invoice

It takes a tag handle and a prefix. A handle may be declared only once in a document. Declarations last for one document: the next document starts with the default handles again. See Tags and schemas.

Reserved directives

Any other directive name is reserved. A reader should ignore it and warn, although libyaml rejects it. It has a name and parameters separated by spaces, and can be followed by a comment:

%FOO bar baz # ignored, with a warning
---
x: 1

An unknown directive

Comments

A comment starts with # and runs to the end of the line. It must have white space, or the start of the line, in front of it. So a: b#c is one value, b#c, and a: "b"#c is an error.

Comments carry no meaning. A reader is free to throw them away, and they do not appear in the data. They cannot appear inside a scalar: in a multi-line plain scalar a comment ends the scalar, and in a block scalar a # line is part of the text if it is indented with the text.

Byte order marks

A byte order mark (U+FEFF) may start the stream and may be placed before each document. Nowhere else: inside a document it is not allowed. See Encodings and characters.

Specification

These rules are in chapter 9 of YAML 1.2.2, and the comment rules are in section 6.6.

.YAML File Format – Documents and directives