YAML Ain't Markup Language (YAML™) Version 1.1

YAML represents any native data structure using three node kinds: the sequence, the mapping and the scalar. By sequence we mean an ordered series of entries, by mapping we mean an unordered association of unique keys to values, and by scalar we mean any datum with opaque structure presentable as a series of Unicode characters. Combined, these primitives generate directed graph structures. These primitives were chosen because they are both powerful and familiar: the sequence corresponds to a Perl array and a Python list, the mapping corresponds to a Perl hash table and a Python dictionary. The scalar represents strings, integers, dates and other atomic data types.

Each YAML node requires, in addition to its kind and content, a tag specifying its data type. Type specifiers are either global URIs, or are local in scope to a single application. For example, an integer is represented in YAML with a scalar plus the global tag “tag:yaml.org,2002:int”. Similarly, an invoice object, particular to a given organization, could be represented as a mapping together with the local tag “!invoice”. This simple model can represent any data structure independent of programming language.

For sequential access mediums, such as an event callback API, a YAML representation must be serialized to an ordered tree. Since in a YAML representation, mapping keys are unordered and nodes may be referenced more than once (have more than one incoming “arrow”), the serialization process is required to impose an ordering on the mapping keys and to replace the second and subsequent references to a given node with place holders called aliases. YAML does not specify how these serialization details are chosen. It is up to the YAML processor to come up with human-friendly key order and anchor names, possibly with the help of the application. The result of this process, a YAML serialization tree, can then be traversed to produce a series of event calls for one-pass processing of YAML data.

The final output process is presenting the YAML serializations as a character stream in a human-friendly manner. To maximize human readability, YAML offsers a rich set of stylistic options which go far beyond the minimal functional needs of simple data storage. Therefore the YAML processor is required to introduce various presentation details when creating the stream, such as the choice of node styles, how to format content, the amount of indentation, which tag handles to use, the node tags to leave unspecified, the set of directives to provide and possibly even what comments to add. While some of this can be done with the help of of the application, in general this process should guided by the preferences of the user.

Parsing is the inverse process of presentation, it takes a stream of characters and produces a series of events. Parsing discards all the details introduced in the presentation process, reporting only the serialization events. Parsing can fail fue to ill-formed input.

Composing takes a series of serialization events and produces a representation graph. Composing discards all the serialization details introduced in the serialization process, producing only the representation graph. Composing can fail due to any of several reasons, detailed below.

The final input process is constructing native data structures from the YAML representation. Construction must be based only on the information available in the representation, and not on additional serialization or presentation details such as comments, directives, mapping key order, node styles, content format, indentation levels etc. Construction can fail due to the unavailability of the required native data types.

YAML's representation of native data is a rooted, connected, directed graph of tagged nodes. By “directed graph” we mean a set of nodes and directed edges (“arrows”), where each edge connects one node to another (see a formal definition). All the nodes must be reachable from the root node via such edges. Note that the YAML graph may include cycles, and a node may have more than one incoming edge.

Nodes that are defined in terms of other nodes are collections and nodes that are independent of any other nodes are scalars. YAML supports two kinds of collection nodes, sequences and mappings. Mapping nodes are somewhat tricky because their keys are unordered and must be unique.

Figure 3.3. Representation Model

To express a YAML representation using a serial API, it necessary to impose an order on mapping keys and employ alias nodes to indicate a subsequent occurrence of a previously encountered node. The result of this process is a serialization tree, where each node has an ordered set of children. This tree can be traversed for a serial event based API. Construction of native structures from the serial interface should not use key order or anchors for the preservation of important data.

Figure 3.4. Serialization Model

A YAML presentation is a stream of Unicode characters making use of of styles, formats, comments, directives and other presentation details to present a YAML serialization in a human readable way. Although a YAML processor may provide these details when parsing, they should not be reflected in the resulting serialization. YAML allows several serializations to be contained in the same YAML character stream as a series of documents separated by document boundary markers. Documents appearing in the same stream are independent; that is, a node must not appear in more than one serialization tree or representation graph.

Figure 3.5. Presentation Model

