Semantic Coherence: YAML – Signal Evidence & AI Readability

[H1]
%YAML 1.2
---
YAML: YAML Ain't Markup Language™
What It Is:
YAML is a human-friendly data serialization
language for all programming languages.
YAML Specifications:
- YAML 1.2:
- Revision 1.2.2 # Oct  1, 2021 (About this version)
- Revision 1.2.1 # Oct  1, 2009
- Revision 1.2.0 # Jul 21, 2009
- YAML 1.1 # Jan 18, 2005
- YAML 1.0 # Jan 29, 2004
YAML Web Sites:
The YAML Company: yaml.com # We Support YAML!
YAML Playground: play.yaml.com # Try many YAMLs!
YAML Information: yaml.info # Learn about YAML!
YAML Test Matrix: matrix.yaml.info # Compare YAMLs!
Program in YAML: yamlscript.org # Code is Data!
YAML Matrix Chat: '#chat:yaml.io'
YAML IRC Channel: libera.chat#yaml
YAML on GitHub: # github.com/yaml/
YAML Specs: yaml-spec/
YAML 1.2 Grammar: yaml-grammar/
YAML Test Suite: yaml-test-suite/
...

Back to top

[H1] YAML Ain’t Markup Language (YAML™) version 1.2
[H2] Revision 1.2.2 (2021-10-01)
Copyright presently by YAML Language Development Team1
Copyright 2001-2009 by Oren Ben-Kiki, Clark Evans, Ingy döt Net
This document may be freely copied, provided it is not modified.
Status of this Document
This is the YAML specification v1.2.2.
It defines the YAML 1.2 data language.
There are no normative changes from the YAML specification v1.2.
The primary objectives of this revision are to correct errors and add clarity.
This revision also strives to make the YAML language development process more
open, more transparent and easier for people to contribute to.
The input format is now Markdown instead of DocBook, and the images are made
from plain text LaTeX files rather than proprietary drawing software.
All the source content for the specification is publicly hosted2.
The previous YAML specification3 was published 12 years ago.
In that time span, YAML’s popularity has grown significantly.
Efforts are ongoing to improve the language and grow it to meet the needs and
expectations of its users.
While this revision of the specification makes no actual changes to YAML, it
begins a process by which the language intends to evolve and stay modern.
The YAML specification is often seen as overly complicated for something which
appears to be so simple.
Even though YAML often is used for software configuration, it has always been
and will continue to be a complete data serialization language.
Future YAML plans are focused on making the language and ecosystem more
powerful and reliable while simultaneously simplifying the development process
for implementers.
While this revision of the specification is limiting itself to informational
changes only, there is companion documentation intended to guide YAML framework
implementers and YAML language users.
This documentation can continue to evolve and expand continually between
published revisions of this specification.
See:
YAML Resources Index
YAML Vocabulary Glossary
YAML Specification Changes
YAML Specification Errata
Abstract
YAML™ (rhymes with “camel”) is a human-friendly, cross language, Unicode based
data serialization language designed around the common native data types of
dynamic programming languages.
It is broadly useful for programming needs ranging from configuration files to
internet messaging to object persistence to data auditing and visualization.
Together with the Unicode standard for characters4, this specification
provides all the information necessary to understand YAML version 1.2 and to
create programs that process YAML information.
Contents
YAML Ain’t Markup Language (YAML™) version 1.2
Revision 1.2.2 (2021-10-01)

Chapter 1. Introduction to YAML
1.1. Goals
1.2. YAML History
1.3. Terminology

Chapter 2. Language Overview
2.1. Collections
2.2. Structures
2.3. Scalars
2.4. Tags
2.5. Full Length Example

Chapter 3. Processes and Models
3.1. Processes
3.1.1. Dump
3.1.2. Load

3.2. Information Models
3.2.1. Representation Graph
3.2.1.1. Nodes
3.2.1.2. Tags
3.2.1.3. Node Comparison

3.2.2. Serialization Tree
3.2.2.1. Mapping Key Order
3.2.2.2. Anchors and Aliases

3.2.3. Presentation Stream
3.2.3.1. Node Styles
3.2.3.2. Scalar Formats
3.2.3.3. Comments
3.2.3.4. Directives

3.3. Loading Failure Points
3.3.1. Well-Formed Streams and Identified Aliases
3.3.2. Resolved Tags
3.3.3. Recognized and Valid Tags
3.3.4. Available Tags

Chapter 4. Syntax Conventions
4.1. Production Syntax
4.2. Production Parameters
4.3. Production Naming Conventions

Chapter 5. Character Productions
5.1. Character Set
5.2. Character Encodings
5.3. Indicator Characters
5.4. Line Break Characters
5.5. White Space Characters
5.6. Miscellaneous Characters
5.7. Escaped Characters

Chapter 6. Structural Productions
6.1. Indentation Spaces
6.2. Separation Spaces
6.3. Line Prefixes
6.4. Empty Lines
6.5. Line Folding
6.6. Comments
6.7. Separation Lines
6.8. Directives
6.8.1. “YAML” Directives
6.8.2. “TAG” Directives
6.8.2.1. Tag Handles
6.8.2.2. Tag Prefixes

