YAML (YAML Ain't Markup Language) is a human-readable data serialization language. It is commonly used for configuration files, but could be used in many applications where data is being stored (e.g. debugging output) or transmitted (e.g. document headers). YAML targets many of the same communications applications as XML but has a minimal syntax which intentionally breaks compatibility with SGML .^[1] It uses both Python-style indentation to indicate nesting, and a more compact format that uses for lists and for maps^[1] making YAML 1.2 a superset of JSON.^[2]

Custom data types are allowed, but YAML natively encodes scalars (such as strings, integers, and floats), lists, and associative arrays (also known as hashes, maps, or dictionaries). These data types are based on the Perl programming language, though all commonly used high-level programming languages share very similar concepts. The colon-centered syntax, used to express key-value pairs, is inspired by electronic mail headers as defined in RFC 0822, and the document separator "---" is borrowed from MIME (RFC 2046). Escape sequences are reused from C, and whitespace wrapping for multi-line strings is inspired from HTML. Lists and hashes can contain nested lists and hashes, forming a tree structure; arbitrary graphs can be represented using YAML aliases (similar to XML in SOAP).^[1] YAML is intended to be read and written in streams, a feature inspired by SAX.^[1]

Support for reading and writing YAML is available for many programming languages.^[3] Some source code editors such as Emacs^[4] and various integrated development environments^[5][6][7] have features that make editing YAML easier, such as folding up nested structures or automatically highlighting syntax errors.

The official recommended filename extension for YAML files has been .yaml^[8] since 2006.^[9]

History and name[edit]

YAML (/ˈjæməl/, rhymes with camel^[2]) was first proposed by Clark Evans in 2001,^[10] who designed it together with Brian "Ingy" Ingerson^[11] and Oren Ben-Kiki.^[11] Originally YAML was said to mean Yet Another Markup Language,^[12] referencing its purpose as a markup language with the yet another construct, but it was then repurposed as YAML Ain't Markup Language, a recursive acronym, to distinguish its purpose as data-oriented, rather than document markup.

Design[edit]

This section is written like a manual or guidebook. Please help rewrite this section from a descriptive, neutral point of view, and remove advice or instruction. (August 2016) (Learn how and when to remove this template message)

Syntax[edit]

A compact cheat sheet as well as a full specification are available at the official site.^[13] The following is a synopsis of the basic elements.

The YAML language accepts the entirety of the Unicode character set, except for some of the control characters. All of the accepted characters may be used in the YAML document. The YAML document may be encoded in UTF-8, UTF-16 and UTF-32. (Though UTF-32 is not mandatory, it is a must if the parser is to have JSON compatibility.)^[14]

• 
  Whitespace indentation is used to denote structure; however, tab characters are never allowed as indentation.


• Comments begin with the number sign (#), can start anywhere on a line and continue until the end of the line. Comments must be separated from other tokens by white space characters.^[15] If # characters appear inside of a string, then they are number sign (#) literals.


• List members are denoted by a leading hyphen (-) with one member per line, or enclosed in square brackets ([ ]) and separated by comma space (, ).


• Associative arrays are represented using the colon space (: ) in the form key: value, either one per line or enclosed in curly braces ( ) and separated by comma space (, ).
  
  • An associative array key may be prefixed with a question mark (?) to allow for liberal multi-word keys to be represented unambiguously.


• Strings (scalars) are ordinarily unquoted, but may be enclosed in double-quotes ("), or single-quotes (').
  
  • Within double-quotes, special characters may be represented with C-style escape sequences starting with a backslash (). According to the documentation the only octal escape supported is .


• Block scalars are delimited with indentation with optional modifiers to preserve (|) or fold (>) newlines.


• Multiple documents within a single stream are separated by three hyphens (---).
  
  • Three periods (...) optionally end a document within a stream.


• Repeated nodes are initially denoted by an ampersand (&) and thereafter referenced with an asterisk (*).


• Nodes may be labeled with a type or tag using the exclamation point (!!) followed by a string, which can be expanded into a URI.


• YAML documents in a stream may be preceded by 'directives' composed of a percent sign (%) followed by a name and space delimited parameters. Two directives are defined in YAML 1.1:
  
  • The %YAML directive is used to identify the version of YAML in a given document.
  
  
  • The %TAG directive is used as a shortcut for URI prefixes. These shortcuts may then be used in node type tags.
  
  

YAML requires that colons and commas used as list separators be followed by a space so that scalar values containing embedded punctuation (such as 5,280 or http://www.wikipedia.org) can generally be represented without needing to be enclosed in quotes.

Two additional sigil characters are reserved in YAML for possible future standardisation: the at sign (@) and backtick (`).

Basic components[edit]

YAML offers an "in-line" style for denoting associative arrays and lists. Here is a sample of the components.

Conventional block format uses a hyphen+space to begin a new item in list.

 --- # Favorite movies
 - Casablanca
 - North by Northwest
 - The Man Who Wasn't There

Optional inline format is delimited by comma+space and enclosed in brackets (similar to JSON).^[16]

 --- # Shopping list
 [milk, pumpkin pie, eggs, juice]

Keys are separated from values by a colon+space. Indented blocks, common in YAML data files, use indentation and new lines to separate the key/value pairs. Inline Blocks, common in YAML data streams, use comma+space to separate the key/value pairs between braces.

 --- # Indented Block
 name: John Smith
 age: 33
--- # Inline Block
 name: John Smith, age: 33

Strings do not require quotation. There are two ways to write multi-line strings, one preserving newlines (using the | character) and one that folds the newlines (using the > character), both followed by a newline character.

data: |
 There once was a tall man from Ealing
 Who got on a bus to Darjeeling
 It said on the door
 "Please don't sit on the floor"
 So he carefully sat on the ceiling

By default, the leading indent (of the first line) and trailing white space is stripped, though other behavior can be explicitly specified.

data: >
 Wrapped text
 will be folded
 into a single
 paragraph

 Blank lines denote
 paragraph breaks

Folded text converts newlines to spaces and removes leading whitespace.

- name: John Smith, age: 33
- name: Mary Smith
 age: 27
- [name, age]: [Rae Smith, 4] # sequences as keys are supported

men: [John Smith, Bill Jones]
women:
 - Mary Smith
 - Susan Williams

Advanced components[edit]

Two features that distinguish YAML from the capabilities of other data serialization languages are structures^[17] and data typing.

YAML structures enable storage of multiple documents within a single file, usage of references for repeated nodes, and usage of arbitrary nodes as keys.^[17]

For clarity, compactness, and avoiding data entry errors, YAML provides node anchors (using &) and references (using *). References to the anchor work for all data types (see the ship-to reference in the example below).

Below is an example of a queue in an instrument sequencer in which two steps are reused repeatedly without being fully described each time.

# sequencer protocols for Laser eye surgery
---
- step: &id001 # defines anchor label &id001
 instrument: Lasik 2000
 pulseEnergy: 5.4
 pulseDuration: 12
 repetition: 1000
 spotSize: 1mm

- step: &id002
 instrument: Lasik 2000
 pulseEnergy: 5.0
 pulseDuration: 10
 repetition: 500
 spotSize: 2mm
- step: *id001 # refers to the first step (with anchor &id001)
- step: *id002 # refers to the second step
- step:
 <<: *id001
 spotSize: 2mm # redefines just this key, refers rest from &id001
- step: *id002

Explicit data typing is seldom seen in the majority of YAML documents since YAML autodetects simple types. Data types can be divided into three categories: core, defined, and user-defined. Core are ones expected to exist in any parser (e.g. floats, ints, strings, lists, maps, ...). Many more advanced data types, such as binary data, are defined in the YAML specification but not supported in all implementations. Finally YAML defines a way to extend the data type definitions locally to accommodate user-defined classes, structures or primitives (e.g. quad-precision floats).

YAML autodetects the datatype of the entity. Sometimes one wants to cast the datatype explicitly. The most common situation is where a single-word string that looks like a number, boolean or tag requires disambiguation by surrounding it with quotes or using an explicit datatype tag.

---
a: 123 # an integer
b: "123" # a string, disambiguated by quotes
c: 123.0 # a float
d: !!float 123 # also a float via explicit data type prefixed by (!!)
e: !!str 123 # a string, disambiguated by explicit type
f: !!str Yes # a string via explicit type
g: Yes # a boolean True (yaml1.1), string "Yes" (yaml1.2)
h: Yes we have No bananas # a string, "Yes" and "No" disambiguated by context.

Not every implementation of YAML has every specification-defined data type. These built-in types use a double exclamation sigil prefix (!!). Particularly interesting ones not shown here are sets, ordered maps, timestamps, and hexadecimal. Here's an example of base64 encoded binary data.

 ---
 picture: !!binary |
 R0lGODdhDQAIAIAAAAAAANn
 Z2SwAAAAADQAIAAACF4SDGQ
 ar3xxbJ9p0qa7R0YxwzaFME
 1IAADs=

Many implementations of YAML can support user-defined data types for object serialization. Local data types are not universal data types but are defined in the application using the YAML parser library. Local data types use a single exclamation mark (!).

---
myObject: !myClass name: Joe, age: 15 

Example[edit]

Data structure hierarchy is maintained by outline indentation.

---
receipt: Oz-Ware Purchase Invoice
date: 2012-08-06
customer:
 first_name: Dorothy
 family_name: Gale

items:
 - part_no: A4786
 descrip: Water Bucket (Filled)
 price: 1.47
 quantity: 4

 - part_no: E1628
 descrip: High Heeled "Ruby" Slippers
 size: 8
 price: 133.7
 quantity: 1

bill-to: &id001
 street: |
 123 Tornado Alley
 Suite 16
 city: East Centerville
 state: KS

ship-to: *id001

specialDelivery: >
 Follow the Yellow Brick
 Road to the Emerald City.
 Pay no attention to the
 man behind the curtain.
...

Notice that strings do not require enclosure in quotations. The specific number of spaces in the indentation is unimportant as long as parallel elements have the same left justification and the hierarchically nested elements are indented further. This sample document defines an associative array with 7 top level keys: one of the keys, "items", contains a 2-element list, each element of which is itself an associative array with differing keys. Relational data and redundancy removal are displayed: the "ship-to" associative array content is copied from the "bill-to" associative array's content as indicated by the anchor (&) and reference (*) labels. Optional blank lines can be added for readability. Multiple documents can exist in a single file/stream and are separated by ---. An optional ... can be used at the end of a file (useful for signaling an end in streamed communications without closing the pipe).

Features[edit]

Indented delimiting[edit]

Because YAML primarily relies on outline indentation for structure, it is especially resistant to delimiter collision. YAML's insensitivity to quotes and braces in scalar values means one may embed XML, JSON or even YAML documents inside a YAML document by simply indenting it in a block literal (using | or >):

---
example: >
 HTML goes into YAML without modification
message: |

 <blockquote style="font: italic 12pt Times">
 <p>"Three is always greater than two,
 even for large values of two"</p>
 <p>--Author Unknown</p>
 </blockquote>
date: 2007-06-01

YAML may be placed in JSON by quoting and escaping all interior quotes. YAML may be placed in XML by escaping reserved characters (<, >, &, ', ") and converting whitespace, or by placing it in a CDATA section.

Non-hierarchical data models[edit]

Unlike JSON, which can only represent data in a hierarchical model with each child node having a single parent, YAML also offers a simple relational scheme that allows repeats of identical data to be referenced from two or more points in the tree rather than entered redundantly at those points. This is similar to the facility IDREF built into XML.^[18] The YAML parser then expands these references into the fully populated data structures they imply when read in, so whatever program is using the parser does not have to be aware of a relational encoding model, unlike XML processors, which do not expand references. This expansion can enhance readability while reducing data entry errors in configuration files or processing protocols where many parameters remain the same in a sequential series of records while only a few vary. An example being that "ship-to" and "bill-to" records in an invoice are nearly always the same data.

Practical considerations[edit]

YAML is line-oriented and thus it is often simple to convert the unstructured output of existing programs into YAML format while having them retain much of the look of the original document. Because there are no closing tags, braces, or quotation marks to balance, it is generally easy to generate well-formed YAML directly from distributed print statements within unsophisticated programs. Likewise, the whitespace delimiters facilitate quick-and-dirty filtering of YAML files using the line-oriented commands in grep, AWK, Perl, Ruby, and Python.

In particular, unlike markup languages, chunks of consecutive YAML lines tend to be well-formed YAML documents themselves. This makes it very easy to write parsers that do not have to process a document in its entirety (e.g. balancing opening and closing tags and navigating quoted and escaped characters) before they begin extracting specific records within. This property is particularly expedient when iterating in a single, stateless pass, over records in a file whose entire data structure is too large to hold in memory, or for which reconstituting the entire structure to extract one item would be prohibitively expensive.

Counterintuitively, although its indented delimiting might seem to complicate deeply nested hierarchies, YAML handles indents as small as a single space, and this may achieve better compression than markup languages. Additionally, extremely deep indentation can be avoided entirely by either: 1) reverting to "inline style" (i.e. JSON-like format) without the indentation; or 2) using relational anchors to unwind the hierarchy to a flat form that the YAML parser will transparently reconstitute into the full data structure.^{[citation needed]}

Security[edit]

YAML is purely a data representation language and thus has no executable commands.^[19] While validation and safe parsing is inherently possible in any data language, implementation is such a notorious pitfall that YAML's lack of an associated command language may be a relative security benefit.

However, YAML allows language-specific tags so that arbitrary local objects can be created by a parser that supports those tags. Any YAML parser that allows sophisticated object instantiation to be executed opens the potential for an injection attack. Perl parsers that allow loading of objects of arbitrary classes create so-called "blessed" values. Using these values may trigger unexpected behavior, e.g. if the class uses overloaded operators. This may lead to execution of arbitrary Perl code.^{[citation needed]}

The situation is similar for Python or Ruby parsers. According to the PyYAML documentation:^[20]

Note that the ability to construct an arbitrary Python object may be dangerous if you receive a YAML document from an untrusted source such as the Internet. The function yaml.safe_load limits this ability to simple Python objects like integers or lists.

Data processing and representation[edit]

The YAML specification identifies an instance document as a "Presentation" or "character stream".^[21] The primary logical structures in a YAML instance document are scalar, sequence, and mapping.^[22] The YAML specification also indicates some basic constraints that apply to these primary logical structures. For example, according to the specification, mapping keys do not have an order. In every case where node order is significant, a sequence must be used.^[23]

Moreover, in defining conformance for YAML processors, the YAML specification defines two primary operations: dump and load. All YAML-compliant processors must provide at least one of these operations, and may optionally provide both.^[24] Finally, the YAML specification defines an information model or "representation graph", which must be created during processing for both dump and load operations, although this representation need not be made available to the user through an API.^[25]

Comparison with other serialization formats[edit]

Comparison with JSON[edit]

JSON syntax is a basis of YAML version 1.2, which was promulgated with the express purpose of bringing YAML "into compliance with JSON as an official subset".^[26] Though prior versions of YAML were not strictly compatible,^[27] the discrepancies were rarely noticeable, and most JSON documents can be parsed by some YAML parsers such as Syck.^[28] This is because JSON's semantic structure is equivalent to the optional "inline-style" of writing YAML. While extended hierarchies can be written in inline-style like JSON, this is not a recommended YAML style except when it aids clarity.

YAML has many additional features lacking in JSON, including comments, extensible data types, relational anchors, strings without quotation marks, and mapping types preserving key order.

Comparison with XML[edit]

YAML lacks the notion of tag attributes that are found in XML. Instead YAML has extensible type declarations (including class types for objects).

YAML itself does not have XML's language-defined document schema descriptors that allow, for example, a document to self-validate. However, there are several externally defined schema descriptor languages for YAML (e.g. Doctrine, Kwalify and Rx) that fulfill that role. Moreover, the semantics provided by YAML's language-defined type declarations in the YAML document itself frequently relaxes the need for a validator in simple, common situations. Additionally, YAXML, which represents YAML data structures in XML, allows XML schema importers and output mechanisms like XSLT to be applied to YAML.

Software (emitters and parsers)[edit]

For fixed data structures, YAML files can simply be generated using print commands that write both the data and the YAML specific decoration. To dump varying, or complex, hierarchical data, however, a dedicated YAML emitter is preferable. Similarly, simple YAML files (e.g. key-value pairs) are readily parsed with regular expressions. For more complex, or varying, data structures, a formal YAML parser is recommended.

YAML emitters and parsers exist for many popular languages. Most of them are written in the native language itself. Some are language bindings of the C library libyaml; they may run faster. There used to be another C library, called Syck, written and orphaned by why the lucky stiff: it is unmaintained, there is no authoritative source bundle, and the web site has been hijacked. Hence the only recommendable C library is libyaml. It was originally developed by Kirill Simonov. In 2018, development was resumed by the new maintainers Ian Cordasco and Ingy döt Net.^[29]

C++ programmers have the choice between the C library libyaml and the C++ library libyaml-cpp. Both have completely independent code bases and completely different APIs. The library libyaml-cpp still has a major version number of 0, indicating that the API may change at any moment, as happened indeed after version 0.3.

Some implementations of YAML, such as Perl's YAML.pm, will load an entire file (stream) and parse it en masse. Conversely, YAML::Tiny only reads the first document in the stream and stops. Other implementations like PyYaml are lazy and iterate over the next document only upon request. For very large files in which one plans to handle the documents independently, instantiating the entire file before processing may be prohibitive. Thus in YAML.pm, occasionally one must chunk a file into documents and parse those individually. YAML makes this easy since this simply requires splitting on the document separator, which is m/^---$/ (once whitespace is stripped) as a regular expression in Perl.^{[verification needed]}

See also[edit]

• Comparison of data serialization formats


• List of lightweight markup languages

References[edit]

External links[edit]

• YAML Quick Reference card


• YAML.org


• YAML Specification


• 
  YAML Validator YAML Lint


• 
  YAML Validator YAML Validator