YAML Ain't Markup Language (YAML) ^(tm) 1.0

3.2.1 Indentation

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

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

A node must be more indented than its parent node. All sibling nodes must use the exact same indentation level. However the content of each such node may be indented independently.

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

[038]	indent(n)	::=	#x20 x n		/* specific level of indentation */
[039]	indent(<n)	::=	indent(m)		/* for some specific m such that m < n */
[040]	indent(<=n)	::=	indent(m)		/* for some specific m such that m <= n */

Since the YAML strean depends upon indentation level to delineate blocks, additional productions are a function of an integer, based on the indent(n), indent(<n) and indent(<=n) productions above. In some cases the notation production(any) is used; it is a shorthand for "production(n) for some specific value of n".

The '-' sequence entry indicator is considered to be part of the indentation, as this seems the way people tend to interpret it. Hence this indicator itself need be not indented relative to its parent node. Note that spaces following this indicator are not taken to be part of the indentation except for in one special case (map_in_seq).

### The first tree lines of this stream

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

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

3.3.1 Document

A YAML stream may contain several independent YAML documents. A document header line is used to start a new document. This line must start with a document separator: '---' followed by a line break or a sequence of space characters. If no explicit header line is specified at the start of the stream, the parser should behave as if a header line containing '--- #YAML:1.0' was specified.

When YAML is used as the format for a communication stream, it is useful to be able to indicate the end of a document independent of starting the next one. Without such a marker, the YAML processor reading the stream would be forced to wait for the header of the next document (that may be long time in coming) in order to detect the end of the previous document.

To support this scenario, a YAML document may be terminated by a '...' line. Nothing but throwaway comments may appear between this line and the (mandatory) header line of the following document.

[049]	document_header	::=	document_start ( flow_space+ directive )*		/* YAML document header */
[050]	document_start	::=	'-' '-' '-'		/* YAML document start indicator */
[051]	document_trailer	::=	document_end any_break comment_line(any)*		/* YAML document trailer */
[052]	document_end	::=	'.' '.' '.'		/* YAML document end indicator */

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

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

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

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

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

3.3.3 Text Node

A text node begins at a particular level of indentation, n, and its content is indented at some level >n. A text node can be a collection (mapping or sequence), a scalar (block or flow) or an alias.

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

[056]	top_value_node(n)	::= | |	top_alias_node top_collect_node(n) top_scalar_node(n)	/* value node outside flow collection */
[057]	flow_value_node(n)	::= | |	alias flow_collect_node(n) flow_scalar_value_node(n)	/* value node inside flow collection */
[058]	top_key_node(n)	::= |	( top_key_indicator   top_value_node(>n)   indent(n) ) ( flow_key_node(n)   flow_space* )	/* key node outside flow collection */
[059]	flow_key_node(n)	::= | |	alias flow_collect_node(n) flow_scalar_key_node(n)	/* key node inside flow collection */
[060]	top_alias_node	::=	flow_space+ alias comment_break comment_line(any)*	/* alias node outside flow collection */
[061]	top_collect_node(n)	::= |	blk_collect_node(n) ( flow_space+   flow_collect_node(n)   comment_break   comment_line(any)* )	/* collection node outside flow collection */
[062]	blk_collect_node(n)	::=	( flow_space+   collect_properties )? comment_break comment_line(any)* blk_collection(n)	/* collection node in block style */
[063]	flow_collect_node(n)	::=	( collect_properties   flow_space+ )? flow_collection(n)	/* collection node inside flow collection */
[064]	top_scalar_node(n)	::= |	blk_scalar_node(n) ( flow_space+   top_scalar_value_node(n)   comment_break   comment_line(any)* )	/* scalar node outside flow collection */
[065]	blk_scalar_node(n)	::=	( flow_space+   scalar_properties )? flow_space+ blk_scalar(n)	/* scalar node in block style */
[066]	top_scalar_value_node(n)	::=	( scalar_properties   flow_space+ )? top_scalar_value(n)	/* scalar node using flow style outside flow collection */
[067]	flow_scalar_value_node(n)	::=	( scalar_properties   flow_space+ )? flow_scalar_value(n)	/* scalar value node inside flow collection */
[068]	flow_scalar_key_node(n)	::=	( scalar_properties   flow_space+ )? flow_scalar_key(n)	/* scalar key node inside flow collection */

3.3.5 Transfer Method

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

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

Explicit/Implicit

By providing an explicit transfer property to a node, implicit typing is prevented. However, an explicit empty transfer method property can be used to force implicit typing to be applied to a node. If either an empty explicit format or no explicit format are given, the loader automatically detects the format.

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

Shorthands

YAML makes use of the taguri: scheme for defining URIs for its global type families and the x-private: scheme for its private type families. While these schemes provide the necessary semantics for identifying type families, they are rather verbose.

To increase readability, YAML does not use the full URI notation in the stream. Instead, it provides several shorthand notations for different groups of type family URIs. A parser may choose not to expand shorthand type family names to URIs. However, in such a case the parser must still perform escaping to ensure a single unique representation of each type family name.

• If the type family begins with a '!' character, it is taken to be a private type family whose URI is under the x-private: scheme. URI fragments are allowed but their semantics is completely up to the semantics of the private type. In particular, they may or may not indicate a format.

# Both examples below make use of the 'x-private:ball'
# type family URI, but with different semantics.
---
pool: !!ball { number: 8 }
---
bearing: !!ball { material: steel }

• If the type family contains no ':' and no '/' characters it is assumed to be defined under the yaml.org domain. This domain is used to define the core and language-independent YAML data types.

# The URI is 'taguri:yaml.org,2002:str'
- !str a Unicode string

