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

1.1 Goals

The design goals for YAML are:

1. YAML documents are very readable by humans.

2. YAML interacts well with scripting languages.

3. YAML uses host languages' native data structures.

4. YAML has a consistent information model.

5. YAML enables stream-based processing.

6. YAML is expressive and extensible.

7. YAML is easy to implement.

YAML was designed with experience gained from the construction and deployment of Brian Ingerson's Perl module Data::Denter. YAML has also enjoyed much markup language critique from SML-DEV list participants and builds upon the experiences with the Minimal XML and Common XML specifications.

1.2 Origin

YAML integrates and builds upon structures and concepts described by C, Java, Perl, Python, RFC0822 (MAIL), RFC1866 (HTML), RFC2045 (MIME), RFC2396 (URI), SAX, SOAP and XML.

YAML's core type system is based on the serialization requirements of Perl. YAML directly supports both scalar values (string, integer) and collections (array, hash). Support for common types enables programmers to use their language's native data constructs for YAML manipulation, instead of requiring a special document object model (DOM).

Like XML's SOAP, the YAML serialization supports native graph structures through a rich alias mechanism. Also like SOAP, YAML provides for application-defined types. This allows YAML to serialize rich data structures required for modern distributed computing.

YAML provides unique global type names using a namespace mechanism inspired by Java's DNS based package naming convention and XML's URI based namespaces.

YAML's block scoping is similar to Python's. In YAML, the extent of a node is indicated by its column. YAML's block leaf leverages this by enabling formatted text to be cleanly mixed within an aggregate structure without troublesome escaping. Further, YAML's block indenting provides for easy inspection of the document's structure.

Motivated by HTML's end-of-line normalization, YAML's folded leaf introduces a unique method of handling whitespace. In YAML, single line breaks may be folded into a single space. This technique allows for paragraphs to be word-wrapped without affecting the canonical form of the content.

YAML's escaped leaf uses familar C-style escape sequences. This enables ASCII representation of non-printable or 8-bit (ISO 8859-1) characters such as '\x3B'. 16-bit Unicode and 32-bit (ISO/IEC 10646) characters are supported with escape sequences such as '\u003B' and '\U0000003B'.

The syntax of YAML was motivated by Internet Mail (RFC0822). Further, YAML borrows the document separator from MIME (RFC2045). YAML's top level production is a stream of independent documents; ideal for distributed processing systems.

YAML was designed to have an incremental interface which includes both a pull-style input stream and a push-style (SAX-like) output stream interfaces. Together this enables YAML to support the processing of large documents, such as a transaction log, or continuous streams, such as a feed from a production machine.

1.3 Relation to XML

There are many differences between YAML and the eXtensible Markup Language (XML). XML was designed to be backwards compatible with Standard Generalized Markup Language (SGML) and thus had many design constraints placed on it that YAML does not share. Also XML, inheriting SGML's legacy, is designed to support structured documents, where YAML is more closely targeted at messaging and native data structures. Where XML is a pioneer in many domains, YAML is the result of many lessons from the XML community.

The YAML and XML information models are starkly different. In XML, the primary construct is an attributed tree, where each element has an ordered, named list of children and an unordered mapping of names to strings. In YAML, the primary graph constructs are keyed collections (natively stored as a hash or array) and scalar values (string, integer, floating point). This difference is critical since YAML's model is directly supported by native data structures in most modern programming languages, where XML's model requires mapping conventions, or an alternative programming component (e.g. a document object model).

1.4 Terminology

The terminology used to describe YAML is defined in the body of this specification. The terms defined in the following list are used in building those definitions and in describing the actions of a YAML processor:

may

Conformant YAML streams and processors are permitted to but need not behave as described.

should

Conformant YAML texts and processors are encouraged to behave as described, but may do otherwise if a warning mesage is provided to the user and any deviant behavior requires concious effort to enable. (i.e. a non-default setting)

must

Conformant YAML texts and processors are required to behave as described, otherwise they are in error.

error

A violation of the rules of this specification; results are undefined. Conforming software must detect and report an error and may recover from it.

2.1 Collections

YAML collections allow for aggregation of data. There are two primary types of collections which YAML supports, sequences and mappings. Most tree structures can be constructed by nesting collections.