3.2.3.1. Node Styles

Each node is presented in some style, depending on its kind. The node style is a presentation detail and is not reflected in the serialization tree or representation graph. There are two groups of styles, block and flow. Block styles use indentation to denote nesting and scope within the document. In contrast, flow styles rely on explicit indicators to denote nesting and scope.

YAML provides a rich set of scalar styles. Block scalar styles include the literal style and the folded style; flow scalar styles include the plain style and two quoted styles, the single quoted style and the double quoted style. These styles offer a range of trade-offs between expressive power and readability.

Normally, the content of block collections begins on the next line. In most cases, YAML also allows block collections to start in-line for more compact notation when nesting block sequences and block mappings inside each other. When nesting flow collections, a flow mapping with a single key: value pair may be specified directly inside a flow sequence, allowing for a compact “ordered mapping” notation.

Figure 3.6. Kind/Style Combinations

A well-formed character stream must match the productions specified in the next chapter. Successful loading also requires that each alias shall refer to a previous node identified by the anchor. A YAML processor should reject ill-formed streams and unidentified aliases. A YAML processor may recover from syntax errors, possibly by ignoring certain parts of the input, but it must provide a mechanism for reporting such errors.

It is not required that all the tags of the complete representation be explicitly specified in the character stream. During parsing, nodes that omit the tag are given a non-specific tag: “?” for plain scalars and “!” for all other nodes. These non-specific tags must be resolved to a specific tag (either a local tag or a global tag) for a complete representation to be composed.

Resolving the tag of a node must only depend on the following three parameters: the non-specific tag of the node, the path leading from the root node to the node, and the content (and hence the kind) of the node. In particular, resolution must not consider presentation details such as comments, indentation and node style. Also, resolution must not consider the content of any other node, except for the content of the key nodes directly along the path leading from the root node to the resolved node. In particular, resolution must not consider the content of a sibling node in a collection or the content of the value node associated with a resolved key node.

Tag resolution is specific to the application, hence a YAML processor should provide a mechanism allowing the application to specify the tag resolution rules. It is recommended that nodes having the “!” non-specific tag should be resolved as “tag:yaml.org,2002:seq”, “tag:yaml.org,2002:map” or “tag:yaml.org,2002:str” depending on the node's kind. This convention allows the author of a YAML character stream to exert some measure of control over the tag resolution process. By explicitly specifying a plain scalar has the “!” non-specific tag, the node is resolved as a string, as if it was quoted or written in a block style. Note, however, that each application may override this behavior. For example, an application may automatically detect the type of programming language used in source code presented as a non-plain scalar and resolve it accordingly.

When a node has more than one occurence (using an anchor and alias nodes), tag resolution must depend only on the path to the first occurence of the node. Typically, the path leading to a node is sufficient to determine its specific tag. In cases where the path does not imply a single specific tag, the resolution also needs to consider the node content to select amongst the set of possible tags. Thus, plain scalars may be matched against a set of regular expressions to provide automatic resolution of integers, floats, timestamps and similar types. Similarly, the content of mapping nodes may be matched against sets of expected keys to automatically resolve points, complex numbers and similar types.

The combined effect of these rules is to ensure that tag resolution can be performed as soon as a node is first encountered in the stream, typically before its content is parsed. Also, tag resolution only requires refering to a relatively small number of previously parsed nodes. Thus, tag resolution in one-pass processors is both possible and practical.

If a document contains unresolved tags, the YAML processor is unable to compose a complete representation graph. In such a case, the YAML processor may compose an partial representation, based on each node's kind and allowing for non-specific tags.

To be valid, a node must have a tag which is recognized by the YAML processor and its content must satisfy the constraints imposed by this tag. If a document contains a scalar node with an unrecognized tag or invalid content, only a partial representation may be composed. In contrast, a YAML processor can always compose a complete representation for an unrecognized or an invalid collection, since collection equality does not depend upon knowledge of the collection's data type. However, such a complete representation can not be used to construct a native data structure.

