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

Copyright © 2001-2008 Oren Ben-Kiki, Clark Evans, Ingy döt Net

1. YAML is easily readable by humans.
2. YAML matches the native data structures of agile languages.
3. YAML data is portable between programming languages.
4. YAML has a consistent model to support generic tools.
5. YAML supports one-pass processing.
6. YAML is expressive and extensible.
7. YAML is easy to implement and use.

May

The word may, or the adjective optional, mean that conforming YAML processors are permitted, but need not behave as described.

Should

The word should, or the adjective recommended, mean that there could be reasons for a YAML processor to deviate from the behavior described, but that such deviation could hurt interoperability and should therefore be advertised with appropriate notice.

Must

The word must, or the term required or shall, mean that the behavior described is an absolute requirement of the specification.

YAML represents any native data structure using three node kinds: sequence - an ordered series of entries; mapping - an unordered association of unique keys to values; and scalar - 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 offers 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 the application, in general this process should be guided by the preferences of the user.

Figure 3.2. Information Models

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.

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.

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.7. Loading Failure Points

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 occurrence (using an anchor and alias nodes), tag resolution must depend only on the path to the first occurrence 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 referring 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.

e-

A production matching no characters.

c-

A production matching one or more characters starting and ending with a special (non-space) character.

b-

A production matching a single line break.

nb-

A production matching one or more characters starting and ending with a non-break character.

s-

A production matching one or more characters starting and ending with a space character.

ns-

A production matching one or more characters starting and ending with a non-space character.

X-Y-

A production matching a sequence of one or more characters, starting with an X- character and ending with a Y- character.

l-

A production matching one or more lines (shorthand for s-b-).

X+, X-Y+

A production as above, with the additional property that the indentation level used is greater than the specified n parameter.

Indentation: n or m

Since the character stream depends upon indentation level to delineate blocks, many productions are parameterized by it. In some cases, the notations “production(<n)”, “production(≤n)” and “production(>n)” are used; these are shorthands for “production(m)” for some specific m where 0 ≤ m < n, 0 ≤ m ≤ n and m > n, respectively.

Context: c

YAML supports two groups of contexts, distinguishing between block styles and flow styles. In the block styles, indentation is used to delineate structure. Due to the fact that the “-” character denoting a block sequence entry is perceived as an indentation character, some productions distinguish between the block-in context (inside a block sequence) and the block-out context (outside one). In the flow styles, explicit indicators are used to delineate structure. As plain scalars have no such indicators, they are the most context sensitive, distinguishing between being nested inside a flow collection (flow-in context) or being outside one (flow-out context). YAML also provides a terse and intuitive syntax for simple keys. Plain scalars in this (flow-key) context are the most restricted, for readability and implementation reasons.

(Scalar) Style: s

Scalar content may be presented in one of five styles: the plain, double-quoted and single-quotedflow styles, and the literal and foldedblock styles.

(Block) Chomping: t

Block scalars offer three possible mechanisms for chomping any trailing line breaks: strip, clip and keep.

Example 5.1. Byte Order Mark

⇔# Comment only.

Legend:
  c-byte-order-mark

# This stream contains no
# documents, only comments.

Example 5.2. Invalid Byte Order Mark

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

ERROR:
 A BOM must not appear
 inside a document.

Example 5.3. Block Structure Indicators

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",
  }
}

Example 5.4. Flow Collection Indicators

• An “#” (#23, octothorpe, hash, sharp, number sign) denotes a comment.

Example 5.5. Comment Indicator

# Comment only.

Legend:
  c-comment

# This stream contains no
# documents, only comments.

Example 5.6. Node Property Indicators

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,
}

Example 5.7. Block Scalar Indicators

literal: |
  text
folded: >
  text

Legend:
  c-literal
  c-folded

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

Example 5.8. Quoted Scalar Indicators

single: 'text'
double: "text"

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

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

Example 5.9. Directive Indicator

%YAML 1.1
--- text

Legend:
  c-directive

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