- Mark McGwire
- Sammy Sosa
- Ken Griffey

hr:  65
avg: 0.278
rbi: 147

american:
   - Boston Red Sox
   - Detroit Tigers
   - New York Yankees
   - Texas Rangers
national:
   - New York Mets
   - Chicago Cubs
   - Atlanta Braves
   - Montreal Expos

- 
  name: Mark McGwire
  hr:   65
  avg:  0.278
  rbi:  147
- 
  name: Sammy Sosa
  hr:   63
  avg:  0.288
  rbi:  141

?
    - New York Yankees
    - Atlanta Braves
:
  - 2001-07-02
  - 2001-08-12
  - 2001-08-14
?
    - Detroit Tigers
    - Chicago Cubs
:
  - 2001-07-23

invoice: 34843
date   : 2001-01-23
bill-to:
   given  : Chris
   family : Dumars
product:
   - quantity: 4
     desc    : Basketball
   - quantity: 1
     desc    : Super Hoop

2.2 Structures

YAML streams can be commented and separated into multiple documents. To allow for graph serialization, YAML has a built-in alias mechanism.

---
name: Mark McGwire
hr:  65
avg: 0.278
rbi: 147

---
name: Sammy Sosa
hr:  63
avg: 0.288
rbi: 141

# Ranking of players by
# season home runs.
---
   - Mark McGwire
   - Sammy Sosa
   - Ken Griffey

# Home runs
hr:
 # 1998 record
   - Mark McGwire
   - Sammy Sosa
# Runs batted in
rbi:
   - Sammy Sosa
   - Ken Griffey

# Home runs
hr:
 # 1998 record
   - Mark McGwire
   - &SS Sammy Sosa
# Runs batted in
rbi:
   - *SS
   - Ken Griffey

2.3 Styles

Besides the simple in-line scalars used above, YAML has support for several nested and quoted scalar styles. For small sequences and mappings, an in-line style helps make YAML easy to author.

--- ]
    Mark McGwire's
    year was crippled
    by a knee injury.

--- |
    \/|\/|
    / |  |_

--- ]\
Sosa completed
another fine
season. \u263A

name: Mark McGwire
occupation: baseball player
comments: ]
   Mark set a major
   league home run
   record in 1998.

years: "1998\t1999\t2000\n"
msg:   "Sosa did fine. \u263A"

- ' \/|\/|  '
- ' / |  |_ '

- [ name        , hr,  avg ]
- [ Mark McGwire, 65, 0.278 ]
- [ Sammy Sosa  , 63, 0.288 ]

Mark McGwire: {hr: 65, avg: 0.278}
Sammy Sosa:   {hr: 63, avg: 0.288}

2.4 Type Family

To encode data type and other application semantics in a YAML serialization, every node has a type family and leaf nodes have a syntax format.

invoice: 34843
date   : 2001-01-23
buyer:
  given  : Chris
  family : Dumars
product:
  - Basketball: 4
  - Superhoop:  1

invoice: !int|dec 34843
date   : !date|ymd 2001-01-23
buyer: !map
   given  : !str Chris
   family : !str Dumars
product: !seq
   - !str Basketball: !int 4
   - !str Superhoop:  !int 1

--- !binary|base64 ]
 R0lGODlhDAAMAIQAAP/
 9/X17unp5WZmZgAAAOf
 n515eXvPz7Y6OjuDg4J
 +fn5OTk6enp56enmlpa
 NjY6Ojo4SEhP/++f/++
 f/++f/++f/++f/++f/+
 EeECcgggoBADs=

--- !seq
  0: Mark McGwire
  1: Sammy Sosa
  2: Ken Griffey
---
empty: !map
invoice: !str 34843

--- !clarkevans.org/schedule/^entry
who: Clark C. Evans
when: 2001-11-18
hours: !^hours 3
description: ]
   Wrote up these examples
   and learned alot about
   baseball statistics.

--- !clarkevans.com/graph/^shape
- !^circle
  center: &ORIGIN {x: 73, y: 129}
  radius: 7
- !^line [23,32,300,200]
- !^text
  center: *ORIGIN
  color: 0x02FDBA
  value: Center of circle

2.5 Full Length Examples

Following are two full-length examples. On the left is a sample invoice, on the right is a sample log file.

