Yet Another Markup Language (YAML) 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

Each type family has a name used for explicit typing and for general identification. This name must comply with the type family production.

definition

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

format

Each type family used for scalar nodes has an optional default string format.

implicit

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.

In general, there may be more than one native type which corresponds to the type family. In the Python languagek, for example, the integer family may be bound to either the a plain integer capable of holding 32 bits, or the long integer with unlimited size. In situations like this, the loader makes the choice.

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, a processor must raise an exception when a native binding for a particular value is not possible.

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 254 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 string format production.

definition

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

regex

Regular expressions may be provided to allow implicit identification of the string format, or to enable the parser to validate that a given value is indeed compliant with the string format.

As noted above, each type family has exactly one default string format; although more than one string format may apply. For example, the decimal format is the default for integers and the base64 format is the default for the binary type family.

3.2.1 Graph Node

A graph node is the building block of YAML structures. In the serialization, they represent indented blocks. Within a native binding they represent an 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.

family

Each node is associated with a type family. For scalar nodes, the family is required to have a default string format. For collections, the family need not have a default format.

3.2.2 Scalar

A scalar is a graph node with a string representation.

string

Each scalar must have a canonical string representation. This is a series of zero or more printable unicode characters according to the type family's default string format.

The default type family for scalar nodes is org.yaml.str. The string representation of the scalar together with its type family should be sufficient to encode most native data types not having a composite structure. Other scalar type families include integer, float, and binary.

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

The second form of equivalence occurs when two nodes are different (have a different memory address), but share the same content or have the 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. However, 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 two collection rules. First, a set of keys may not contain two nodes that are equal. Second, each key is associated with exactly one value. 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.

The default type family for collection nodes is org.yaml.map, which covers associative containers such as the Perl hash or Python dictionary. When the domain is a continuous series of positive integers starting with zero, the preferred type family is org.yaml.seq which includes the Perl array or Python list.

3.2.6 Equality

Node equality determines when two given nodes have the same content. Technically, equality is an equivalence relation (like identity above). When two nodes are equivalent under this 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 means 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 means that 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 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

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

root

A series of zero or more document nodes.

document

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

The term disjoint means that for any two nodes x and y, there does not exist a third node z such that is both reachable from x and y. For any node x, x is reachable from y means that 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 layout graph nodes as a tree structure, a mechanism is needed to manage duplicates. This is solved with a three node system: branch, leaf, and alias. The first occurance of a scalar is represented by a leaf, the first occurance of a collection is represented by a branch, and subsequent occurances of either a collection or a scalar is represented by an alias. All tree nodes in the serial model have the following properties:

kind

An adapter may be one of three kinds, a branch or 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 alias production. The anchor is used to associate the first occurance of a graph node with subsequent occurances, 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.

3.3.2 Leaf

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

family

Like a scalar, each leaf is associated with a type family having a default string format.

string

Also like a scalar, each leaf has a canonical string representation.

When a leaf is converted into a graph node it becomes a scalar with the same type family and string representation. Note that the anchor, if any, is not converted.

3.3.3 Alias

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

referent

The branch or leaf which the alias references is the closest preceding having an identical anchor.

When an alias is converted into a graph node it becomes a subsequent occurance of it's 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 called the key and the second member of the set is called the value.

3.3.5 Branch

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

family

Like a collection, each branch is associated with a type family. This type family need not have a default string format.

pairs

A branch has zero or more pairs.

When an branch is converted to a graph node, three operations occur. The domain is constructed with the graph node for each key in it's set of pairs. Likewise, the range is constructed with the graph node for each value in it's 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 ordering. Through 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:

• the parent of y is x
• x is a key and y is a value in a given pair.
• x and y are both keys of two pairs within a branch, and the pair containing x comes before the pair containing y.
• the parent of x precedes 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 plain, folded, escaped, and block. All but the escaped style are limited to scalars having only printable characters.

branch style

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

3.4.2 Format

Each leaf node is given a particular format to represent the actual format used by it's string representation. Note that once this property is added, the string representation stops being canonical since it overrides the default format for the leaf's family.

format

The format used by the leaf's string representation.

3.4.3 Comment

Before each pair in the serialization is an optional comment.

comment

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

3.4.4 Directive

Attached to each document is a document directive section.

directive section

A map collection where each member of the domain and range are scalar values.

4.1.1 Character Set

Serialized YAML uses a subset of the Unicode character set. A YAML parser must accept all printable ASCII characters and all non-ASCII Unicode characters. However a YAML emitter should attempt to emit only printable characters (including space, tab and line break characters). Characters known to be non-printable may be escaped.

As with standard practice, the surrogate block, #xFFFE and #xFFFF are excluded.

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 initial encoding shall be UTF-8. Otherwise the initial encoding shall be UTF-32 (LE or BE), UTF-16 (LE or BE) or UTF-8, as deduced from the byte order mark. Note that as YAML files may only contain printable characters, this does not raise any ambiguities. For more information on 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 they are treated as content text characters. 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 Escape Sequences

Escape codes are used in escaped and double quoted leaves to denote common non-printable characters, specify characters by a hexadecimal value, and produce the literal escape and double quote characters.

In single quoted leaves, a single quote character needs to be escaped. This is done by repeating the character.

4.1.5 Line Breaks

Unicode defines the following line break characters.

4.1.6 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 an end of line marker followed by zero or more space characters. Indentation level is defined recursively.

Since the YAML serialization depends upon indentation level to delineate blocks, additional productions are a function of an integer, based on the indent(n) production above.

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

4.2.2 End-of-Line Normalization

On input and before parsing, a compliant YAML parser must translate the two-character combination CR LF, any CR which is not followed by an LF, and any NEL into a single LF (this does not apply to escaped characters). LS and PS characters are preserved. This functionality is indicated by the use of the normalized_line_break production defined below.

On output, a YAML emitter is free to serialize end of line markers using whatever convention is most appropriate, though again LS and PS must be preserved.

4.2.3 Line Folding

To increase readability, YAML serialization allows for breaking long text lines. Therefore in many cases the parser replaces a single normalized line feed with a single space (#x20). LS and PS characters are preserved, so it is safe to use them to indicate line/paragraph text structure even when line folding is done.

When encountering two or more consecutive (possibly indented) normalized line feeds, the parser does not convert them into spaces. However, if the series of line feeds is surrounded by other text characters, the parser ignores the first line feed, requiring a single line feed to be serialized as two, two line feeds to be serialized as three etc. Thus each "empty line" in a folded text represents a single line feed character, be it at the start, middle or end of the value.

When this functionality is implied, the folded_line_breaks(n) production below will be used.