6.9. Node Properties
6.9.1. Node Tags
6.9.2. Node Anchors

Chapter 7. Flow Style Productions
7.1. Alias Nodes
7.2. Empty Nodes
7.3. Flow Scalar Styles
7.3.1. Double-Quoted Style
7.3.2. Single-Quoted Style
7.3.3. Plain Style

7.4. Flow Collection Styles
7.4.1. Flow Sequences
7.4.2. Flow Mappings

7.5. Flow Nodes

Chapter 8. Block Style Productions
8.1. Block Scalar Styles
8.1.1. Block Scalar Headers
8.1.1.1. Block Indentation Indicator
8.1.1.2. Block Chomping Indicator

8.1.2. Literal Style
8.1.3. Folded Style

8.2. Block Collection Styles
8.2.1. Block Sequences
8.2.2. Block Mappings
8.2.3. Block Nodes

Chapter 9. Document Stream Productions
9.1. Documents
9.1.1. Document Prefix
9.1.2. Document Markers
9.1.3. Bare Documents
9.1.4. Explicit Documents
9.1.5. Directives Documents

9.2. Streams

Chapter 10. Recommended Schemas
10.1. Failsafe Schema
10.1.1. Tags
10.1.1.1. Generic Mapping
10.1.1.2. Generic Sequence
10.1.1.3. Generic String

10.1.2. Tag Resolution

10.2. JSON Schema
10.2.1. Tags
10.2.1.1. Null
10.2.1.2. Boolean
10.2.1.3. Integer
10.2.1.4. Floating Point

10.2.2. Tag Resolution

10.3. Core Schema
10.3.1. Tags
10.3.2. Tag Resolution

10.4. Other Schemas