• The “@” (#40, at) and “`” (#60, grave accent) are reserved for future use.

Example 5.10. Invalid use of Reserved Indicators

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

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

Example 5.11. Line Break Characters

|
  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"

• An ignored space character outside scalar content. Such spaces are used for indentation and separation between tokens. To maintain portability, tab characters must not be used in these cases, since different systems treat tabs differently. Note that most modern editors may be configured so that pressing the tab key results in the insertion of an appropriate number of spaces.

Example 5.12. Invalid Use of Tabs

# 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.

Example 5.13. Tabs and Spaces

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

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

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

• A non space (and non-break) character:

• A decimal digit for numbers:

• An ASCII letter (alphabetic) character:

• A word (alphanumeric) character for identifiers:

• A URI character for tags, as specified in RFC2396 with the addition of the “[” and “]” for presenting IPv6 addresses as proposed in RFC2732. A limited form of 8-bit escaping is available using the “%” character. By convention, URIs containing 16 and 32 bit Unicode characters are encoded in UTF-8, and then each octet is written as a separate character.

• Escaped ASCII null (#x0) character:

• Escaped ASCII bell (#x7) character:

• Escaped ASCII backspace (#x8) character:

• Escaped ASCII horizontal tab (#x9) character:

• Escaped ASCII vertical tab (#xB) character:

• Escaped ASCII form feed (#xC) character:

• Escaped ASCII escape (#x1B) character:

• Escaped ASCII space (#x20) character:

• Escaped ASCII double quote (“"”):

• Escaped ASCII back slash (“\”):

• Escaped Unicode non-breaking space (#xA0) character:

• Escaped 8-bit Unicode character:

• Escaped 16-bit Unicode character:

• Escaped 32-bit Unicode character:

Example 5.14. Escaped Characters

"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"

Example 5.15. Invalid Escaped Characters

Bad escapes:
  "\c
  \xq-"

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

Example 6.1. Indentation Spaces

··# 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",
        ]
    }
}

Example 6.2. Comment Lines

··# Comment↓
···↓
↓

# This stream contains no
# documents, only comments.

Legend:
  c-b-comment l-comment

Example 6.3. Comments Ending a Line

Example 6.4. Multi-Line Comments

• YAML usually allows separation spaces to include a comment ending the line and additional comment lines. Note that the token following the separation comment lines must be properly indented, even though there is no such restriction on the separation comment lines themselves.

• Inside simple keys, however, separation spaces are confined to the current line.

Example 6.5. Separation Spaces

{·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"
  }
}

• Plain scalars must not contain any tab characters, and all leading spaces are always discarded.

• Quoted scalars may contain tab characters. Again, all leading white space is always discarded.

Example 6.6. Ignored Prefix

Example 6.7. Empty Lines

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

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

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

Example 6.8. Line Folding

Block Folding

In the folded block style, folding does not apply to line breaks or empty lines that precede or follow a text line containing leading white space. Note that such a line may consist of only such leading white space; an emptyblock line is confined to (optional) indentation spaces only. Further, the final line break and empty lines are subject to chomping, and are never folded. The combined effect of these rules is that each “paragraph” is interpreted as a line, empty lines are used to present a line feed, the formatting of “more indented” lines is preserved, and final line breaks may be included or excluded from the node’s content information as appropriate.

Flow Folding

Folding in flow styles provides more relaxed, less powerful semantics. Flow styles typically depend on explicit indicators to convey structure, rather than indentation. Hence, in flow styles, spaces preceding or following the text in a line are a presentation detail and must not be considered a part of the node’s content information. Once all such spaces have been discarded, folding proceeds as described above. In contrast with the block folded style, all line breaks are folded, without exception, and a line consisting only of spaces is considered to be an empty line, regardless of the number of spaces. The combined effect of these processing rules is that each “paragraph” is interpreted as a line, empty lines are used to present a line feed, and text can be freely “more indented” without affecting the node’s content information.

Example 7.1. Reserved Directives

The “YAML” directive specifies the version of YAML the document adheres to. This specification defines version “1.1”. A version 1.1 YAML processor should accept documents with an explicit “%YAML 1.1” directive, as well as documents lacking a “YAML” directive. Documents with a “YAML” directive specifying a higher minor version (e.g. “%YAML 1.2”) should be processed with an appropriate warning. Documents with a “YAML” directive specifying a higher major version (e.g. “%YAML 2.0”) should be rejected with an appropriate error message.

It is an error to specify more than one “YAML” directive for the same document, even if both occurrences give the same version number.

%YAML 1.1
%YAML 1.1
foo

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

The “TAG” directive establishes a shorthand notation for specifying node tags. Each “TAG” directive associates a handle with a prefix, allowing for compact and readable tag notation.

It is an error to specify more than one “TAG” directive for the same handle in the same document, even if both occurrences give the same 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> "baz",
  !<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

Example 7.9. Document Boundary Markers

---↓
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

Example 7.11. Empty Stream

⇔# A stream may contain
# no documents.

Legend:
  l-yaml-stream

# This stream contains no
# documents, only comments.

Example 7.12. First Document

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

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

Legend:
  l-first-document

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

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

Example 7.13. Next Documents

! "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

Example 8.2. Node Anchors

First occurrence: &anchor Value
Second occurrence: *anchor

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

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

Verbatim Tags

A tag may be written verbatim by surrounding it with the “<” and “>” characters. In this case, the YAML processor must deliver the verbatim tag as-is to the application. In particular, verbatim tags are not subject to tag resolution. A verbatim tag must either begin with a “!” (a local tag) or be a valid URI (a global tag).

Example 8.3. Verbatim Tags

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

Legend:
  c-verbatim-tag

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

Example 8.4. Invalid Verbatim Tags

- !<!> 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 “!”.

Example 8.5. Tag Shorthands

%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",
]

Example 8.6. Invalid Shorthand Tags

%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.

Example 8.7. Non-Specific Tags

# 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",
]

Example 8.8. Mandatory Scalar Indentation

---
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"

Example 8.9. Flow Content

---
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"
} } }

Example 8.10. Block Content

block styles:
  scalars:
    literal: !!str |
      #!/usr/bin/perl
      print "Hello, world!\n";↓
    folded: >
      This sentence
      is false.↓
  collections: !!seq
    sequence: !!seq # Entry:↓
      - entry # Plain
      # 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"
} } } }

