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’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).

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.

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.

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.

A YAML node is the representation of a particular data stucture. Nodes may contain other nodes. A YAML node represents a single native data structure. Such nodes have content of one of three kinds:

In addition, each node has a tag which serves to restrict the set of possible values the content can have.

The content of a scalar node is an opaque datum that can be presented as a series of zero or more Unicode characters.

The content of a sequence node is an ordered series of zero or more nodes. In particular, a sequence may contain the same node more than once. It could even contain itself (directly or indirectly).

The content of a mapping node is an unordered set of key:value pairs, with the restriction that each of the keys is unique. YAML places no further restrictions on the nodes. In particular, keys may be arbitrary nodes, the same node may be used as the value of several key:value pairs, and a mapping could even contain itself as a key or a value (directly or indirectly).

YAML represents type information of native data structures with a simple identifier, called a tag. Global tags are URIs and hence globally unique across all applications. The tag: URI scheme is recommended for all global YAML tags. In contrast, local tags are specific to a single application. Local tags start with an exclamation mark !, are not URIs and are not expected to be globally unique. YAML provides a TAG directive to make tag notation less verbose; it also offers easy migration from local to global tags. To ensure this, local tags are restricted to the URI character set and use URI character escaping.

YAML does not mandate any special relationship between different tags that begin with the same substring. Tags ending with URI fragments (containing a hash mark #) are no exception; tags that share the same base URI but differ in their fragment part are considered to be different, independent tags. By convention, fragments are used to identify different variants of a tag, while / is used to define nested tag namespace hierarchies.

However, this is merely a convention, and each tag may employ its own rules. For example, Perl tags may use a double colon :: to express namespace hierarchies, Java tags may use dots . etc.

Tags are prefixed with exclamation mark ! and describe the type of a node. This allows for adding new types without having to extend the syntax or mingle type information with data. Omitting the tag leaves the type to the parser’s discretion; usually that means you’ll get arrays|lists, hashes|dictionaries, strings, numbers, and other simple data types.

You’ll probably only see tags in two forms:

Most of these are inferred from plain data !!seq for sequences, !!int for numbers, and so on but a few don’t have dedicated syntax and have to be given explicitly. For example, !!binary is used for representing arbitrary binary data encoded as base64. So !!binary aGVsbG8= would be parsed as the bytestring hello.

There’s much more to tags, most of which is rarely used in practice. Read more on the {yaml-tag-repository}[Language-independent YAML tags, window="blank"].

The other node property is the anchor, which is how YAML can store recursive data structures. Anchor names are prefixed with & and can’t contain whitespace, brackets, braces, or commas.

An alias node is an anchor name prefixed with a star mark * and indicates that the node with that anchor name should occur in both places. (Alias nodes can’t have properties themselves; the properties of the anchored node are used.) For example, you might share configuration:

Or serialize a list that contains itself:

Anchor names act somewhat like variable assignments: at any point in the document, the parser only knows about the anchors it’s seen so far, and a second anchor with the same name takes precedence. This means that aliases cannot refer to anchors that appear later in the document.

Anchor names aren’t intended to carry information, which unfortunately means that most YAML parsers throw them away, and re-serializing a document will get you anchor names like ANCHOR1.

YAML’s block styles employ indentation rather than indicators to denote structure. This results in a more human readable (though less compact) notation. Block scalar styles using the greater mark > or pipe | allow escaping and add a new line (\n) to the end of your string.

results in:

YAML’s flow styles can be thought of as the natural extension of JSON to cover folding long content lines for readability, tagging nodes to control construction of native data structures, and using anchors and aliases to reuse constructed object instances.

Most values in a YAML document will be plain scalars. They’re defined by exclusion: if it’s not anything else, it’s a plain scalar. Technically, they can only be flow style, so they’re really "plain flow scalar style" scalars.

Plain scalars are the most flexible kind of value, and may resolve to a variety of types from the YAML tag repository:

Otherwise, it’s a string. Well. Probably. As part of tag resolution (see yamlref-more-tags), an application is allowed to parse plain scalars however it wants; you might add logic that parses 1..5 as a range type, or you might recognize keywords and replace them with special objects. But if you’re doing any of that, you’re hopefully aware of it.

Between the above parsing and conflicts with the rest of YAML’s syntax, for a plain scalar to be a string, it must meet these restrictions:

That actually leaves you fairly wide open; the biggest restriction is on the first character. You can have spaces, you can wrap across lines, you can include whatever (non-control) Unicode you want.

If you need explicit strings, you have some other options.

A collection is the generic term for a YAML data grouping. YAML has two types of collections:

Sequences are ordered collections, with type !!seq. They’re pretty simple.

Flow style is a comma-delimited list in square brackets, just like JSON: [one, two, 3]. A trailing comma is allowed, and whitespace is generally ignored. The contents must also be written in flow style.

Block style is written like a bulleted list:

Indentation determines where each element ends, and where the entire sequence ends.

Other blocks may be nested without intervening newlines:

A mapping is a YAML collection defined by key:value pairs. Mappings are unordered, er, mappings, with type !!map. The keys must be unique, but may be of any type. Also, they’re unordered.

Did I mention that mappings are unordered? The order of the keys in the document is irrelevant and arbitrary. If you need order, you need a sequence.

Flow style looks unsurprisingly like JSON: {x: 1, y: 2}. Again, a trailing comma is allowed, and whitespace doesn’t matter.

As a special case, inside a sequence, you can write a single-pair mapping without the braces. So [a: b, c: d, e: f] is a sequence containing three mappings. This is allowed in block sequences too, and is used for the ordered mapping type !!omap.

Block style is actually a little funny. The canonical form is a little surprising:

? introduces a key, and : introduces a value. You very rarely see this form, because the ? is optional as long as the key and colon are all on one line (to avoid ambiguity) and the key is no more than 1024 characters long (to avoid needing infinite lookahead).

So that’s more commonly written like this:

The explicit ? syntax is more useful for complex keys. For example, it’s the only way to use block styles in the key:

Other than the syntactic restrictions, an implicit key isn’t special in any way and can also be of any type:

It’s fairly uncommon to see anything but strings as keys, though, since languages often don’t support it. Python can’t have lists and dicts as dict keys; Perl 5 and JavaScript only support string keys; and so on.

Unlike sequences, you may not nest another block inside a block mapping on the same line.

This is invalid:

But this is fine:

You can also nest a block sequence without indenting like:

One slight syntactic wrinkle: in either style, the colon must be followed by whitespace. foo:bar is a single string, remember. (For JSON’s sake, the whitespace can be omitted, if the colon immediately follows a flow sequence, a flow mapping, or a quoted string.)

YAML has lots of ways to write explicit strings. Aside from plain scalars, there are two other flow scalar styles.

Single-quoted strings are surrounded by single-quotes '. Single-quotes may be escaped by double-quotes '', but otherwise no escaping is done at all. You may wrapover multiple lines, but the newline and any surrounding whitespace becomes a single space. A line containing only whitespace becomes a newline.

Double-quoted strings are surrounded by ". Backslash escapes are recognized:

As usual, you may wrap a double-quoted string across multiple lines, but the newline and any surrounding whitespace becomes a single space. As with single-quoted strings, a line containing only whitespace becomes a newline. You can escape spaces and tabs to protect them from being thrown away. You can also escape a newline to preserve any trailing whitespace on that line, but throw away the newline and any leading whitespace on the next line.

These rules are weird, so here’s a contrived example:

Which becomes:

Right, well. Hopefully that clears that up.

!!str is actually an illusion.

Tag names are actually URIs, using UTF-8 percent-encoding. YAML suggests using the tag: scheme and your domain name to help keep tags globally unique; for example, the string tag is really tag:yaml.org,2002:str. (Domain names can change hands over time, hence the inclusion of a year.)

That’s quite a mouthful, and wouldn’t be recognized as a tag anyway, because tags have to start with !. So tags are written in shorthand with a prefix, like !foo!bar. The !foo! is a named tag handle that expands to a given prefix, kind of like XML namespacing. Named tag handles must be defined by a %TAG directive before the document:

A tag of !foo!bar would then resolve to tag:example.com,2015:app/bar.

I’ve never seen %TAG used in practice. Instead, everyone uses the two special tag handles.

Both special handles can be reassigned with %TAG, just like any other handle. An important (and confusing) point here is that the resolved name determines whether or not a tag is local; how it’s written is irrelevant. You’re free to do this:

Now !foo!bar is shorthand for !foo-types/bar, which is a local tag. You can also do the reverse:

Which would make !bar a global tag! This is deliberate, as a quick way to convert an entire document from local tags to global tags.

You can reassign !!, too. But let’s not.

Tags can also be written verbatim as !<foo>, in which case foo is taken to be the resolved final name of the tag, ignoring %TAG and any other resolution mechanism. This is the only way to write a global tag without using %TAG, since tags must start with a !.

Every node has a tag, whether it’s given one explicitly or not. Nodes without explicit tags are given one of two special non-specific tags: ! for quoted and folded scalars; or ? for sequences, mappings, and plain scalars.

The ? tag tells the application to do tag resolution. Technically, this means the application can do any kind of arbitrary inspection to figure out the type of the node. In practice, it just means that scalars are inspected to see whether they’re booleans, integers, floats, whatever else, or just strings.

The ! tag forces a node to be interpreted as a basic built-in type, based on its kind: !!str, !!seq, or !!map. You can explicitly give the ! tag to a node if you want, for example writing ! true or ! 133 to force parsing as strings. Or you could use quotes. Just saying.