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.

4.2.4 Throwaway comments

In some applications there is a strong requirement to allow the inclusion of throwaway comments into a YAML document. Such comments have no effect whatsoever on the abstract information model 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.

To support this requirement, YAML defines a throwaway comment line construct. Such comments must be indented at the same level as the line following the comment. A throwaway comment begins with a '#' and spans the whole line, including its terminating line break. On input, the parser must ignore such throwaway comments and proceed as if they were not present in the document.

Since throwaway comment are complete lines, they may appear only where a line break is valid. When throwaway comments are allowed after a line break, the throwaway_line_break(n) production below will be used. Note that throwaway comments are not allowed inside leaf nodes, making the '#' character safe to use there.

# This comment is ignored
# by the YAML parser
this: contains two
 # lines of text

4.3.1 Directive

Directives are instructions to the YAML parser specifying how to parse the document. Like throwaway comments, directives are not reflected in the abstract information model represented in the document. Directives apply to a single document. It is an error for the same directive to be specified more than once for the same document.

Additional directives may be added in future versions of YAML. A parser should ignore unknown directives with an appropriate warning. There is no provision for specifying private directives. This is intentional.

The only directive defined in this version is 'YAML'. This directive specifies the version of YAML the document adheres to. This specification defines version '1.0'.

A version 1.0 parser should accept documents with an explicit 'YAML:1.0' directive, as well as documents lacking a 'YAML' directive. Documents with a directive specifying a higher minor version (e.g. 'YAML:1.1') should be processed with an appropriate warning. Documents with a directive specifying a higher major version (e.g. 'YAML:2.0') should be rejected with an appropriate error message.

4.3.2 Serialization Node

A serialization node begins at a particular level of indentation, n, and its content is indented at a level n+1. A serialization node can be either a branch (keyed or series), a leaf (block, plain, escaped, single quoted, double quoted, or implicit), or an alias.

A YAML document is a normal node at indentation level 0, which starts with a document header. This header is optional for the first document if it is a branch and there are no directives or properties specified.

4.3.3 Property

Each serialization node may have anchor and transfer method properties. These properties are specified in a properties list appearing before the node value itself. For a top level node (a document), the properties appear in the document header. It is an error for the same property to be specified more than once for the same node.

4.3.4 Transfer Method

Explicit type information can be provide via a transfer string which contains the type family and, for leaf nodes, an optional string format. Where the family and format are separated by a semi-colon.

By providing an explicit transfer string to a node, the implicit typing is prevented. However, an explicit empty transfer string can be used to force implicit typing to be applied to a non-implicit leaf value.

Type families beginning with a reverse DNS string are reserved for that domain's owners. Type families beginning with a IANA mime type are reserved for that mime type's owners.

Type families consisting of a single word are a shorthand for transfer strings defined in the yaml.org domain. Thus, the transfer strings 'map' must be deserialized by the parser as if it was written using the full 'org.yaml.map' notation.

Type families consisting of a '.' character followed by a single word are taken to be in the same DNS domain used for the nearest ancestor node with an explicit absolute DNS type family. It is an error if there is no such ancestor node. The type family for the node is the result of replacing the final word in the ancestor's absolute DNS transfer string with the relative transfer string. Thus, if a node with the transfer string '.customer' is contained within a branch with the transfer string 'tld.company.invoice', the parser must deserialize the node as if it was written using the full 'tld.company.customer' notation.

Type families beginning with '!' are used for private transfer string. Such transfer strings should not be expected to have consistent semantics in different documents.

All other formats of transfer strings are reserved. TODO: Update the productions to reflect a transfer string as a composition of a type family, followed by an optional colon and string format.

# '!point' is a private transfer
# type. The three coordinates all
# have the same transfer string.
center : !!point
 x : !float 12
 y : !org.yaml.float 3
 z : ! \
  7.5
# 'tld.company.invoice' is an absolute
# DNS based transfer string name.
invoice: !tld.company.invoice
 # 'seq' is a shorthand for 'org.yaml.seq'.
 # This does not effect '.customer' below
 # because it is not an absolute DNS based
 # transfer string name.
 customers: !seq
  # '.customer' is a relative DNS transfer
  # type name serving as a shorthand for
  # the longer absolute DNS based notation
  # 'tld.company.customer'.
  - !.customer
   given : Chris
   family : Dumars

