1.1. Goals

The design goals for YAML are, in decreasing priority:

1. YAML should be easily readable by humans.
2. YAML data should be portable between programming languages.
3. YAML should match the native data structures of dynamic languages.
4. YAML should have a consistent model to support generic tools.
5. YAML should support one-pass processing.
6. YAML should be expressive and extensible.
7. YAML should be easy to implement and use.

1.2. YAML History

The YAML 1.0 specification was published in early 2004 by by Clark Evans, Oren Ben-Kiki, and Ingy döt Net after 3 years of collaborative design work through the yaml-core mailing list³. The project was initially rooted in Clark and Oren’s work on the SML-DEV⁴ mailing list (for simplifying XML) and Ingy’s plain text serialization module⁵ for Perl. The language took a lot of inspiration from many other technologies and formats that preceded it.

The first YAML framework was written in Perl in 2001 and Ruby was the first language to ship a YAML framework as part of its core language distribution in 2003.

The YAML 1.1⁶ specification was published in 2005. Around this time, the developers became aware of JSON⁷. By sheer coincidence, JSON was almost a complete subset of YAML (both syntactically and semantically).

In 2006, Kyrylo Simonov produced PyYAML⁸ and LibYAML⁹. A lot of the YAML frameworks in various programming languages are built over LibYAML and many others have looked to PyYAML as a solid reference for their implementations.

The YAML 1.2¹⁰ specification was published in 2009. Its primary focus was making YAML a strict superset of JSON. It also removed many of the problematic implicit typing recommendations.

Since the release of the 1.2 specification, YAML adoption has continued to grow, and many large-scale projects use it as their primary interface language. In 2020, the new YAML language design team began meeting regularly to discuss improvements to the YAML language and specification; to better meet the needs and expectations of its users and use cases.

The YAML 1.2.2 specification, published in October 2021, was the first step in YAML’s rejuvenated development journey. YAML is now more popular than it has ever been, but there is a long list of things that need to be addressed for it to reach its full potential. The YAML design team is focused on making YAML as good as possible.

1.3. Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119¹¹.

The rest of this document is arranged as follows. Chapter 2 provides a short preview of the main YAML features. Chapter 3 describes the YAML information model and the processes for converting from and to this model and the YAML text format. The bulk of the document, chapters 4, 5, 6, 7, 8 and 9, formally define this text format. Finally, chapter 10 recommends basic YAML schemas.