--- !clarkevans.com/^invoice
invoice: 34843
date   : 2001-01-23
bill-to: &id001
    given  : Chris
    family : Dumars
    address:
        lines: |
            458 Walkman Dr.
            Suite #292
        city    : Royal Oak
        state   : MI
        postal  : 48046
ship-to: *id001
product:
    - sku         : BL394D
      quantity    : 4
      description : Basketball
      price       : 450.00
    - sku         : BL4438H
      quantity    : 1
      description : Super Hoop
      price       : 2392.00
tax  : 251.42
total: 4443.52
comments: ]
    Late afternoon is best.
    Backup contact is Nancy
    Billsmer @ 338-4338.

---
Date: 2001-11-23
Time: 13:02+5:00
User: ed
Warning: ]
  This is an error message
  for the log file
---
Date: 2001-11-23
Time: 15:02+5:00
User: ed
Warning: ]
  A slightly different error
  message.
---
Date: 2001-11-23
Time: 15:03+5:00
User: ed
Fatal: ]
  Unknown variable "bar"
Stack:
  - file: TopClass.py
    line: 23
    code: |
      x = MoreObject("345\n")
  - file: MoreClass.py
    line: 58
    code: |
      foo = bar

3.1 General Concepts

There are several core concepts shared by each information model, primarily relating to type information and how it is communicated between the serialization format and a native binding.

3.2 Graph Model

The graph model abstracts data structures of common programming languages. The model is a graph of collection and scalar values, where each node in the graph is provided with type information. The model provides an intermediate interface between the parser/emitter, which can be shared by multiple native languages, and the loader/dumper, which is specific to a particular binding. The model also provides a concrete representation for language-independent storage, simple structural queries, and graph transformations.

In the graph model, YAML is viewed as a directed graph of typed nodes. Nodes that can reference other nodes are collections and nodes with a string representation are scalars. The graph model also requires node identity and a mechanism to determine if two different nodes have the same content.

3.3 Tree Model

To allow for YAML to be communicated as a series of events, an ordered tree structure must be used instead of a graph. This section describes an extension to the graph model where the graph is flattened and ordered to provide a tree interface. The resulting tree-structured model imposes a linear ordering and uses several constructs which are not part of the graph model. Applications constructing a native binding from the tree model should not use these additional constructs and the imposed ordering for the preservation of important data.

3.4 Syntax Model

To enhance readability, a YAML serialization extends the tree model with syntax styles, comments and directives. Although the parser may provide this information, applications should take care not to use these features to encode information found in a native binding.

4.1 Characters

Characters are the basis for a serialized version of a YAML document. Below is a general definition of a character followed by several characters which have specific meaning in particular contexts.

4.2 Line Processing

Serialized YAML uses text lines to convey structure. This requires special processing rules for white space (space, tab and line break) characters. These rules are compatible with Unicode's newline guidelines.

# These are three throwaway comment

# lines (the second line is empty).
this: |
    contains two lines of text, the
    # second of which starts with '#'.
# A comment may follow a leaf value.

4.3 YAML Stream

A series of bytes is a YAML stream if, taken as a whole, it complies with the following production. Note that an empty stream is a valid YAML stream containing no documents.

--- ]
This YAML stream contains a single text value.
The next stream is a log file - a series 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
type: GET
HTTP: '1.0'
url: '/index.html'
---
at: 2001-08-12 09:25:10.00
type: GET
HTTP: '1.0'
url: '/toc.html'

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

# The following is a sequence of five documents.
# The first two contain an empty map, the second two
# an empty sequence, and the last an empty string.
--- {}
--- !map
--- []
--- !seq
---

# All entries in the series
# have the same type and value.
- 10.0
- !float 10
- !yaml.org/^float '10'
- !https://yaml.org/float ]\
  1\
  0

# Private types are per-document.
---
pool: !!ball
   number: 8
   color: black
---
bearing: !!ball
        material: steel

# 'http://company.tld/invoice' is some type family.
invoice: !company.tld/^invoice
  # 'seq' is a shorthand for 'https://yaml.org/seq'.
  # This does not effect '^customer' below
  # because it is does not specify a prefix.
  customers: !seq
    # '^customer' is a shorthand for the full
    # notation 'http://company.tld/customer'.
    - !^customer
      given : Chris
      family : Dumars

