YAML Ain't Markup Language (YAML™) 1.0

YAML streams use a 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 0x9F. On output, a YAML processor must only produce those acceptable characters, and should also escape all non-printable Unicode characters.

This character range explicitly excludes the surrogate block [#xD800-#xDFFF], DEL 0x7F, the C0 control block [#x0-#x1F], the C1 control block [#x80-#x9F], #xFFFE and #xFFFF. Note that in UTF-16, characters above #xFFFF are represented with a surrogate pair. When present, DEL and characters in the C0 and C1 control block must be represented in a YAML stream using escape sequences.

A YAML processor must support the UTF-16 and UTF-8 character encodings. If an input stream does not begin with a byte order mark, the encoding shall be UTF-8. UTF-16 (LE or BE) or UTF-8, as signaled by the byte order mark. Since YAML files may only contain printable characters, this does not raise any ambiguities. For more information about the byte order mark and the Unicode character encoding schemes see the Unicode FAQ.

Indicators are special characters that are used to describe the structure of a YAML document. In general, they cannot be used as the first character of a plain scalar.

The Unicode standard defines several line break characters. These line breaks can be grouped into two categories. Specific line breaks have well-defined semantics for breaking text into lines and paragraphs. Generic line breaks are not given meaning beyond “ending a line”.

Outside scalar text content, YAML allows any line break to be used to terminate lines, and in most cases also allows such line breaks to be preceded by trailing comment characters. On output, a YAML processor is free to emit such line breaks using whatever convention is most appropriate. YAML output should avoid using trailing line spaces.

This section includes several common character range definitions.

In a YAML character stream, structure is often determined from indentation, where indentation is defined as a line break character followed by zero or more space characters. With one notable exception, a node must be more indented than its parent node. All sibling nodes must use the exact same indentation level, however the content of each such node could be further indented. Indentation is used exclusively to delineate structure and is otherwise ignored; in particular, indentation characters must never be considered part of the document's content.

Tab characters are not allowed in indentation since different systems treat tabs differently. To maintain portability, YAML's tab policy is conservative; they shall not be used. Note that most modern editors may be configured so that pressing the tab key results in the insertion of an appropriate number of spaces.

Since the YAML stream depends upon indentation level to delineate blocks, many productions are a function of an integer, based on the i-spaces(n) production above. In some cases, the notations production(<n), production(≤n) and production(>n) are used; these are shorthands for “production(m) for some specific m such that m is less than/less than or equal/greater than n”, respectively. The notation production(any) is a shorthand for “production(m) for some specific value of m such that m ≥ 0”.

The “-” sequence entry, “?” complex key and “:” mapping entry indicators 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 a block sequence entry. For example:

a key in a mapping at indentation level 0:
# The value for this key is a block sequence.
- This sequence is also at indentation level 0.
-   Another entry in the sequence.
- # The value of this entry is a nested sequence.
 - This nested sequence must be
  indented at least to level 1.
 - Another entry in the nested sequence.
- Last entry in block sequence at indentation level 0.
second key in mapping: at indentation level 0.

In addition, in the special case when the value of a sequence entry or complex key:value pair is a block collection, and neither the nested block collection nor its first entry have any properties specified (tag or anchor), then this first entry may be specified in the same line as the indicator of the containing sequence entry. In this case both the indicator and any following spaces are counted as part of the indentation. For example:

- This sequence is not indented.
-   inline-map: further indented by four.
    this key: is also further indented by four.
    ? - nested sequence used as key
      - indented by eight spaces
    : nested map: used as value
      indented by: six spaces
-  - inline-seq; further indented by three.
   -    second entry in nested sequence.
- Last entry in top sequence.

Throwaway comments have no effect whatsoever on the document's representation graph. The usual purpose of a comment is to communicate between the human maintainers of the file. A typical example is comments in a configuration file.

A throwaway comment is marked by a “#” indicator and always spans to the end of a line. Comments can be indented on their own line, or may, in some cases, follow other syntax elements with leading spaces.

Outside text content, empty lines or lines containing only white space are taken to be implicit throwaway comment lines. Lines containing indentation followed by “#” and comment characters are taken to be explicit throwaway comment lines.

A throwaway comment may appear before a document's top level node or following any node. It may not appear inside a scalar node, but may precede or follow it.

###The first tree lines of this stream

## are comments (the second one is empty).
this: |   # Comments may trail block indicators.
    contains three lines of text.
    The third one starts with a
    # character. This isn't a comment.

# The last three lines of this stream
# are comments (the first line is empty).

A YAML stream may contain several independent YAML documents. A document header line may be used to start a document and must be used to separate documents within a stream. This line must start with a document separator: “---” followed by a line break or a sequence of space characters. If no explicit header line is specified at the start of the stream, the processor should behave as if a header line containing an unadorned “---” was specified.

When YAML is used as the format for a communication stream, it is useful to be able to indicate the end of a document independent of starting the next one without closing the data stream. 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 document. To support this scenario, a YAML document may be terminated by a “...” line. Nothing but throwaway comments may appear between this line and the (mandatory) header line of the following document.

Since “---” and “...” indicate document boundaries, these character strings are forbidden as content lines unless they are indented.

--- >
This YAML stream contains a single text value.
The next stream is a log file - a sequence of
log entries. Adding an entry to the log is a
simple matter of appending it at the end.

---
at: 2001-08-12 09:25:00.00 Z
type: GET
HTTP: '1.0'
url: '/index.html'
---
at: 2001-08-12 09:25:10.00 Z
type: GET
HTTP: '1.0'
url: '/toc.html'

# This stream is an example of a top-level mapping.
invoice : 34843
date    : 2001-01-23
total   : 4443.52

# A one-line alternative syntax for the above document.
{ invoice: 34843, date: 2001-01-23, total: 4443.52 }

# The following is a stream of three documents. TODO
# The first is an empty mapping, the second an
# empty sequence, and the last an empty string.
--- {}
--- [ ]
--- ''

# A communication channel based on a YAML stream.
---
sent at: 2002-06-06 11:46:25.10 Z
payload: Whatever
# Receiver can process this as soon as the following is sent:
...
# Even if the next message is sent long after:
---
sent at: 2002-06-06 12:05:53.47 Z
payload: Whatever
...

Directives are instructions to the YAML processor. Like throwaway comments, directives are not reflected in the document's representation graph. Directives apply to a single document. It is an error for the same directive to be specified more than once for the same document.

A presentation node begins at a particular level of indentation, n, and its content is indented at some level > n. A presentation node can be a collection, a scalar or an alias.

A YAML document is a normal node. However a document can't be an alias (there is nothing it may refer to). Also if the header line is omitted the first document must be a collection.

Each presentation node may have anchor and tag properties. These properties are specified in a properties list appearing before the node value itself. For a root node (a document), the properties appear in the document header line, following the directives (if any). It is an error for the same property to be specified more than once for the same node.

Tags can be presented in the character stream with the tag indicator, “!”. Unlike anchors, tags are part of the document's representation graph. The YAML processor is responsible for resolving tags which are not present in the character stream.

a string: '12'
another string: "12"
explicit string: !str 12
explicit integer: !int 12
implicit integer: 12

- !http://www.yaml.org/bing invalid
- !tag:yaml.org,2002:str
  

Only the tag shorthand is allowed in
a character stream, URIs, including
the taguri is forbidden.
  

# The following values have the same tag URI:
# 'tag:domain.tld,2002/a%3C%0A%25b'.
- !domain.tld,2002/a<\n%b value
- !domain.tld,2002/a\x3c\x0A%b value

# 'tag:domain.tld,2002:invoice' is some tag.
invoice: !domain.tld,2002/^invoice
  # 'seq' is shorthand for 'tag:yaml.org,2002:seq'.
  # This does not effect '^customer' below
  # because it is does not specify a prefix.
  customers: !seq
    # '^customer' is shorthand for the full notation
    # '!domain.tld,2002/customer' that stands for the
    # URI 'tag:domain.tld,2002:customer'.
    - !^customer
      given : Chris
      family : Dumars

An anchor is a property that can be used to mark a node for future reference. An alias node can then be used to indicate additional inclusions of an anchored node by specifying the node's anchor.

A sequence node is an ordered collection of sub-nodes, where each subordinate node has a higher indentation level. A flow style is available for short, simple sequences. For syntax compactness, if a sub-sequence node has no properties, and its first entry is specified without any properties, the sub-sequence may immediately follow the sequence entry indicator.

TODO: Talk about the single-key map.

empty: []
flow: [ one, two, three # May span lines,
         , four,        # indentation is
           five ]       # mostly ignored.
block:
- Note indicator is not indented.
-
 - Subordinate sequence entry (note must be indented).
 - Another entry in subordinate sequence
- - Another way to write a sub-sequence
  - Another entry in sub-sequence
- >
 A folded sequence entry (fifth entry)

A mapping node is an unordered association of unique keys with values. It is an error for two equal key entries to appear in the same mapping node. In such a case the processor may continue, ignoring the second key and issuing an appropriate warning. This strategy preserves a consistent information model for streaming and random access applications.

A flow form is available for short, simple mapping nodes. For syntax compactness, if a mapping node has no properties, and its first key is specified as a flow scalar without any properties, this first key may immediately follow the sequence entry indicator.

TODO: Talk about optional ':'.

empty: {}
null values: { one, two }
flow: { one: 1, two: 2 }
two equal maps in a sequence: [ key: value, { "key" : value } ]
spanning: { one: 1,
   two: 2 }
block:
 key : value
 nested mapping:
  key: Subordinate mapping
 nested sequence:
  - Subordinate sequence
!float 12 : This key is a float.
"\a" : This key had to be escaped.
? '?'
: This key had to be quoted.
? >
 This is a multi
 line folded key
: Whose value is
  also multi-line.
? This key has implicit null value
?
 - This key
 - is a sequence
: - With a sequence value.
? This: key
  is a: mapping
:
 with a: mapping value.
---
- A key: value pair in a sequence.
  A second: key:value pair.
- The previous entry is equal to the following one.
-
 A key:
     value pair in a sequence.
 A second:
     key:value pair.

Inside all scalar nodes, a compliant YAML processor must translate the two-character combination CR LF, any CR that is not followed by an LF, and any NEL into a single LF (this does not apply to escaped characters). LS and PS characters are preserved. These rules are compatible with Unicode's newline guidelines.

Normalization functionality is indicated by the use of the b-as-line-feed production defined below.

On output, a YAML processor is free to serialize end of line markers using whatever convention is most appropriate, though again LS and PS must be preserved.

Each block scalar may have explicit indentation and chomping modifiers. These modifiers are specified following the block style indicator. It is an error for the same modifier to be specified more than once for the same node.

Typically the indentation level of a block scalar node is detected from its first non-empty content line. This detection fails when this first non-empty line contains leading white space characters. Note that content lines, including the first non-empty content line, may begin with a “#” character.

When the first non-empty content line begins with spaces, YAML requires that the indentation level for the scalar node text content be given explicitly. This level is specified as the integer number of the additional indentation spaces used for the text content.

If the block scalar begins with lines containing only spaces, and no explicit indentation is given, the processor assumes such lines are empty lines. It is an error for any such leading empty line to contain more spaces than the indentation level that is deduced from the first non-empty content line.

The indentation level is always non-zero, except for the top level node of each document. This node is commonly indented by zero spaces (not indented). When the content is not indented, all lines up to the next document separator, document terminator, or end of the stream are assumed to be content lines, even if they begin with a “#” character. Note that in this case, all lines up to the next document seperator are assumed to be content lines, even if they begin with a “#” character.

It is always valid to specify an explicit indentation level, though a YAML processor should only do so in cases where detection fails. It is an error for detection to fail when there is no explicit indentation specified.

# Explicit indentation must be given
# in both the following cases.
leading spaces: |2
      This value starts with four spaces.

leading spaces after empty lines: |2

      This value starts with four spaces.

# The following is valid:
leading comment indicator: |

  # Content line starts with a '#'
  character, and follows empty lines.

# This is a comment because it is not
# more indented than the base level.
# Since blocks may not contain comments,
# this ends the block and the following
# empty line is not a content line.

# Explicit indentation may
# also be given when it is
# not required.
redundant: |2
  This value is indented 2 spaces.

# Indentation applies to top level nodes.
--- |
Usually top level nodes are not indented.
--- |
  This text is indented two spaces.
  It contains no leading spaces.
--- |0
  This text contains two leading spaces.
---
This text is not indented, so
# this is a content line and
--- |
  However, this is indented two spaces
# So this is a comment ending the block.

Typically the final line break of a block scalar is considered to be a part of its value, and any trailing empty lines are taken to be comment lines. This default clip chomping behavior can be overriden by specifying a chomp control modifier.

When this functionality is implied, the l-l-empty-trailing(n) production will be used.

clipped: |
    This has one newline.

same as "clipped" above: "This has one newline.\n"

stripped: |-
    This has no newline.

same as "stripped" above: "This has no newline."

kept: |+
    This has two newlines.

same as "kept" above: "This has two newlines.\n\n"

A literal scalar is the simplest scalar style. No processing is performed on literal scalar characters aside from end of line normalization and stripping away the indentation. Indentation is detected from the first non-empty content line. Explicit indentation must be specified in case this yields the wrong result.

Since escaping is not done, the literal style is restricted to printable characters and long lines cannot be wrapped. In exchange for these restrictions, literal scalars are the most readable format for source code or other text values with significant use of indicators, quotes, escape sequences, and line breaks.

empty: |

literal: |
 The \ ' " characters may be
 freely used. Leading white
    space is significant.

 Line breaks are significant. Thus this value
 contains one empty line and ends with a single
 line break, but does not start with one.

is equal to: "The \\ ' \" characters may \
 be\nfreely used. Leading white\n   space \
 is significant.\n\nLine breaks are \
 significant. Thus this value\ncontains \
 one empty line and ends with a single\nline \
 break, but does not start with one.\n"

# Comments may follow a block scalar value.
# They must be less indented.

# Modifiers may be combined in any order.
indented and chomped: |2-
    This has no newline.

also written as: |-2
    This has no newline.

both are equal to: "  This has no newline."

Folding supports scenarios where word-wrapping is useful for presentation, where the serialized content does not contain line breaks at convenient places. TODO: Rephrase.

When folding is done, a single normalized line feed is converted to a single space (#x20). When two or more consecutive (possibly indented) normalized line feeds are encountered, the processor does not convert them into spaces. Instead, the parser ignores the first line feed and preserves the rest. Thus a single line feed can be serialized as two, two line feeds can be serialized as three, etc. In this process, specific line breaks are preserved and may be safely used to convey text structure.

Since scalars come in both a block and flow variants, folding behavior must be defined in both contexts.

A folded scalar is similar to a literal scalar. However, unlike a literal scalar, a folded scalar is subject to (block) line folding. This allows long lines to be broken anywhere a space character (#x20) appears, at the cost of requiring an empty line to represent each line feed character.

empty: >

one paragraph: >
 Line feeds are converted to spaces,
 so this value contains no line
 breaks except for the final one.

multiple paragraphs: >2

  An empty line, either at
  the start or in the value:

  Is interpreted as a line
  break. Thus this value
  contains three line breaks.

indented text: >
    This is a folded paragraph
    followed by a list:
     * first entry
     * second entry
    Followed by another folded
    paragraph, another list:

     * first entry

     * second entry

    And a final folded
    paragraph.

above is equal to: |
    This is a folded paragraph followed by a list:
     * first entry
     * second entry
    Followed by another folded paragraph, another list:

     * first entry

     * second entry

    And a final folded paragraph.

# Explicit comments may follow
# but must be less indented.

The single quoted flow scalar style is indicated by surrounding “'” characters. Therefore, within a single quoted scalar such characters need to be escaped. No other form of escaping is done, limiting single quoted scalars to printable characters.

Single quoted scalars are subject to (flow) folding. This allows empty lines to be broken everywhere a single space character (#x20) separates non-space characters, at the cost of requiring an empty line to represent each line feed character.

empty: ''
second:
  '! : \ etc. can be used freely.'
third: 'a single quote '' must be escaped.'
span: 'this contains
      six spaces

      and one
      line break'
is same as: "this contains six spaces\nand one line break"

Escaping allows YAML scalar nodes to specify arbitrary Unicode characters, using C-style escape codes. Non-escaped nodes are restricted to printable Unicode characters.

An escaped line break is completely ignored.

The double quoted style variant adds escaping to the single quoted style variant. This is indicated by surrounding “"” characters. Escaping allows arbitrary Unicode characters to be specified at the cost of some verbosity: escaping the printable “\” and “"” characters. It is an error for a double quoted value to contain invalid escape sequences.

Like single quoted scalars, double quoted scalars may span multiple lines, resulting in a single space content character for each line break. If the line break is escaped, any white space preceding it is preserved, and the line break and any leading white space in the continuation line are discarded.

empty: ""
second: "! : etc. can be used freely."
third: "a \" or a \\ must be escaped."
fourth:
  "this value ends with an LF.\n"
span: "this contains
  four  \
      spaces"
is equal to: "this contains four  spaces"

The plain style variant is a restricted form of the single quoted style variant. As it has no identifying markers, it may not start or end with white space characters, may not start with most indicators, and may not contain certain indicators. Also, a plain scalar is subject to implicit typing. This can be avoided by providing a explicittag property.

Since it lacks identifying markers, the restrictions on a plain scalar depends on the context. There are three different such contexts, with increasing restrictions. Top level plain values are the least restricted plain scalar format. While they can't start with most indicators, they may contain any indicator except “ #” and “: ”. Plain scalars used in flow collections are further restricted not to contain flow indicators. Finally, plain keys are further restricted to a single line.

first: There is no unquoted empty string.
second: 12          ## This is an integer.
boolean: n          ## This is false.
third: !str 12      ## This is a string.
span: this contains
      six spaces

      and one
      line break

indicators: this has no comments.
            #:foo and bar# are
            both text.
flow: [ can span
           lines, # comment
             like
           this ]
note: { one-line keys: but
        multi-line values }