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

3.1.1 Type Family

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

name

A URI used as a globally unique identifier for the type family. YAML does not require that this URI point to anything in particular. However, where possible, it is considered good practice to have the URI point to some human-readable document providing information about the type data family.

definition

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

formats

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

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

implicit formats

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

explicit formats

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

canonical format

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

In general, there may be more than one native type which corresponds to a YAML type family. In the Python language, for example, the integer family may be bound to either the plain integer capable of holding 32 bits, or the long integer with unlimited size. In ambiguous situations like this, the loader should choose between the alternative based on the requirements of the native binding.

In other cases, a binding may not have an appropriate native construct for a given type family. This may be addressed with a generic YAML construct to act as a place-holder so that the data value and the type family may round-trip. Alternatively, with warning to the user, a value may be cast to a different, perhaps less specific family. Otherwise, when a native binding for a particular value is not possible, the parser must treat it as an error.

3.1.2 String Format

It may be possible to write a string value of a leaf 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 string format.

name

Each string format has a name used for for explicit typing and 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.

As noted above, each scalar type family has exactly one canonical string format, although more than one string format may apply. For example, the scientific format is the canonical format for floating point numbers, but such numbers are typically written using the fixed format.

3.2.1 Graph Node

A graph node is the building block of YAML structures. In the serialization, they are represented by indented blocks. Within a native binding they represent application-specific objects. In the graph model, a node is tagged with a type family and can either be a collection or a scalar.

kind

A node may be one of two kinds, a collection or a scalar.

type family

Each node is associated with a type family. For native data, this association may be implicit, based on the native data type of the node.

3.2.2 Scalar

A scalar is a graph node with a string representation.

value

Each scalar has a value as specified by the type family definition.

string representations

Each scalar has one or more string representations. Each string representation is a series of zero or more printable Unicode characters compliant with one of the type family's string formats.

canonical representation

A single unique string representation of the scalar according to the type family's canonical string format.

A string representation of a scalar together with its type family and format should be sufficient to encode most native data types not having a composite structure.

YAML requires the Unicode string scalar type family. Other scalar type families include integer, float, date, time, timestamp and binary. Application specific type families may also be used.

3.2.3 Identity

In most programming languages, there are two manners in which variables can be equivalent. The first is by reference, where the two variables refer to the same memory address. We call this equivalence relation "identity".

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

3.2.4 Node set

A node set is an unordered association of zero or more graph nodes. A node may participate in many node sets without restriction, allowing for a graph structure. Node sets may not contain duplicates, that is, a node with a particular identity may only appear once. The primary purpose of the node set is to provide a basis for the definition of a collection. A native binding usually exposes node sets through a mechanism to enumerate the keys of a hash or dictionary.

3.2.5 Collection

A collection is a graph node which represents sequences such as lists or arrays, or mappings such as hashes or dictionaries. In the graph model, sequences are treated uniformly as mappings with integer keys. There are three collection rules. First, a set of keys may not contain two nodes that are equal. Second, each key is associated with exactly one value. Finally, each value is associated with at least one key. Note that this does not prevent a value from being associated with more than one key.

domain

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

range

A range is node set without restrictions. Nodes which 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.

YAML requires the mapping collection type family, which covers associative containers such as the Perl hash or Python dictionary. When the domain is a series of sequential integers starting with zero, the preferred type family is the sequence which corresponds to a Perl array or a Python list.

3.2.6 Equality

Node equality determines when two given nodes have the same content. When two nodes are equivalent under this equivalence relation, they are said to be "equal". Equality is defined between scalar nodes and between collection nodes, as described below.

scalar equality

Two scalars are equal if and only if they have the same type family and their canonical string representations have exactly the same series of Unicode characters.

collection equality

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

3.2.7 Documents Stream

A YAML text (file or stream) is a series of disjoint graphs, each with a root node.

stream

A series of zero or more document root nodes.

document

A top level graph 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.

3.3.1 Tree node

To lay out graph nodes as a tree structure, a mechanism is needed to manage duplicate occurrences. This is solved with three node kinds: branch, leaf, and alias. The first occurrence of a scalar is represented by a leaf, the first occurrence of a collection is represented by a branch, and subsequent occurrences of either a collection or a scalar are represented by an alias. All tree nodes in this model have the following properties:

kind

A tree node may be one of three kinds, a branch, a leaf or an alias.

parent

The parent property gives access to the branch which holds the current tree node.

anchor

The anchor is a Unicode string which complies with the anchor production. The anchor is used to associate the first occurrence of a graph node with subsequent occurrences, via the alias tree node. This property is optional for leaf or branch nodes, provided that the scalar or collection represented does not occur more than once.

Note that when a tree 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 participate in several collections.

3.3.2 Leaf

Leaf tree nodes represent the first occurrence of a scalar in a given serialization.