# It is possible to use XML namespace URIs as
# YAML namespaces. Using the ancestor's URI
# allows specifying it only once. The $ separates
# between the XML namespace URI and the tag name.
doc: !http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd$^html
 - !^body
  - !^p This is an HTML paragraph.

4.4 Alias

Once an anchor is used to mark a node, an alias should be used to indicate additional occurrences of the node in the graph. An alias refers to the most recent preceding node having the same anchor.

An alias node only exists in the syntax and tree models. When converted to the graph model, an alias node becomes a second occurrence of the anchored node.

It is an error to have an alias use an anchor which does not occur previously in the serialization of the document.

anchor : &A001 This leaf has an anchor.
override : &A001 ]
 The alias node below is a
 repeated use of this value.
alias : *A001

4.5 Branch

Branch nodes come in two styles, series and keyed. Each style has two variants, nested and in-line.

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

empty: {}
inline: { one: 1, two: 2 }
nested:
 first : First entry
 second:
  key: Subordinate keyed
 third:
  - Subordinate series
  - !map
  - Previous keyed is empty.
  - A key: value pair in a series.
    A second: key:value pair.
  - The previous entry is equal to the following one.
  -
   A key: value pair in a series.
   A second: key:value pair.
 !float 12 : This key is a float.
 ? ]
  ?
 : This key had to be protected.
 ? ]\
  \a
 : This key had to be escaped.
 "\b": Another way to escape
 ? ]
  This is a
  multi-line
  plain key
 : ]
  Whose value is
  also multi-line.
 ?
  - This key
  - is a series
 :
  - With a series value.
 ?
  This: key
  is a: mapping
 :
  with a: mapping value.

4.6 Leaf

While most of the document productions are fairly strict, the leaf production is generous. It offers three in-line style variants and eight nested style variants to choose from depending upon the readability requirements.

Throwaway comments may follow a leaf node, but may not appear inside one. The first comment line following a nested leaf node must be explicit and less indented than the nested leaf value. Further comment lines are unrestricted. Comment lines following an in-line leaf node are unrestricted.

Empty lines in nested leaf blocks appearing before the trailing explicit comment line, if any, are interpreted as content rather than as implicit comments. Such lines may be less indented than the text content.

empty: |
detected: |
 The \ character may be freely
 used. Leading white space
    is significant.

 All line breaks are significant,
 including the final one. Thus
 this value contains one empty
 line and ends with a line break,
 but does not start with one.
# Comments may follow a nested
 # leaf value. Once the first
  # comment line is seen, they
   # can be at any indentation
    # level, or even empty lines.

# Explicit indentation must
# be given in all the three
# following cases.
leading spaces: |2
      This value starts with
  four spaces. It ends with
  two line breaks.

leading line break: |2

  This value starts with
  a line break and ends
  with one.
leading comment indicator: |2
  # first line starts with a
  #. This value does not start
  with a line break but ends
  with one.
# Explicit indentation may
# also be given when it is
# not required.
redundant: |2
  This value is indented 2 spaces.

empty: |-
detected: |-
 All line breaks are significant,
 except for the trailing ones.
 Thus this value does not end
 with a line break.

# Comments may follow.

empty: |\
detected: |\
 Escape sequences may be used,
 for example this\nforces a
 line break and th\
 is isn't one. Quotes " '
 and other indicators may be
 freely used, but the \\
 character must be escaped.
explicit: |\2

  This value starts with
  a line break but does
  not end with one.\
# Comments may follow.

empty: |\-
detected: |\-
 Trailing line breaks
 are stripped, so this
 value does not end
 with a line break.

escaped: |\-
 Escaped line breaks
 are not chomped so
 this value ends with
 a single line break.\n

ignored: |\-
 It is possible to
 explicitly ignore
 a trailing line break,
 for example in case
 it is an LS or PS
 character.\
# Comments may follow.

empty: ]
detected: ]
 Line feeds are converted
 to spaces, and the final
 line break series is
 clipped, so this value
 contains no line breaks.
explicit: ]2

  An empty line, either
  at the start, end of
  in the value:

  Is interpreted as a
  line break. Thus this
  value contains three
  line breaks.

# Comments may follow.

empty: ]-
detected: ]-
 The final sequence of
 line breaks is chomped,
 so this value contains
 no line breaks.

