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

The design goals for YAML are:

YAML’s initial direction was set by the data serialization and markup language discussions among SML-DEV members. Later on, it directly incorporated experience from Brian Ingerson’s Perl module Data::Denter. Since then, YAML has matured through ideas and support from its user community.

YAML integrates and builds upon concepts described by C, Java, Perl, Python, Ruby, RFC0822 (MAIL), RFC1866 (HTML), RFC2045 (MIME), RFC2396 (URI), XML, SAX and SOAP.

The syntax of YAML was motivated by Internet Mail (RFC0822) and remains partially compatible with that standard. Further, borrowing from MIME (RFC2045), YAML’s top-level production is a stream of independent documents; ideal for message-based distributed processing systems.

YAML’s indentation-based scoping is similar to Python’s (without the ambiguities caused by tabs). Indented blocks facilitate easy inspection of the data’s structure. YAML’s literal style leverages this by enabling formatted text to be cleanly mixed within an indented structure without troublesome escaping. YAML also allows the use of traditional indicator-based scoping similar to Perl’s. Such flow content can be freely nested inside indented blocks.

YAML’s double-quoted style uses familiar C-style escape sequences. This enables ASCII encoding of non-printable or 8-bit (ISO 8859-1) characters such as “\x3B”. Non-printable 16-bit Unicode and 32-bit (ISO/IEC 10646) characters are supported with escape sequences such as “\u003B” and “\U0000003B”.

Motivated by HTML’s end-of-line normalization, YAML’s line folding employs an intuitive method of handling line breaks. A single line break is folded into a single space, while empty lines are interpreted as line break characters. This technique allows for paragraphs to be word-wrapped without affecting the canonical form of the content.

YAML’s core type system is based on the requirements of agile languages such as Perl, Python, and Ruby. YAML directly supports both collection (mapping, sequence) and scalar content. Support for common types enables programmers to use their language’s native data structures for YAML manipulation, instead of requiring a special document object model (DOM).

Like XML’s SOAP, YAML supports serializing native graph data structures through an aliasing mechanism. Also like SOAP, YAML provides for application-defined types. This allows YAML to represent rich data structures required for modern distributed computing. YAML provides globally unique type names using a namespace mechanism inspired by Java’s DNS-based package naming convention and XML’s URI-based namespaces.

YAML was designed to support incremental interfaces that include both input (“getNextEvent()”) and output “sendNextEvent()”) one-pass interfaces. Together, these enable YAML to support the processing of large documents (e.g. transaction logs) or continuous streams (e.g. feeds from a production machine).

Newcomers to YAML often search for its correlation to the eXtensible Markup Language (XML). Although the two languages may actually compete in several application domains, there is no direct correlation between them.

YAML is primarily a data serialization language. XML was designed to be backwards compatible with the Standard Generalized Markup Language (SGML) and thus had many design constraints placed on it that YAML does not share. Inheriting SGML’s legacy, XML is designed to support structured documentation, where YAML is more closely targeted at data structures and messaging. Where XML is a pioneer in many domains, YAML is the result of lessons learned from XML and other technologies.

It should be mentioned that there are ongoing efforts to define standard XML/YAML mappings. This generally requires that a subset of each language be used. For more information on using both XML and YAML, please visit http://yaml.org/xml/index.html.

This specification uses key words based on RFC2119 to indicate requirement level. In particular, the following words are used to describe the actions of a YAML processor:

YAML’s block collections use indentation for scope and begin each entry on its own line. Block sequences indicate each entry with a dash and space ( “-”). Mappings use a colon and space (“: ”) to mark each mapping key: value pair.

- Mark McGwire
- Sammy Sosa
- Ken Griffey

hr:  65    # Home runs
avg: 0.278 # Batting average
rbi: 147   # Runs Batted In

american:
  - Boston Red Sox
  - Detroit Tigers
  - New York Yankees
national:
  - New York Mets
  - Chicago Cubs
  - Atlanta Braves

-
  name: Mark McGwire
  hr:   65
  avg:  0.278
-
  name: Sammy Sosa
  hr:   63
  avg:  0.288