4.3.5 Anchor

An anchor is a property which can be used to mark a serialization node for future reference. An alias node can then be used to indicate additional inclusions of an anchored node by specifying the node's anchor.

4.5.1 Series

A series value is the simplest kind of value, it is a series of nodes at a higher indentation. An in-line style is available for short, simple series.

empty: []
inline: [ one, two, three ]
nested:
 - First item in top series
 -
  - Subordinate series entry
 - \
  A multi-line
  series entry
 - Sixth item in top series

4.5.2 Keyed

A keyed node is an association of unique keys with values. It is an error for two equal key values to appear in the same keyed node. In such a case the parser may continue processing, ignoring the second key and issuing an appropriate warning. This strategy preserves a consistent information model for streaming and random access applications.

An in-line form is available for short, simple keyed nodes. Also, if a keyed node has no properties and consists of a single key:value pair, it may be specified in-line in a series entry.

empty: {}
inline: { one: 1, two: 2 }
keyed:
 first : First entry
 second:
  key: Subordinate keyed!
 third:
  - Subordinate series
  - !keyed
  - Previous keyed is empty.
  - Single pair: keyed in series.
  - The previous entry is equal to the following one.
  -
   Single pair: keyed in series.
 !float 12 : This key is a float.
 ? \
  :
 : This key had to be folded.
 ? \\
  \a
 : This key had to be escaped.
 "\b": Another way to escape
 ? \
  This is a
  multi-line
  folded key
 : \
  Whose value is in the next line.
 ?
  - this key
  - is a series
 :
  - with a series value
 ?
  this: key
  is a: keyed
 :
  with a: keyed value

4.6.1 Block

A block leaf is the simplest leaf form. No processing is performed on block leaf characters aside from end of line normalization and stripping away the indentation. This restricts block leaves to printable characters only. Also, long lines can't be broken.

In exchange for these severe restrictions, a block leaf may freely use any any printable character, including line breaks. This makes block leaves the most readable format for source code or other text values with significant use of indicators, quotes, escape sequences, and line break characters.

The value of a block leaf contains, by default, the trailing line break character. To prevent this trailing line break from being included, the block indicator should be repeated.

empty: ||
second: |
 This is a block leaf,    with significant
 whitespace, and the use of " @, etc.
      All whitespace    is    significant.
third: ||
 No leading nor trailing new line.
fourth:
 - |

  First series item which has a
  leading and a trailing new line.
 - ||
  Second series item. Has neither
  leading nor trailing new line.
  Has two new lines altogether.

4.6.2 Plain