# Comments may follow.

empty: ]\
detected: ]\
 Escaped line feeds are not
 converted to a space, so
 this \n is a line feed.
explicit: ]\2

  This value starts with
  a line feed, but doesn't
  end witj one even though
  it has a trailing empty
  line.\

# Comments may follow.

empty: ]\-
detected: ]\-
 Trailing line feeds are
 chomped, but escaped ones
 are preserved, so this
 value ends with a single
 line feed.\n

# Comments may follow.

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

empty: ""
second: "! : etc. can be used freely."
third: "a \" or a \\ must be escaped."
fourth: "this value ends with an LF.\n"

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

5.1 Sequence

This type family is used for series 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 this type family to an empty leaf 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 null values, 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
# loaded to a sequence, with
# unspecified entries containing
# a null value.
sparse sequence: !seq
    2: Third entry
    4: ~
# The following sequence node is
# loaded into an identical
# in-memory sequence, which has
# a seperate identity.
equal sequence:
 - ~
 - ~
 - Third entry
 - ~
 - ~

5.2 Map

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

Applying this type family to an empty leaf provides a natural syntax for representing an empty map.

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

If the set of keys of a map happens to be all the integers in the range 0 to some N, YAML allows serializing the map using the series style with an explicit map type family.

5.3 String

This type family is used for all leaf styles with the exception of simple leaves, unless they are given an explicit transfer method property. It is also used as the implicit type for all simple leaves starting with an alphabetic character. Note that all non-ASCII characters are assumed to be alphabetic for this purpose. This allows the detection pattern to be independent of the Unicode character properties table.

This type is usually bound to the native language's string or character array construct.

Specifying an explicit string type family is required to bypass implicit typing for a simple leaf. The same effect can be achieved by converting it to another leaf style.

# The following leaves are
# loaded to the string
# value '1' '2'.
- !str 12
- '12'
- "12"
- ]
 12
- ]\
 1\
 2
- |-
 12

5.4 Null

The null type family accepts simple leaves 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.5 Pointer

The pointer type family accepts a keyed node with a single key, '=', and is loaded 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 loaded
# into a pointer to a text string.
YAML: !ptr
 = : content

5.6 Integer

The integer represents arbitrarly sized mathematical integers less than infinity. Integers can be formatted using the familar decimal notation, or may have a leading '0x' to signal hexadecimal, or a leading '0' to signal an octal base. Leaves of this type should be represented by a native integer data type, if possible. However, there are cases where an integer provided may overflow the native type's storage capability. In this case, the loader should find some manner to round-trip the integer, perhaps as a string value. In general, integers representable using 32 binary digits should safely round-trip through most systems.

canonical: 12
decimal: +12
octal: 014
hexadecimal: 0xC

5.7 Float

The floating point type family handles approximations to real numbers. This should be loaded to some native float data type. The loader 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 loader, though 32 bit IEEE floats should be safe.

canonical: 1.23e-1
exponential: 12.30e-02
fixed: 0.1230

5.8 Date

YAML supports a single date format which is a strict subset of the ISO 8601 standard and the formats proposed by the W3C note on datetime.

date: 2001-12-14

5.9 Time

YAML supports a single time of day format which is one of many formats defined in the ISO 8601 standard. The format chosen was motivated by the W3C note on this issue.

canonical: 21:59:43.1
hms: 21:59:43.10

5.10 Timestamp

A timestamp denotes a particular point in time, which is a combination of a date and a time of day. Hence the format for a timestamps builds upon the format for a date and a time. The caninical combination chosen is a subset of a valid ISO 8601 format. A similar, more readable format, is also supported.

canonical: 2001-12-15T02:59:43.1Z
valid iso8601: 2001-12-14T21:59:43.10-05:00
space separated: 2001-12-14 21:59:43.10 -05:00

5.11 Binary

The binary type family accepts the base64 format 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).

canonical: !binary ]\
 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=
base64: !binary ]
 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.12 Special Keys

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

All special keys stand for special in-memory values which are different from any value in any other type family. Specifically, these special in-memory values must not be implemented as string values.

