YAML Ain't Markup Language (YAML™) 1.0

3.1.1 Character Set

YAML streams use a subset of the Unicode character set. A YAML parser must accept all printable ASCII characters, the space, tab, line break, and all Unicode characters beyond 0x9F. A YAML emitter must only produce those characters accepted by the parser, but should also escape all non-printable Unicode characters if a character table is readily available.

c-printable ::=
    #x9 | #xA | #xD
  | [#x20-#x7E] | #x85
  | [#xA0-#xD7FF]
  | [#xE000-#xFFFD]
  | [#x10000-#x10FFFF] 

The range above 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. DEL and characters in the C0 and C1 control block may be represented in a YAML stream using escape sequences.

3.1.2 Encoding

A YAML parser is required to support the UTF-32, 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. Otherwise the encoding shall be UTF-32 (LE or BE), UTF-16 (LE or BE) or UTF-8, as signaled by the byte order mark. Note that as 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.

c-byte-order-mark ::= #xFEFF 

3.1.3 Indicators

Indicators are special characters that are used to describe the structure of a YAML document.

c-sequence-entry ::= '-' 

c-mapping-entry ::= ':' 

c-sequence-start ::= '[' 

c-sequence-end ::= ']' 

c-mapping-start ::= '{' 

c-mapping-end ::= '}' 

c-collect-entry ::= ',' 

c-top-key ::= '?' 

c-alias ::= '*' 

c-anchor ::= '&' 

c-transfer ::= '!' 

c-literal ::= '|' 

c-folded ::= '>' 

c-single-quote ::= ''' 

c-double-quote ::= '"' 

c-throwaway ::= '#' 

c-directive ::= '%' 

c-reserved ::= '@' | '`' 

3.1.4 Line Breaks

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. The semantics of generic line break characters is not defined beyond "ending a line".

b-line-feed ::= #xA 

b-carriage-return ::= #xD 

b-next-line ::= #x85 

b-line-separator ::= #x2028 

b-paragraph-separator ::= #x2029 

b-char ::=
    b-line-feed
  | b-carriage-return
  | b-next-line
  | b-line-separator
  | b-paragraph-separator 

b-generic ::=
    ( b-carriage-return
      b-line-feed )greedy
  | b-carriage-return
  | b-line-feed
  | b-next-line 

b-specific ::=
    b-line-separator
  | b-paragraph-separator 

b-any ::=
  b-generic | b-specific 

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 emitter is free to emit such line breaks using whatever convention is most appropriate. An emitter should avoid emitting trailing line spaces.

3.1.5 Miscellaneous

This section includes several common character range definitions.

nb-char ::= c-printable - b-char 

s-char ::= #x9 | #x20 

ns-char ::= nb-char - s-char 

ns-ascii-letter ::=
  [#x41-#x5A] | [#x61-#x7A] 

ns-decimal-digit ::= [#x30-#x39] 

ns-hex-digit ::=
    ns-decimal-digit
  | [#x41-#x46] | [#x61-#x66] 

ns-word-char ::=
    ns-decimal-digit
  | ns-ascii-letter | '-' 

3.2.1 Indentation

In a YAML text representation, structure is determined from indentation, where indentation is defined as a line break character followed by zero or more space characters.

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

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 may be indented independently.

The indentation level is used exclusively to delineate structure. Indentation characters are otherwise ignored. In particular, they are never taken to be a part of the the serialized text.

i-spaces(n) ::= #x20 x n 

i-spaces(<n) ::= i-spaces(m) 

i-spaces(<=n) ::= i-spaces(m) 

Since the YAML stream depends upon indentation level to delineate blocks, additional productions are a function of an integer, based on the i-spaces(n), i-spaces(<n) and i-spaces(<=n) productions above. In some cases the notation production(any) is used; it is a shorthand for "production(n) for some specific of n such that n >= 0".

The '-' sequence entry indicator is perceived by people to be part of the indentation. Hence the indentation rules are slightly more flexible when dealing with this indicator. 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 is a block collection, and neither the nested block collection nor its first entry have any properties specified (type family 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 '-' and any following spaces are counted as part of the indentation. For example:

- This sequence is not indented.
-   map-in-seq: further indented by four.
    this key: is also further indented by four.
-  - seq-in-seq; further indented by three.
   -    second entry in nested sequence.
- Last entry in top sequence. 

3.2.2 Throwaway comments

Throwaway comments have no effect whatsoever on the data serialized in the stream. Their usual purpose is to communicate between the human maintainers of the file. A typical example is comments in a configuration file.

A throwaway comment always spans to the end of a line. It consists of white spaces, optionally followed by a '#' indicator and arbitrary comment characters to the end of the line.

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 node or following any node. It may not appear inside a scalar node, but may precede or follow it.

c-nb-throwaway-comment ::=
  c-throwaway nb-char* 

l-comment(n) ::=
    l-empty-comment(n)
  | l-text-comment(n) 

l-empty-comment(n) ::=
  i-spaces(<=n) b-any 

l-text-comment(n) ::=
  i-spaces(<n)
  c-nb-throwaway-comment
  b-any 

s-b-trailing-comment ::=
  ( s-char+
    c-nb-throwaway-comment? )?
  b-any 

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

3.3.1 Document

A YAML stream may contain several independent YAML documents. A document header line is used to start a new document. 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 parser 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 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.

ns-ns-document-header ::=
  ns-ns-document-start
  ( s-char+ c-ns-directive )* 

ns-ns-document-start ::= '-' '-' '-' 

l-l-after-document ::=
  ns-ns-document-end b-any
  l-comment(any)* 

ns-ns-document-end ::= '.' '.' '.' 

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

3.3.2 Directive

Directives are instructions to the YAML parser. Like throwaway comments, directives are not reflected in the data serialized in the stream. Directives apply to a single document. It is an error for the same directive to be specified more than once for the same document.

c-ns-directive ::=
  c-directive ns-ns-directive-name
  c-mapping-entry ns-ns-directive-value 

ns-ns-directive-name ::=
  ( ns-char - c-mapping-entry )+ 

ns-ns-directive-value ::= ns-char+ 

This version of YAML defines a single directive, %YAML. Additional directives may be added in future versions of YAML. A parser should ignore unknown directives with an appropriate warning. There is no provision for specifying private directives. This is intentional.

The %YAML directive specifies the version of YAML the document adheres to. This specification defines version 1.0.

A version 1.0 parser should accept documents with an explicit %YAML:1.0 directive, as well as documents lacking a %YAML directive. Documents with a directive specifying a higher minor version (e.g. %YAML:1.1) should be processed with an appropriate warning. Documents with a directive specifying a higher major version (e.g. %YAML:2.0) should be rejected with an appropriate error message.

3.3.3 Text Node

A text node begins at a particular level of indentation, n, and its content is indented at some level >n. A text node can be a collection (mapping or sequence), a scalar (block or flow) 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.

s-l-top-value-node(n) ::=
    s-l-top-alias-node
  | s-l-top-collect-node(n)
  | s-l-top-scalar-node(n) 

ns-ns-flow-value-node(n) ::=
    ns-ns-alias
  | c-c-flow-collect-node(n)
  | ns-ns-flow-scalar-value-node(n) 

ns-s-top-key-node(n) ::=
    ( c-top-key s-l-top-value-node(>n)
      i-spaces(n) )
  | ( ns-ns-flow-key-node(n) s-char* ) 

ns-ns-flow-key-node(n) ::=
    ns-ns-alias
  | c-c-flow-collect-node(n)
  | ns-ns-flow-scalar-key-node(n) 

s-l-top-alias-node ::=
  s-char ns-ns-alias
  s-b-trailing-comment
  l-comment(any)* 

l-l-top-flow-collect-node(n) ::=
  i-spaces(n)
  c-c-flow-collect-node(n)
  s-b-trailing-comment
  l-comment(any)* 

s-l-top-collect-node(n) ::=
    s-l-blk-collect-node(n)
  | ( s-s-required(n)
      c-c-flow-collect-node(n)
      s-b-trailing-comment
      l-comment(any)* ) 

s-l-blk-collect-node(n) ::=
  ( s-char+ c-ns-collect-properties )?
  s-b-trailing-comment
  l-comment(any)*
  l-l-blk-collection(n) 

c-c-flow-collect-node(n) ::=
  ( c-ns-collect-properties s-char+ )?
  c-c-flow-collection(n) 

s-l-top-scalar-node(n) ::=
    s-l-blk-scalar-node(n)
  | ( s-s-required(n)
      ns-ns-top-scalar-value-node(n)
      s-b-trailing-comment
      l-comment(any)* ) 

s-l-blk-scalar-node(n) ::=
  ( s-char+ c-ns-scalar-properties )?
  s-char+ c-l-blk-scalar(n) 

ns-ns-top-scalar-value-node(n) ::=
  ( c-ns-scalar-properties s-char+ )?
  ns-ns-top-scalar-value(n) 

ns-ns-flow-scalar-value-node(n) ::=
  ( c-ns-scalar-properties s-char+ )?
  ns-ns-flow-scalar-value(n) 

ns-ns-flow-scalar-key-node(n) ::=
  ( c-ns-scalar-properties s-char+ )?
  ns-ns-flow-scalar-key(n) 

3.3.4 Node Property

Each text node may have anchor and transfer method properties. These properties are specified in a properties list appearing before the node value itself. For a top-level 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.

c-ns-collect-properties ::=
    ( c-ns-collect-transfer
      ( s-char+ c-ns-anchor-property )? )
  | ( c-ns-anchor-property
      ( s-char+ c-ns-collect-transfer )? ) 

c-ns-scalar-properties ::=
    ( c-ns-scalar-transfer
      ( s-char+ c-ns-anchor-property )? )
  | ( c-ns-anchor-property
      ( s-char+ c-ns-scalar-transfer )? ) 

3.3.5 Transfer Method

The transfer method property specifies how to load the associated node. It includes the type family for the node and, for global scalar type families, an optional specific format used, separated by a '#' character.

Like throwaway comments and directives, formats are not reflected in the data serialized in the stream. In contrast, the type family is considered to be part of this data.

implicit integer type family: 12
also implicit integer family: ! "12"
explicit integer, implicit format: !int 12
also implicit format: !int# 0x12
explicit format: !int#dec 0x12 

# The following values have the same type family.
- !domain.tld,2002/type\x30 value
- !domain.tld,2002/type0 value 

# The following are different as far as YAML is concerned.
- !domain.tld,2002/type%30 value
- !domain.tld,2002/type0 value 

# 'taguri:domain.tld,2002:invoice' is some type family.
invoice: !domain.tld,2002/^invoice
  # 'seq' is shorthand for 'taguri: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 'taguri:domain.tld,2002:customer'.
    - !^customer
      given : Chris
      family : Dumars 

c-prefix ::= '^' 

c-format ::= '#' 

ns-transfer-char ::=
    ns-esc-sequence
  | ( ns-char - c-escape - c-format ) 

ns-mundane-transfer-char ::=
  ns-transfer-char - ':' - '/' 

c-ns-collect-transfer ::=
  c-transfer
  ( /* empty (implicit) */
  | ns-ns-transfer-family
  | ( prefix-of-above?
      c-prefix
      suffix-of-above ) ) 

c-ns-scalar-transfer ::=
  c-transfer
  ( /* empty (implicit) */
  | ns-ns-transfer-family
  | ns-ns-transfer-format
  | ( prefix-of-above?
      c-prefix
      suffix-of-above ) ) 

ns-ns-transfer-family ::=
  c-ns-private-family
  ns-ns-global-family 

ns-ns-transfer-format ::=
  ns-ns-transfer-family
  c-format ns-ns-format 

c-ns-private-family ::=
  c-transfer ns-transfer-char+ 

ns-ns-global-family ::=
    ns-ns-core-family
  | ns-ns-vocabulary-family
  | ns-ns-domain-family 

ns-ns-format ::= ns-transfer-char* 

ns-ns-core-family ::=
  ( ns-mundane-transfer-char
  - c-transfer )
  ns-mundane-transfer-char* 

ns-ns-vocabulary-family ::=
  ns-word-char+ '/' ns-transfer-char* 

ns-ns-domain-family ::=
  ns-word-char+
  ( '.' ns-word-char )
  ',' ns-ns-domain-year
  ( '-' ns-ns-domain-day-month
    ( '-' ns-ns-domain-day-month )? )?
  '/' ns-transfer-char* 

ns-ns-domain-year ::=
  ns-decimal-digit x 4 

ns-ns-domain-day-month ::=
  ns-decimal-digit x 2 

3.3.6 Anchor

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.

c-ns-anchor-property ::=
  c-anchor ns-ns-anchor-name 

ns-ns-anchor-name ::= ns-char+ 

3.5.1 Sequence

A sequence node is the simplest node kind. It is a an ordered collection of sub-nodes at a higher indentation level. A flow style is available for short, simple sequences. Also, if a sub-sequence node has no properties, and its first entry is specified without any properties, the sub-sequence node may immediately follow the sequence entry indicator.

l-l-blk-sequence(n) ::=
  ( i-spaces(n[-1])
    c-l-blk-seq-entry(n[-1]) )+ 

c-l-blk-seq-entry(n) ::=
  c-sequence-entry
  ( s-l-top-value-node(>n)
  | i-l-seq-in-seq(n)
  | i-l-map-in-seq(n) ) 

i-l-seq-in-seq(n) ::=
  i-spaces(m)
  c-l-blk-seq-entry(n+m+1)
  l-l-blk-sequence(n+m+1)? 

c-c-flow-sequence(n) ::=
  c-sequence-start
  s-s-optional(n)
  ( ns-ns-flow-value-node(n)
    s-s-optional(n)
    ( c-collect-entry
      s-s-required(n)
      ns-ns-flow-value-node(n)
      s-s-optional(n) )* )?
  c-sequence-end 

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) 

3.5.2 Mapping

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. Also, 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.

l-l-blk-mapping(n) ::=
  ( i-spaces(n)
    ns-l-blk-map-entry(n) )+ 

i-l-map-in-seq(n) ::=
  i-spaces(m)
  ns-ns-flow-scalar-key(n+m+1)
  s-char*
  c-mapping-entry
  s-l-top-value-node(>n+m+1)
  l-l-blk-mapping(n+m+1)? 

ns-l-blk-map-entry(n) ::=
  ns-s-top-key-node(n)
  c-mapping-entry
  s-l-top-value-node(>n) 

c-c-flow-mapping(n) ::=
  c-mapping-start
  s-s-optional(n)
  ( ns-ns-flow-map-entry(n)
    s-s-optional(n)
    ( c-collect-entry
      s-s-required(n)
      ns-ns-flow-map-entry(n)
      s-s-optional(n) )* )?
  c-mapping-end 

ns-ns-flow-map-entry(n) ::=
  ns-ns-flow-key-node(n)
  s-char*
  c-mapping-entry
  s-s-required(n)
  ns-ns-flow-value-node(n) 

empty: {}
flow: { one: 1, two: 2 }
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 also works as a key
: with a value at the next line.
?
 - 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. 

3.6.1 End Of line Normalization

Inside all scalar nodes, a compliant YAML parser 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.

b-as-line-feed ::= b-generic 

b-normalized ::=
  b-as-line-feed | b-specific 

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

3.6.2 Block Modifiers

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.

ns-ns-blk-modifiers ::=
    ( ns-explicit-indent
      c-chomp-control? )
  | ( c-chomp-control
      ns-explicit-indent? ) 

3.6.3 Explicit Indentation

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 parser 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). 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 emitters should not do so in cases where detection succeeds. It is an error for detection to fail when there is no explicit indentation specified.

ns-explicit-indent ::= ns-decimal-digit 

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

3.6.4 Chomping

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.

c-chomp-control ::=
    c-strip-chomp
  | c-keep-chomp 

c-strip-chomp ::= '-' 

c-keep-chomp ::= '+' 

strip ('-')

The '-' chomp control specifies that the final line break character of the block scalar should be stripped from its value.

keep ('+')

The '+' chomp control specifies that any trailing empty lines following the block scalar should be considered to be a part of its value. If this modifier is not specified, such lines are considered to be empty throwaway comment lines and are ignored.

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

l-l-empty-trailing(n) ::=
    l-empty-comment(n)+
  | l-blk-empty-line-feed(n)+ 

l-blk-empty-line-feed(n) ::=
  i-spaces(<=n) b-as-line-feed 

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" 

3.6.5 Literal

A literal scalar is the simplest scalar form. 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 content line. Explicit indentation must be specified in case this yields the wrong result.

This restricts literal scalars to printable characters only. Also, long lines can't be broken. In exchange for these restrictions, a literal scalar may use any printable character, including line breaks. This makes literal scalars the most readable format for source code or other text values with significant use of indicators, quotes, escape sequences, and line breaks.

c-l-literal(n) ::=
  c-literal
  ns-ns-blk-modifiers?
  s-b-trailing-comment
  l-l-literal-value(n)?
  l-l-empty-trailing(n)?
  ( l-text-comment(<n)
    l-comment(any)* )? 

l-l-literal-value(n) ::=
  l-l-literal-chunk(n)+ 

l-l-literal-chunk(n) ::=
  l-blk-empty-line-feed(n)*
  ( l-literal-text(n)
  | l-blk-empty-specific(n) ) 

l-blk-empty-specific(n) ::=
  i-spaces(<=n) b-specific 

l-literal-text(n) ::=
  i-spaces(n) nb-char+ b-normalized 

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

3.6.6 Folding

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 parser does not convert them into spaces. Instead, the parser ignores the first of the line feeds and preserves the rest. Thus a single line feed can be serialized as two, two line feeds can be serialized as three, etc.

When folding is done, specific line breaks are preserved and may be safely used to convey text structure.

b-as-space ::= b-generic 

b-ignored ::= b-generic 

b-l-blk-trimmed(n) ::=
  b-ignored
  l-blk-empty-line-feed(n)+ 

i-s-ignored-leading(n) ::=
  i-spaces(n) s-char+ 

s-s-ignored-trailing ::= s-char+ 

l-flow-empty-specific(n) ::=
  ( i-spaces(<=n)
  | i-s-ignored-leading(n) )
  b-specific 

l-flow-empty-line-feed(n) ::=
  ( i-spaces(<=n)
  | i-s-ignored-leading(n) )
  b-as-line-feed 

b-l-flow-trimmed(n) ::=
  b-ignored
  l-flow-empty-line-feed(n)+ 

s-l-end-flow-line(n) ::=
  s-s-ignored-trailing
  ( b-as-space
  | b-l-flow-trimmed(n)
  | b-specific ) 

3.6.7 Folded

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.

c-l-folded(n) ::=
  c-folded
  ns-ns-blk-modifiers
  s-b-trailing-comment
  l-l-folded-value(n)?
  l-l-empty-trailing(n)?
  ( l-text-comment(<n)
    l-comment(any)* )? 

l-l-folded-value(n) ::=
  l-blk-empty-line-feed(n)*
  ( l-l-folded-chunk(n)
  | l-l-non-folded-chunk(n) ) 

l-l-folded-chunk(n) ::=
  ( i-nb-folded-paragraph(n)
    b-l-blk-trimmed(n) )*
  i-nb-folded-paragraph(n)
  b-l-after-folded-chunk(n) 

i-nb-folded-paragraph(n) ::=
  ( i-nb-folded-text(n)
    b-as-space )*
  i-nb-folded-text(n) 

i-nb-folded-text(n) ::=
  i-spaces(n) ns-char nb-char* 

b-l-after-folded-chunk(n) ::=
  b-normalized
  ( l-blk-empty-line-feed(n)*
    l-l-non-folded-chunk(n) )? 

l-l-non-folded-chunk(n) ::=
  ( l-empty-non-folded(n)
  | l-indented-non-folded(n) )
  l-l-folded-value(n)? 

l-empty-non-folded(n) ::=
  i-spaces(<=n) b-specific 

l-indented-non-folded(n) ::=
  i-spaces(n) s-char nb-char*
  b-normalized 

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. 

3.6.8 Single Quoted

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.

c-c-single-quoted(n) ::=
  c-single-quote
  nb-nb-single-quoted-value(n)?
  c-single-quote 

nb-nb-single-quoted-value(n) ::=
    nb-nb-one-single-line
  | ( nb-l-first-single-line(n)
      l-l-inner-single-line(n)*
      i-nb-last-single-line(n) ) 

nb-nb-one-single-line ::=
  nb-single-char+ 

nb-l-first-single-line(n) ::=
  ( nb-single-char* ns-single-char )?
  s-l-end-flow-line(n) 

l-l-inner-single-line(n) ::=
    l-flow-empty-specific(n)
  | ( i-s-ignored-leading(n)
      ns-single-char
      nb-l-first-single-line(n) ) 

i-nb-last-single-line(n) ::=
  i-s-ignored-leading(n)
  ( ns-single-char nb-single-char* )? 

ns-escaped-single-quote ::=
  c-single-quote c-single-quote 

nb-single-char ::=
    ns-escaped-single-quote
  | ( nb-char - c-single-quote ) 

ns-single-char ::=
  nb-single-char - s-char 

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" 

3.6.9 Escaping

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

c-escape ::= '\' 

ns-esc-escape ::= c-escape c-escape 

ns-esc-double-quote ::=
  c-escape c-double-quote 

ns-esc-bel ::= c-escape 'a' 

ns-esc-backspace ::= c-escape 'b' 

ns-esc-esc ::= c-escape 'e' 

ns-esc-form-feed ::= c-escape 'f' 

ns-esc-line-feed ::= c-escape 'n' 

ns-esc-return ::= c-escape 'r' 

ns-esc-tab ::= c-escape 't' 

ns-esc-vertical-tab ::= c-escape 'v' 

ns-esc-null ::= c-escape '0' 

ns-esc-space ::= c-escape #20 

ns-esc-non-breaking-space ::=
  c-escape '_' 

ns-esc-next-line ::= c-escape 'N' 

ns-esc-line-separator ::= c-escape 'L' 

ns-esc-paragraph-separator ::= c-escape 'P' 

ns-esc-8-bit ::=
  c-escape 'x' ( ns-hex-digit x 2 ) 

ns-esc-16-bit ::=
  c-escape 'u' ( ns-hex-digit x 4 ) 

ns-esc-32-bit ::=
  c-escape 'U' ( ns-hex-digit x 8 ) 

ns-esc-sequence ::=
    ns-esc-escape
  | ns-esc-double-quote
  | ns-esc-bel
  | ns-esc-backspace
  | ns-esc-esc
  | ns-esc-form-feed
  | ns-esc-line-feed
  | ns-esc-return
  | ns-esc-tab
  | ns-esc-vertical-tab
  | ns-esc-null
  | ns-esc-space
  | ns-esc-non-breaking-space
  | ns-esc-next-line
  | ns-esc-line-separator
  | ns-esc-paragraph-separator
  | ns-esc-8-bit
  | ns-esc-16-bit
  | ns-esc-32-bit 

An escaped line break is completely ignored.

b-escaped ::= c-escape b-any 

3.6.10 Double Quoted

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.

c-c-double-quoted(n) ::=
  c-double-quote
  nb-nb-double-quoted-value(n)?
  c-double-quote 

nb-nb-double-quoted-value(n) ::=
    nb-nb-one-double-line
  | ( nb-l-first-double-line(n)
      l-l-inner-double-line(n)*
      i-nb-last-double-line(n) ) 

nb-nb-one-double-line ::=
  nb-double-char+ 

nb-l-first-double-line(n) ::=
  ( nb-double-char* ns-double-char )?
  s-l-end-double-line(n) 

l-l-inner-double-line(n) ::=
    l-flow-empty-specific(n)
  | ( i-s-ignored-leading(n)
      ns-double-char
      nb-l-first-double-line(n) ) 

i-nb-last-double-line(n) ::=
  i-s-ignored-leading(n)
  ( ns-double-char nb-double-char* )? 

s-l-end-double-line(n) ::=
    s-l-end-flow-line(n)
  | ( s-char* b-escaped ) 

nb-double-char ::=
    ns-esc-sequence
  | ( nb-char - c-escape ) 

ns-double-char ::=
  nb-double-char - s-char 

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" 

3.6.11 Plain

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 an explicit transfer method 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.

ns-ns-plain-top-value(n) ::=
  ns-ns-plain-value(n) 

ns-ns-plain-flow-value(n) ::=
  ns-ns-plain-value(n) 

ns-ns-plain-key ::=
  ns-ns-one-plain-line 

ns-ns-plain-value(n) ::=
    ns-ns-one-plain-line
  | ( ns-l-first-plain-line(n)
      l-l-inner-plain-line(n)*
      i-ns-last-plain-line(n) ) 

ns-ns-one-plain-line ::=
  ns-first-plain-char
  nb-ns-plain-text? 

ns-l-first-plain-line(n) ::=
  ns-ns-one-plain-line
  s-l-end-flow-line(n) 

l-l-inner-plain-line(n) ::=
    l-flow-empty-specific(n)
  | ( i-s-ignored-leading(n)
      ns-plain-char
      nb-ns-plain-text?
      s-l-end-flow-line(n) ) 

i-ns-last-plain-line(n) ::=
  i-s-ignored-leading(n)
  ( ns-plain-char
    nb-ns-plain-text? )? 

nb-ns-plain-text ::=
  nb-plain-char* ns-plain-char 

ns-first-plain-char ::=
    ( ns-plain-char
    - c-sequence-entry
    - c-mapping-entry
    - c-sequence-start
    - c-sequence-end
    - c-mapping-start
    - c-mapping-end
    - c-collect-entry
    - c-top-key
    - c-alias
    - c-anchor
    - c-transfer
    - c-literal
    - c-folded
    - c-single-quote
    - c-double-quote
    - c-throwaway
    - c-directive
    - c-reserved
  | ( ( c-sequence-entry
      | c-top-key
      | c-mapping-entry
      | c-collect-entry )
      ns-plain-char ) 

nb-plain-top-char ::=
    ( nb-char
    - c-mapping-entry
    - c-throwaway )
  | ( ns-plain-char
      c-throwaway )
  | ( c-mapping-entry
      ns-plain-char ) 

nb-plain-flow-char ::=
    ( nb-plain-top-char
    - c-sequence-start
    - c-sequence-end
    - c-mapping-start
    - c-mapping-end
    - c-collect-entry )
  | ( c-collect-entry
      ns-plain-char ) 

nb-plain-key-char ::=
  nb-plain-flow-char 

nb-plain-char ::=
    nb-plain-top-char
  | nb-plain-flow-char
  | nb-plain-key-char 

ns-plain-char ::=
  nb-plain-char - s-char 

first: There is no unquoted empty string.
second: 12          ## This is an integer.
boolean: -          ## 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 } 

4.2.1 Native Node

A native node is YAML's building block for data structures. A native node stands for anything from a single integer to a complex data structure such as a complete VRML scene or SQL database. A native node has the following properties:

type family

Each native node is associated with a type family. This association may be based on the native data type of the node or its value. Indirectly each node is also associated with a kind through its family.

value

A node has an associated value. This value must satisfy the constraints specified by the type family. In particular, the value of a collection (mappings and sequences) is given in terms of other nodes, while the value of a scalar is defined independent of any other node.

4.2.2 Type Family

The type family mechanism provides an abstraction of data types that is portable across languages and platforms. Each native binding may have zero or more native concrete types or class constructs that correspond to a given type family.

YAML supports both global and private type families. Global type families have consistent semantics across all YAML documents. Private type families should not be expected to maintain the same semantics in different documents, even if these appear in the same document stream.

name

Global type family names are URIs under the taguri: scheme. Private type family names are URIs under the x-private: scheme. The taguri: scheme is described in http://www.taguri.org.

YAML only makes use of taguri: URIs that take the form taguri:domain,date:identifier. Specifically, it does not make use of taguri: URIs that are based on an E-mail address. Nor does it make use of URIs outside the taguri: scheme.

definition

A description of the particular category of information, independent of language and platform.

kind

Each type family must have a kind that is either a scalar or a collection. There are two kinds of collections, sequence and mapping. Usually the kind of each type family follows immediately from the definition (for example, integers are scalars while Point structures are mappings). In other cases, deciding on the kind requires a data modeling decision (for example, whether a date is thought of as a single scalar or as a mapping with independent sub-parts).

scalar

Scalar type families are the simplest. The value of a scalar node is defined in some mathematical terms, independent of any other nodes and type families.

sequence

The value of a sequence node is defined as an ordered set of nodes. Each sequence type family may impose additional constraints on these nodes. For example, it may require that they belong to particular type families.

mapping

The value of a mapping node is defined as a function from a domain to a range. Each mapping type family may impose additional constraints. For example, it may require a specific set of keys and that the value for each key must be of a particular type family.

domain

A domain is an unordered set of nodes, restricted such that no two nodes in the set may be equal. Nodes that are members of the domain are often called "keys".

range

A range is an unordered set of nodes without restrictions. Nodes that are members of the range are often called "values".

function

A function is a rule of correspondence from the domain onto the range such that there is a unique value in the range assigned to every key in the domain, and every value in the range is assigned to at least one key.

collection

Is possible to think of a sequence as a mapping using a special domain (all integer values between zero and some maximal value). A unified collection model is helpful both for theoretical analysis and in constructing practical YAML tools and APIs.

4.2.3 Equivalence

In most programming languages, there are two distinct manners in which variables can be equivalent.

identity

The first form of equivalence is by reference, where the two variables refer to the same memory address. We call this equivalence relation "identity".

equality

The second form of equivalence occurs when two nodes are different (have different memory addresses), but have the same content. We call this second form of equivalence "equality". It follows that when two nodes are identical they are also equal.

Equality is defined between scalar nodes and between collection nodes, as described below.

scalar equality

Two scalar nodes are equal if and only if they have the same type family and their values are the same under the type family's definition

collection equality

Equality of collections is defined recursively. Two collection nodes are equal if and only if they have the same type family and for each key in the domain of one, there is a corresponding key in the domain of the other such that both keys are equal and their corresponding values are equal; here corresponding value refers to the unique node in the range of the collection assigned to the key by the collection's function.

For the purpose of node equivalence, all YAML collection type families are considered to be mutable and all scalar type families are considered to be immutable. It is possible to modify the value of a mutable (collection) node "in place". For immutable (scalar) nodes, it is impossible to do so; instead, modifications require the creation of a new, independent scalar value of the same type family and using it instead. To better understand this distinction, consider the following example:

C syntax: |
    struct Point { int x; int y; } p = { 1, 2 };
YAML syntax: !Point { x: 1, y: 2 } 

It is impossible to modify the integer value 1. The only modification possible is constructing a new, unrelated integer value 3 and using this new value for the X coordinate. Performing this replacement would cause the point to change "in place" from { x: 1, y: 2 } to { x: 3, y: 2 }. Thus, in this example points are mutable but integers are not.

For immutable (scalar) type families, the distinction between equal and identical nodes is only of interest for efficiency reasons (reducing memory usage), and has no semantic significance. Hence for such type families a YAML processor may freely replace two equal but separate (non-identical) nodes with two occurrences of the same (identical) node, and vice versa.

For mutable (collection) type families, however, the distinction between equality and indentity is an important part of the information model and a YAML processor is required to preserve node identity.

4.2.4 Documents Stream

A YAML stream is a sequence of disjoint directed graphs, each with a root node.

stream

A sequence of zero or more document root nodes.

document

A top-level node that is disjoint from all other root document nodes.

The term disjoint means that for any two nodes x and y, there does not exist a third node z that is reachable from both x and y. For any node x, x is reachable from y if and only if either x and y are identical, or y is a collection and there exists a node z in the domain or the range of y such that x is reachable from z.

4.3.1 Format

It may be possible to write a string value of a scalar in more than one way. For example, an integer value of 255 can also be written in hex as 0xFF. This distinction is covered by the concept of a format. A format defines a way to write the values of a scalar type family as Unicode strings. Using formats allows generic YAML APIs to be implemented in terms of such strings and still allow handling of arbitrary native data.

name

Each format has a name used for explicit typing. This name may also be used as a fragment identifier in combination with the type family URI for general identification. This name must comply with the format production, and must be unique within the type families it applies to.

definition

A description of the format as it applies to particular data values.

regexp

Regular expressions may be provided to allow implicit typing using the string format, or to enable the YAML processor to validate that a given value is indeed compliant with the string format.

Formats are an extension required by the graph model, and are not part of the native model. Hence, when constructing native data structures from YAML data, format need not be preserved. For example, a YAML integer node should be loaded to a native integer data type, discarding the information that the integer was serialized in hex format.

4.3.2 Type Family Formats

Each type family used for scalar nodes has associated formats. These formats can be separated into two groups, implicit formats and explicit formats. In addition, one of the formats is designated to be the type family's canonical format.

Type families used for collection nodes do not have any associated formats.

implicit formats

A set of zero or more formats used for implicit typing. Each format may only be used in a single type family for this purpose.

explicit formats

A set of zero or more formats used for explicit typing. It is possible for two type families to share the same explicit format, though this practice is discouraged.

canonical format

In addition to the above, each scalar type family must provide a canonical format. This must be one of the implicit or explicit formats, or a subset of one of these formats. The canonical format must provide exactly one unique string representation for each possible value of the scalar.

4.3.3 Graph Node

In the graph model, each scalar node has an associated format that is one of those defined by the node's type family. Collection nodes do not have an associated format. The value of graph scalar nodes is a Unicode string that is a representation of the appropriate native value using the node's format.

4.3.4 Implicit Types and Formats

In the graph model, the type family and format are optional. When a type family or format is missing, we say that it is implicit. If a format is provided, the type family is mandatory. Since the type family is mandatory in the native model, the loader must resolve the type family and format using implicit typing. When native data is converted to YAML, the dumper is responsible for deciding which graph nodes will have explicit type family and format.

Since graph nodes may be implicitly typed, the loader may not be able to determine the type family of the node. Even when the type family is known, the loader may not have an appropriate native type. Therefore, a given YAML document need not have a native binding for every programming language or application.

4.4.1 Serial Node

To lay out graph nodes as a tree structure, a mechanism is needed to manage duplicate occurrences. This is solved using an additional node kind, alias. The first occurrence of a node is represented using a serial node of the appropriate kind. Subsequent occurrences of either a collection or a scalar are represented by an alias node.

All nodes in the serial model have the following properties in addition to the properties defined in the graph model:

parent

The parent property gives access to the collection that contains the current serial node.

anchor

The anchor is a Unicode string that complies with the ns-ns-anchor-name production. The anchor is used to associate the first occurrence of a graph node with subsequent occurrences, via the alias serial node. This property is optional, provided that the graph node does not occur more than once in the serialization.

Note that when a serial node is converted to a graph node, the anchor, if any, is not preserved. Likewise the parent property and the alias kind are not preserved as the graph node may be contained in several collections.

4.4.2 Alias

The alias node represents subsequent occurrences of a graph node in the serialization. Like all serial nodes, an alias node has a parent and an anchor property. In addition, an anchor node has a single additional property:

referent

The serial node serial node that the alias references is the closest preceding node having the same anchor.

When an alias node is converted into a graph node it becomes a subsequent occurrence of the graph node represented by its referent node.

4.4.3 Pair

A pair is an ordered set of two serial nodes. The first member of the set is the key and the second member of the set is the value.

4.4.4 Serial Mapping

Mapping serial nodes represent the first occurrence of a mapping in a given serialization. The value of mapping serial nodes is an ordered set of node pairs.

When a mapping serial node is converted into a graph node, three operations occur. The domain is constructed with the graph node for each key in its set of pairs. Likewise, the range is constructed with the graph node for each value in its set of pairs. Last, the function is constructed via association of key graph nodes to value graph nodes, as provided by the set of pairs. Note that the ordering of the pairs is explicitly not converted.

4.4.5 Ordering

When serializing a YAML graph, every serial node is put into a single linear sequence within a given document through the mapping pair ordering. With the composition of collections, this ordering becomes total. For any two nodes or aliases, x and y we say that x precedes y when any of the following holds:

4.5.1 Style

In the syntax, each node has an additional style property, depending on its kind.

scalar style

Scalar styles include two block styles and three flow styles. All but the double quoted style are limited to scalars having only printable characters.

collection style

There are two styles for each of the collection kinds, a block style and an flow style.

4.5.2 Comment

The syntax allows optional comment blocks to be interleaved with the node blocks. Comment blocks may appear before or after any node block. A comment block can't appear inside a scalar node value.

comment

A comment is a sequence of zero or more Unicode characters complying with the comment productions.

4.5.3 Directive

Attached to each document is a document directive section.

directive section

A collection of directives to the parser where each member of the domain and range are scalar values matching the ns-ns-directive-name and ns-ns-directive-value productions.

4.5.4 Details

The YAML syntax contains multiple mechanisms for increased readability, such as escaping, indentation, folding, line break normalization etc. While the parser may make such details available, they should not be used to encode information required for the construction of the native data.