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.

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

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.

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

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