The '=' key is used to denote the "default value" of a map. In some cases, it is useful to migrate a schema so that a scalar value is replaced with a collection. A processor may present a "scalar value" method which provides the value directly if the node is a scalar, or, returns the value of this special key if the node is a collection. If applications only ask for the scalar value, then the schema may freely grow over time replacing scalar values with richer data constructs without breaking older processing systems.

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

The rest of the keys should not be used in serialized YAML documents. Their names are merely a convention for representing the appropriate special in-memory values. Hence these keys are called "virtual keys".

Virtual keys are used when a YAML parser encounters a valid YAML value of an unknown transfer method. For a schema-specific application, this is not different from encountering any other valid YAML document which does not satisfy the schema. Such an application may safely use a parser which rejects any value of any unknown transfer method, or discards the transfer method property with an appropriate warning and parses the value as if the property was not present.

For a schema-independent application (for example, a hypothetical YAML pretty print application), this is not an option. Parsers used by such applications should encode the value instead. This may be done by wrapping the value in a map containing virtual special keys. The '!' key denotes the unsupported type family, and the '|' key denotes the format used. In some cases it may be necessary to encode anchors and alias nodes as well. The '&' and '*' keys are used for this purpose.

This encoding should be reversed on output, allowing the application to safely round-trip any valid YAML document. In-memory, the encoded data may be accessed and manipulated in a standard way using the three basic data types (map, sequence and string), allowing limited processing to be applied to arbitrary YAML data.

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
# should NOT be serialized this way.
encoded node :
 !special '!' : '!type'
 !special '&' : 12
 = : value
# The proper way to serialize the
# above structure is as follows:
node : !!type &12 value

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

Changes From The 20 Feb 2002 Draft

Anchors for aliases

Are now forbidden.

Timestamp format

Fixed a problem with the regexp. Allow both a valid ISO8601 format (using 'T') and a space separated format (for readability).

Productions

Break node productions to smaller bits.

Changes From The 20 Feb 2002 Draft

YAC#22

The #TAB directive is now required to allow tabs in indentation.

Changes From The 16 Feb 2002 Draft

Corrected examples

Floating point numbers in all examples now statr with '0'.

Wording improvements

In various places.

Empty line indentation

Is now be indent(<=n) instead of the previous indent(n)?

Changes From The 10 Feb 2002 Draft

YAC 20

The yaml: scheme has been replaced by an http: one. Mapping of XML namespaces is now done using '$' instead of ';'. The prefix indicator is now '^' and the format indicator is now '|'.

Changes From The 10 Dec 2001 Draft

Transfer Method

Is now split to type family and format; type family is now a URI.

Date/Time Types

Were added.

Tree Model

Now includes the format.

Wording changes

Throughout the whole spec.

Format in Transfer Method

Is now separated by a '`'.

YAC List

Removed the Probable changes section; it is now replaced by the YAC list.

YAC#3, YAC#5

Added a uniform URI based namespace scheme.

YAC#6

Unrecognized explicitly typed implicit (simple) leafs are allowed.

YAC#7

C1 Control codes are explicitly forbidden.

YAC#10

In-series in-line syntax was modified according to the flexible indentation scheme (YAC needs to be updated).

YAC#11

Rename implicit leaves to simple leaves.

YAC#12

Throwaways are now allowed everywhere. Blank lines are comments. There are ambiguity problems in chomped leaf values.

YAC#13

Indentation is now generic (flexible).

YAC#14

Nested leaf format is now built out of three orthogonal properties.

YAC#15

Top level nodes can be in-line.

YAC#16

A '--- #YAML:1.0' is assumed if there's no header.

YAC#18

YAML Ain't Markup Language

Changes From The 11 Nov 2001 Draft

Quoted Strings

Are now implemented as a text implicit transfer format. This changed slightly the definition of an escaped leaf so that the two would be equivalent.

Relative DNS type familys

Are now supported using the simplest form only. the definition of an escaped leaf so that the two would be equivalent.

Syntax/Grammar/Formatting

Were fixed according to Brian's inputs.

Block

Is now chomped using '||' rather than '|-' for consistency.

Document Header

Can now be anything starting with '--'; therefore is required before the first document in a multi-document stream.

Transfer Methods

Can now accept any printable characters, not just words. '!' now means 'force implicit typing'.

New Scalar Styles

We now have the following: | || \ \\ ' " implicit.

Treat sequence/map as Collection Styles