2.1. Collections

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 key/value pair. Comments begin with an octothorpe (also called a “hash”, “sharp”, “pound” or “number sign” - “#”).

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

2.2. Structures

YAML uses three dashes (“---”) to separate directives from document content. This also serves to signal the start of a document if no directives are present. Three dots ( “...”) indicate the end of a document without starting a new one, for use in communication channels.

# 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 (objects) 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
# 1998 rbi ranking
rbi:
- 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

2.3. Scalars

Scalar content can be written in block notation, using a literal style (indicated by “|”) where all line breaks are significant. Alternatively, they can be written with the folded style (denoted by “>”) 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 two 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"
hex esc: "\x0d\x0a 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"

2.4. Tags

In YAML, untagged nodes are given a type depending on the application. The examples in this specification generally use the seq, map and str types from the fail safe schema. A few examples also use the int, float and null types from the JSON schema.

canonical: 12345
decimal: +12345
octal: 0o14
hexadecimal: 0xC

canonical: 1.23015e+3
exponential: 12.3015e+02
fixed: 1230.15
negative infinity: -.inf
not a number: .nan

null:
booleans: [ true, false ]
string: '012345'

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 tag shorthand notation 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 a null value
--- !!set
? Mark McGwire
? Sammy Sosa
? Ken Griffey

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

2.5. Full Length Example

Below are two full-length examples of YAML. The first is a sample invoice; the second 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

2.6. Processes and Models

YAML is both a text format and a method for presenting any native data structure in this format. Therefore, this specification defines two concepts: a class of data objects called YAML representations and a syntax for presenting YAML representations as a series of characters, called a YAML stream.

A YAML processor is a tool for converting information between these complementary views. It is assumed that a YAML processor does its work on behalf of another module, called an application. This chapter describes the information structures a YAML processor must provide to or obtain from the application.

YAML information is used in two ways: for machine processing and for human consumption. The challenge of reconciling these two perspectives is best done in three distinct translation stages: representation, serialization and presentation. Representation addresses how YAML views native data structures to achieve portability between programming environments. Serialization concerns itself with turning a YAML representation into a serial form, that is, a form with sequential access constraints. Presentation deals with the formatting of a YAML serialization as a series of characters in a human-friendly manner.

3.1. Dump

Dumping native data structures to a character stream is done using the following three stages:

Representing Native Data Structures

YAML represents any native data structure using three node kinds: sequence - an ordered series of entries; mapping - an unordered association of unique keys to values; and scalar - any datum with opaque structure presentable as a series of Unicode characters.

Combined, these primitives generate directed graph structures. These primitives were chosen because they are both powerful and familiar: the sequence corresponds to a Perl array and a Python list, the mapping corresponds to a Perl hash table and a Python dictionary. The scalar represents strings, integers, dates and other atomic data types.

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

Serializing the Representation Graph

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

Presenting the Serialization Tree

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

3.2. Load

Loading native data structures from a character stream is done using the following three stages:

Parsing the Presentation Stream

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

Composing the Representation Graph

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

Constructing Native Data Structures

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

4.1. Representation Graph

YAML’s representation of native data structure 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 directed graph 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; 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 4.2. Representation Model

4.2. Serialization Tree

To express a YAML representation using a serial API, it is 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 data structures from the serial interface should not use key order or anchor names for the preservation of application data.

Figure 4.3. Serialization Model

4.3. Presentation Stream

A YAML presentation is a stream of Unicode characters making use of styles, scalar content formats, comments, directives and other presentation details to present a YAML serialization in a human readable way. YAML allows several serialization trees to be contained in the same YAML presentation stream, as a series of documents separated by markers.

Figure 4.4. Presentation Model

5.1. Well-Formed Streams and Identified Aliases

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

5.2. Resolved Tags

Typically, most tags are not explicitly specified in the character stream. During parsing, nodes lacking an explicit tag are given a non-specific tag: “!” for non-plain scalars and “?” for all other nodes. Composing a complete representation requires each such non-specific tag to be resolved to a specific tag, be it a global tag or a local tag.

Resolving the tag of a node must only depend on the following three parameters: (1) the non-specific tag of the node, (2) the path leading from the root to the node and (3) the content (and hence the kind) of the node. When a node has more than one occurrence (using aliases), tag resolution must depend only on the path to the first (anchored) occurrence of the node.

Note that resolution must not consider presentation details such as comments, indentation and node style. Also, resolution must not consider the content of any other node, except for the content of the key nodes directly along the path leading from the root to the resolved node. Finally, resolution must not consider the content of a sibling node in a collection or the content of the value node associated with a key node being resolved.

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

YAML processors should resolve nodes having the “!” non-specific tag as “tag:yaml.org,2002:seq”, “tag:yaml.org,2002:map” or “tag:yaml.org,2002:str” depending on their kind. This tag resolution convention allows the author of a YAML character stream to effectively “disable” the tag resolution process. By explicitly specifying a “!” non-specific tag property, the node would then be resolved to a “vanilla” sequence, mapping or string, according to its kind.

Application specific tag resolution rules should be restricted to resolving the “?” non-specific tag, most commonly to resolving plain scalars. These may be matched against a set of regular expressions to provide automatic resolution of integers, floats, timestamps and similar types. An application may also match the content of mapping nodes against sets of expected keys to automatically resolve points, complex numbers and similar types. Resolved sequence node types such as the “ordered mapping” are also possible.

That said, tag resolution is specific to the application. YAML processors should therefore provide a mechanism allowing the application to override and expand these default tag resolution rules.

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

5.3. Recognized and Valid Tags

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

5.4. Available Tags

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

6.1. Character Set

To ensure readability, YAML streams use only the printable subset of the Unicode character set. The allowed character range explicitly excludes the C0 control block¹⁴ x00-x1F (except for TAB x09, LF x0A and CR x0D which are allowed), DEL x7F, the C1 control block x80-x9F (except for NEL x85 which is allowed), the surrogate block¹⁵ xD800-xDFFF, xFFFE and xFFFF.

On input, a YAML processor must accept all characters in this printable subset.

On output, a YAML processor must only produce only characters in this printable subset. ^? Characters outside this set must be presented using escape sequences. In addition, any allowed characters known to be non-printable should also be escaped.

Note: This isn’t mandatory since a full implementation would require extensive character property tables.

To ensure JSON compatibility, YAML processors must allow all non-C0 characters inside quoted scalars. ^? To ensure readability, non-printable characters should be escaped on output, even inside such scalars.

Note: JSON quoted scalars cannot span multiple lines or contain tabs, but YAML quoted scalars can.

6.2. Character Encodings

All characters mentioned in this specification are Unicode code points. Each such code point is written as one or more bytes depending on the character encoding used. Note that in UTF-16, characters above xFFFF are written as four bytes, using a surrogate pair.

The character encoding is a presentation detail and must not be used to convey content information.

On input, a YAML processor must support the UTF-8 and UTF-16 character encodings. For JSON compatibility, the UTF-32 encodings must also be supported.

If a character stream begins with a byte order mark, the character encoding will be taken to be as indicated by the byte order mark. Otherwise, the stream must begin with an ASCII character. This allows the encoding to be deduced by the pattern of null (x00) characters.

Byte order marks may appear at the start of any document, however all documents in the same stream must use the same character encoding.

To allow for JSON compatibility, byte order marks are also allowed inside quoted scalars. For readability, such content byte order marks should be escaped on output.

The encoding can therefore be deduced by matching the first few bytes of the stream with the following table rows (in order):

The recommended output encoding is UTF-8. If another encoding is used, it is recommended that an explicit byte order mark be used, even if the first stream character is ASCII.

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.

# This stream contains no
# documents, only comments.

- Invalid use of BOM
⇔
- Inside a document.

ERROR:
 A BOM must not appear
 inside a document.

6.3. Indicator Characters

Indicators are characters that have special semantics.

”-” (x2D, hyphen) denotes a block sequence entry.

”?” (x3F, question mark) denotes a mapping key.

”:” (x3A, colon) denotes a mapping value.

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

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

”,” (x2C, comma) ends a flow collection entry.

”[” (x5B, left bracket) starts a flow sequence.

”]” (x5D, right bracket) ends a flow sequence.

”{” (x7B, left brace) starts a flow mapping.

”}” (x7D, right brace) ends a flow mapping.

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

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

”#” (x23, octothorpe, hash, sharp, pound, number sign) denotes a comment.

# Comment only.

# This stream contains no
# documents, only comments.

”&” (x26, ampersand) denotes a node’s anchor property.

”*” (x2A, asterisk) denotes an alias node.

The “!” (x21, exclamation) is used for specifying node tags. It is used to denote tag handles used in tag directives and tag properties; to denote local tags; and as the non-specific tag for non-plain scalars.

anchored: !local &anchor value
alias: *anchor

{ "anchored": !local &A1 "value",
  "alias": *A1 }

”|” (7C, vertical bar) denotes a literal block scalar.

”>” (x3E, greater than) denotes a folded block scalar.

literal: |
  some
  text
folded: >
  some
  text

{ "literal": "some\ntext\n",
  "folded": "some text\n" }

”'” (x27, apostrophe, single quote) surrounds a single-quoted flow scalar.

”"” (x22, double quote) surrounds a double-quoted flow scalar.

single: 'text'
double: "text"

{ "single": "text",
  "double": "text" }

”%” (x25, percent) denotes a directive line.

%YAML 1.3
--- text

"text"

The “@” (x40, at) and “`” (x60, grave accent) are reserved for future use.

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

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

The “[”, “]”, “{”, “}” and “,” indicators denote structure in flow collections. They are therefore forbidden in some cases, to avoid ambiguity in several constructs. This is handled on a case-by-case basis by the relevant productions.

6.4. Line Break Characters

The line feed (x0A) and carriage return (0x0D) are line break characters.

All other characters, including the form feed (x0C), are considered to be non-break characters. Note that these include the non-ASCII line breaks: next line (x85), line separator (x2028) and paragraph separator (x2029).

YAML version 1.1 did support the above non-ASCII line break characters; however, JSON does not. Hence, to ensure JSON compatibility, YAML treats them as non-break characters as of version 1.2. YAML 1.3 processors parsing a version 1.1 document should therefore treat these line breaks as non-break characters, with an appropriate warning.

Line breaks are interpreted differently by different systems and have multiple widely used formats.

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 format is a presentation detail and must not be used to convey content information.

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

On output, a YAML processor is free to emit line breaks using whatever convention is most appropriate.

In the examples, line breaks are sometimes displayed using the “↓” glyph for clarity.

|
  Line break (no glyph)
  Line break (glyphed)↓

"Line break (no glyph)\nLine break (glyphed)\n"

6.5. White Space Characters

YAML recognizes two white space characters: space and tab.

The rest of the (printable) non-break characters are considered to be non-space characters.

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

# Tabs and spaces
quoted:·"Quoted →"
block:→|
··void main() {
··→printf("Hello, world!\n");
··}

{ "quoted": "Quoted \t",
  "block": "void main()
    {\n\tprintf(\"Hello, world!\\n\");\n}\n" }

6.6. Miscellaneous Characters

The YAML syntax productions make use of the following additional character classes:

• A decimal digit for numbers.
• A hexadecimal digit for escape sequences.
• ASCII letter (alphabetic) characters.
• Word (alphanumeric) characters for identifiers.
• URI characters for tags, as defined in the URI specification¹⁷.

By convention, any URI characters other than the allowed printable ASCII characters are first encoded in UTF-8 and then each byte is escaped using the “%” character. The YAML processor must not expand such escaped characters. Tag characters must be preserved and compared exactly as presented in the YAML stream, without any processing.

The “!” character is used to indicate the end of a named tag handle; hence its use in tag shorthands is restricted. In addition, such shorthands must not contain the “[”, “]”, “{”, “}” and “,” characters. These characters would cause ambiguity with flow collection structures.

6.7. Escaped Characters

All non-printable characters must be escaped. YAML escape sequences use the “\” notation common to most modern computer languages. Each escape sequence must be parsed into the appropriate Unicode character. The original escape sequence is a presentation detail and must not be used to convey content information.

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:

An escaped tab character (x09) evaluates to a tab character.

The \x, \u, and \U escape sequences are followed by two, four, and eight hexadecimal digits respectively. Those digits are interpreted as a Unicode code point. The value of the escape is the character at that code point.

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

[ "Fun with \\",
  "\" \u0007 \b \u001b \f",
  "\n \r \t \u000b \u0000",
  "\u0020 \u00a0 \u0085 \u2028 \u2029 A A A" ]

Bad escapes:
  "\c
  \xq-"

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

7.1. Indentation Spaces

In YAML block styles, structure is determined by indentation. In general, indentation is defined as a zero or more space characters at the start of a line. ^?

To maintain portability, tab characters must not be used in indentation, since different systems treat tabs differently. Note that most modern editors may be configured so that pressing the tab key results in the insertion of an appropriate number of spaces.

The amount of indentation is a presentation detail and must not be used to convey content information.

A block style construct is terminated when encountering a line which is less indented than the construct. The productions use the notation “indentation-spaces-less-than(n)” and “indentation-spaces-less-or-equal(n)” to express this.

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

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

{ "Not indented": {
    "By one space": "By four\n  spaces\n",
    "Flow style": [
      "By two",
      "Also by two",
      "Still by two" ] } }

The “-”, “?” and “:” characters used to denote block collection entries are perceived by people to be part of the indentation. This is handled on a case-by-case basis by the relevant productions.

?·a
:·-→b
··-··-→c
·····-·d

{ "a":
  [ "b",
    [ "c",
      "d" ] ] }

7.2. Separation Spaces

Outside indentation and scalar content, YAML uses white space characters for separation between tokens within a line. Note that such white space may safely include tab characters.

Separation spaces are a presentation detail and must not be used to convey content information.

-·foo:→·bar
- -·baz
  -→baz

[ { "foo": "bar" },
  [ "baz",
    "baz" ] ]

7.3. Line Prefixes

Inside scalar content, each line begins with a non-content line prefix. This prefix always includes the indentation. For flow scalar styles it additionally includes all leading white space, which may contain tab characters.

Line prefixes are a presentation detail and must not be used to convey content information.

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

{ "plain": "text lines",
  "quoted": "text lines",
  "block": "text\n \tlines\n" }

7.4. Empty Lines

An empty line line consists of the non-content prefix followed by a line break.

The semantics of empty lines depend on the scalar style they appear in. This is handled on a case-by-case basis by the relevant productions.

Folding:
  "Empty line
···→
  as a line feed"
Chomping: |
  Clipped empty lines
·

{ "Folding": "Empty line\nas a line feed",
  "Chomping": "Clipped empty lines\n" }

7.5. Line Folding

Line folding allows long lines to be broken for readability, while retaining the semantics of the original long line. If a line break is followed by an empty line, it is trimmed; the first line break is discarded and the rest are retained as content.

Otherwise (the following line is not empty), the line break is converted to a single space (x20).

A folded non-empty line may end with either of the above line breaks.

>-
  trimmed↓
··↓
·↓
↓
  as↓
  space

"trimmed\n\n\nas space"

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

Block Folding

In the folded block style, the final line break and trailing empty lines are subject to chomping and are never folded. In addition, folding does not apply to line breaks surrounding text lines that contain leading white space. Note that such a more-indented line may consist only of such leading white space.

The combined effect of the block line folding rules is that each “paragraph” is interpreted as a line, empty lines are interpreted as a line feed and the formatting of more-indented lines is preserved.

>
··foo·↓
·↓
··→·bar↓
↓
··baz↓

"foo \n\n\t bar\n\nbaz\n"

Flow Folding

Folding in flow styles provides more relaxed semantics. Flow styles typically depend on explicit indicators rather than indentation to convey structure. Hence spaces preceding or following the text in a line are a presentation detail and must not be used to convey content information. Once all such spaces have been discarded, all line breaks are folded without exception.

The combined effect of the flow line folding rules is that each “paragraph” is interpreted as a line, empty lines are interpreted as line feeds and text can be freely more-indented without affecting the content information.

"↓
··foo·↓
·↓
··→·bar↓
↓
··baz↓ "

" foo\nbar\nbaz "

7.6. Comments

An explicit comment is marked by a “#” indicator. Comments are a presentation detail and must not be used to convey content information.

Comments must be separated from other tokens by white space characters.

Note: To ensure JSON compatibility, YAML processors must allow for the omission of the final comment line break of the input stream. However, as this confuses many tools, YAML processors should terminate the stream with an explicit line break on output.

key:····# Comment↓
  valueeof

{ "key": "value" }

Outside scalar content, comments may appear on a line of their own, independent of the indentation level. Note that outside scalar content, a line containing only white space characters is taken to be a comment line.

··# Comment↓
···↓
↓

# This stream contains no
# documents, only comments.

In most cases, when a line may end with a comment, YAML allows it to be followed by additional comment lines. The only exception is a comment ending a block scalar header.

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

{ "key": "value" }

7.7. Separation Lines

Implicit keys are restricted to a single line. In all other cases, YAML allows tokens to be separated by multi-line (possibly empty) comments.

Note that structures following multi-line comment separation must be properly indented, even though there is no such restriction on the separation comment lines themselves.

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

{ { "first": "Sammy",
    "last": "Sosa" }: {
    "hr": 65,
    "avg": 0.278 } }

7.8. Directives

Directives are instructions to the YAML processor. 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.

Directives are a presentation detail and must not be used to convey content information.

Each directive is specified on a separate non-indented line starting with the “%” indicator, followed by the directive name and a list of parameters. The semantics of these parameters depends 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"

"foo"

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

"foo"

%YAML 1.3
%YAML 1.2
foo

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

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

"foo"

%TAG ! !foo
%TAG ! !foo
bar

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

# Private
!foo "bar"
...
# Global
%TAG ! tag:example.com,2000:app/
---
!foo "bar"

!<!foo> "bar"
---
!<tag:example.com,2000:app/foo> "bar"

%TAG !! tag:example.com,2000:app/
---
!!int 1 - 3 # Interval, not integer

!<tag:example.com,2000:app/int> "1 - 3"

%TAG !e! tag:example.com,2000:app/
---
!e!foo "bar"

!<tag:example.com,2000:app/foo> "bar"

%TAG !m! !my-
--- # Bulb here
!m!light fluorescent
...
%TAG !m! !my-
--- # Color here
!m!light green

!<!my-light> "fluorescent"
---
!<!my-light> "green"

%TAG !e! tag:example.com,2000:app/
---
- !e!foo "bar"

- !<tag:example.com,2000:app/foo> "bar"

7.9. Node Properties

Each node may have two optional properties, anchor and tag, in addition to its content. Node properties may be specified in any order before the node’s content. Either or both may be omitted.

!!str &a1 "foo":
  !!str bar
&a2 baz : *a1

{ &B1 "foo": "bar",
  "baz": *B1 }

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

{ "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 !e! tag:example.com,2000:app/
---
- !local foo
- !!str bar
- !e!tag%21 baz

[ !<!local> "foo",
  !<tag:yaml.org,2002:str> "bar",
  !<tag:example.com,2000:app/tag!> "baz" ]

%TAG !e! tag:example,2000:app/
---
- !e! foo
- !h!bar baz

ERROR:
- The !e! handle has no suffix.
- The !h! handle wasn't declared.

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

[ "12",
  12,
  "12" ]

First occurrence: &anchor Value
Second occurrence: *anchor

{ "First occurrence": &A "Value",
  "Second occurrence": *A }

8.1. Alias Nodes

Subsequent occurrences of a previously serialized node are presented as alias nodes. 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 is denoted by the “*” indicator. The alias refers to the most recent preceding node having the same anchor. It is an error for an alias node to 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 Foo
Second occurrence: *anchor
Override anchor: &anchor Bar
Reuse anchor: *anchor

{ "First occurrence": &A "Foo",
  "Override anchor": &B "Bar",
  "Second occurrence": *A,
  "Reuse anchor": *B }

8.2. Empty Nodes

YAML allows the node content to be omitted in many cases. Nodes with empty content are interpreted as if they were plain scalars with an empty value. Such nodes are commonly resolved to a “null” value.

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

{
  foo : !!str°,
  !!str° : bar,
}

{ "foo": "",
  "": "bar" }

Both the node’s properties and node content are optional. This allows for a completely empty node. Completely empty nodes are only valid when following some explicit indication for their existence.

{
  ? foo :°,
  °: bar,
}

{ "foo": null,
  null : "bar" }

8.3. Flow Scalar Styles

YAML provides three flow scalar styles: double-quoted, single-quoted and plain (unquoted). Each provides a different trade-off between readability and expressive power.

The scalar style is a presentation detail and must not be used to convey content information, with the exception that plain scalars are distinguished for the purpose of tag resolution.

"implicit block key" : [
  "implicit flow key" : value,
 ]

{ "implicit block key":
  [ { "implicit flow key": "value" } ] }

"folded·↓
to a space,→↓
·↓
to a line feed, or·→\↓
·\·→non-content"

"folded to a space,\nto a line feed, or \t \tnon-content"

"·1st non-empty↓
↓
·2nd non-empty·
→3rd non-empty·"

" 1st non-empty\n2nd non-empty 3rd non-empty "

'here''s to "quotes"'

"here's to \"quotes\""

'implicit block key' : [
  'implicit flow key' : value,
 ]

{ "implicit block key":
  [ { "implicit flow key": "value" } ] }

'·1st non-empty↓
↓
·2nd non-empty·
→3rd non-empty·'

" 1st non-empty\n2nd non-empty 3rd non-empty "

# Outside flow collection:
- ::vector
- ": - ()"
- Up, up, and away!
- -123
- https://example.com/foo#bar
# Inside flow collection:
- [ ::vector,
  ": - ()",
  "Up, up and away!",
  -123,
  https://example.com/foo#bar ]

[ "::vector",
  ": - ()",
  "Up, up, and away!",
  -123,
  "http://example.com/foo#bar",
  [ "::vector",
    ": - ()",
    "Up, up, and away!",
    -123,
    "http://example.com/foo#bar" ] ]

implicit block key : [
  implicit flow key : value,
 ]

{ "implicit block key":
  [ { "implicit flow key": "value" } ] }

1st non-empty↓
↓
·2nd non-empty·
→3rd non-empty

"1st non-empty\n2nd non-empty 3rd non-empty"

8.4. Flow Collection Styles

A flow collection may be nested within a block collection ([FLOW-OUT context]), nested within another flow collection ([FLOW-IN context]) or be a part of an implicit key ([FLOW-KEY context] or [BLOCK-KEY context]). Flow collection entries are terminated by the “,” indicator. The final “,” may be omitted. This does not cause ambiguity because flow collection entries can never be completely empty.

- [ one, two, ]
- [three ,four]

[ [ "one",
    "two" ],
  [ "three",
    "four" ] ]

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

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

- { one : two , three: four , }
- {five: six,seven : eight}

[ { "one": "two",
    "three": "four" },
  { "five": "six",
    "seven": "eight" } ]

{
? explicit: entry,
implicit: entry,
?°°
}

{ "explicit": "entry",
  "implicit": "entry",
  null: null }

{
unquoted·:·"separate",
https://foo.com,
omitted value:°,
°:·omitted key,
}

{ "unquoted": "separate",
  "http://foo.com": null,
  "omitted value": null,
  null: "omitted key" }

{
"adjacent":value,
"readable":·value,
"empty":°
}

{ "adjacent": "value",
  "readable": "value",
  "empty": null }

[
foo: bar
]

[ { "foo": "bar" } ]

[
? foo
 bar : baz
]

[ { "foo bar": "baz" } ]

- [ YAML·: separate ]
- [ °: empty key entry ]
- [ {JSON: like}:adjacent ]

[ [ { "YAML": "separate" } ],
  [ { null: "empty key entry" } ],
  [ { { "JSON": "like" }: "adjacent" } ] ]

[ foo
 bar: invalid,
 "foo_...>1K characters..._bar": invalid ]

ERROR:
- The foo bar key spans multiple lines
- The foo...bar key is too long

8.5. Flow Nodes

JSON-like flow styles all have explicit start and end indicators. The only flow style that does not have this property is the plain scalar. Note that none of the “JSON-like” styles is actually acceptable by JSON. Even the double-quoted style is a superset of the JSON string format.

- [ a, b ]
- { a: b }
- "a"
- 'b'
- c

[ [ "a", "b" ],
  { "a": "b" },
  "a",
  "b",
  "c" ]

A complete flow node also has optional node properties, except for alias nodes which refer to the anchored node properties.

- !!str "a"
- 'b'
- &anchor "c"
- *anchor
- !!str°

[ "a",
  "b",
  "c",
  "c",
  "" ]

9.1. Block Scalar Styles

YAML provides two block scalar styles, literal and folded. Each provides a different trade-off between readability and expressive power.

- | # Empty header↓
 literal
- >1 # Indentation indicator↓
 ·folded
- |+ # Chomping indicator↓
 keep

- >1- # Both indicators↓
 ·strip

[ "literal\n",
  " folded\n",
  "keep\n\n",
  " strip" ]

- |°
·detected
- >°
·
··
··# detected
- |1
··explicit
- >°
·→
·detected

[ "detected\n",
  "\n\n# detected\n",
  " explicit\n",
  "\t\ndetected\n" ]

- |
··
·text
- >
··text
·text
- |2
·text

ERROR:
- A leading all-space line must
  not have too many spaces.
- A following text line must
  not be less indented.
- The text is less indented
  than the indicated level.

strip: |-
  text↓
clip: |
  text↓
keep: |+
  text↓

{ "strip": "text",
  "clip": "text\n",
  "keep": "text\n" }

# Strip
  # Comments:
strip: |-
  # text↓
··⇓
·# Clip
··# comments:
↓
clip: |
  # text↓
·↓
·# Keep
··# comments:
↓
keep: |+
  # text↓
↓
·# Trail
··# comments.

{ "strip": "# text",
  "clip": "# text\n",
  "keep": "# text\n\n" }

strip: >-
↓
clip: >
↓
keep: |+
↓

{ "strip": "",
  "clip": "",
  "keep": "\n" }

|↓
·literal↓
·→text↓
↓

"literal\n\ttext\n"

|
·
··
··literal↓
···↓
··
··text↓
↓
·# Comment

"\n\nliteral\n·\n\ntext\n"

>↓
·folded↓
·text↓
↓

"folded text\n"

>

·folded↓
·line↓
↓
·next
·line↓
   * bullet

   * list
   * lines

·last↓
·line↓

# Comment

"\nfolded line\nnext line\n  \
* bullet\n \n  * list\n  \
* lines\n\nlast line\n"

>

 folded
 line

 next
 line
···* bullet↓
↓
···* list↓
···* lines↓

 last
 line

# Comment

"\nfolded line\nnext line\n  \
* bullet\n \n  * list\n  \
* lines\n\nlast line\n"

>
↓
 folded
 line↓
↓
 next
 line↓
   * bullet

   * list
   * lines↓
↓
 last
 line

# Comment

"\nfolded line\nnext line\n  \
* bullet\n \n  * list\n  \
* lines\n\nlast line\n"

>

 folded
 line

 next
 line
   * bullet

   * list
   * lines

 last
 line↓
↓
# Comment

"\nfolded line\nnext line\n  \
* bullet\n \n  * list\n  \
* lines\n\nlast line\n"

9.2. Block Collection Styles

For readability, block collections styles are not denoted by any indicator. Instead, YAML uses a lookahead method, where a block collection is distinguished from a plain scalar only when a key/value pair or a sequence entry is seen.

block sequence:
··- one↓
  - two : three↓

{ "block sequence": [
    "one",
    { "two": "three" } ] }

-° # Empty
- |
 block node
-·- one # Compact
··- two # sequence
- one: two # Compact mapping

[ null,
  "block node\n",
  [ "one", "two" ],
  { "one": "two" } ]

block mapping:
·key: value↓

{ "block mapping": {
    "key": "value" } }

? explicit key # Empty value↓°
? |
  block key↓
:·- one # Explicit compact
··- two # block value↓

{ "explicit key": null,
  "block key\n": [
    "one",
    "two" ] }

plain key: in-line value
°:° # Both empty
"quoted key":
- entry

{ "plain key": "in-line value",
  null: null,
  "quoted key": [ "entry" ] }

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

[ { "sun": "yellow" },
  { { "earth": "blue" }:
      { "moon": "white" } } ]

-↓
··"flow in block"↓
-·>
 Block scalar↓
-·!!map # Block collection
  foo : bar↓

[ "flow in block",
  "Block scalar\n",
  { "foo": "bar" } ]

literal: |2
··value
folded:↓
···!foo
··>1
·value

{ "literal": "value",
  "folded": !<!foo> "value" }

sequence: !!seq
- entry
- !!seq
 - nested
mapping: !!map
 foo: bar

{ "sequence": [
    "entry",
    [ "nested" ] ],
  "mapping": { "foo": "bar" } }

10.1. Documents

A YAML character stream may contain several documents. Each document is completely independent from the rest.

⇔# Comment
# lines
Document

"Document"

%YAML 1.3
---
Document
... # Suffix

"Document"

Bare
document
...
# No document
...
|
%!PS-Adobe-2.0 # Not the first line

"Bare document"
---
"%!PS-Adobe-2.0\n"

---
{ matches
% : 20 }
...
---
# Empty
...

{ "matches %": 20 }
---
null

%YAML 1.3
--- |
%!PS-Adobe-2.0
...
%YAML 1.3
---
# Empty
...

"%!PS-Adobe-2.0\n"
---
null

10.2. Streams

A YAML stream consists of zero or more documents. Subsequent documents require some sort of separation marker line. If a document is not terminated by a document end marker line, then the following document must begin with a directives end marker line.

Document
---
# Empty
...
%YAML 1.3
---
matches %: 20

"Document"
---
null
---
{ "matches %": 20 }

A sequence of bytes is a well-formed stream if, taken as a whole, it complies with the above yaml-stream production.

A.1. Production Syntax

Productions are defined using the syntax production-name ::= term, where a term is either:

An atomic term

• A quoted string ("abc"), which matches that concatenation of characters. A single character is usually written with single quotes ('a').
• A hexadecimal number (x0A), which matches the character at that Unicode code point.
• A range of hexadecimal numbers ([x20-x7E]), which matches any character whose Unicode code point is within that range.
• The name of a production (yaml-character), which matches that production.

A lookaround

• [ lookahead = term ], which matches the empty string if term would match.
• [ lookahead ≠ term ], which matches the empty string if term would not match.
• [ lookbehind = term ], which matches the empty string if term would match beginning at any prior point on the line and ending at the current position.

A special production

• <start-of-line>, which matches the empty string at the beginning of a line.
• <end-of-input>, matches the empty string at the end of the input.

A parenthesized term

Matches its contents.

A concatenation

Is term-one term-two, which matches term-one followed by term-two.

A alternation

Is term-one | term-two, which matches the term-one if possible, or term-two otherwise.

A quantified term:

• term?, which matches (term | "").
• term*, which matches (term term* | "").
• term+, which matches (term term*).

Note: Quantified terms are always greedy.

The order of precedence is parenthesization, then quantification, then concatenation, then alternation.

Some lines in a production definition might have a comment like:

production-a ::=
  production-b      # clarifying comment

These comments are meant to be informative only. For instance a comment that says # not followed by non-ws char just means that you should be aware that actual production rules will behave as described even though it might not be obvious from the content of that particular production alone.

production-a(n) ::= production-b(n)

production-a(0) ::= production-b(0)
production-a(1) ::= production-b(1)
…

production-a(n) ::=
  ( production-b(n+m) production-c(n+m) )+

production-a(0) ::=
    ( production-b(0) production-c(0) )+
  | ( production-b(1) production-c(1) )+
  | …
production-a(1) ::=
    ( production-b(1) production-c(1) )+
  | ( production-b(2) production-c(2) )+
  | …
…

A.2. Document Stream Productions

The YAML 1.3 syntax productions are presented here in a top down fashion.

[1]
yaml-stream ::=
  document-prefix*
  any-document?
  (
      (
        document-suffix+
        document-prefix*
        any-document?
      )
    | byte-order-mark
    | comment-line
    | start-indicator-and-document
  )*

[2]
document-prefix ::=
  byte-order-mark?
  comment-line*

[3]
document-suffix ::=
  document-end-indicator
  comment-lines

[4]
document-start-indicator ::=
  "---"

[5]
document-end-indicator ::=
  "..."                             # Not followed by non-ws char

[6]
any-document ::=
    directives-and-document
  | start-indicator-and-document
  | bare-document

[7]
directives-and-document ::=
  directive-line+
  start-indicator-and-document

[8]
start-indicator-and-document ::=
  document-start-indicator
  (
      bare-document
    | (
        empty-node
        comment-lines
      )
  )

[9]
bare-document ::=
  block-node(-1,BLOCK-IN)
  /* Excluding forbidden-content */

[10]
directive-line ::=
  '%'
  (
      yaml-directive-line
    | tag-directive-line
    | reserved-directive-line
  )
  comment-lines

[11]
forbidden-content ::=
  <start-of-line>
  (
      document-start-indicator
    | document-end-indicator
  )
  (
      line-ending
    | blank-character
  )

[12]
block-node(n,c) ::=
    block-node-in-a-block-node(n,c)
  | flow-node-in-a-block-node(n)

[13]
block-node-in-a-block-node(n,c) ::=
    block-scalar(n,c)
  | block-collection(n,c)

[14]
flow-node-in-a-block-node(n) ::=
  separation-characters(n+1,FLOW-OUT)
  flow-node(n+1,FLOW-OUT)
  comment-lines

[15]
block-collection(n,c) ::=
  (
    separation-characters(n+1,c)
    node-properties(n+1,c)
  )?
  comment-lines
  (
      block-sequence-context(n,c)
    | block-mapping(n)
  )

[16]
block-sequence-context(n,BLOCK-OUT) ::= block-sequence(n-1)
block-sequence-context(n,BLOCK-IN)  ::= block-sequence(n)

[17]
block-scalar(n,c) ::=
  separation-characters(n+1,c)
  (
    node-properties(n+1,c)
    separation-characters(n+1,c)
  )?
  (
      block-literal-scalar(n)
    | block-folded-scalar(n)
  )

[18]
block-mapping(n) ::=
  (
    indentation-spaces(n+1+m)
    block-mapping-entry(n+1+m)
  )+

[19]
block-mapping-entry(n) ::=
    block-mapping-explicit-entry(n)
  | block-mapping-implicit-entry(n)

[20]
block-mapping-explicit-entry(n) ::=
  block-mapping-explicit-key(n)
  (
      block-mapping-explicit-value(n)
    | empty-node
  )

[21]
block-mapping-explicit-key(n) ::=
  '?'                               # Not followed by non-ws char
  block-indented-node(n,BLOCK-OUT)

[22]
block-mapping-explicit-value(n) ::=
  indentation-spaces(n)
  ':'                               # Not followed by non-ws char
  block-indented-node(n,BLOCK-OUT)

[23]
block-mapping-implicit-entry(n) ::=
  (
      block-mapping-implicit-key
    | empty-node
  )
  block-mapping-implicit-value(n)

[24]
block-mapping-implicit-key ::=
    implicit-json-key(BLOCK-KEY)
  | implicit-yaml-key(BLOCK-KEY)

[25]
block-mapping-implicit-value(n) ::=
  ':'                               # Not followed by non-ws char
  (
      block-node(n,BLOCK-OUT)
    | (
        empty-node
        comment-lines
      )
  )

[26]
compact-mapping(n) ::=
  block-mapping-entry(n)
  (
    indentation-spaces(n)
    block-mapping-entry(n)
  )*

[27]
block-sequence(n) ::=
  (
    indentation-spaces(n+1+m)
    block-sequence-entry(n+1+m)
  )+

[28]
block-sequence-entry(n) ::=
  '-'
  [ lookahead ≠ non-space-character ]
  block-indented-node(n,BLOCK-IN)

[29]
block-indented-node(n,c) ::=
    (
      indentation-spaces(m)
      (
          compact-sequence(n+1+m)
        | compact-mapping(n+1+m)
      )
    )
  | block-node(n,c)
  | (
      empty-node
      comment-lines
    )

[30]
compact-sequence(n) ::=
  block-sequence-entry(n)
  (
    indentation-spaces(n)
    block-sequence-entry(n)
  )*

[31]
block-literal-scalar(n) ::=
  '|'
  block-scalar-indicators(t)
  literal-scalar-content(n+m,t)

[32]
literal-scalar-content(n,t) ::=
  (
    literal-scalar-line-content(n)
    literal-scalar-next-line(n)*
    block-scalar-chomp-last(t)
  )?
  block-scalar-chomp-empty(n,t)

[33]
literal-scalar-line-content(n) ::=
  empty-line(n,BLOCK-IN)*
  indentation-spaces(n)
  non-break-character+

[34]
literal-scalar-next-line(n) ::=
  break-as-line-feed
  literal-scalar-line-content(n)

[35]
block-folded-scalar(n) ::=
  '>'
  block-scalar-indicators(t)
  folded-scalar-content(n+m,t)

[36]
folded-scalar-content(n,t) ::=
  (
    folded-scalar-lines-different-indentation(n)
    block-scalar-chomp-last(t)
  )?
  block-scalar-chomp-empty(n,t)

[37]
folded-scalar-lines-different-indentation(n) ::=
  folded-scalar-lines-same-indentation(n)
  (
    break-as-line-feed
    folded-scalar-lines-same-indentation(n)
  )*

[38]
folded-scalar-lines-same-indentation(n) ::=
  empty-line(n,BLOCK-IN)*
  (
      folded-scalar-lines(n)
    | folded-scalar-spaced-lines(n)
  )

[39]
folded-scalar-lines(n) ::=
  folded-scalar-text(n)
  (
    folded-whitespace(n,BLOCK-IN)
    folded-scalar-text(n)
  )*

[40]
folded-scalar-spaced-lines(n) ::=
  folded-scalar-spaced-text(n)
  (
    line-break-and-empty-lines(n)
    folded-scalar-spaced-text(n)
  )*

[41]
folded-scalar-text(n) ::=
  indentation-spaces(n)
  non-space-character
  non-break-character*

[42]
line-break-and-empty-lines(n) ::=
  break-as-line-feed
  empty-line(n,BLOCK-IN)*

[43]
folded-scalar-spaced-text(n) ::=
  indentation-spaces(n)
  blank-character
  non-break-character*

[44]
block-scalar-indicators(t) ::=
  (
      (
        block-scalar-indentation-indicator
        block-scalar-chomping-indicator(t)
      )
    | (
        block-scalar-chomping-indicator(t)
        block-scalar-indentation-indicator
      )
  )
  (
      comment-line
    | line-ending
  )

[45]
block-scalar-indentation-indicator ::=
  decimal-digit-1-9

[46]
block-scalar-chomping-indicator(STRIP) ::= '-'
block-scalar-chomping-indicator(KEEP)  ::= '+'
block-scalar-chomping-indicator(CLIP)  ::= ""

[47]
block-scalar-chomp-last(STRIP) ::= line-break | <end-of-input>
block-scalar-chomp-last(CLIP)  ::= break-as-line-feed | <end-of-input>
block-scalar-chomp-last(KEEP)  ::= break-as-line-feed | <end-of-input>

[48]
block-scalar-chomp-empty(n,STRIP) ::= line-strip-empty(n)
block-scalar-chomp-empty(n,CLIP)  ::= line-strip-empty(n)
block-scalar-chomp-empty(n,KEEP)  ::= line-keep-empty(n)

[49]
line-strip-empty(n) ::=
  (
    indentation-spaces-less-or-equal(n)
    line-break
  )*
  line-trail-comments(n)?

[50]
line-keep-empty(n) ::=
  empty-line(n,BLOCK-IN)*
  line-trail-comments(n)?

[51]
line-trail-comments(n) ::=
  indentation-spaces-less-than(n)
  comment-content
  line-ending
  comment-line*

A.3. Flow Style Productions

[52]
flow-node(n,c) ::=
    alias-node
  | flow-content(n,c)
  | (
      node-properties(n,c)
      (
        (
          separation-characters(n,c)
          flow-content(n,c)
        )
        | empty-node
      )
    )

[53]
flow-content(n,c) ::=
    flow-yaml-content(n,c)
  | flow-json-content(n,c)

[54]
flow-yaml-content(n,c) ::=
  flow-plain-scalar(n,c)

[55]
flow-json-content(n,c) ::=
    flow-sequence(n,c)
  | flow-mapping(n,c)
  | single-quoted-scalar(n,c)
  | double-quoted-scalar(n,c)

[56]
flow-mapping(n,c) ::=
  '{'
  separation-characters(n,c)?
  flow-mapping-context(n,c)?
  '}'

[57]
flow-mapping-entries(n,c) ::=
  flow-mapping-entry(n,c)
  separation-characters(n,c)?
  (
    ','
    separation-characters(n,c)?
    flow-mapping-entries(n,c)?
  )?

[58]
flow-mapping-entry(n,c) ::=
    (
      '?'                           # Not followed by non-ws char
      separation-characters(n,c)
      flow-mapping-explicit-entry(n,c)
    )
  | flow-mapping-implicit-entry(n,c)

[59]
flow-mapping-explicit-entry(n,c) ::=
    flow-mapping-implicit-entry(n,c)
  | (
      empty-node
      empty-node
    )

[60]
flow-mapping-implicit-entry(n,c) ::=
    flow-mapping-yaml-key-entry(n,c)
  | flow-mapping-empty-key-entry(n,c)
  | flow-mapping-json-key-entry(n,c)

[61]
flow-mapping-yaml-key-entry(n,c) ::=
  flow-yaml-node(n,c)
  (
      (
        separation-characters(n,c)?
        flow-mapping-separate-value(n,c)
      )
    | empty-node
  )

[62]
flow-mapping-empty-key-entry(n,c) ::=
  empty-node
  flow-mapping-separate-value(n,c)

[63]
flow-mapping-separate-value(n,c) ::=
  ':'
  [ lookahead ≠ non-space-plain-scalar-character(c) ]
  (
      (
        separation-characters(n,c)
        flow-node(n,c)
      )
    | empty-node
  )

[64]
flow-mapping-json-key-entry(n,c) ::=
  flow-json-node(n,c)
  (
      (
        separation-characters(n,c)?
        flow-mapping-adjacent-value(n,c)
      )
    | empty-node
  )

[65]
flow-mapping-adjacent-value(n,c) ::=
  ':'
  (
      (
        separation-characters(n,c)?
        flow-node(n,c)
      )
    | empty-node
  )

[66]
flow-pair(n,c) ::=
    (
      '?'                           # Not followed by non-ws char
      separation-characters(n,c)
      flow-mapping-explicit-entry(n,c)
    )
  | flow-pair-entry(n,c)

[67]
flow-pair-entry(n,c) ::=
    flow-pair-yaml-key-entry(n,c)
  | flow-mapping-empty-key-entry(n,c)
  | flow-pair-json-key-entry(n,c)

[68]
flow-pair-yaml-key-entry(n,c) ::=
  implicit-yaml-key(FLOW-KEY)
  flow-mapping-separate-value(n,c)

[69]
flow-pair-json-key-entry(n,c) ::=
  implicit-json-key(FLOW-KEY)
  flow-mapping-adjacent-value(n,c)

[70]
implicit-yaml-key(c) ::=
  flow-yaml-node(0,c)
  separation-blanks?
  /* At most 1024 characters altogether */

[71]
implicit-json-key(c) ::=
  flow-json-node(0,c)
  separation-blanks?
  /* At most 1024 characters altogether */

[72]
flow-yaml-node(n,c) ::=
    alias-node
  | flow-yaml-content(n,c)
  | (
      node-properties(n,c)
      (
          (
            separation-characters(n,c)
            flow-yaml-content(n,c)
          )
        | empty-node
      )
    )

[73]
flow-json-node(n,c) ::=
  (
    node-properties(n,c)
    separation-characters(n,c)
  )?
  flow-json-content(n,c)

[74]
flow-sequence(n,c) ::=
  '['
  separation-characters(n,c)?
  flow-sequence-context(n,c)?
  ']'

[75]
flow-sequence-entries(n,c) ::=
  flow-sequence-entry(n,c)
  separation-characters(n,c)?
  (
    ','
    separation-characters(n,c)?
    flow-sequence-entries(n,c)?
  )?

[76]
flow-sequence-entry(n,c) ::=
    flow-pair(n,c)
  | flow-node(n,c)

[77]
double-quoted-scalar(n,c) ::=
  '"'
  double-quoted-text(n,c)
  '"'

[78]
double-quoted-text(n,BLOCK-KEY) ::= double-quoted-one-line
double-quoted-text(n,FLOW-KEY)  ::= double-quoted-one-line
double-quoted-text(n,FLOW-OUT)  ::= double-quoted-multi-line(n)
double-quoted-text(n,FLOW-IN)   ::= double-quoted-multi-line(n)

[79]
double-quoted-multi-line(n) ::=
  double-quoted-first-line
  (
      double-quoted-next-line(n)
    | blank-character*
  )

[80]
double-quoted-one-line ::=
  non-break-double-quoted-character*

[81]
double-quoted-first-line ::=
  (
    blank-character*
    non-space-double-quoted-character
  )*

[82]
double-quoted-next-line(n) ::=
  (
      double-quoted-line-continuation(n)
    | flow-folded-whitespace(n)
  )
  (
    non-space-double-quoted-character
    double-quoted-first-line
    (
        double-quoted-next-line(n)
      | blank-character*
    )
  )?

[83]
non-space-double-quoted-character ::=
    non-break-double-quoted-character
  - blank-character

[84]
non-break-double-quoted-character ::=
    double-quoted-scalar-escape-character
  | (
        json-character
      - '\'
      - '"'
    )

[85]
double-quoted-line-continuation(n) ::=
  blank-character*
  '\'
  line-break
  empty-line(n,FLOW-IN)*
  indentation-spaces-plus-maybe-more(n)

[86]
flow-mapping-context(n,FLOW-OUT)  ::= flow-sequence-entries(n,FLOW-IN)
flow-mapping-context(n,FLOW-IN)   ::= flow-sequence-entries(n,FLOW-IN)
flow-mapping-context(n,BLOCK-KEY) ::= flow-sequence-entries(n,FLOW-KEY)
flow-mapping-context(n,FLOW-KEY)  ::= flow-sequence-entries(n,FLOW-KEY)

[87]
flow-sequence-context(n,FLOW-OUT)  ::= flow-sequence-entries(n,FLOW-IN)
flow-sequence-context(n,FLOW-IN)   ::= flow-sequence-entries(n,FLOW-IN)
flow-sequence-context(n,BLOCK-KEY) ::= flow-sequence-entries(n,FLOW-KEY)
flow-sequence-context(n,FLOW-KEY)  ::= flow-sequence-entries(n,FLOW-KEY)

[88]
single-quoted-scalar(n,c) ::=
  "'"
  single-quoted-text(n,c)
  "'"

[89]
single-quoted-text(BLOCK-KEY) ::= single-quoted-one-line
single-quoted-text(FLOW-KEY)  ::= single-quoted-one-line
single-quoted-text(FLOW-OUT)  ::= single-quoted-multi-line(n)
single-quoted-text(FLOW-IN)   ::= single-quoted-multi-line(n)

[90]
single-quoted-multi-line(n) ::=
  single-quoted-first-line
  (
      single-quoted-next-line(n)
    | blank-character*
  )

[91]
single-quoted-one-line ::=
  non-break-single-quoted-character*

[92]
single-quoted-first-line ::=
  (
    blank-character*
    non-space-single-quoted-character
  )*

[93]
single-quoted-next-line(n) ::=
  flow-folded-whitespace(n)
  (
    non-space-single-quoted-character
    single-quoted-first-line
    (
        single-quoted-next-line(n)
      | blank-character*
    )
  )?

[94]
non-space-single-quoted-character ::=
    non-break-single-quoted-character
  - blank-character

[95]
non-break-single-quoted-character ::=
    single-quoted-escaped-single-quote
  | (
        json-character
      - "'"
    )

[96]
single-quoted-escaped-single-quote ::=
  "''"

[97]
flow-plain-scalar(n,FLOW-OUT)  ::= plain-scalar-multi-line(n,FLOW-OUT)
flow-plain-scalar(n,FLOW-IN)   ::= plain-scalar-multi-line(n,FLOW-IN)
flow-plain-scalar(n,BLOCK-KEY) ::= plain-scalar-single-line(BLOCK-KEY)
flow-plain-scalar(n,FLOW-KEY)  ::= plain-scalar-single-line(FLOW-KEY)

[98]
plain-scalar-multi-line(n,c) ::=
  plain-scalar-single-line(c)
  plain-scalar-next-line(n,c)*

[99]
plain-scalar-single-line(c) ::=
  plain-scalar-first-character(c)
  plain-scalar-line-characters(c)

[100]
plain-scalar-next-line(n,c) ::=
  flow-folded-whitespace(n)
  plain-scalar-characters(c)
  plain-scalar-line-characters(c)

[101]
plain-scalar-line-characters(c) ::=
  (
    blank-character*
    plain-scalar-characters(c)
  )*

[102]
plain-scalar-first-character(c) ::=
    (
        non-space-character
      - '?'                         # Mapping key
      - ':'                         # Mapping value
      - '-'                         # Sequence entry
      - '{'                         # Mapping start
      - '}'                         # Mapping end
      - '['                         # Sequence start
      - ']'                         # Sequence end
      - ','                         # Entry separator
      - '#'                         # Comment
      - '&'                         # Anchor
      - '*'                         # Alias
      - '!'                         # Tag
      - '|'                         # Literal scalar
      - '>'                         # Folded scalar
      - "'"                         # Single quote
      - '"'                         # Double quote
      - '%'                         # Directive
      - '@'                         # Reserved
      - '`'                         # Reserved
    )
  | (
      ( '?' | ':' | '-' )
      [ lookahead = non-space-plain-scalar-character(c) ]
    )