A plain leaf is similar to a block leaf. However, unlike a block leaf, a plain leaf is subject to line folding. This allows long lines to be broken anywhere a space character (#x20) appears, at the cost of requiring an empty line to represent each line feed character. Also, unlike a block leaf, the value does not include the trailing line break character. If such a character is desired it must be explicitly specified using a trailing empty line.

empty: \
second: \
 The value of the previous key is the empty string.
 The last character in this value is a period.
third: \
  This value has just one leading white space,
 and is terminated by a hard newline (LF).

fourth: \
 Indicators like ! & : are allowed.  Further,
 whitespace     is   preserved.
fifth:
 - \
  A single line entry.
 -  \
   A second, multi-line,
  entry of the series.
 - \
  A third, multi-line series
  entry, without any leading
  or trailing white space.
 - \


 - \
  The value of the previous
  entry is two hard newlines
  (LF LF).
sixth: \
 This is not a key : value pair.
seventh: \
 - This is not a series entry.
eigth: \
 This isn't a newline: \n

4.6.3 Escaped

An escaped leaf is similar to a plain leaf. However, after line folding is done, escape sequences are processed within an escaped leaf. This allows every Unicode character to be represented, and allows lines to be broken anywhere (rather than just on a space character) by escaping the (folded) line break. This comes at the cost of some verbosity: starting at a separate line, escaping the printable '\' character, and specifying line feed characters using a blank line or a '\n' escape sequence.

It is an error for an escaped leaf to contain invalid escape sequences.

empty: \\
second: \\
 Escaped leaf.\nWith a new line.
"third":
 - \\
  Line breaks are folded so this ->
  <- new line is the same a space. A
  new line may be inserted by using a
  blank line:

  Or an escape: \n. A line may be brok\
  en anywhere by escaping the newline.
  A new line may also be inserted at
  the very beginning or end:

 - \\
  There is no need to escape " and '.
  However \" is allowed.
 - \\
  Furthermore indicators such
  as ! & : can be used.
 - \\
  Escape sequences can be used
  to specify unprintable
  characters: \a, \x01.
 - \\
    Leading and trailing
     spaces are significant
     in all lines
 - \\
  This is a series of six escaped leaves.

4.6.4 Single Quoted

A single quoted leaf is indicated by surrounding ''' characters. Therefore within a single quoted leaf such characters needs to be escaped. No other form of escaping is done, limiting single quoted leaves to printable characters. Also, single quoted leaves may not contain any line break characters.

Single quoted leaves are the most readable form for short, printable single-line text values which contain indicators or the escape character.

empty: ''
second: '! : \ etc. can be used freely.'
third: 'a single quote '' must be escaped.'

4.6.5 Double Quoted

A double quoted leaf is similar to a single quoted leaf. Similarly to a single quoted leaf, a double quoted leaf is indicated by surrounding '"' and may not contain non-printable or line break characters. However unlike a single quoted leaf, escaping is done within a double quoted leaf. This allows arbitrary Unicode characters to be specified at the cost of some verbosity: escaping the printable '\' and '"' characters.

Double quoted leaves are the most readable form for short text values containing non-printable characters and/or indicators but not the escape character.

It is an error for a double quoted leaf to contain invalid escape sequences.

empty: ""
second: "! : etc. can be used freely."
third: "a double quote \" must be escaped."
fourth: "this value ends with a line feed.\n"

4.6.6 Implicit

A implicit leaf is similar to a single quoted leaf. However, unlike a single quoted leaf, an implicit leaf has no identifying markers. Therefore an implicit leaf may not start or end with white space characters, may not start with most indicators, and may not contain certain indicators. Also, an implicit leaf is subject to implicit transfer. This can be avoided by providing an explicit transfer string annotation.

In exchange for these restrictions implicit leaves are the most readable of all leaf styles for keys, numerical values, or other short, printable leaf values of any type.

empty:
second: The value of the previous key is the empty string.
third: 12
fourth: The above entry is an integer.

5.3.1 Sequence

This type family is the default for sequence nodes unless they are given an explicit transfer method property. Example bindings include the Perl array, Python's list or tuple, and Java's array or vector.

Applying the seq type family to leafs also provides a natural syntax for representing an empty sequence.

# The following is an empty
# top level sequence.
--- !seq
---
# An empty sequence.
empty: !seq

In some applications large sequences may contain only a small number of non-null entries. While it is possible to serialize such sparse sequences using the null implicit type family, this is awkward. YAML allows to serialize such sequences using the mapping style with an explicit sequence type family. The only supported keys are integers, serving as zero-based sequence entry indices.

# The following map style node is
# deserialized to a sequence, with
# unspecified entries containing
# a null value.
sparse sequence: !seq
 2: Third entry
 4: ~
# The following sequence node is
# deserialized into an identical
# in-memory sequence, which has
# a seperate identity.
identical sequence:
 - ~
 - ~
 - Third entry
 - ~
 - ~

5.3.2 Map

This type family is the default for map nodes unless they are given an explicit transfer method property. Example bindings include the Perl hash, Python's dictionary, and Java's dictionary.

Applying the map type family to leafs also provides a natural syntax for representing an empty map.

# The following is an empty top level map.
--- !map
---
# An empty map.
empty map: !map

5.3.3 String

This type family is the default for leaf nodes unless they are given an explicit transfer method property. This type is usually bound to the native language's string or character array construct.

Specifying this as an explicit type family is required for turning off implicit transfer for a plain leaf. The same effect can be achieved by converting it to another leaf style.

# The following leafs are
# deserialized to the string
# value '1' '2'.
string: !string 12
also: ||
 12
and: \\
 12

This type family can also be specified using the implicit transfer mechanism by surrounding a plain leaf value with quotes. In this case the type family strips the surrounding quotes from the value of the leaf. If double quotes are used then the type family also expands escape sequences within the leaf. In this case it is an error for the leaf to contain invalid escape sequences.

# The following leafs
# all have the same value.
block: ||
 "line1"
 'line2'
 line 3
folded: \
 "line1"

 'line2'

 line 3
implicit (single): '"line1"

 'line2'

 line 3'
escaped: \\
 "line\ 1"\n'line\
 2'

 line
 3
implicit (double): ""line\ 1"\n'line\
 2'

 line
 3"
forced implicit (double) in block: ! ||
 ""line\ 1"\n'line\
 2'

 line
 3"

5.3.4 Null

The null type family accepts leafs with the value '~' and converts them into any native null-like value (e.g., undef in Perl, None in Python). A null value is used to indicate the lack of a value. Note that in most programming languages a map entry with a key and a null value is valid and different from not having that key in the map.

first: ~
second:
 - ~
 - Second entry.
 - ~
 - This sequence has 4 entries, two with values.
three:
 This map has three keys,
 only two with values.

5.3.5 Pointer

The pointer type family accepts a map with a single key, '=', and is deserialized into any native pointer-like data type, pointing to the value given for that key (e.g., a hard reference in Perl). Note that this is not necessarily the native data type used to implement alias nodes. For example, in Java aliases are directly supported, but pointers must be emulated using a special class.

Perl: |
 $map{YAML} = \"content";
# The following map is deserialized
# into a pointer to a text string.
YAML: !ptr
 = : content

5.3.6 Integer

The integer type family handles bases as in C - a leading '0x' indicates base 16, a leading '0' indicates base 8. This should be deserialized to some native integer data type. The parser may choose from a range of such native data types according to the value of the integer. The valid range depends on the parser, though 32 bit integers should be safe.

decimal: 12
hexadecimal: 0x1f
octal: 011

5.3.7 Float

The floating point type family handles approximations to real numbers as in C (both with and without a scientific notation). This should be deserialized to some native float data type. The parser may choose from a range of such native data types according to the size and accuracy of the floating point value. The valid range and accuracy depend on the parser, though 32 bit IEEE floats should be safe.

float: 12.
scientific: 1.2e-3

5.3.8 Binary

The binary type family accepts the base64 format as defined in RFC2045 and deserializes it into some native binary data type (e.g., byte[] in Java). This is the recommended way to store such data in YAML files. Note however that many forms of binary data have internal structure which may benefit from being represented as YAML nodes (e.g. the Java serialization format).

arrow: !binary;base64 \
 R0lGODlhDAAMAIQAAP//9/X17unp5WZmZgAAAOf
 n515eXvPz7Y6OjuDg4J+fn5OTk6enp56enmlpaW
 NjY6Ojo4SEhP/++f/++f/++f/++f/++f/++f/++
 f/++f/++f/++f/++f/++f/++f/++SH+Dk1hZGUg
 d2l0aCBHSU1QACwAAAAADAAMAAAFLCAgjoEwnuN
 AFOhpEMTRiggcz4BNJHrv/zCFcLiwMWYNG84Bww
 EeECcgggoBADs=
description: \
 The binary value above is a tiny arrow
 encoded as a gif image.

5.3.9 Special Keys

The special key type family is used for special YAML defined items, which are used as map keys to denote structural information.

The '&', '*' and '!' keys must not be used in serialized YAML documents. They are only used internally (in-memory) to encode anchors and type family information in applications which do not support them directly. On output these should be converted back to the appropriate YAML syntax. The '=' and '//' keys, however, may appear in serialized YAML documents.

The '=' key is used to denote the "default value" of a map. In cases where a value needs to be annotated by additional attributes, this avoids the need to come up with a key for the value itself.

The '//' key is used to attach a persistent comment to a map. A simple filter can remove these comments before reaching the application, while allowing such comments to survive round-trips and to be manipulated as normal data when necessary.

annotated text:
 - This text contains
 -
  = : colored
  color : red
 - characters.

"!": These three keys
"&": had to be quoted
"=": and are normal strings.
# NOTE: the following encoded node
# is NOT in valid serialized YAML
# format. It directly represents an
# in-memory structure.
encoded node :
 ! : transfer
 & : 12
 = : value
# The YAML way to serialize the
# above structure is as follows:
node : !transfer &12 value

commented: !!point
 x : 12
 y : 3
 // : This is the center point.