Yet Another Markup Language (YAML) 1.0

2.2.1 Character Set

Serialized YAML uses a subset of the Unicode character set.

Due to the end of line normalization rules, the carriage return (#xD) is not included. As with standard practice, the the surrogate block, FFFE and FFFF are excluded.

2.2.2 Encoding

A YAML processor is required to support both UTF-16 and UTF-8 character encodings. If an input stream begins with a byte order mark, then the initial character encoding shall be UTF-16. Otherwise, the initial encoding shall be UTF-8.

If the stream begins with #xFFFE, then the byte order of the input stream must be swapped when reading. For more information on the byte order mark see the Unicode FAQ.

2.2.3 End-of-Line Normalization

On input and before parsing, a compliant YAML parser must translate both the two-character sequence #xD #xA (CR LF) and any #xD (CR) which is not followed by a #xA (LF) into a single #xA (LF) character (this does not apply to escaped characters). This allows for the definition of an end-of-line marker.

On output, a YAML emitter is free to serialize end of line markers using what ever convention is most appropriate. For Internet mail, CRLF is the preferred form.

2.2.4 Indicators

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

2.2.5 Escape Sequences

Escape sequences are used to denote significant whitespace, specify characters by a hexadecimal value, and produce the literal quote and escape indicators.

2.2.6 Miscellaneous Characters

This section includes several common character range definitions.

2.3.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 spaces or tabs. 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.

2.3.2 Line Folding

To increase readability, YAML serialization allows for breaking long text lines. Therefore in many cases the parser replaces a line break with a single space (#x20). When encountering a sequence of (possibly indented) line breaks without any additional intermediate characters, the parser ignores the first one and preserves the rest. Thus, a single line break would be serialized as two, two line breaks would be serialized as three, etc. When this functionality is implied, the lfeols(n) production below will be used.

In quoted strings there is special handling of line breaks immediately preceded by a \ character. In this case the following production is used:

2.3.3 Quoted String

A quoted string is a mechanism to treat a sequence of characters as a single unit. Within a quoted string, indicators (with the exception of \ and ' or ") can be used without worry and escape sequences can be used to introduce unprintable characters and control line folding.

A quoted string begins and ends with a quote character. It can extend for as many lines as necessary, although an editor or emitter is free to re-break and indent a quoted string as needed to maintain readability.

A line break in a multi-line quoted string is subject to line folding, unless prefixed by a \ in which case the line break is completely ignored. This allows a quoted string to be broken into multiple lines at arbitrary positions.

A quoted string cannot contain an un-escaped quote or an invalid escape sequence.

anchor : &0001  This scalar has an anchor.
repeat :  &001  An anchor string may be reused.
non-ref:        Next node refers to the previous one.
reference: *01

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

list: @
    : First item in top list
    : @
        : Subordinate list
    : @
    : Above list is empty
    :
        A multi-line
        bulleted list entry
    : Sixth item in top list

map: %
    first : First entry
    second: %
        key: Subordinate map!
    third item: @
        : Subordinate list
        : %
        : Previous map is empty.
    ":": This key had to be quoted.
    "This is
    a multi-line
    key" :
        Whose value is in the next line.

line: [!line] %
    from: [!point] %
        x: 12.5
        y: 3.5
    to:
        !: point
        x: 12.5
        y: 3.5
ordered: 10-JAN-2001
sent: [!date %m/d/y] 1/12/2001
delivered: %
    !: date
    %: d/m/y
    =: 14/1/2001
triangle: [!poly] @
    : [!point] %
        x: 12.5
        y: 3.5
    : [!point] %
        x: 3.5
        y: 12.5
    : [!point] %
        x: 1.5
        y: 2.3

first: "Quoted scalar.\nWith a new line."
second: @
    :   "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."
    :   'Each type of quotes may
        be used to avoid the need
        for quoting the other: "'
    :   "Furthermore indicators such
        as @ # : can be added."
    :   'Escape sequences can be used
        to specify quotes and unprintable
        characters: \', \a, \x01.'
    :   "  Leading and trailing  
           spaces are significant
           in all lines   "
    :   'This was a list of six quoted
        scalars!'

empry:
first: The value of the previous key is the empty string.
second:
     This value has just one leading white space,
    and is terminated by a hard newline (LF).

third:
    <html><head><title>Embedded HTML!</title></head>
    <body><p class="none">This can even
    have embedded HTML since there is no
    escaping, and since < (the starting character)
    is not an indicator!
    </p></body>
fourth: Indicators like @ : % are allowed, as 
    well as quotes, as long as the first
    character is not an indicator.  Further,
    whitespace     is   preserved.
fifth: @
    : A single line entry.
    :   A second, multi-line,
        entry of the list.
    :
        A third, multi-line list
        entry, without any leading
        or trailing white space.
    :


    :   The value of the previous
        entry is two hard newlines
        (LF LF).

first: |
    This is a block scalar,    with significant
    whitespace, and the use of " @, etc.
         All whitespace    is    significant.
second: |-
    No leading nor trailing new line.
second: @
    : |
        
        First list item which has a 
        leading and trailing new line.
    : |-
        Second list item. Does not have 
        leading nor trailing new line.  
        Has two new lines altogether.

3.1 Changes From The 31 Jul 2001 Draft

Simple Scalar and End Of Lines

Moved eol productions to the end, rather then the start, of most productions. The wording and productions for the simple scalar were fixed to match each other and the indended semantics. The simple scalar 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.

3.2 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.4, 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 seperator line, and forbidding annotations which have no sensible semantics (anchor to null, anchor to a reference, shorthand for a reference).

3.3 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 type (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 scalar 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 seperation of structure tokens.

Block Scalar Syntax

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

3.4 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 scalar. The special syntax for binary scalars 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 scalar 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 scalar 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.

3.5 Changes From The 09 Jun 2001 Draft

Relationship with MIME

Beyond using base64 for binary scalars, 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 scalar styles. Also, the productions were changes to use a consistent semantics to the indentation level parameter.

List Scalar Prefixes

A list scalar entry may be prefixed by an optional : indicator to improve readability of multi-line simple scalar 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.

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

3.7 Probable Future Changes

Character Set

It may be useful to base the definition of a valid character on Unicode character properties. For example, we may define a valid character as any printable Unicode character.

Shorthand Syntax

As this is the first draft to contain this features, changes are to be expected. In particular, the exact set of valid keys needs to be defined and partitioned to "standard YAML keys" and "application defined keys". Similarly, the set of possible values for each key must be defined. Currently, for example, it excludes the possibility of using Java style '.'-separated class names as a value.

Shorthand References

On the one hand, this may be useful. On the other, in some cases (reference to a map), it is no longer possible to map a YAML reference to a native language pointer or reference. The current draft simply forbids attaching shorthand to a reference, but the decision is not final (yet).

Seperator Lines

The policy with regard to seperator lines and empty lines following them needs to be finalized.

Reviewing Examples

Ensure there are enough examples. In particular, special syntax forms should be demonstrated to remove doubt in the interpretation of the productions.

Verifying Productions

Verify all productions are correct, are actually used, and properly hyper-linked. Joe has done a good job reviewing the previous draft, so this draft is much improved. Still, a re-verification will need to be done for a release candidate.

Polish

Spell and grammar checking, formatting, etc. Again, this draft is much improved thanks to Joe's review, but this will need to be repeated for a release candidate.