[103]
plain-scalar-characters(c) ::=
    (
        non-space-plain-scalar-character(c)
      - ':'
      - '#'
    )
  | (
      [ lookbehind = non-space-character ]
      '#'
    )
  | (
      ':'
      [ lookahead = non-space-plain-scalar-character(c) ]
    )

[104]
non-space-plain-scalar-character(FLOW-OUT)  ::= block-plain-scalar-character
non-space-plain-scalar-character(FLOW-IN)   ::= flow-plain-scalar-character
non-space-plain-scalar-character(BLOCK-KEY) ::= block-plain-scalar-character
non-space-plain-scalar-character(FLOW-KEY)  ::= flow-plain-scalar-character

[105]
block-plain-scalar-character ::=
  non-space-character

[106]
flow-plain-scalar-character ::=
    non-space-character
  - flow-collection-indicators

[107]
alias-node ::=
  '*'
  anchor-name

[108]
empty-node ::=
  ""

A.4. Structural Productions

[109]
indentation-spaces(0) ::=
  ""

# When n≥0
indentation-spaces(n+1) ::=
  space-character
  indentation-spaces(n)

[110]
indentation-spaces-less-than(1) ::=
  ""

# When n≥1
indentation-spaces-less-than(n+1) ::=
    (
      space-character
      indentation-spaces-less-than(n)
    )
  | ""