type family

Like a scalar, each leaf is associated with a type family.

format

Unlike a scalar, each leaf is associated with a specific string format.

string value

Each leaf has a string value which is a string representation of the scalar according to the specific string format used.

When a leaf is converted into a graph node it becomes a scalar of the same type family. The scalar's value would be such that its string representation according to the specific format used would be identical to the leaf's string value. Note that the particular format used is not converted.

3.3.3 Alias

The alias tree node represents subsequent occurrences of a scalar or collection in the serialization.

referent

The branch or leaf which the alias references is the closest preceding tree node having the same anchor.

When an alias is converted into a graph node it becomes a subsequent occurrence of its referent's graph node.

3.3.4 Pair

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

3.3.5 Branch

Branch tree nodes represent the first occurrence of a collection in a given serialization.

type family

Like a collection, each branch is associated with a type family.

pairs

A branch has an ordered set of zero or more pairs.

When a branch 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 assocation 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.

3.3.6 Ordering

When serializing a YAML graph, every tree node is put into a single linear sequence within a given document through the branch pair ordering. With the composition of branches, this ordering becomes total, so that for any two distinct tree nodes in a serialization, one can be said to precede another.

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 is a key and y is a value in a given pair.

• x and y are nodes in two pairs within a branch, 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.

3.4.1 Style

The tree node is extended with a style property, which can have different values depending upon its kind.

leaf style

Leaf styles include eight nested styles and three in-line styles. All but the escaped and double quoted styles are limited to scalars having only printable characters.

branch style

Branch styles are series and keyed. The series style may only be used if the domain of the collection's function is the set of sequential positive integers starting at zero.

3.4.2 Comment

The syntax model 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 in a nested leaf node block value.

comment

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

3.4.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.1.1 Character Set

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

The range above explicitly excludes the surrogate block [#xD800-#xDFFF], DEL 0x7F, the C0 control block [#x0-#x1F], the C1 control block [#x80-#x9F], #xFFFE and #xFFFF. Note that in UTF-16, characters above #xFFFF are represented with a surrogate pair. DEL and characters in the C0 and C1 control block may be represented in a YAML serilization using escape sequences.

4.1.2 Encoding

A YAML processor is required to support the UTF-32, UTF-16 and UTF-8 character encodings. If an input stream does not begin with a byte order mark, the encoding shall be UTF-8. Otherwise the encoding shall be UTF-32 (LE or BE), UTF-16 (LE or BE) or UTF-8, as signaled by the byte order mark. Note that as YAML files may only contain printable characters, this does not raise any ambiguities. For more information about the byte order mark and the Unicode character encoding schemes see the Unicode FAQ.

4.1.3 Indicators

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

Indicators can be grouped into three categories. The '-' and ':' space indicators are always followed by a white space character (space, tab or line break). If followed by any other character, these indicators are treated as content. The '[', ']', '{', '}' and ',' in line indicators are used to denote in-line branch structure and therefore must not be used as content text characters unless protected in some way. The remaining indicators are used to denote the start of various YAML elements and hence may used as internal content text character in most cases. The exact restrictions on the use of indicators as content text characters depend on the particular leaf style used.

4.1.4 Line Breaks

The Unicode standard defines the following line break characters.

Line breaks can be grouped into two groups. Specific line breaks have well-defined sematics for breaking text into lines and paragraphs. The semantics of generic line break characters is not defined beyond ending a line.

Outside text content, YAML allows any line break to be used to terminate lines, and in most cases also allows such line breaks to be preceded by trailing line space characters. On output, a YAML emitter is free to emit non content line breaks using whatever convention is most appropriate. An emitter should avoid emitting trailing line spaces.

4.1.5 Miscellaneous Characters

This section includes several common character range definitions.

4.2.1 Indentation

In a YAML serialization, 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 unless a '#TAB' directive is used. If such a directive is used, each indentation tab is equivalent to a certain number of spaces determined by the specified tab policy.

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 value of serialized text.

Since the YAML serialization 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.

4.2.2 Throwaway comments

Throwaway comments have no effect whatsoever on the tree or graph models represented in the file. Their usual purpose is to communicate between the human maintainers of the file. A typical example is comments in a configuration file.

A throwaway comment always spans a complete line. An explicit throwaway comment line consists of of some indentation, a '#' indicator, and arbitrary comment characters to the end of the line. Empty lines or lines containing only indentation spaces are taken to be an implicit throwaway comment.

A throwaway comment may appear before a document node or following any node. A throwaway comment may not appear inside a nested line leaf node, but may precede or follow such a node. When following a nested leaf value, the first comment line must be explicit and be less indented than the nested node value. Following comment lines are not restricted.

# These are three throwaway comment

# lines (the second line is empty).
this: |
    contains two lines of text, the
    # second of which starts