In productions and in information model.

Add Structured Keys

Using a key indicator (done - Oren).

Add Examples

Added a detailed examples section to the introduction to better acquaint the user so that the spec can proceed with some basic knowledge.

In-line maps/sequences

Are now supported. Empty maps/sequences are a natural special case.

Minor Changes

Made list of prior versions shorter.

Moved list of changes down... it was cluttering the top of the spec.

Information model and Preview

Completely new rewrite.

Changes From The 04 Nov 2001 Draft

Polish

Minor wording fixes, added internal links, etc.

List

Was renamed to "sequence".

Separator

Was changed to "---" instead of "----".

Indentation

Was changed to one space instead of one tab.

Base64

Is no longer an implicit type. The surrounding '[=...=]' are kept, however, in case we change our mind later (e.g., if we introduce pipelining). The type was renamed to "binary" to stress its class rather than the encoding used.

Float

Was renamed to "real" to decouple it from specific in-memory representation. Mathematicians may object :-)

Length

Was removed from the sequence map.

Type vs. Class

Added some wording to clarify the difference. Most likely this will need to be changed once we settle the pipelining issue.

Productions

Were completely overhauled, again, to accomodate the new semantics.

Next Line Scalars

Now have two separate indicators, one for quoted and one for unquoted values.

Duplicate keys

Are now an error. The parser may ignore the second occurrence with a warning.

Changes From The 12 Aug 2001 Draft

Indentation

Has been changed to use tabs instead of spaces.

Throwaway comments

Were added. The persistent comment key was changed to '//'.

Indicators

Were changed. '-' now signifies a list entry and '\' signifies a next-line leaf value. '@' and '%' are no longer necessary (they may be if we ever support map/list keys). As a result no lookahead is ever required.

Multiple documents

Are now possible in a single file (again), using '----' as a separator.

Wording

Has been changed in numerous locations, hopefully to make it clearer. There was also some shuffling of the text sections to remove redundancy.

Productions

Were thoroughly overhauled and therefore undoubtedly contain new bugs. Also, all the shorthand production names were replaced by long ones to improve readability.

Indicator keys

Are no longer allowed. Structure keys are used instead, where some have only an in-memory representation.

Map/List keys

Are no longer allowed. This may have to be revisited when Perl 6 comes out.

Deep References

Are still supported but as an explicit type rather than as a hack.

Types List

Has been shrunk to only the common types, with a reference to yaml.org for a fuller list of types. The three core types were added as required types.

Type vs. Kind

This distinction was inserted explicitly into the text, with several examples to drive the point home.

Changes From The 01 Aug 2001 Draft

Character Set

Is now defined as simply printable Unicode characters without explicit ranges. This makes the spec resistant to the evolution of the Unicode spec.

Reserved Indicators

The set of such indicators has been minimized. There is now a conflict between reserving them for future use and allowing people to use them as markers for implicit leaf types.

Simple Scalar

Has been renamed to unquoted leaf.

Generic Model

Has been generalized to allow for types nodes.

Implicit Typing

Has been added with an assortment of suggested types.

General Keys

Keys can now be any nodes to allow for Java serialization.

Multi-level references

Are now supported for Perl serialization.

Changes From The 31 Jul 2001 Draft

Simple Scalar and End Of Lines

Moved eol productions to the end, rather than the start, of most productions. The wording and productions for the simple leaf were fixed to match each other and the intended semantics. The simple leaf example set was enhanced to clarify the proper interpretation.

Empty Document

Both empty top level maps and no top level maps are now allowed, and hence so are empty documents.

Changes From The 22 Jul 2001 Draft

Thanks to Joe Lapp for reviewing the 22 Jul 2001 draft and recommending these changes.

Phrasing fixes

Fixed phrasing in the abstract, and sections 1.3, 2.1, 2.3.1, 2.4.3, 2.4.4, 2.4.5, 2.4.6 and 2.5.3.

Production fixes

Fixed productions: added production 47, 59, fixed productions 57, 58, 60 and 64 (productions numbers in the 22 Jul 2001 draft are off by one in some cases). Most are bug fixes. Actual changes include allowing for empty lines surrounding a top level map, allowing an optional trailing separator line, and forbidding annotations which have no sensible semantics (anchor to null, anchor to a reference, shorthand for a reference).