[111]
indentation-spaces-less-or-equal(0) ::=
  ""

# When n≥0
indentation-spaces-less-or-equal(n+1) ::=
    (
      space-character
      indentation-spaces-less-or-equal(n)
    )
  | ""

[112]
line-prefix-spaces(n,BLOCK-OUT) ::= indentation-spaces-exact(n)
line-prefix-spaces(n,BLOCK-IN)  ::= indentation-spaces-exact(n)
line-prefix-spaces(n,FLOW-OUT)  ::= indentation-spaces-plus-maybe-more(n)
line-prefix-spaces(n,FLOW-IN)   ::= indentation-spaces-plus-maybe-more(n)

[113]
indentation-spaces-exact(n) ::=
  indentation-spaces(n)

[114]
indentation-spaces-plus-maybe-more(n) ::=
  indentation-spaces(n)
  separation-blanks?

[115]
flow-folded-whitespace(n) ::=
  separation-blanks?
  folded-whitespace(n,FLOW-IN)
  indentation-spaces-plus-maybe-more(n)

[116]
folded-whitespace(n,c) ::=
    (
      line-break
      empty-line(n,c)+
    )
  | break-as-space

[117]
comment-lines ::=
    comment-line+
  | <start-of-line>

[118]
comment-line ::=
  separation-blanks
  comment-content?
  line-ending