YAML also has flow styles, using explicit indicators rather than indentation to denote scope. The flow sequence is written as a comma separated list within square brackets. In a similar manner, the flow mapping uses curly braces.

- [name        , hr, avg  ]
- [Mark McGwire, 65, 0.278]
- [Sammy Sosa  , 63, 0.288]

Mark McGwire: {hr: 65, avg: 0.278}
Sammy Sosa: {
    hr: 63,
    avg: 0.288
  }

YAML uses three dashes (“---”) to separate documents within a stream. Three dots ( “...”) indicate the end of a document without starting a new one, for use in communication channels. Comment lines begin with the Octothorpe (also called “hash”, “sharp”, or “number sign” - “#”).

# Ranking of 1998 home runs
---
- Mark McGwire
- Sammy Sosa
- Ken Griffey

# Team ranking
---
- Chicago Cubs
- St Louis Cardinals

---
time: 20:03:20
player: Sammy Sosa
action: strike (miss)
...
---
time: 20:03:47
player: Sammy Sosa
action: grand slam
...

Repeated nodes are first identified by an anchor (marked with the ampersand - “&”), and are then aliased (referenced with an asterisk - “*”) thereafter.

---
hr: # 1998 hr ranking
  - Mark McGwire
  - Sammy Sosa
rbi:
  # 1998 rbi ranking
  - Sammy Sosa
  - Ken Griffey

---
hr:
  - Mark McGwire
  # Following node labeled SS
  - &SS Sammy Sosa
rbi:
  - *SS # Subsequent occurrence
  - Ken Griffey

A question mark and space (“? ”) indicate a complex mapping key. Within a block collection, key: value pairs can start immediately following the dash, colon, or question mark.

? - Detroit Tigers
  - Chicago cubs
:
  - 2001-07-23

? [ New York Yankees,
    Atlanta Braves ]
: [ 2001-07-02, 2001-08-12,
    2001-08-14 ]

---
# products purchased
- item    : Super Hoop
  quantity: 1
- item    : Basketball
  quantity: 4
- item    : Big Shoes
  quantity: 1

Scalar content can be written in block form, using a literal style (“|”) where all line breaks are significant. Alternatively, they can be written with the folded style (“>”) where each line break is folded to a space unless it ends an empty or a “more indented” line.

# ASCII Art
--- |
  \//||\/||
  // ||  ||__

---
  Mark McGwire's
  year was crippled
  by a knee injury.

>
 Sammy Sosa completed another
 fine season with great stats.

   63 Home Runs
   0.288 Batting Average

 What a year!

name: Mark McGwire
accomplishment: >
  Mark set a major league
  home run record in 1998.
stats: |
  65 Home Runs
  0.278 Batting Average

YAML’s flow scalars include the plain style (most examples thus far) and quoted styles. The double-quoted style provides escape sequences. The single-quoted style is useful when escaping is not needed. All flow scalars can span multiple lines; line breaks are always folded.

unicode: "Sosa did fine.\u263A"
control: "\b1998\t1999\t2000\n"
hexesc:  "\x13\x10 is \r\n"

single: '"Howdy!" he cried.'
quoted: ' # not a ''comment''.'
tie-fighter: '|\-*-/|'

plain:
  This unquoted scalar
  spans many lines.

quoted: "So does this
  quoted scalar.\n"

In YAML, untagged nodes are given an type depending on the application. The examples in this specification generally use the “seq”, “map” and “str” types from the YAML tag repository. A few examples also use the “int” and “float” types. The repository includes additional types such as “null”, “bool”, “set” and others.

canonical: 12345
decimal: +12,345
sexagesimal: 3:25:45
octal: 014
hexadecimal: 0xC

canonical: 1.23015e+3
exponential: 12.3015e+02
sexagesimal: 20:30.15
fixed: 1,230.15
negative infinity: -.inf
not a number: .NaN

null: ~
true: y
false: n
string: '12345'

canonical: 2001-12-15T02:59:43.1Z
iso8601: 2001-12-14t21:59:43.10-05:00
spaced: 2001-12-14 21:59:43.10 -5
date: 2002-12-14

Explicit typing is denoted with a tag using the exclamation point (“!”) symbol. Global tags are URIs and may be specified in a shorthand form using a handle. Application-specific local tags may also be used.

---
not-date: !!str 2002-04-28

picture: !!binary |
 R0lGODlhDAAMAIQAAP//9/X
 17unp5WZmZgAAAOfn515eXv
 Pz7Y6OjuDg4J+fn5OTk6enp
 56enmleECcgggoBADs=

application specific tag: !something |
 The semantics of the tag
 above may be different for
 different documents.

%TAG ! tag:clarkevans.com,2002:
--- !shape
  # Use the ! handle for presenting
  # tag:clarkevans.com,2002:circle
- !circle
  center: &ORIGIN {x: 73, y: 129}
  radius: 7
- !line
  start: *ORIGIN
  finish: { x: 89, y: 102 }
- !label
  start: *ORIGIN
  color: 0xFFEEBB
  text: Pretty vector drawing.

# sets are represented as a
# mapping where each key is
# associated with the empty string
--- !!set
? Mark McGwire
? Sammy Sosa
? Ken Griff

# ordered maps are represented as
# a sequence of mappings, with
# each mapping having one key
--- !!omap
- Mark McGwire: 65
- Sammy Sosa: 63
- Ken Griffy: 58

Below are two full-length examples of YAML. On the left is a sample invoice; on the right is a sample log file.

--- !<tag:clarkevans.com,2002:invoice>
invoice: 34843
date   : 2001-01-23
bill-to: &id001
    given  : Chris
    family : Dumars
    address:
        lines: |
            458 Walkman Dr.
            Suite #292
        city    : Royal Oak
        state   : MI
        postal  : 48046
ship-to: *id001
product:
    - sku         : BL394D
      quantity    : 4
      description : Basketball
      price       : 450.00
    - sku         : BL4438H
      quantity    : 1
      description : Super Hoop
      price       : 2392.00
tax  : 251.42
total: 4443.52
comments:
    Late afternoon is best.
    Backup contact is Nancy
    Billsmer @ 338-4338.

---
Time: 2001-11-23 15:01:42 -5
User: ed
Warning:
  This is an error message
  for the log file
---
Time: 2001-11-23 15:02:31 -5
User: ed
Warning:
  A slightly different error
  message.
---
Date: 2001-11-23 15:03:17 -5
User: ed
Fatal:
  Unknown variable "bar"
Stack:
  - file: TopClass.py
    line: 23
    code: |
      x = MoreObject("345\n")
  - file: MoreClass.py
    line: 58
    code: |-
      foo = bar

This section details the processes shown in the diagram above. Note a YAML processor need not provide all these processes. For example, a YAML library may provide only YAML input ability, for loading configuration files, or only output ability, for sending data to other applications.

This section specifies the formal details of the results of the above processes. To maximize data portability between programming languages and implementations, users of YAML should be mindful of the distinction between serialization or presentation properties and those which are part of the YAML representation. Thus, while imposing a order on mapping keys is necessary for flattening YAML representations to a sequential access medium, this serialization detail must not be used to convey application level information. In a similar manner, while indentation technique and a choice of a node style are needed for the human readability, these presentation details are neither part of the YAML serialization nor the YAML representation. By carefully separating properties needed for serialization and presentation, YAML representations of application information will be consistent and portable between various programming environments.

The following diagram summarizes the three information models. Full arrows denote composition, hollow arrows denote inheritance, “1” and “*” denote “one” and “many” relationships. A single “+” denotes serialization details, a double “++” denotes presentation details.

Figure 3.2. Information Models

3.2.1. Representation Graph

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

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

Figure 3.3. Representation Model

3.2.1.1. Nodes

YAML nodes have content of one of three kinds: scalar, sequence, or mapping. In addition, each node has a tag which serves to restrict the set of possible values which the node’s content can have.

Scalar

The content of a scalar node is an opaque datum that can be presented as a series of zero or more Unicode characters.

Sequence

The content of a sequence node is an ordered series of zero or more nodes. In particular, a sequence may contain the same node more than once or it could even contain itself (directly or indirectly).

Mapping

The content of a mapping node is an unordered set of key: value node pairs, with the restriction that each of the keys is unique. YAML places no further restrictions on the nodes. In particular, keys may be arbitrary nodes, the same node may be used as the value of several key: value pairs, and a mapping could even contain itself as a key or a value (directly or indirectly).

When appropriate, it is convenient to consider sequences and mappings together, as collections. In this view, sequences are treated as mappings with integer keys starting at zero. Having a unified collections view for sequences and mappings is helpful both for creating practical YAML tools and APIs and for theoretical analysis.

3.2.1.2. Tags

YAML represents type information of native data structures with a simple identifier, called a tag. Global tags are URIs and hence globally unique across all applications. The “tag”: URI scheme (mirror) is recommended for all global YAML tags. In contrast, local tags are specific to a single application. Local tags start with “!”, are not URIs and are not expected to be globally unique. YAML provides a “TAG” directive to make tag notation less verbose; it also offers easy migration from local to global tags. To ensure this, local tags are restricted to the URI character set and use URI character escaping.

YAML does not mandate any special relationship between different tags that begin with the same substring. Tags ending with URI fragments (containing “#”) are no exception; tags that share the same base URI but differ in their fragment part are considered to be different, independent tags. By convention, fragments are used to identify different “variants” of a tag, while “/” is used to define nested tag “namespace” hierarchies. However, this is merely a convention, and each tag may employ its own rules. For example, Perl tags may use “::” to express namespace hierarchies, Java tags may use “.”, etc.

YAML tags are used to associate meta information with each node. In particular, each tag must specify the expected node kind (scalar, sequence, or mapping). Scalar tags must also provide mechanism for converting formatted content to a canonical form for supporting equality testing. Furthermore, a tag may provide additional information such as the set of allowed content values for validation, a mechanism for tag resolution, or any other data that is applicable to all of the tag’s nodes.

3.2.1.3. Nodes Comparison

Since YAML mappings require key uniqueness, representations must include a mechanism for testing the equality of nodes. This is non-trivial since YAML allows various ways to format a given scalar content. For example, the integer eleven can be written as “013” (octal) or “0xB” (hexadecimal). If both forms are used as keys in the same mapping, only a YAML processor which recognizes integer formats would correctly flag the duplicate key as an error.

Canonical Form

YAML supports the need for scalar equality by requiring that every scalartag must specify a mechanism to producing the canonical form of any formatted content. This form is a Unicode character string which presents the content and can be used for equality testing. While this requirement is stronger than a well defined equality operator, it has other uses, such as the production of digital signatures.

Equality

Two nodes must have the same tag and content to be equal. Since each tag applies to exactly one kind, this implies that the two nodes must have the same kind to be equal. Two scalars are equal only when their tags and canonical forms are equal character-by-character. Equality of collections is defined recursively. Two sequences are equal only when they have the same tag and length, and each node in one sequence is equal to the corresponding node in the other sequence. Two mappings are equal only when they have the same tag and an equal set of keys, and each key in this set is associated with equal values in both mappings.

Identity

Two nodes are identical only when they represent the same native data structure. Typically, this corresponds to a single memory address. Identity should not be confused with equality; two equal nodes need not have the same identity. A YAML processor may treat equal scalars as if they were identical. In contrast, the separate identity of two distinct but equal collections must be preserved.

3.2.2. Serialization Tree

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

Figure 3.4. Serialization Model

3.2.2.1. Keys Order

In the representation model, mapping keys do not have an order. To serialize a mapping, it is necessary to impose an ordering on its keys. This order is a serialization detail and should not be used when composing the representation graph (and hence for the preservation of important data). In every case where node order is significant, a sequence must be used. For example, an ordered mapping can be represented as a sequence of mappings, where each mapping is a single key: value pair. YAML provides convenient compact notation for this case.

3.2.2.2. Anchors and Aliases

In the representation graph, a node may appear in more than one collection. When serializing such data, the first occurrence of the node is identified by an anchor and each subsequent occurrence is serialized as an alias node which refers back to this anchor. Otherwise, anchor names are a serialization detail and are discarded once composing is completed. When composing a representation graph from serialized events, an alias node refers to the most recent node in the serialization having the specified anchor. Therefore, anchors need not be unique within a serialization. In addition, an anchor need not have an alias node referring to it. It is therefore possible to provide an anchor for all nodes in serialization.

3.2.3. Presentation Stream

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

Figure 3.5. Presentation Model

3.2.3.1. Node Styles

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

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

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

Figure 3.6. Kind/Style Combinations

3.2.3.2. Scalar Formats

YAML allows scalar content to be presented in several formats. For example, the boolean “true” might also be written as “yes”. Tags must specify a mechanism for converting any formatted scalar content to a canonical form for use in equality testing. Like node style, the format is a presentation detail and is not reflected in the serialization tree and representation graph.

3.2.3.3. Comments

Comments are a presentation detail and must not have any effect on the serialization tree or representation graph. In particular, comments are not associated with a particular node. The usual purpose of a comment is to communicate between the human maintainers of a file. A typical example is comments in a configuration file. Comments may not appear inside scalars, but may be interleaved with such scalars inside collections.

3.2.3.4. Directives

Each document may be associated with a set of directives. A directive has a name and an optional sequence of parameters. Directives are instructions to the YAML processor, and like all other presentation details are not reflected in the YAML serialization tree or representation graph. This version of YAML defines a two directives, “YAML” and “TAG”. All other directives are reserved for future versions of YAML.

The process of loading native data structures from a YAML stream has several potential failure points. The character stream may be ill-formed, aliases may be unidentified, unspecified tags may be unresolvable, tags may be unrecognized, the content may be invalid, and a native type may be unavailable. Each of these failures results with an incomplete loading.

A partial representation need not resolve the tag of each node, and the canonical form of scalar content need not be available. This weaker representation is useful for cases of incomplete knowledge of the types used in the document. In contrast, a complete representation specifies the tag of each node, and provides the canonical form of scalar content, allowing for equality testing. A complete representation is required in order to construct native data structures.

Figure 3.7. Loading Failure Points

To make the syntax easier to follow, production names use Hungarian-style notation. Each production is given one of the following prefix based on the type of characters it matches.

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

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

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

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

⇔# Comment only.

Legend:
  c-byte-order-mark

# This stream contains no
# documents, only comments.

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

ERROR:
 A BOM must not appear
 inside a document.

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

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

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

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

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

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

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

# Comment only.

Legend:
  c-comment

# This stream contains no
# documents, only comments.

anchored: !local &anchor value
alias: *anchor

Legend:
  c-anchor
  c-alias
  c-tag

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

literal: |
  text
folded: >
  text

Legend:
  c-literal
  c-folded

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

single: 'text'
double: "text"

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

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

%YAML 1.1
--- text

Legend:
  c-directive

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

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

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

The Unicode standard defines the following line break characters:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Legend:
  ns-esc-char

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

Bad escapes:
  "\c
  \xq-"

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

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

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

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

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

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

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

Comments always span to the end of the line.

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

··# Comment↓
···↓
↓

# This stream contains no
# documents, only comments.

Legend:
  c-b-comment l-comment

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

key:····# Comment↓
  value↓

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

%YAML 1.1
%YAML 1.1
foo

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

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

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

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

%TAG ! !foo
%TAG ! !foo
bar

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

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

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

%YAML 1.1
---
!!seq [
  !<!foobar> "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

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

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

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

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

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

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

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

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

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

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

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

⇔# A stream may contain
# no documents.

Legend:
  l-yaml-stream

# This stream contains no
# documents, only comments.

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

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

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

Legend:
  l-first-document

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

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

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

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

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

Legend:
  l-next-document

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

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

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

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

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

Legend:
  c-verbatim-tag

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

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

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

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

Legend:
  c-ns-shorthand-tag

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

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

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

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

Legend:
  c-ns-non-specific-tag

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

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

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

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

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

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

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

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

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

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

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
}