Changes From The 23 Jun 2001 Draft

Merge Spec

Due to the decision to leave all API related issues outside the core spec, the spec has been re-merged into a single file, covering just what used to be the introduction and serialization sections of the previous specs.

Character Encodings

The spec now refers only to the Unicode standard. Due to the efforts by the Unicode and ISO/IEC 10646 groups, both standards are in almost complete agreement. The additional features provided by the ISO/IEC standard are rarely used in practice, while Unicode is simpler and is more widely supported by existing languages and systems.

Strict Indentation

Indentation is now a strict 4 spaces per level. This allows for the new whitespace policy and the new block notation.

Shorthand Notation

The spec introduces a shorthand notation for attaching special keys to any node kind (converting it to a map if necessary). This will need more work.

Null Nodes

Null nodes have finally been added, after somehow eluding all previous versions.

Bullet Lists

Change the * optional prefix for leaf list entries to a mandatory : and therefore remove the special name "bulleted list entries".

Simplify Keys

Multi-line simple keys are now out. The door is open for re-introducing them, however.

Change Whitespace Policy

White space folding has been replaced by line break folding. White space is now always significant, except for indentation and for separation of structure tokens.

Block Scalar Syntax

The syntax for block leaves has been replaced by a more elegant one.

Changes From The 16 Jun 2001 Draft

Split Spec

The spec is now separated into several files. This allows different versions of the spec to share the same version of unchanged section, and make it easier to refer to a particular version of important pieces of the spec such as serialization and interfaces. All the HTML files use the same shared CSS file. Cross references between the separate parts of the spec are now relative, though references to older versions are absolute and refer to the main site.

Cyclical Graph

Change the wording on the information model to allow for graphs with cycles. The alternative is to define the anchor semantics in such a way that would preclude cycles.

Null Character Escape

The escape sequence \z was added to allow convenient escaping of the ASCII zero (null) character.

Remove Binary Scalars

The information model now contains just one type of leaf. The special syntax for binary leaves has been removed. This functionality will be re-added in the form of a color.

Remove Class Shorthand

The syntax no longer supports the !class syntax. This functionality will be re-added in the form of a color.

Bullet Lists

Change the optional prefix for leaf list entries to * and rename such entries to "bulleted list entries".

Make Keys More Scalars-Compatible

Allow for multi-line simple keys and unify the description of leaf keys and values where it makes sense.

HTML Tidying

All the HTML pages have gone through Tidy. Also, all the HTML files have been run through an HTML validation service and a CSS validation service. Broken links and spelling were checked using another online HTML validator. This needs to be repeated for all future drafts.

Changes From The 09 Jun 2001 Draft

Relationship with MIME

Beyond using base64 for binary leaves, no additional special relationship with MIME is expected. Hence references to the MIME and mail RFCs were moved from section 1.1 ("required reading") to section 1.2 ("background material").

Strict Indentation

Indentation is now completely strict for all leaf styles. Also, the productions were changes to use a consistent semantics to the indentation level parameter.

List Scalar Prefixes

A list leaf entry may be prefixed by an optional : indicator to improve readability of multi-line simple leaf values.

Anchor Semantics

Leading zeros are now ignored for comparing anchor strings.

No Empty Line At Start

The document production was fixed so as not to require an empty line at the start of a document.

Character Escapes

The set of character escapes is now maximal (including the rare \e escape for the useful ASCII ESC character). Also, it is now possible to "escape" a line break in a quoted string (the previous drafts were inconsistent at this point).

32 Bit Characters

The current draft allows such characters, and includes a specialized escaping format ('\Uxxxxxxxx') to support them.

Changes From The 26 May 2001 Draft

Changes Section

The changes section was added for easier comparison of different versions. The final draft will not contain this section.

Class Indicator

The indicator was changed from # to ! to allow for # to be used for comments.

No Empty Line At End

The document production was fixed so as not to require an empty line at the end of a document.

Strict Indentation

Indentation in quoted strings and binary blocks is now strict to ensure readability.

Productions

Problems in the productions were fixed, especially where related to white space issues and formatting of the result.

BOM Comment

The link to the Unicode FAQ was moved to section 2.2.2.

Binary Scalars

The information model now distinguishes between text and binary leaves.