[119]
comment-content ::=
  '#'
  non-break-character*

[120]
empty-line(n,c) ::=
  (
      line-prefix-spaces(n,c)
    | indentation-spaces-less-than(n)
  )
  break-as-line-feed

[121]
separation-characters(n,BLOCK-OUT) ::= separation-lines(n)
separation-characters(n,BLOCK-IN)  ::= separation-lines(n)
separation-characters(n,FLOW-OUT)  ::= separation-lines(n)
separation-characters(n,FLOW-IN)   ::= separation-lines(n)
separation-characters(n,BLOCK-KEY) ::= separation-blanks
separation-characters(n,FLOW-KEY)  ::= separation-blanks

[122]
separation-lines(n) ::=
    (
      comment-lines
      indentation-spaces-plus-maybe-more(n)
    )
  | separation-blanks

[123]
separation-blanks ::=
    blank-character+
  | <start-of-line>

[124]
yaml-directive-line ::=
  "YAML"
  separation-blanks
  yaml-version-number

[125]
yaml-version-number ::=
  decimal-digit+
  '.'
  decimal-digit+

[126]
reserved-directive-line ::=
  directive-name
  (
    separation-blanks
    directive-parameter
  )*

[127]
directive-name ::=
  non-space-character+

[128]
directive-parameter ::=
  non-space-character+