In a given processing environment, there need not be an available native type corresponding to a given tag. If a node's tag is unavailable, a YAML processor will not be able to construct a native data structure for it. In this case, a complete representation may still be composed, and an application may wish to use this representation directly.

YAML streams use the printable subset of the Unicode character set. On input, a YAML processor must accept all printable ASCII characters, the space, tab, line break, and all Unicode characters beyond #x9F. On output, a YAML processor must only produce these acceptable characters, and should also escape all non-printable Unicode characters. The allowed character range explicitly excludes the surrogate block #xD800-#xDFFF, DEL #x7F, the C0 control block #x0-#x1F, the C1 control block #x80-#x9F, #xFFFE and #xFFFF. Any such characters must be presented using escape sequences.

All characters mentioned in this specification are Unicode code points. Each such code point is written as one or more octets depending on the character encoding used. Note that in UTF-16, characters above #xFFFF are written as four octets, using a surrogate pair. A YAML processor must support the UTF-16 and UTF-8 character encodings. If a character stream does not begin with a byte order mark (#FEFF), the character encoding shall be UTF-8. Otherwise it shall be either UTF-8, UTF-16 LE or UTF-16 BE as indicated by the byte order mark. On output, it is recommended that a byte order mark should only be emitted for UTF-16 character encodings. Note that the UTF-32 encoding is explicitly not supported. For more information about the byte order mark and the Unicode character encoding schemes see the Unicode FAQ.

In the examples, byte order mark characters are displayed as “⇔”.

⇔# Comment only.

Legend:
  c-byte-order-mark

# This stream contains no
# documents, only comments.

# Invalid use of BOM
⇔# inside a
# document.

ERROR:
 A BOM must not appear
 inside a document.

Indicators are characters that have special semantics used to describe the structure and content of a YAML document.

sequence:
- one
- two
mapping:
  ? sky
  : blue
  ? sea : green

Legend:
  c-sequence-entry
  c-mapping-key
  c-mapping-value

%YAML 1.1
---
!!map {
  ? !!str "sequence"
  : !!seq [
    !!str "one", !!str "two"
  ],
  ? !!str "mapping"
  : !!map {
    ? !!str "sky" : !!str "blue",
    ? !!str "sea" : !!str "green",
  }
}

sequence: [ one, two, ]
mapping: { sky: blue, sea: green }

Legend:
  c-sequence-start c-sequence-end
  c-mapping-start  c-mapping-end
  c-collect-entry

%YAML 1.1
---
!!map {
  ? !!str "sequence"
  : !!seq [
    !!str "one", !!str "two"
  ],
  ? !!str "mapping"
  : !!map {
    ? !!str "sky" : !!str "blue",
    ? !!str "sea" : !!str "green",
  }
}

# Comment only.

Legend:
  c-comment

# This stream contains no
# documents, only comments.

anchored: !local &anchor value
alias: *anchor

Legend:
  c-anchor
  c-alias
  c-tag

%YAML 1.1
---
!!map {
  ? !!str "anchored"
  : !local &A1 "value",
  ? !!str "alias"
  : *A1,
}

literal: |
  text
folded: >
  text

Legend:
  c-literal
  c-folded

%YAML 1.1
---
!!map {
  ? !!str "literal"
  : !!str "text\n",
  ? !!str "folded"
  : !!str "text\n",
}

single: 'text'
double: "text"

Legend:
  c-single-quote
  c-double-quote

%YAML 1.1
---
!!map {
  ? !!str "double"
  : !!str "text",
  ? !!str "single"
  : !!str "text",
}

%YAML 1.1
--- text

Legend:
  c-directive

%YAML 1.1
---
!!str "text"