Example 8.11. Alias Nodes

First occurrence: &anchor Value
Second occurrence: *anchor

Legend:
  c-ns-alias-node
  ns-anchor-name

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

A complete flow node is either an alias node presenting a second occurrence of a previous node, or consists of the node properties followed by the node’s content. A node with empty content is considered to be an empty plain scalar.

[
  Without properties,
  &anchor "Anchored",
  !!str 'Tagged',
  *anchor, # Alias node
  !!str,   # Empty plain scalar
]

Legend:
  ns-flow-node(n,c) ns-flow-content(n,c)

%YAML 1.1
---
!!seq [
  !!str "Without properties",
  &A !!str "Anchored",
  !!str "Tagged",
  *A,
  !!str "",
]

Since both the node’s properties and node content are optional, this allows for a completely empty node. Completely empty nodes are only valid when following some explicit indicator for their existence.

In the examples, completely empty nodes are displayed as the glyph “°”. Note that this glyph corresponds to a position in the characters stream rather than to an actual character.

{
  ? foo :°,
  ?° : bar,
}

Legend:
  e-empty-flow

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

A complete block node consists of the node’s properties followed by the node’s content. In addition, a block node may consist of a (possibly completely empty) flow node followed by a line break (with optional comments).

A block node always spans to the end of the line, even when completely empty. Completely empty block nodes may only appear when there is some explicit indicator for their existence.

seq:
-° # Empty plain scalar↓
- ? foo
  :°↓
  ?°↓
  : bar,

Legend:
  s-l-empty-block

%YAML 1.1
---
!!seq [
  !!str "",
  !!map {
    ? !!str "foo"
    : !!str "",
    ? !!str "",
    : !!str "bar",
  }
]

Flow sequence content is denoted by surrounding “[” and “]” characters.

Sequence entries are separated by a “,” character.

The final entry may omit the “,” character. This does not cause ambiguity since sequence entries must not be completely empty.

- [ inner, inner, ]
- [inner,last]

Legend:
  c-sequence-start c-sequence-end
  ns-s-flow-seq-inner(n,c)
  ns-s-flow-seq-last(n,c)

%YAML 1.1
---
!!seq [
  !!seq [
    !!str "inner",
    !!str "inner",
  ],
  !!seq [
    !!str "inner",
    !!str "last",
  ],
]

Any flow node may be used as a flow sequence entry. In addition, YAML provides a compact form for the case where a flow sequence entry is a mapping with a single key: value pair, and neither the mapping node nor its single key node have any properties specified.

[
"double
 quoted", 'single
           quoted',
plain
 text, [ nested ],
single: pair ,
]

Legend:
  ns-flow-node(n,c)
  ns-s-flow-single-pair(n,c)

%YAML 1.1
---
!!seq [
  !!str "double quoted",
  !!str "single quoted",
  !!str "plain text",
  !!seq [
    !!str "nested",
  ],
  !!map {
    ? !!str "single"
    : !!str "pair"
  }
]

A block sequence is simply a series of entries, each presenting a single node.

block: # Block
       # sequence↓
- one↓
- two : three↓

Legend:
  c-l-comments
  l-block-seq-entry(n,c)

%YAML 1.1
---
!!map {
  ? !!str "block"
  : !!seq [
    !!str "one",
    !!map {
      ? !!str "two"
      : !!str "three"
    }
  ]
}

Each block sequence entry is denoted by a leading “-” indicator, separated by spaces from the entry node.

People read the “-” character as part of the indentation. Hence, block sequence entries require one less space of indentation, unless the block sequence is nested within another block sequence (hence the need for the block-in context and block-out context).

The entry node may be either completely empty, a normal block node, or use a compact in-line form.

The compact in-line form may be used in the common case when the block sequence entry is itself a block collection, and neither the collection entry nor its first nested node have any properties specified. In this case, the nested collection may be specified in the same line as the “-” character, and any following spaces are considered part of the in-line nested collection’s indentation.

