Yet Another Markup Language (YAML) 1.0

2.2.1 Character Set

By default, serialized YAML uses a subset of the ISO/IEC 10646 character set.

[01]

char

::= #x9 | #xA | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]

/* a single Unicode character, including the space and new line characters */

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.

In the information model binary scalar values do not comply with the above character set. Such values are taken to contain arbitrary non-textual data and therefore are not concerned with character set issues.

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.

[02]

bom

::= #xFEFF

/* the Unicode ZERO WIDTH NON-BREAKING SPACE character used to mark a UTF-16 stream and determine byte ordering. */

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 allows for the definition of an end-of-line marker.

[03]	eol	::= #xA	/* a normalized end of line marker */
[04]	blank	::= eol eol	/* a blank line */

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.

It should be noted that this production does not imply that tab(3) is a constant thought the entire serialization, as the particular indentation style may change over time. Specifically, an indentation level tab(n) is set with the first subordinate line of a node at tab(n-1). All subordinate lines must share this same indentation setting. This allows indentation to vary over the serialization as long as it remains constant for a given node's content.

Since the YAML serialization depends upon indentation level to delineate blocks, additional productions are a function of an integer, based on the tab(n) production above. In all such cases, production(n) stands for a construct which is itself indented at tab(n) and whose subordinate lines are indented at tab(n+1).

2.3.2 Whitespace Folding