[129]
tag-directive-line ::=
  "TAG"
  separation-blanks
  tag-handle
  separation-blanks
  tag-prefix

[130]
tag-handle ::=
    named-tag-handle
  | secondary-tag-handle
  | primary-tag-handle

[131]
named-tag-handle ::=
  '!'
  word-character+
  '!'

[132]
secondary-tag-handle ::=
  "!!"

[133]
primary-tag-handle ::=
  '!'

[134]
tag-prefix ::=
    local-tag-prefix
  | global-tag-prefix

[135]
local-tag-prefix ::=
  '!'
  uri-character*

[136]
global-tag-prefix ::=
  tag-character
  uri-character*

[137]
node-properties(n,c) ::=
    (
      anchor-property
      (
        separation-characters(n,c)
        tag-property
      )?
    )
  | (
      tag-property
      (
        separation-characters(n,c)
        anchor-property
      )?
    )

[138]
anchor-property ::=
  '&'
  anchor-name

[139]
anchor-name ::=
  anchor-character+

[140]
anchor-character ::=
    non-space-character
  - flow-collection-indicators

[141]
tag-property ::=
    verbatim-tag
  | shorthand-tag
  | non-specific-tag

[142]
verbatim-tag ::=
  "!<"
  uri-character+
  '>'

[143]
shorthand-tag ::=
  tag-handle
  tag-character+