Reference Links
[H1] Chapter 1. Introduction to YAML
YAML (a recursive acronym for “YAML Ain’t Markup Language”) is a data
serialization language designed to be human-friendly and work well with modern
programming languages for common everyday tasks.
This specification is both an introduction to the YAML language and the
concepts supporting it.
It is also a complete specification of the information needed to develop
applications for processing YAML.
Open, interoperable and readily understandable tools have advanced computing
immensely.
YAML was designed from the start to be useful and friendly to people working
with data.
It uses Unicode printable characters, some of which provide structural
information and the rest containing the data itself.
YAML achieves a unique cleanness by minimizing the amount of structural
characters and allowing the data to show itself in a natural and meaningful
way.
For example, indentation may be used for structure, colons separate
key/value pairs and dashes are used to create “bulleted” lists.
There are many kinds of data structures, but they can all be adequately
represented with three basic primitives: mappings (hashes/dictionaries),
sequences (arrays/lists) and scalars (strings/numbers).
YAML leverages these primitives and adds a simple typing system and aliasing
mechanism to form a complete language for serializing any native data
structure.
While most programming languages can use YAML for data serialization, YAML
excels in working with those languages that are fundamentally built around the
three basic primitives.
These include common dynamic languages such as JavaScript, Perl, PHP, Python
and Ruby.
There are hundreds of different languages for programming, but only a handful
of languages for storing and transferring data.
Even though its potential is virtually boundless, YAML was specifically created
to work well for common use cases such as: configuration files, log files,
interprocess messaging, cross-language data sharing, object persistence and
debugging of complex data structures.
When data is easy to view and understand, programming becomes a simpler task.
[H2] 1.1. Goals
The design goals for YAML are, in decreasing priority:
YAML should be easily readable by humans.
YAML data should be portable between programming languages.
YAML should match the native data structures of dynamic languages.
YAML should have a consistent model to support generic tools.
YAML should support one-pass processing.
YAML should be expressive and extensible.
YAML should be easy to implement and use.
[H2] 1.2. YAML History
The YAML 1.0 specification was published in early 2004 by by Clark Evans, Oren
Ben-Kiki, and Ingy döt Net after 3 years of collaborative design work through
the yaml-core mailing list5.
The project was initially rooted in Clark and Oren’s work on the
SML-DEV6 mailing list (for simplifying XML) and Ingy’s plain text
serialization module7 for Perl.
The language took a lot of inspiration from many other technologies and formats
that preceded it.
The first YAML framework was written in Perl in 2001 and Ruby was the first
language to ship a YAML framework as part of its core language distribution in
2003.
The YAML 1.18 specification was published in 2005.
Around this time, the developers became aware of JSON9.
By sheer coincidence, JSON was almost a complete subset of YAML (both
syntactically and semantically).
In 2006, Kyrylo Simonov produced PyYAML10 and LibYAML11.
A lot of the YAML frameworks in various programming languages are built over
LibYAML and many others have looked to PyYAML as a solid reference for their
implementations.
The YAML 1.23 specification was published in 2009.
Its primary focus was making YAML a strict superset of JSON.
It also removed many of the problematic implicit typing recommendations.
Since the release of the 1.2 specification, YAML adoption has continued to
grow, and many large-scale projects use it as their primary interface language.
In 2020, the new YAML language design team began meeting regularly
to discuss improvements to the YAML language and specification; to better meet
the needs and expectations of its users and use cases.
This YAML 1.2.2 specification, published in October 2021, is the first step in
YAML’s rejuvenated development journey.
YAML is now more popular than it has ever been, but there is a long list of
things that need to be addressed for it to reach its full potential.
The YAML design team is focused on making YAML as good as possible.
[H2] 1.3. Terminology
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”,
“SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be
interpreted as described in RFC 211912.
The rest of this document is arranged as follows.
Chapter 2 provides a short preview of the main YAML features.
Chapter 3 describes the YAML information model and the processes for
converting from and to this model and the YAML text format.
The bulk of the document, chapters 4, 5, 6, 7, 8 and 9, formally
define this text format.
Finally, chapter 10 recommends basic YAML schemas.
[H1] Chapter 2. Language Overview
This section provides a quick glimpse into the expressive power of YAML.
It is not expected that the first-time reader grok all of the examples.
Rather, these selections are used as motivation for the remainder of the
specification.
[H2] 2.1. Collections
YAML’s block collections use indentation for scope and begin each entry on
its own line.
Block sequences indicate each entry with a dash and space (“- ”).
Mappings use a colon and space (“: ”) to mark each key/value pair.
Comments begin with an octothorpe (also called a “hash”, “sharp”, “pound” or
“number sign” - “#”).
Example 2.1 Sequence of Scalars (ball players)

- Mark McGwire
- Sammy Sosa
- Ken Griffey
Example 2.2 Mapping Scalars to Scalars (player statistics)

hr: 65 # Home runs
avg: 0.278 # Batting average
rbi: 147 # Runs Batted In
Example 2.3 Mapping Scalars to Sequences (ball clubs in each league)

american:
- Boston Red Sox
- Detroit Tigers
- New York Yankees
national:
- New York Mets
- Chicago Cubs
- Atlanta Braves
Example 2.4 Sequence of Mappings (players’ statistics)

-
name: Mark McGwire
hr: 65
avg: 0.278
-
name: Sammy Sosa
hr: 63
avg: 0.288
YAML also has flow styles, using explicit indicators rather than
indentation to denote scope.
The flow sequence is written as a comma separated list within square
brackets.
In a similar manner, the flow mapping uses curly braces.
Example 2.5 Sequence of Sequences

- [name , hr, avg ]
- [Mark McGwire, 65, 0.278]
- [Sammy Sosa , 63, 0.288]
Example 2.6 Mapping of Mappings

Mark McGwire: {hr: 65, avg: 0.278}
Sammy Sosa: {
hr: 63,
avg: 0.288,
}
[H2] 2.2. Structures
YAML uses three dashes (“---”) to separate directives from document
content.
This also serves to signal the start of a document if no directives are
present.
Three dots ( “...”) indicate the end of a document without starting a new
one, for use in communication channels.
Example 2.7 Two Documents in a Stream (each with a leading comment)

# Ranking of 1998 home runs
---
- Mark McGwire
- Sammy Sosa
- Ken Griffey
# Team ranking
---
- Chicago Cubs
- St Louis Cardinals
Example 2.8 Play by Play Feed from a Game

---
time: 20:03:20
player: Sammy Sosa
action: strike (miss)
...
---
time: 20:03:47
player: Sammy Sosa
action: grand slam
...
Repeated nodes (objects) are first identified by an anchor (marked with
the ampersand - “&”) and are then aliased (referenced with an asterisk -
“*”) thereafter.
Example 2.9 Single Document with Two Comments

---
hr: # 1998 hr ranking
- Mark McGwire
- Sammy Sosa
# 1998 rbi ranking
rbi:
- Sammy Sosa
- Ken Griffey
Example 2.10 Node for “Sammy Sosa” appears twice in this document

---
hr:
- Mark McGwire
# Following node labeled SS
- &SS Sammy Sosa
rbi:
- *SS # Subsequent occurrence
- Ken Griffey
A question mark and space (“? ”) indicate a complex mapping key.
Within a block collection, key/value pairs can start immediately following
the dash, colon or question mark.
Example 2.11 Mapping between Sequences

? - Detroit Tigers
- Chicago cubs
: - 2001-07-23
? [ New York Yankees,
Atlanta Braves ]
: [ 2001-07-02, 2001-08-12,
2001-08-14 ]
Example 2.12 Compact Nested Mapping

---
# Products purchased
- item : Super Hoop
quantity: 1
- item : Basketball
quantity: 4
- item : Big Shoes
quantity: 1
[H2] 2.3. Scalars
Scalar content can be written in block notation, using a literal style
(indicated by “|”) where all line breaks are significant.
Alternatively, they can be written with the folded style (denoted by “>”)
where each line break is folded to a space unless it ends an empty or a
more-indented line.
Example 2.13 In literals, newlines are preserved

# ASCII Art
--- |
\//||\/||
// || ||__
Example 2.14 In the folded scalars, newlines become spaces

--- >
Mark McGwire's
year was crippled
by a knee injury.
Example 2.15 Folded newlines are preserved for “more indented” and blank
lines

--- >
Sammy Sosa completed another
fine season with great stats.
63 Home Runs
0.288 Batting Average
What a year!
Example 2.16 Indentation determines scope

name: Mark McGwire
accomplishment: >
Mark set a major league
home run record in 1998.
stats: |
65 Home Runs
0.278 Batting Average
YAML’s flow scalars include the plain style (most examples thus far) and
two quoted styles.
The double-quoted style provides escape sequences.
The single-quoted style is useful when escaping is not needed.
All flow scalars can span multiple lines; line breaks are al

[H1]
YAML Ain’t Markup Language (YAML™) Version 1.2

[H2] Revision 1.2.1 (2009-10-01)

[H3] Oren Ben-Kiki
<oren@ben-kiki.org>

[H3] Clark Evans
<cce@clarkevans.com>

[H3] Ingy döt Net
<ingy@ingy.net>

Latest (patched) version:
HTML:
spec.html
PDF:
spec.pdf
PS:
spec.ps
Errata:
errata.html
Previous (original) version:
/spec/1.2/2009-07-21/spec.html

Copyright © 2001-2009 Oren Ben-Kiki, Clark Evans, Ingy döt Net

This document may be freely copied, provided it is not modified.

Status of this Document

This document reflects the third version of YAML data serialization
language. The content of the specification was arrived at by consensus
of its authors and through user feedback on the yaml-core
mailing list. We encourage implementers to please update their software
with support for this version.

The primary objective of this revision is to bring YAML into compliance
with JSON as an official subset. YAML 1.2 is compatible with 1.1 for
most practical applications - this is a minor revision. An expected
source of incompatibility with prior versions of YAML, especially the
syck implementation, is the change in implicit typing rules. We have
removed unique implicit typing rules and have updated these rules to
align them with JSON's productions. In this version of YAML, boolean
values may be serialized as “true” or
“false”; the empty scalar as “null”.
Unquoted numeric values are a superset of JSON's numeric production.
Other changes in the specification were the removal of the Unicode line
breaks and production bug fixes. We also define 3 built-in implicit
typing rule sets: untyped, strict JSON, and a more flexible YAML rule
set that extends JSON typing.

The difference between late 1.0 drafts which syck 0.55 implements and
the 1.1 revision of this specification is much more extensive. We fixed
usability issues with the tagging syntax. In particular, the single
exclamation was re-defined for private types and a simple prefixing
mechanism was introduced. This revision also fixed many production edge
cases and introduced a type repository. Therefore, there are several
incompatibilities between syck and this revision as well.

The list of known errors in this specification is available at errata.html.
Please report errors in this document to the
yaml-core mailing list. This revision contains fixes for all
errors known as of 2009-10-01.

We wish to thank implementers who have tirelessly tracked earlier
versions of this specification, and our fabulous user community whose
feedback has both validated and clarified our direction.

Abstract

YAML™ (rhymes with “camel”) is a
human-friendly, cross language, Unicode based data serialization
language designed around the common native data types of agile
programming languages. It is broadly useful for programming needs
ranging from configuration files to Internet messaging to object
persistence to data auditing. Together with the Unicode standard for characters,
this specification provides all the information necessary to understand
YAML Version 1.2 and to create programs that process YAML information.

Table of Contents

1. Introduction

1.1. Goals

1.2. Prior Art

1.3. Relation to JSON

1.4. Relation to XML

1.5. Terminology

2. Preview

2.1. Collections

2.2. Structures

2.3. Scalars

2.4. Tags

2.5. Full Length Example

3. Processing YAML Information

3.1. Processes

3.1.1. Dump

3.1.2. Load

3.2. Information Models

3.2.1. Representation Graph

3.2.1.1. Nodes

3.2.1.2. Tags

3.2.1.3. Node Comparison

3.2.2. Serialization Tree

3.2.2.1. Keys Order

3.2.2.2. Anchors and Aliases

3.2.3. Presentation Stream

3.2.3.1. Node Styles

3.2.3.2. Scalar Formats

3.2.3.3. Comments

3.2.3.4. Directives

3.3. Loading Failure Points

3.3.1. Well-Formed Streams and Identified Aliases

3.3.2. Resolved Tags

3.3.3. Recognized and Valid Tags

3.3.4. Available Tags

4. Syntax Conventions

4.1. Production Parameters

4.2. Production Naming Conventions

5. Characters

5.1. Character Set

5.2. Character Encodings

5.3. Indicator Characters

5.4. Line Break Characters

5.5. White Space Characters

5.6. Miscellaneous Characters

5.7. Escaped Characters

6. Basic Structures

6.1. Indentation Spaces

6.2. Separation Spaces

6.3. Line Prefixes

6.4. Empty Lines

6.5. Line Folding

6.6. Comments

6.7. Separation Lines

6.8. Directives

6.8.1. “YAML” Directives

6.8.2. “TAG” Directives

6.8.2.1. Tag Handles

6.8.2.2. Tag Prefixes

6.9. Node Properties

6.9.1. Node Tags

6.9.2. Node Anchors

7. Flow Styles

7.1. Alias Nodes

7.2. Empty Nodes

7.3. Flow Scalar Styles

7.3.1. Double-Quoted Style

7.3.2. Single-Quoted Style

7.3.3. Plain Style

7.4. Flow Collection Styles

7.4.1. Flow Sequences

7.4.2. Flow Mappings

7.5. Flow Nodes

8. Block Styles

8.1. Block Scalar Styles

8.1.1. Block Scalar Headers

8.1.1.1. Block Indentation Indicator

8.1.1.2. Block Chomping Indicator

8.1.2. Literal Style

8.1.3. Folded Style

8.2. Block Collection Styles

8.2.1. Block Sequences

8.2.2. Block Mappings

8.2.3. Block Nodes

9. YAML Character Stream

9.1. Documents

9.1.1. Document Prefix

9.1.2. Document Markers

9.1.3. Bare Documents

9.1.4. Explicit Documents

9.1.5. Directives Documents

9.2. Streams

10. Recommended Schemas

10.1. Failsafe Schema

10.1.1. Tags

10.1.1.1. Generic Mapping

10.1.1.2. Generic Sequence

10.1.1.3. Generic String

10.1.2. Tag Resolution

10.2. JSON Schema

10.2.1. Tags

10.2.1.1. Null

10.2.1.2. Boolean

10.2.1.3. Integer

10.2.1.4. Floating Point

10.2.2. Tag Resolution

10.3. Core Schema

10.3.1. Tags

10.3.2. Tag Resolution

10.4. Other Schemas

Index

[H2] Chapter 1. Introduction

“YAML Ain’t Markup Language” (abbreviated YAML) is a data
serialization language designed to be human-friendly and work well with
modern programming languages for common everyday tasks. This
specification is both an introduction to the YAML language and the
concepts supporting it, and also a complete specification of the
information needed to develop applications for processing YAML.

Open, interoperable and readily understandable tools have advanced
computing immensely. YAML was designed from the start to be useful and
friendly to people working with data. It uses Unicode printable characters, some of which provide structural
information and the rest containing the data itself. YAML achieves a
unique cleanness by minimizing the amount of structural characters and
allowing the data to show itself in a natural and meaningful way. For
example, indentation may be used for structure,
colons separate key: value pairs, and dashes are used to create
“bullet” lists.

There are myriad flavors of data
structures, but they can all be adequately represented with three basic primitives:
mappings (hashes/dictionaries),
sequences (arrays/lists) and
scalars (strings/numbers). YAML
leverages these primitives, and adds a simple typing system and aliasing mechanism to form a complete language
for serializing any native data structure. While
most programming languages can use YAML for data serialization, YAML
excels in working with those languages that are fundamentally built
around the three basic primitives. These include the new wave of agile
languages such as Perl, Python, PHP, Ruby, and Javascript.

There are hundreds of different languages for programming, but only a
handful of languages for storing and transferring data. Even though its
potential is virtually boundless, YAML was specifically created to work
well for common use cases such as: configuration files, log files,
interprocess messaging, cross-language data sharing, object persistence,
and debugging of complex data structures. When data is easy to view and
understand, programming becomes a simpler task.

[H2] 1.1. Goals

The design goals for YAML are, in decreasing priority:

YAML is easily readable by humans.

YAML data is portable between programming languages.

YAML matches the native data
structures of agile languages.

YAML has a consistent model to support generic tools.

YAML supports one-pass processing.

YAML is expressive and extensible.

YAML is easy to implement and use.

[H2] 1.2. Prior Art

YAML’s initial direction was set by the data serialization and
markup language discussions among SML-DEV members. Later
on, it directly incorporated experience from Ingy döt Net’s
Perl module Data::Denter. Since then, YAML has matured through ideas and
support from its user community.

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

The syntax of YAML was motivated by Internet Mail (RFC0822) and remains
partially compatible with that standard. Further, borrowing from MIME
(RFC2045), YAML’s top-level production is a stream of independent documents, ideal for message-based
distributed processing systems.

YAML’s indentation-based scoping is similar
to Python’s (without the ambiguities caused by tabs). Indented blocks facilitate easy inspection
of the data’s structure. YAML’s literal style leverages
this by enabling formatted text to be cleanly mixed within an indented structure
without troublesome escaping. YAML also allows the use of
traditional indicator-based
scoping similar to JSON’s and Perl’s. Such flow content can be freely
nested inside indented
blocks.

YAML’s double-quoted style uses familiar
C-style escape sequences. This enables ASCII encoding of
non-printable or 8-bit
(ISO 8859-1) characters such as “\x3B”. Non-printable 16-bit Unicode and
32-bit (ISO/IEC 10646) characters are supported with escape
sequences such as “\u003B” and “\U0000003B”.

Motivated by HTML’s end-of-line normalization, YAML’s line folding employs an intuitive
method of handling line breaks.
A single line break is folded into a single space, while empty lines are interpreted as line break characters. This technique allows for
paragraphs to be word-wrapped without affecting the canonical form of
the scalar content.

YAML’s core type system is based on the requirements of agile
languages such as Perl, Python, and Ruby. YAML directly supports both
collections (mappings, sequences) and scalars. Support for these common types
enables programmers to use their language’s native data structures for YAML manipulation,
instead of requiring a special document object model (DOM).

Like XML’s SOAP, YAML supports serializing a graph of native data structures
through an aliasing mechanism. Also
like SOAP, YAML provides for application-defined types. This allows YAML to represent rich data structures required
for modern distributed computing. YAML provides globally unique
type names using a
namespace mechanism inspired by Java’s DNS-based package naming
convention and XML’s URI-based namespaces. In addition, YAML allows
for private types
specific to a single application.

YAML was designed to support incremental interfaces that include both
input (“getNextEvent()”) and output
(“sendNextEvent()”) one-pass interfaces. Together, these
enable YAML to support the processing of large documents (e.g. transaction logs) or
continuous streams (e.g. feeds from
a production machine).

[H2] 1.3. Relation to JSON

Both JSON and YAML aim to be human readable data interchange formats.
However, JSON and YAML have different priorities. JSON’s foremost
design goal is simplicity and universality. Thus, JSON is trivial to
generate and parse, at the cost of reduced human readability. It also
uses a lowest common denominator information model, ensuring any JSON
data can be easily processed by every modern programming environment.

In contrast, YAML’s foremost design goals are human readability and
support for serializing
arbitrary native data
structures. Thus, YAML allows for extremely readable files,
but is more complex to generate and parse. In addition, YAML ventures
beyond the lowest common denominator data types, requiring more complex
processing when crossing between different programming environments.

YAML can therefore be viewed as a natural superset of JSON, offering
improved human readability and a more complete information model. This
is also the case in practice; every JSON file is also a valid YAML
file. This makes it easy to migrate from JSON to YAML if/when the
additional features are required.

JSON's RFC4627
requires that mappings keys merely “SHOULD” be unique, while YAML insists they
“MUST” be. Technically, YAML therefore complies with the
JSON spec, choosing to treat duplicates as an error. In practice, since
JSON is silent on the semantics of such duplicates, the only portable
JSON files are those with unique keys, which are therefore valid YAML
files.

It may be useful to define a intermediate format between YAML and JSON.
Such a format would be trivial to parse (but not very human readable),
like JSON. At the same time, it would allow for serializing arbitrary native data structures, like
YAML. Such a format might also serve as YAML’s "canonical format".
Defining such a “YSON” format (YSON is a Serialized Object
Notation) can be done either by enhancing the JSON specification or by
restricting the YAML specification. Such a definition is beyond the
scope of this specification.

[H2] 1.4. Relation to XML

Newcomers to YAML often search for its correlation to the eXtensible
Markup Language (XML). Although the two languages may actually compete
in several application domains, there is no direct correlation between
them.

YAML is primarily a data serialization language. XML was designed to be
backwards compatible with the Standard Generalized Markup Language
(SGML), which was designed to support structured documentation. XML
therefore had many design constraints placed on it that YAML does not
share. XML is a pioneer in many domains, YAML is the result of lessons
learned from XML and other technologies.

It should be mentioned that there are ongoing efforts to define
standard XML/YAML mappings. This generally requires that a subset of
each language be used. For more information on using both XML and YAML,
please visit https://yaml.org/xml.

[H2] 1.5. Terminology

This specification uses key

[H1]
YAML Ain’t Markup Language (YAML™) Version 1.2

[H2] Revision 1.2.0 (2009-07-21)

[H3] Oren Ben-Kiki
<oren@ben-kiki.org>

[H3] Clark Evans
<cce@clarkevans.com>

[H3] Ingy döt Net
<ingy@ingy.net>

This version:
HTML:
spec.html
PDF:
spec.pdf
PS:
spec.ps
Errata:
errata.html

Copyright © 2001-2009 Oren Ben-Kiki, Clark Evans, Ingy döt Net

This document may be freely copied, provided it is not modified.

Status of this Document

This document reflects the third version of YAML data serialization
language. The content of the specification was arrived at by consensus
of its authors and through user feedback on the yaml-core
mailing list. We encourage implementers to please update their software
with support for this version.

The primary objective of this revision is to bring YAML into compliance
with JSON as an official subset. YAML 1.2 is compatible with 1.1 for
most practical applications - this is a minor revision. An expected
source of incompatibility with prior versions of YAML, especially the
syck implementation, is the change in implicit typing rules. We have
removed unique implicit typing rules and have updated these rules to
align them with JSON's productions. In this version of YAML, boolean
values may be serialized as “true” or
“false”; the empty scalar as “null”.
Unquoted numeric values are a superset of JSON's numeric production.
Other changes in the specification were the removal of the Unicode line
breaks and production bug fixes. We also define 3 built-in implicit
typing rule sets: untyped, strict JSON, and a more flexible YAML rule
set that extends JSON typing.

The difference between late 1.0 drafts which syck 0.55 implements and
the 1.1 revision of this specification is much more extensive. We fixed
usability issues with the tagging syntax. In particular, the single
exclamation was re-defined for private types and a simple prefixing
mechanism was introduced. This revision also fixed many production edge
cases and introduced a type repository. Therefore, there are several
incompatibilities between syck and this revision as well.

The list of known errors in this specification is available at errata.html.
Please report errors in this document to the
yaml-core mailing list.

We wish to thank implementers who have tirelessly tracked earlier
versions of this specification, and our fabulous user community whose
feedback has both validated and clarified our direction.

Abstract

YAML™ (rhymes with “camel”) is a
human-friendly, cross language, Unicode based data serialization
language designed around the common native data types of agile
programming languages. It is broadly useful for programming needs
ranging from configuration files to Internet messaging to object
persistence to data auditing. Together with the Unicode standard for characters,
this specification provides all the information necessary to understand
YAML Version 1.2 and to create programs that process YAML information.

Table of Contents

1. Introduction

1.1. Goals

1.2. Prior Art

1.3. Relation to JSON

1.4. Relation to XML

1.5. Terminology

2. Preview

2.1. Collections

2.2. Structures

2.3. Scalars

2.4. Tags

2.5. Full Length Example

3. Processing YAML Information

3.1. Processes

3.1.1. Dump

3.1.2. Load

3.2. Information Models

3.2.1. Representation Graph

3.2.1.1. Nodes

3.2.1.2. Tags

3.2.1.3. Node Comparison

3.2.2. Serialization Tree

3.2.2.1. Keys Order

3.2.2.2. Anchors and Aliases

3.2.3. Presentation Stream

3.2.3.1. Node Styles

3.2.3.2. Scalar Formats

3.2.3.3. Comments

3.2.3.4. Directives

3.3. Loading Failure Points

3.3.1. Well-Formed Streams and Identified Aliases

3.3.2. Resolved Tags

3.3.3. Recognized and Valid Tags

3.3.4. Available Tags

4. Syntax Conventions

4.1. Production Parameters

4.2. Production Naming Conventions

5. Characters

5.1. Character Set

5.2. Character Encodings

5.3. Indicator Characters

5.4. Line Break Characters

5.5. White Space Characters

5.6. Miscellaneous Characters

5.7. Escaped Characters

6. Basic Structures

6.1. Indentation Spaces

6.2. Separation Spaces

6.3. Line Prefixes

6.4. Empty Lines

6.5. Line Folding

6.6. Comments

6.7. Separation Lines

6.8. Directives

6.8.1. “YAML” Directives

6.8.2. “TAG” Directives

6.8.2.1. Tag Handles

6.8.2.2. Tag Prefixes

6.9. Node Properties

6.9.1. Node Tags

6.9.2. Node Anchors

7. Flow Styles

7.1. Alias Nodes

7.2. Empty Nodes

7.3. Flow Scalar Styles

7.3.1. Double-Quoted Style

7.3.2. Single-Quoted Style

7.3.3. Plain Style

7.4. Flow Collection Styles

7.4.1. Flow Sequences

7.4.2. Flow Mappings

7.5. Flow Nodes

8. Block Styles

8.1. Block Scalar Styles

8.1.1. Block Scalar Headers

8.1.1.1. Block Indentation Indicator

8.1.1.2. Block Chomping Indicator

8.1.2. Literal Style

8.1.3. Folded Style

8.2. Block Collection Styles

8.2.1. Block Sequences

8.2.2. Block Mappings

8.2.3. Block Nodes

9. YAML Character Stream

9.1. Documents

9.1.1. Document Prefix

9.1.2. Document Markers

9.1.3. Bare Documents

9.1.4. Explicit Documents

9.1.5. Directives Documents

9.2. Streams

10. Recommended Schemas

10.1. Failsafe Schema

10.1.1. Tags

10.1.1.1. Generic Mapping

10.1.1.2. Generic Sequence

10.1.1.3. Generic String

10.1.2. Tag Resolution

10.2. JSON Schema

10.2.1. Tags

10.2.1.1. Null

10.2.1.2. Boolean

10.2.1.3. Integer

10.2.1.4. Floating Point

10.2.2. Tag Resolution

10.3. Core Schema

10.3.1. Tags

10.3.2. Tag Resolution

10.4. Other Schemas

Index

[H2] Chapter 1. Introduction

“YAML Ain’t Markup Language” (abbreviated YAML) is a data
serialization language designed to be human-friendly and work well with
modern programming languages for common everyday tasks. This
specification is both an introduction to the YAML language and the
concepts supporting it, and also a complete specification of the
information needed to develop applications for processing YAML.

Open, interoperable and readily understandable tools have advanced
computing immensely. YAML was designed from the start to be useful and
friendly to people working with data. It uses Unicode printable characters, some of which provide structural
information and the rest containing the data itself. YAML achieves a
unique cleanness by minimizing the amount of structural characters and
allowing the data to show itself in a natural and meaningful way. For
example, indentation may be used for structure,
colons separate key: value pairs, and dashes are used to create
“bullet” lists.

There are myriad flavors of data
structures, but they can all be adequately represented with three basic primitives:
mappings (hashes/dictionaries),
sequences (arrays/lists) and
scalars (strings/numbers). YAML
leverages these primitives, and adds a simple typing system and aliasing mechanism to form a complete language
for serializing any native data structure. While
most programming languages can use YAML for data serialization, YAML
excels in working with those languages that are fundamentally built
around the three basic primitives. These include the new wave of agile
languages such as Perl, Python, PHP, Ruby, and Javascript.

There are hundreds of different languages for programming, but only a
handful of languages for storing and transferring data. Even though its
potential is virtually boundless, YAML was specifically created to work
well for common use cases such as: configuration files, log files,
interprocess messaging, cross-language data sharing, object persistence,
and debugging of complex data structures. When data is easy to view and
understand, programming becomes a simpler task.

[H2] 1.1. Goals

The design goals for YAML are, in decreasing priority:

YAML is easily readable by humans.

YAML matches the native data
structures of agile languages.

YAML data is portable between programming languages.

YAML has a consistent model to support generic tools.

YAML supports one-pass processing.

YAML is expressive and extensible.

YAML is easy to implement and use.

[H2] 1.2. Prior Art

YAML’s initial direction was set by the data serialization and
markup language discussions among SML-DEV members. Later
on, it directly incorporated experience from Ingy döt Net’s
Perl module Data::Denter. Since then, YAML has matured through ideas and
support from its user community.

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

The syntax of YAML was motivated by Internet Mail (RFC0822) and remains
partially compatible with that standard. Further, borrowing from MIME
(RFC2045), YAML’s top-level production is a stream of independent documents, ideal for message-based
distributed processing systems.

YAML’s indentation-based scoping is similar
to Python’s (without the ambiguities caused by tabs). Indented blocks facilitate easy inspection
of the data’s structure. YAML’s literal style leverages
this by enabling formatted text to be cleanly mixed within an indented structure
without troublesome escaping. YAML also allows the use of
traditional indicator-based
scoping similar to JSON’s and Perl’s. Such flow content can be freely
nested inside indented
blocks.

YAML’s double-quoted style uses familiar
C-style escape sequences. This enables ASCII encoding of
non-printable or 8-bit
(ISO 8859-1) characters such as “\x3B”. Non-printable 16-bit Unicode and
32-bit (ISO/IEC 10646) characters are supported with escape
sequences such as “\u003B” and “\U0000003B”.

Motivated by HTML’s end-of-line normalization, YAML’s line folding employs an intuitive
method of handling line breaks.
A single line break is folded into a single space, while empty lines are interpreted as line break characters. This technique allows for
paragraphs to be word-wrapped without affecting the canonical form of
the scalar content.

YAML’s core type system is based on the requirements of agile
languages such as Perl, Python, and Ruby. YAML directly supports both
collections (mappings, sequences) and scalars. Support for these common types
enables programmers to use their language’s native data structures for YAML manipulation,
instead of requiring a special document object model (DOM).

Like XML’s SOAP, YAML supports serializing a graph of native data structures
through an aliasing mechanism. Also
like SOAP, YAML provides for application-defined types. This allows YAML to represent rich data structures required
for modern distributed computing. YAML provides globally unique
type names using a
namespace mechanism inspired by Java’s DNS-based package naming
convention and XML’s URI-based namespaces. In addition, YAML allows
for private types
specific to a single application.

YAML was designed to support incremental interfaces that include both
input (“getNextEvent()”) and output
(“sendNextEvent()”) one-pass interfaces. Together, these
enable YAML to support the processing of large documents (e.g. transaction logs) or
continuous streams (e.g. feeds from
a production machine).

[H2] 1.3. Relation to JSON

Both JSON and YAML aim to be human readable data interchange formats.
However, JSON and YAML have different priorities. JSON’s foremost
design goal is simplicity and universality. Thus, JSON is trivial to
generate and parse, at the cost of reduced human readability. It also
uses a lowest common denominator information model, ensuring any JSON
data can be easily processed by every modern programming environment.

In contrast, YAML’s foremost design goals are human readability and
support for serializing
arbitrary native data
structures. Thus, YAML allows for extremely readable files,
but is more complex to generate and parse. In addition, YAML ventures
beyond the lowest common denominator data types, requiring more complex
processing when crossing between different programming environments.

YAML can therefore be viewed as a natural superset of JSON, offering
improved human readability and a more complete information model. This
is also the case in practice; every JSON file is also a valid YAML
file. This makes it easy to migrate from JSON to YAML if/when the
additional features are required.

It may be useful to define a intermediate format between YAML and JSON.
Such a format would be trivial to parse (but not very human readable),
like JSON. At the same time, it would allow for serializing arbitrary native data structures, like
YAML. Such a format might also serve as YAML’s "canonical format".
Defining such a “YSON” format (YSON is a Serialized Object
Notation) can be done either by enhancing the JSON specification or by
restricting the YAML specification. Such a definition is beyond the
scope of this specification.

[H2] 1.4. Relation to XML

Newcomers to YAML often search for its correlation to the eXtensible
Markup Language (XML). Although the two languages may actually compete
in several application domains, there is no direct correlation between
them.

YAML is primarily a data serialization language. XML was designed to be
backwards compatible with the Standard Generalized Markup Language
(SGML), which was designed to support structured documentation. XML
therefore had many design constraints placed on it that YAML does not
share. XML is a pioneer in many domains, YAML is the result of lessons
learned from XML and other technologies.

It should be mentioned that there are ongoing efforts to define
standard XML/YAML mappings. This generally requires that a subset of
each language be used. For more information on using both XML and YAML,
please visit http://yaml.org/xml.

[H2] 1.5. Terminology

This specification uses key words based on RFC2119 to indicate
requirement level. In particular, the following words are used to
describe the actions of a YAML processor:

May

The word may, or the adjective
optional, mean that conforming YAML processors are permitted to, but
need not behave as described.

Should

The word should, or the adjective
recommended, mean that there could be reasons
for a YAML processor to
deviate from the behavior described, but that such deviation could
hurt interoperability and should therefore be