commercial-at: @text
grave-accent: `text

ERROR:
 Reserved indicators can't
 start a plain scalar.

The Unicode standard defines the following line break characters:

A YAML processor must accept all the possible Unicode line break characters.

Line breaks can be grouped into two categories. Specific line breaks have well-defined semantics for breaking text into lines and paragraphs, and must be preserved by the YAML processor inside scalar content.

Generic line breaks do not carry a meaning beyond “ending a line”. Unlike specific line breaks, there are several widely used forms for generic line breaks.

Generic line breaks inside scalar content must be normalized by the YAML processor. Each such line break must be parsed into a single line feed character. The original line break form is a presentation detail and must not be used to convey content information.

Normalization does not apply to ignored (escaped or chomped) generic line breaks.

Outside scalar content, YAML allows any line break to be used to terminate lines.

On output, a YAML processor is free to present line breaks using whatever convention is most appropriate, though specific line breaks must be preserved in scalar content. These rules are compatible with Unicode's newline guidelines.

In the examples, line break characters are displayed as follows: “↓” or no glyph for a generic line break, “⇓” for a line separator and “¶” for a paragraph separator.

|
  Generic line break (no glyph)
  Generic line break (glyphed)↓
  Line separator⇓
  Paragraph separator¶

Legend:
  b-generic b-line-separator
  b-paragraph-separator

%YAML 1.1
--- !!str
"Generic line break (no glyph)\n\
 Generic line break (glyphed)\n\
 Line separator\u2028\
 Paragraph separator\u2029"

The YAML syntax productions make use of the following character range definitions:

# Tabs do's and don'ts:
# comment: →
quoted: "Quoted →"
block: |
  void main() {
  →printf("Hello, world!\n");
  }
elsewhere:→# separation
→indentation, in→plain scalar

ERROR:
 Tabs may appear inside
 comments and quoted or
 block scalar content.
 Tabs must not appear
 elsewhere, such as
 in indentation and
 separation spaces.

In the examples, tab characters are displayed as the glyph “→”. Space characters are sometimes displayed as the glyph “·” for clarity.

··"Text·containing···
··both·space·and→
··→tab→characters"

Legend:
  #x9 (TAB) #x20 (SP)

%YAML 1.1
--- !!str
"Text·containing·\
 both·space·and·\
 tab→characters"

All non-printable characters must be presented as escape sequences. Each escape sequences must be parsed into the appropriate Unicode character. The original escape sequence form is a presentation detail and must not be used to convey content information. YAML escape sequences use the “\” notation common to most modern computer languages. Note that escape sequences are only interpreted in double quoted scalars. In all other scalar styles, the “\” character has no special meaning and non-printable characters are not available.

YAML escape sequences are a superset of C's escape sequences:

"Fun with \\
 \" \a \b \e \f \↓
 \n \r \t \v \0 \⇓
 \  \_ \N \L \P \¶
 \x41 \u0041 \U00000041"

Legend:
  ns-esc-char

%YAML 1.1
---
"Fun with \x5C
 \x22 \x07 \x08 \x1B \0C
 \x0A \x0D \x09 \x0B \x00
 \x20 \xA0 \x85 \u2028 \u2029
 A A A"

Bad escapes:
  "\c
  \xq-"

ERROR:
- c is an invalid escaped character.
- q and - are invalid hex digits.

As YAML's syntax is designed for maximal readability, it makes heavy use of the context that each syntactical entity appears in. For notational compactness, this is expressed using parameterized BNF productions. The set of parameters and the range of allowed values depend on the specific production. The full list of possible parameters and their values is:

In a YAML character stream, structure is often determined from indentation, where indentation is defined as a line break character (or the start of the stream) followed by zero or more space characters. Note that indentation must not contain any tab characters. The amount of indentation is a presentation detail used exclusively to delineate structure and is otherwise ignored. In particular, indentation characters must never be considered part of a node's content information.

··# Leading comment line spaces are
···# neither content nor indentation.
····
Not indented:
·By one space: |
····By four
······spaces
·Flow style: [    # Leading spaces
···By two,        # in flow style
··Also by two,    # are neither
··→Still by two   # content nor
····]             # indentation.

Legend:
  s-indent(n) Content
  Neither content nor indentation

%YAML 1.1
---
!!map {
  ? !!str "Not indented"
  : !!map {
      ? !!str "By one space"
      : !!str "By four\n  spaces\n",
      ? !!str "Flow style"
      : !!seq [
          !!str "By two",
          !!str "Still by two",
          !!str "Again by two",
        ]
    }
}

In general, a node must be indented further than its parent node. All sibling nodes must use the exact same indentation level, however the content of each sibling node may be further indented independently. The “-”, “?” and “:” characters used to denote block collection entries are perceived by people to be part of the indentation. Hence the indentation rules are slightly more flexible when dealing with these indicators. First, a block sequence need not be indented relative to its parent node, unless that node is also a block sequence. Second, compact in-line notations allow a nested collection to begin immediately following the indicator (where the indicator is counted as part of the indentation). This provides for an intuitive collection nesting syntax.

An explicit comment is is marked by a “#” indicator. Comments are a presentation detail and must have no effect on the serialization tree (and hence the representation graph).

Comments always span to the end of the line.

Outside scalar content, comments may appear on a line of their own, independent of the indentation level. Note that tab characters must not be used and that empty lines outside scalar content are taken to be (empty) comment lines.

··# Comment↓
···↓
↓

# This stream contains no
# documents, only comments.

Legend:
  c-b-comment l-comment

When a comment follows another syntax element, it must be separated from it by space characters. Like the comment itself, such characters are not considered part of the content information.

key:····# Comment↓
  value↓

Legend:
  c-nb-comment-text s-b-comment

%YAML 1.1
---
!!map {
  ? !!str "key"
  : !!str "value"
}

In most cases, when a line may end with a comment, YAML allows it to be followed by additional comment lines.

key:····# Comment↓
········# lines↓
  value↓
↓

Legend:
  s-b-comment l-comment s-l-comments

%YAML 1.1
---
!!map {
  ? !!str "key"
  : !!str "value"
}

Outside scalar content, YAML uses space characters for separation between tokens. Note that separation must not contain tab characters. Seperation spaces are a presentation detail used exclusively to delineate structure and are otherwise ignored; in particular, such characters must never be considered part of a node's content information.

{·first:·Sammy,·last:·Sosa·}:↓
# Statistics:
··hr:··# Home runs
····65
··avg:·# Average
····0.278

Legend:
  s-separate-spaces
  s-separate-lines(n)
  s-indent(n)

%YAML 1.1
---
!!map {
  ? !!map {
    ? !!str "first"
    : !!str "Sammy",
    ? !!str "last"
    : !!str "Sosa"
  }
  : !!map {
    ? !!str "hr"
    : !!int "65",
    ? !!str "avg"
    : !!float "0.278"
  }
}

YAML discards the “empty” prefix of each scalar content line. This prefix always includes the indentation, and depending on the scalar style may also include all leading white space. The ignored prefix is a presentation detail and must never be considered part of a node's content information.

plain: text
··lines
quoted: "text
··→lines"
block: |
··text
···→lines

Legend:
  s-ignored-prefix-plain(n)
  s-ignored-prefix-quoted(n)
  s-ignored-prefix-block(n)
  s-indent(n)

%YAML 1.1
---
!!map {
  ? !!str "plain"
  : !!str "text lines",
  ? !!str "quoted"
  : !!str "text lines",
  ? !!str "block"
  : !!str "text·→lines\n"
}

An empty line line consists of the ignored prefix followed by a line break. When trailing block scalars, such lines can also be interpreted as (empty) comment lines. YAML provides a chomping mechanism to resolve this ambiguity.

- foo
·↓
  bar
- |-
  foo
·↓
  bar
··↓

%YAML 1.1
---
!!seq {
  !!str "foo\nbar",
  !!str "foo\n\nbar"
}

Legend:
  l-empty(n,s)
  l-comment

Line folding allows long lines to be broken for readability, while retaining the original semantics of a single long line. When folding is done, any line break ending an empty line is preserved. In addition, any specific line breaks are also preserved, even when ending a non-empty line.

Hence, folding only applies to generic line breaks that end non-empty lines. If the following line is also not empty, the generic line break is converted to a single space (#x20).

If the following line is empty line, the generic line break is ignored.

Thus, a folded non-empty line may end with one of three possible folded line break forms. The original form of such a folded line break is a presentation detail and must not be used to convey node's content information.

>-
  specific⇓
  trimmed↓
··↓
·↓
↓
  as↓
  space

%YAML 1.1
--- !!str
"specific\L\
 trimmed\n\n\n\
 as space"

Legend:
  b-l-folded-specific(n,s)
  b-l-folded-as-space
  b-l-folded-trimmed(n,s)

The above rules are common to both the folded block style and the scalar flow styles. Folding does distinguish between the folded block style and the scalar flow styles in the following way:

Directives are instructions to the YAML processor. Like comments, directives are presentation details and are not reflected in the serialization tree (and hence the representation graph). This specification defines two directives, “YAML” and “TAG”, and reserves all other directives for future use. There is no way to define private directives. This is intentional.

Each directive is specified on a separate non-indented line starting with the “%” indicator, followed by the directive name and a space-separated list of parameters. The semantics of these tokens depend on the specific directive. A YAML processor should ignore unknown directives with an appropriate warning.

%FOO  bar baz # Should be ignored
               # with a warning.
--- "foo"

%YAML 1.1
--- !!str
"foo"

Legend:
  l-reserved-directive
  ns-directive-name
  ns-directive-parameter

%YAML 1.2 # Attempt parsing
           # with a warning
---
"foo"

%YAML 1.1
---
!!str "foo"

Legend:
  l-yaml-directive ns-yaml-version

%YAML 1.1
%YAML 1.1
foo

ERROR:
The YAML directive must only be
given at most once per document.

%TAG !yaml! tag:yaml.org,2002:↓
---
!yaml!str "foo"

%YAML 1.1
---
!!str "foo"

Legend:
  l-tag-directive
  c-tag-handle ns-tag-prefix

%TAG ! !foo
%TAG ! !foo
bar

ERROR:
The TAG directive must only
be given at most once per
handle in the same document.

%TAG !      !foo
%TAG !yaml! tag:yaml.org,2002:
---
- !bar "baz"
- !yaml!str "string"

Legend:
  ns-local-tag-prefix ns-global-tag-prefix

%YAML 1.1
---
!!seq [
  !<!foobar> "bar",
  !<tag:yaml.org,2002:str> "string"
]

# Private application:
!foo "bar"

# Migrated to global:
%TAG ! tag:ben-kiki.org,2000:app/
---
!foo "bar"

%YAML 1.1
---
!<!foo> "bar"

%YAML 1.1
---
!<tag:ben-kiki.org,2000:app/foo> "bar"

# Explicitly specify default settings:
%TAG !     !
%TAG !!    tag:yaml.org,2002:
# Named handles have no default:
%TAG !o! tag:ben-kiki.org,2000:
---
- !foo "bar"
- !!str "string"
- !o!type "baz"

%YAML 1.1
---
!!seq [
  !<!foo> "bar",
  !<tag:yaml.org,2002:str> "string"
  !<tag:ben-kiki.org,2000:type> "baz"
]

Legend:
  c-primary-tag-handle
  c-secondary-tag-handle
  c-named-tag-handle

YAML streams use document boundary markers to allow more than one document to be contained in the same stream. Such markers are a presentation detail and are used exclusively to convey structure. A line beginning with “---” may be used to explicitly denote the beginning of a new YAML document.

When YAML is used as the format of a communication channel, it is useful to be able to indicate the end of a document without closing the stream, independent of starting the next document. Lacking such a marker, the YAML processor reading the stream would be forced to wait for the header of the next document (that may be long time in coming) in order to detect the end of the previous one. To support this scenario, a YAML document may be terminated by an explicit end line denoted by “...”, followed by optional comments. To ease the task of concatenating YAML streams, the end marker may be repeated.

---↓
foo
...
# Repeated end marker.
...↓
---↓
bar
# No end marker.
---↓
baz
...↓

%YAML 1.1
---
!!str "foo"
%YAML 1.1
---
!!str "bar"
%YAML 1.1
---
!!str "baz"

Legend:
  c-document-start l-document-suffix

A YAML document is a single native data structure presented as a single root node. Presentation details such as directives, comments, indentation and styles are not considered part of the content information of the document.

In general, the document's node is indented as if it has a parent indented at -1 spaces. Since a node must be more indented that its parent node, this allows the document's node to be indented at zero or more spaces. Note that flow scalar continuation lines must be indented by at least one space, even if their first line is not indented.

"Root flow
 scalar"
--- !!str >
 Root block
 scalar
---
# Root collection:
foo : bar
... # Is optional.
---
# Explicit document may be empty.

Legend:
  l-implicit-document l-explicit-document

%YAML 1.1
---
!!str "Root flow scalar"
%YAML 1.1
---
!!str "Root block scalar"
%YAML 1.1
---
!!map {
  ? !!str "foo"
  : !!str "bar"
}
---
!!str ""

A sequence of bytes is a YAML character stream if, taken as a whole, it complies with the l-yaml-stream production. The stream begins with a prefix containing an optional byte order mark denoting its character encoding, followed by optional comments. Note that the stream may contain no documents, even if it contains a non-empty prefix. In particular, a stream containing no chareacters is valid and contains no documents.

⇔# A stream may contain
# no documents.

Legend:
  l-yaml-stream

# This stream contains no
# documents, only comments.

The first document may be implicit (omit the document start marker). In such a case it must not specify any directives and will be parsed using the default settings. If the document is explicit (begins with an document start marker), it may specify directives to control its parsing.

# Implicit document. Root
# collection (mapping) node.
foo : bar

# Explicit document. Root
# scalar (literal) node.
--- |
 Text content

Legend:
  l-first-document

%YAML 1.1
---
!!str "Text content\n"

%YAML 1.1
---
!!map {
  ? !!str "foo"
  : !!str "bar"
}

To ease the task of concatenating character streams, following documents may begin with a byte order mark and comments, though the same character encoding must be used through the stream. Each following document must be explicit (begin with a document start marker). If the document specifies no directives, it is parsed using the same settings as the previous document. If the document does specify any directives, all directives of previous documents, if any, are ignored.

! "First document"
---
!foo "No directives"
%TAG ! !foo
---
!bar "With directives"
%YAML 1.1
---
!baz "Reset settings"

%YAML 1.1
---
!!str "First document"
---
!<!foo> "No directives"
---
!<!foobar> "With directives"
---
!<!baz> "Reset settings"

Legend:
  l-next-document

The anchor property marks a node for future reference. An anchor is denoted by the “&” indicator. An alias node can then be used to indicate additional inclusions of the anchored node by specifying its anchor. An anchored node need not be referenced by any alias node; in particular, it is valid for all nodes to be anchored.

Note that as a serialization detail, the anchor name is preserved in the serialization tree. However, it is not reflected in the representation graph and must not be used to convey content information. In particular, the YAML processor need not preserve the anchor name once the representation is composed.

First occurence: &anchor Value
Second occurence: *anchor

Legend:
  c-ns-anchor-property
  ns-anchor-name

%YAML 1.1
---
!!map {
  ? !!str "First occurence"
  : &A !!str "Value",
  ? !!str "Second occurence"
  : *A
}

The tag property identifies the type of the native data structure presented by the node. A tag is denoted by the “!” indicator. In contrast with anchors, tags are an inherent part of the representation graph.

!<tag:yaml.org,2002:str> foo :
  !<!bar> baz

Legend:
  c-verbatim-tag

%YAML 1.1
---
!!map {
  ? !<tag:yaml.org,2002:str> "foo"
  : !<!bar> "baz"
}

- !<!> foo
- !<$:?> bar

ERROR:
- Verbatim tags aren't resolved,
  so ! is invalid.
- The $:? tag is neither a global
  URI tag nor a local tag starting
  with “!”.

%TAG !o! tag:ben-kiki.org,2000:
---
- !local foo
- !!str bar
- !o!type baz

Legend:
  c-ns-shorthand-tag

%YAML 1.1
---
!!seq [
  !<!local> "foo",
  !<tag:yaml.org,2002:str> "bar",
  !<tag:ben-kiki.org,2000:type> "baz",
]

%TAG !o! tag:ben-kiki.org,2000:
---
- !$a!b foo
- !o! bar
- !h!type baz

ERROR:
- The !$a! looks like a handle.
- The !o! handle has no suffix.
- The !h! handle wasn't declared.

# Assuming conventional resolution:
- "12"
- 12
- ! 12

Legend:
  c-ns-non-specific-tag

%YAML 1.1
---
!!seq [
  !<tag:yaml.org,2002:str> "12",
  !<tag:yaml.org,2002:int> "12",
  !<tag:yaml.org,2002:str> "12",
]

Node content may be presented in either a flow style or a block style. Block content always extends to the end of a line and uses indentation to denote structure, while flow content starts and ends at some non-space character within a line and uses indicators to denote structure. Each collection kind can be presented in a single flow collection style or a single block collection style. However, each collection kind also provides compact in-line forms for common cases. Scalar content may be presented in the plain style or one of the two quoted styles (the single quoted style and the double quoted style). Regardless of style, scalar content must always be indented by at least one space. In contrast, collection content need not be indented (note that the indentation of the first flow scalar line is determined by the block collection it is nested in, if any).

---
foo:
·"bar
·baz"
---
"foo
·bar"
---
foo
·bar
--- |
·foo
...

Legend:
  Normal "more-indented" indentation
  Mandatory for "non-indented" scalar

%YAML 1.1
---
!!map {
  ? !!str "foo"
  : !!str "bar baz"
}
%YAML 1.1
---
!!str "foo bar"
%YAML 1.1
---
!!str "foo bar"
%YAML 1.1
---
!!str "foo bar\n"

---
scalars:
  plain: !!str some text↓
  quoted:
    single: 'some text'↓
    double: "some text"↓
collections:
  sequence: !!seq [ !str entry,
    # Mapping entry:↓
      key: value ]↓
  mapping: { key: value }↓

Legend:
  ns-flow-scalar
  c-flow-collection
  not content

%YAML 1.1
--- !!map {
  ? !!str "scalars" : !!map {
      ? !!str "plain"
      : !!str "some text",
      ? !!str "quoted"
      : !!map {
        ? !!str "single"
        : !!str "some text",
        ? !!str "double"
        : !!str "some text"
  } },
  ? !!str "collections": : !!map {
    ? !!str "sequence" : !!seq [
      ? !!str "entry",
      : !!map {
        ? !!str "key" : !!str "value"
    } ],
    ? !!str "mapping": : !!map {
      ? !!str "key" : !!str "value"
} } }

block styles:
  scalars:
    literal: !!str |
      #!/usr/bin/perl
      print "Hello, world!\n";↓
    folded: >
      This sentence
      is false.↓
  collections: !!seq
    sequence: !!seq # Entry:↓
      - entry
      # Mapping entry:↓
      - key: value↓
    mapping: ↓
      key: value↓

Legend:
  c-l+block-scalar
  c-l-block-collection
  not content

%YAML 1.1
---
!!map {
  ? !!str "block styles" : !!map {
    ? !!str "scalars" : !!map {
      ? !!str "literal"
      : !!str "#!!/usr/bin/perl\n\
          print \"Hello,
          world!!\\n\";\n",
      ? !!str "folded"
      : !!str "This sentence
          is false.\n"
    },
    ? !!str "collections" : !!map {
      ? !!str "sequence" : !!seq [
        !!str "entry",
        !!map {
          ? !!str "key" : !!str "value"
        }
      ],
      ? !!str "mapping" : !!map {
        ? !!str "key" : !!str "value"
} } } }

Subsequent occurrences of a previously serialized node are presented as alias nodes, denoted by the “*” indicator. The first occurrence of the node must be marked by an anchor to allow subsequent occurrences to be presented as alias nodes. An alias node refers to the most recent preceding node having the same anchor. It is an error to have an alias node use an anchor that does not previously occur in the document. It is not an error to specify an anchor that is not used by any alias node. Note that an alias node must not specify any properties or content, as these were already specified at the first occurrence of the node.