[144]
non-specific-tag ::=
  '!'

A.5. Character Productions

[145]
byte-order-mark ::=
  xFEFF

[146]
yaml-character ::=
                                    # 8 bit
    x09                             # Tab
  | x0A                             # Line feed
  | x0D                             # Carriage return
  | [x20-x7E]                       # Printable ASCII
                                    # 16 bit
  | x85                             # Next line (NEL)
  | [xA0-xD7FF]                     # Basic multilingual plane (BMP)
  | [xE000-xFFFD]                   # Additional unicode areas
  | [x010000-x10FFFF]               # 32 bit

[147]
json-character ::=
    x09                             # Tab
  | [x20-x10FFFF]                   # Non-C0-control characters

[148]
non-space-character ::=
    non-break-character
  - blank-character

[149]
non-break-character ::=
    yaml-character
  - x0A
  - x0D
  - byte-order-mark

[150]
blank-character ::=
    x20                             # Space
  | x09                             # Tab

[151]
space-character ::=
  x20

[152]
line-ending ::=
    line-break
  | <end-of-input>

[153]
break-as-space ::=
  line-break

[154]
break-as-line-feed ::=
  line-break

[155]
line-break ::=
    (
      x0D                           # Carriage return
      x0A                           # Line feed
    )
  | x0D
  | x0A