An in-line block sequence begins with an indented same-line sequence entry, followed by optional additional normal block sequence entries, properly indented.

- # Empty
- |
 block node
-·- one # in-line
··- two # sequence
- one: two # in-line
           # mapping

Legend:
  s-l-empty-block
  s-l+block-node(n,c)
  s-l+block-in-line(n)

%YAML 1.1
---
!!seq [
  !!str "",
  !!str "block node\n",
  !!seq [
    !!str "one",
    !!str "two",
  ]
  !!map {
    ? !!str "one"
    : !!str "two",
  }
]

Flow mapping content is denoted by surrounding “{” and “}” characters.

Mapping entries are separated by a “,” character.

The final entry may omit the “,” character. This does not cause ambiguity since mapping entries must not be completely empty.

Flow mappings allow two forms of keys: explicit and simple.

{
?° : value # Empty key
? explicit
 key: value,
simple key : value
[ collection, simple, key ]: value
}

Legend:
  c-s-flow-explicit-key(n,c)
  ns-s-flow-simple-key(n,c)

%YAML 1.1
---
!!map {
  ? !!str ""
  : !!str "value",
  ? !!str "explicit key"
  : !!str "value",
  ? !!str "simple key"
  : !!str "value",
  ? !!seq [
    !!str "collection",
    !!str "simple",
    !!str "key"
  ]
  : !!str "value"
}

{
multi-line
 simple key : value,
very long ...(>1KB)... key: value
}

ERROR:
- A simple key is restricted
  to only one line.
- A simple key must not be
  longer than 1024 characters.

Flow mappings also allow two forms of values, explicit and completely empty.

{
key : value,
empty:° # empty value↓
}

Legend:
  c-s-flow-explicit-value(n,c)

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

Thus, there are four possible combinations for a flow mapping entry:

Inside flow mappings, all four combinations may be used.

{
? explicit key1 : Explicit value,
? explicit key2 :° , # Explicit empty
? explicit key3,     # Empty value
simple key1 : explicit value,
simple key2 :° ,     # Explicit empty
simple key3,         # Empty value
}

Legend:
  c-s-flow-explicit-explicit(n,c)
  c-s-flow-explicit-empty(n,c)
  ns-s-flow-simple-explicit(n,c)
  ns-s-flow-simple-empty(n,c)

%YAML 1.1
---
!!map {
  ? !!str "explicit key1"
  : !!str "explicit value",
  ? !!str "explicit key2"
  : !!str "",
  ? !!str "explicit key3"
  : !!str "",
  ? !!str "simple key1"
  : !!str "explicit value",
  ? !!str "simple key2"
  : !!str "",
  ? !!str "simple key3"
  : !!str "",
}

YAML also allows omitting the surrounding “{” and “}” characters when nesting a flow mapping in a flow sequence if the mapping consists of a single key: value pair and neither the mapping nor the key have any properties specified. In this case, only three of the combinations may be used, to prevent ambiguity.

[
? explicit key1 : explicit value,
? explicit key2 :° , # Explicit empty
? explicit key3,     # Implicit empty
simple key1 : explicit value,
simple key2 :° ,     # Explicit empty
]

Legend:
  c-s-flow-explicit-explicit(n,c)
  c-s-flow-explicit-empty(n,c)
  ns-s-flow-simple-explicit(n,c)

%YAML 1.1
---
!!seq [
  !!map {
    ? !!str "explicit key1"
    : !!str "explicit value",
  },
  !!map {
    ? !!str "explicit key2"
    : !!str "",
  },
  !!map {
    ? !!str "explicit key3"
    : !!str "",
  },
  !!map {
    ? !!str "simple key1"
    : !!str "explicit value",
  },
  !!map {
    ? !!str "simple key2"
    : !!str "",
  },
]

A Block mapping is simply a series of entries, each presenting a key: value pair.

A block mapping entry may be presented using either an explicit or a simple key.

plain key:° # empty value↓
"quoted key":↓
- one # explicit next-line
- two # block value↓

Legend:
  ns-block-simple-key(n)
  s-l+block-simple-value(n)

%YAML 1.1
---
!!map {
  ? !!str "plain key"
  : !!str "",
  ? !!str "quoted key\n"
  : !!seq [
    !!str "one",
    !!str "two",
  ]
}

An in-line block mapping begins with a same-line mapping entry, followed by optional additional normal block mapping entries, properly indented.

- sun: yellow↓
- ? earth: blue↓
  : moon: white↓

Legend:
  ns-l-in-line-mapping(n)

%YAML 1.1
---
!!seq {
  !!map {
    ? !!str "sun"
    : !!str "yellow",
  },
  !!map {
    ? !!map {
      ? !!str "earth"
      : !!str "blue"
    }
    : !!map {
      ? !!str "moon"
      : !!str "white"
    }
  }
}