• Otherwise, if the type family begins with a single word, followed by a '/' character, it is assumed to belong to a sub-domain of yaml.org.

  Each domain language.yaml.org will include all globally unique types of the language that aren't covered by the set of language-independent types. Globally unique types for each language include any built-in types and any standard library types. For languages such as Java and C#, all type names based on reverse DNS strings are globally unique. For languages such as Perl, that has a central authority (CPAN) for managing the global namespace, all the types sanctioned by the central authority are globally unique. The list of supported languages and their types is maintained as part of the YAML type repository.

# The URI is 'taguri:perl.yaml.org,2002:Text::Tabs'
- !perl/Text::Tabs {}

• Otherwise, the type family must begin with a domain name and a date (separated by a ',' character), followed by a '/' character. In this case it is taken to be defined under the specified domain and date.

# The URI is 'taguri:clarkevans.com,2003-02:timesheet'
- !clarkevans.com,2003-02/timesheet

Type families defined in the yaml.org domain or any of its sub-domains must be defined using the appropriate specialized shorthand rather than using the generic domain syntax. This ensures each type family has a unique representation as a shorthand, in addition to having a unique representation as a URI.

Escaping

YAML allows non-printable Unicode characters to be used in a transfer method using escape sequences.

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

Expanding

Sometimes it may be helpful for a YAML type family or transfer method to be expanded to a full URI. A YAML processor may provide a mechanism to perform such expansion. Since URIs support a limited ASCII-based character set, this expansion requires all characters outside this set to be encoded in UTF-8 and the resulting bytes to be encoded using % notation.

When an explicit % character appears in a transfer method, it is passed to the URI form unchanged, allowing explicit % escapes to be used in the transfer method where necessary. It is an error for a transfer method not to have a valid expanded URI format (e.g., contain an invalid explicit % escape sequence).

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

Prefixing

YAML provides convenient shorthand for the common case where a node and (most of) its descendents have global types families whose shorthand forms share a common prefix. For this case, YAML allows using the '^' character to separate the ancestor node's type family into a prefix and a suffix. The parser does not consider the separator to be part of type family name.

When the parser encounters a descendant node whose type family name begins with '^', it appends the ancestor node's prefix to it. Again the '^' character is not taken to be part of the name.

It is possible for a descendant node to establish a different prefix. In this case the node may not make use of its ancestor's node prefix. It must specify a full type family name, separated into a prefix and suffix as above.

It is an error for a node's type family name to begin with '^' unless it has an ancestor node establishing a prefix. However, a node may establish a prefix even if none of its descendents make use of it.

Note that the type prefix mechanism is purely syntactical and does not imply any additional semantics. In particular, the prefix must not be assumed to be an identifier for anything.

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

[071]	prefix_separator	::=	'^'		/* separates prefix from type */
[072]	format_separator	::=	'#'		/* separates type from format */
[073]	trans_char	::= |	escape_sequence ( flow_non_space - escape_indicator - format_separator )		/* characters valid in a transfer metrhod */
[074]	mundane_trans_char	::=	trans_char - ':' - '/'		/* non-magical URI character */
[075]	collect_transfer	::=	transfer_indicator ( /* empty (implicit) */ | private_family | global_family )		/* collection transfer method (no format) */
[076]	scalar_transfer	::= |	collect_transfer ( transfer_indicator   global_family   format_separator   format )		/* scalar transfer method (with format) */
[077]	private_family	::=	transfer_indicator trans_char+ ( format_separator   trans_char* )?		/* private type names */
[078]	global_family	::= | |	core_family language_family domain_family		/* global type names */
[079]	format	::=	trans_char*		/* format of a scalar */
[080]	core_family	::= |	( ( mundane_trans_char   - transfer_indicator )   mundane_trans_char* ) ( prefix-of-above?   prefix_separator   suffix-of-above )		/* shorthand for taguri: yaml.org,2002:type names */
[081]	language_family	::= |	( word_char+   '/' trans_char* ) ( prefix-of-above?   prefix_separator   suffix-of-above )		/* shorthand for taguri:language .yaml.org,2002:type names */
[082]	domain_family	::= |	( word_char+   ( '.' word_char+ )+   ',' domain_year   ( '-' domain_day_month     ( '-' domain_day_month )? )?   '/' trans_char* ) ( prefix-of-above?   prefix_separator   suffix-of-above )		/* shorthand for taguri:domain,date:type names */
[083]	domain_year	::=	decimal_digit x 4		/* type family domain ownership year */
[084]	domain_day_month	::=	decimal_digit x 2		/* type family domain ownership day or month (01 by default) */

4.2.1 Native Node

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

type family

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

value

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

4.2.2 Type Family

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

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

name

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

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

definition

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

kind

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

scalar

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

sequence

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

mapping

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

domain

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

range

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

function

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

collection

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

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

4.2.4 Documents Stream

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

stream

A sequence of zero or more document root nodes.

document

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

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

4.3.1 Format

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

name

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

definition

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

regexp

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

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

4.3.3 Graph Node

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

4.3.4 Implicit Types and Formats

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

4.4.1 Serial Node

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

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

parent

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

anchor

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

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

4.4.2 Alias

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

referent

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

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

4.4.4 Serial Mapping

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

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

4.4.5 Ordering

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

• x is the parent of y.

• x and y are nodes within a sequence, and x appears before y.

• x is a key and y is a value in a given pair.

• x and y are nodes in two pairs within a mapping, and the pair containing x comes before the pair containing y.

• There exists a node z such that x precedes z and z precedes y.

4.5.1 Style

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

scalar style

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

collection style

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

4.5.2 Comment

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

comment

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

4.5.3 Directive

Attached to each document is a document directive section.

directive section

A collection of directives to the parser where each member of the domain and range are scalar values matching the directive_name and directive_value productions.

4.5.4 Details

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