[156]
flow-collection-indicators ::=
    '{'                             # Flow mapping start
  | '}'                             # Flow mapping end
  | '['                             # Flow sequence start
  | ']'                             # Flow sequence end

[157]
double-quoted-scalar-escape-character ::=
  '\'
  (
      '0'
    | 'a'
    | 'b'
    | 't' | x09
    | 'n'
    | 'v'
    | 'f'
    | 'r'
    | 'e'
    | x20
    | '"'
    | '/'
    | '\'
    | 'N'
    | '_'
    | 'L'
    | 'P'
    | ( 'x' hexadecimal-digit{2} )
    | ( 'u' hexadecimal-digit{4} )
    | ( 'U' hexadecimal-digit{8} )
  )

[158]
tag-character ::=
    uri-character
  - '!'
  - flow-collection-indicators

[159]
uri-character ::=
    (
      '%'
      hexadecimal-digit{2}
    )
  | word-character
  | '#'
  | ';'
  | '/'
  | '?'
  | ':'
  | '@'
  | '&'
  | '='
  | '+'
  | '$'
  | ','
  | '_'
  | '.'
  | '!'
  | '~'
  | '*'
  | "'"
  | '('
  | ')'
  | '['
  | ']'

[160]
word-character ::=
    decimal-digit
  | ascii-alpha-character
  | '-'

[161]
hexadecimal-digit ::=
    decimal-digit
  | [x41-x46]                       # A-F
  | [x61-x66]                       # a-f

[162]
decimal-digit ::=
  [x30-x39]                         # 0-9

[163]
decimal-digit-1-9 ::=
  [x31-x39]                         # 1-9

[164]
ascii-alpha-character ::=
    [x41-x5A]                       # A-Z
  | [x61-x7A]                       # a-z

B.1. Failsafe Schema

The failsafe schema is guaranteed to work with any YAML document. It is therefore the recommended schema for generic YAML tools. A YAML processor should therefore support this schema, at least as an option.

Block style: !!map
  Clark : Evans
  Ingy  : döt Net
  Oren  : Ben-Kiki

Flow style: !!map { Clark: Evans, Ingy: döt Net, Oren: Ben-Kiki }

Block style: !!seq
- Clark Evans
- Ingy döt Net
- Oren Ben-Kiki

Flow style: !!seq [ Clark Evans, Ingy döt Net, Oren Ben-Kiki ]

Block style: !!str |-
  String: just a theory.

Flow style: !!str "String: just a theory."

B.2. JSON Schema

The JSON schema is the lowest common denominator of most modern computer languages and allows parsing JSON files. A YAML processor should therefore support this schema, at least as an option. It is also strongly recommended that other schemas should be based on it.

!!null null: value for null key
key with null value: !!null null

YAML is a superset of JSON: !!bool true
Pluto is a planet: !!bool false

negative: !!int -12
zero: !!int 0
positive: !!int 34

negative: !!float -1
zero: !!float 0
positive: !!float 2.3e4
infinity: !!float .inf
not a number: !!float .nan

A null: null
Booleans: [ true, false ]
Integers: [ 0, -0, 3, -19 ]
Floats: [ 0., -0.0, 12e03, -2E+05 ]
Invalid: [ True, Null,
  0o7, 0x3A, +12.3 ]

{ "A null": null,
  "Booleans": [ true, false ],
  "Integers": [ 0, 0, 3, -19 ],
  "Floats": [ 0.0, -0.0, 12000, -200000 ],
  "Invalid": [ "True", "Null",
    "0o7", "0x3A", "+12.3" ] }

B.3. Core Schema

The Core schema is an extension of the JSON schema, allowing for more human-readable presentation of the same types. This is the recommended default schema that YAML processor should use unless instructed otherwise. It is also strongly recommended that other schemas should be based on it.

A null: null
Also a null: # Empty
Not a null: ""
Booleans: [ true, True, false, FALSE ]
Integers: [ 0, 0o7, 0x3A, -19 ]
Floats: [
  0., -0.0, .5, +12e03, -2E+05 ]
Also floats: [
  .inf, -.Inf, +.INF, .NAN ]

{ "A null": null,
  "Also a null": null,
  "Not a null": "",
  "Booleans": [ true, true, false, false ],
  "Integers": [ 0, 7, 58, -19 ],
  "Floats": [
    0.0, -0.0, 0.5, 12000, -200000 ],
  "Also floats": [
    Infinity, -Infinity, Infinity, NaN ] }

B.4. Other Schemas

None of the above recommended schemas preclude the use of arbitrary explicit tags. Hence YAML processors for a particular programming language typically provide some form of local tags that map directly to the language’s native data structures (e.g., !ruby/object:Set).

While such local tags are useful for ad hoc applications, they do not suffice for stable, interoperable cross-application or cross-platform data exchange.

Interoperable schemas make use of global tags (URIs) that represent the same data across different programming languages. In addition, an interoperable schema may provide additional tag resolution rules. Such rules may provide additional regular expressions, as well as consider the path to the node. This allows interoperable schemas to use untagged nodes.

It is strongly recommended that such schemas be based on the core schema defined above.