Since a YAML serialization uses whitespace for indentation, in many cases the parser must condense sequences of one or more whitespace characters into a single space (#x20). When this functionality is implied, the lfold production below will be used.

With this definition, there are two sorts of folded strings which are useful to describe.

A folded string starts with a printable which is not an indicator. It is then followed by a sequence of printable words with intermediate folded whitespace. At parse time, the folded space must be condensed into a single space (#x20) character.

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 \) can be used without worry and escape sequences can be used to introduce significant whitespace which would otherwise be subject to 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 considered to be white space for the purpose of folding, unless prefixed by a \ in which case the line break, and the indentation following it, are completely ignored. This allows a quoted string to be broken into multiple lines at arbitrary positions.

A quoted string can't contain two consecutive line breaks without an intermediate printable or escaped character. Also, a quoted string cannot contain an un-escaped quote or an invalid escape sequence.

[53]	qstr(n)	::=	iquote ( qchr | escape | lfold | qline(n+1) )* iquote	/* quoted string */
[54]	qline(n)	::=	iescape? tab(n) ( qchr | escape )	/* line break in a quoted string */

built-in:  !.real              23.42
local:     !local              Local class name.
non-class:                     Free of class.
qualified: !com.clarkevans.ts  Qualified class name.

anchor:    &0001         This scalar has an anchor.
clsanc:    !cls &0002    Has alocal class and an anchor.
non-ref:                 Next node refers to the previous.
reference: *02

list: @
  First item in top list
  @
    Subordinate list
  @
  Above list is empty
  : A multi line entry
    with the optional prefix
  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.

2.5 Scalars

While most of the document productions above are fairly strict, the scalar production is generous. It offers four in-line styles of expressing scalar values depending upon the readability requirements. The table below describes the various styles.

Note that if a YAML document is loaded into a random access representation, then the representation may ignore the distinction between the three text scalar styles, but must distinguish between a text scalar and a binary scalar.

2.5.1 Simple Scalar

For this case, each line is indented, whitespace is folded (line breaks always counts as white space), escaping is not available, and the content must not start with an indicator. To delineate the end of this scalar, indention is employed.

first: This is a one line scalar.
second:
    <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>
third: Indicators like @ : % are allowed, as
       well as quotes, as long as the first
       character is not an indicator.  Further,
       whitespace     is   folded.
fourth: @
    A single line entry.
    The second, multi-line,
        entry of the list.
    : The third list
      entry, with the
      optional : prefix.

2.5.2 Block Scalar

This mechanism supports source code or other text values with significant use of indicators, quoted escaping, or significant whitespace. To retain readability for this case, the block scalar allows raw text strings to be used in an indented fashion where each line indented is preceded by a block indicator. All whitespace is significant up to and including the end of line marker. To end the block, a block end indicator is used and any characters on this line are also included, up to and not including the end of line marker.

first: |This is a block scalar,    with significant
       |whitespace, and the use of " @, etc.
       |The \ is used to signify the end of the block.
       |     Whitespace    *is*    significant.
       \
second:
   \No leading nor trailing new line.
third: @
   |
   |First list item which has a
   |leading and trailing new line.
   \
   |Second list item. Does not have
   |leading nor trailing new line.
   |Does have three new lines in the
   \middle.

2.5.3 Quoted Scalar

A quoted scalar uses quoted strings. With this mechanism, the indicators (excepting the quote and slash) can be used freely, whitespace is folded (line breaks count as white space unless escaped), and escape sequences can be used to indicate significant whitespace, non-printable characters, quotes and slashes.

first: "Quoted scalar.\nWith a new line."
second: @
  "Spaces are folded so this
   new line is not significant."
  "Furthermore indicators such
   as @ # : can be added."
  "Escape sequences can be used
   to removed or \ add white\
   space, \\ and \" must be escaped."
  "The subordinate lines additional
      indentation may be more then a single
      space, and a line may be brok\
      en in mid-word."
  "This was a list of five quoted
   scalars!"

2.5.4 Binary Scalar

A binary scalar uses the base64 encoding. Base64 strings are a sequence of base64 characters intermixed with whitespace which is ignored by the base64 processor. An additional constraint is that no more than 76 base64 characters are allowed within each line.

binary: [R0lGODlhDAAMAIQAAP//9/X17unp5WZmZgAAAO
         fn515eXvPz7Y6OjuDg 4J+fn5OTk6enp56enmlp
         aWNjY6Ojo4SEhP/++f/++f/++f/++f/++f/++f
         /++f/++f/++f/++f/+ +f/++f/++f/++SH+Dk1h
         ZGUgd2l0aCBHSU1QACwAAAAADAAMAAAFLCAgjo
         EwnuNAFOhpEMTRiggc z4BNJHrv/zCFcLiwMWYN
         G84BwwEeECcgggoBADs=]
desc:
  The binary value above is a tiny arrow encoded
  as a gif image.

3.1 Parser Interface

The parser or iterator interface provides a sequential access to a YAML document where the flow control is dicated by the consumer. The parser interface uses the serialization model, handling duplicate nodes within the graph through a reference. The parser interface has several components.

As part of this interface, each cursor returned from the parser must remain valid until close() is called, or the next() is called on the cursor, or next() is called on an ancestral cursor. Note that this implies that N cursors may be open at any given time, one cursor for each map or list in a given lineage. It is the parser's task to make sure that each cursor points to valid information.

3.2 Emitter Interface

The emitter or visitor interface interface provides a sequential access to a YAML document where the flow control is dicated by the producer. The emitter interface uses the serialization model, handling duplicate nodes within the graph through a reference. The emitter interface has several components.

As part of this interface, a cursor is deemed valid untill end() has been called on it. It is an error to call end() on a cursor when a subordinate cursor is still valid. This implies that the emitter need not use N cursors, and that one cursor which is re-used with a depth indicator will suffice.

3.3 Interface Converter

In some cases it is necessary to convert a pull to a push interface, or a push to a pull interface. While converting from pull to push is relatively easy, converting from push to pull requires a multi-threaded approach or a large intermediate memory buffer. To help automate conversions, the YAML processing library includes both interface converters.

4.1 "C" Language

Since the "C" programming language does not have dynamic lists or maps, this binding only implements the sequential interface.

4.2 Python

For the Python binding, unless specified otherwise by a class, scalar values are bound to the string type, lists are bound to the list type, and maps are bound to the dictionary type with the key represented as a string.

If a scalar has a real class, then the scalar must be bound as a floating point value if possible, otherwise a warning must be issued. Likewise, if a scalar has a int class, then the scalar must be bound to a normal integer, otherwise a warning must be issued. Conversions can fail if the scalar value is not parse-able or if the size of the parsed value will not fit within the standard type.

If any other class is encountered, then the results depend upon the type. First, the class identifier is used to construct a class with the same package name. And then, depending upon the type, initialization is carried out differently. If the node is a map, then the keys are assumed to be attributes, and the setattr method is used to initialize the object. If the node is a scalar, then repr is used. Otherwise, if the node is a array, then additem method is used.

4.3 Perl

For the Perl binding...

4.4 Java

For the Java binding...

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

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

5.3 Probable Future Changes

API details

How the API handles the sequence of maps; push/pull issues; mapping to scripting languages of interest (Python, Perl); etc.

Color Idiom

It is possible to allow for schema evolution, attachment of comments, handling unknown classes and many other use cases by supporting the color idiom.

Comment Attribute

A textual comment may be attached to each node, similar to the class attribute. It is probably best to do this as part of the color idiom, but it could concievably be added on its own.

Canonical Form

It may be useful to define a canonical form for a YAML document, specifying completely indentation, folding, and white space issues. There are already two references to such a form in the draft; if we don't define such a form these references should be removed.

32-bit Characters

The implications of supporting them need to be checked and proper wording added to the draft. Given any kind of choice, the effects on complying YAML processors should be minimized.

Reviewing Examples

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

Tidying the HTML

Ensure the draft is valid (X)HTML using Tidy or the like, and ensuring all links (internal and external) are correct.

Verifying Productions

Verify all productions are correct, are actually used, and properly hyper-linked.

Polish

Spell and grammar checking, formatting, etc.