YAML
External
- Wikipedia https://en.wikipedia.org/wiki/YAML
- http://yaml.org
- http://docs.ansible.com/ansible/YAMLSyntax.html
- Using YAML for Java Application Configuration https://dzone.com/articles/using-yaml-java-application
- http://www.yaml.org/spec/1.2/spec.html
Internal
Overview
YAML is a human-readable data serialization format. YAML syntax was designed to easily map on scalars, list and associative arrays. It is well suited for hierarchical data representation. It does not use enclosures such as quotation marks, brackets, braces and open/close tags, which can be hard fro the human eye to balance in nested hierarchies. Data structure hierarchy is maintained by outline indentation. The specific number of spaces in the indentation is not important as long as parallel elements have the same left justification, and the hierarchically nested elements are indented further.
Strings do not require enclosure in quotations.
The format has support for references, where sections in the document can be referenced, thus eliminating redundancy.
Multiple documents can exist in a single file/stream and they are separated by "---".
Comments
# This is a comment
Style
There are two styles: flow and block. In the "flow" style, successive YAML elements are placed on the same line, directly next to each other. This style is different from the "block style", where separate YAML elements are arranged into separate blocks defined by the same indentation.
Scalars
a: 10
YAML auto-detects the data type. A good rule when writing YAML is to quote strings and allow implicit type conversion for everything else.
Devoid of Value
The null word is used to indicate a lack of value. This is typically converted into any native null-like value (e.g., null in Java). Note that a null is different from an empty string and that a mapping entry with some key and a null value is valid and different from not having that key in the mapping.
b: null
Core Data Types
Strings, ints, floats, lists and maps.
a: 123 # an integer b: "123" # a string, disambiguated by quotes c: 123.0 # a float d: !!float 123 # a 'casted' float e: !!str 123 # a 'casted' string
Booleans
true and false must not be enclosed in quotes to be recognized as booleans.
N, n, Y, y are automatically identified as boolean scalars, unless enclosed in quotes. If you intend to pass the character N as a string value, specify 'N' and not N.
Boolean scalar support:
a: true a: Y a: Yes a: ON b: false b: n b: N
c: "true" # string not boolean
Integer
If a integral value is specified as an unquoted bare word, it is treated as a numeric type:
count: 1
The same quoted value is treated as string:
count: "1" # string not int
count: '1' # string not int
Leading-Zero Integer
If using a leading zero (for example 09) in a field without quoting the value in single quotes, the value may be interpreted incorrectly by the YAML parser. If the value is a valid octal, it is converted to an integer. If not, is converted to a float.
Float
If a float value is specified as an unquoted bare word, it is treated as a numeric type:
size: 32.1
The same quoted value is treated as string.
size: "32.1" # string not float
size: '32.1' # string not float
String
Forced Type Inference
Particular type inference can be forced with the !!type syntax:
age !!str 21 # will be a string, equivalent with "21" port: !!int 80 # will be an integer, equivalent with bare, unquoted 80
Defined Data Types
User-Defined Data Types
Collections
There are two types of collections: lists (or sequences) and associative arrays (or maps).
List (or Sequence)
List elements are designated by hyphen + space, and have the same offset:
- Audi - Mercedes - BMW
A list may contain a combination of "simple" elements and "complex" elements:
- simple
- complex:
key1: val1
key2: val2
Optional In-Line List Format
List elements are enclosed in brackets, and the list elements are separated by comma + space.
cars: ['Audi', 'BMW', 'Chevrolet']
Associative Array (or Map)
Keys are separated from values by a colon + space.
name: Audi color: black capacity: 5
Optional In-Line Associative Array Format
Associative array element are enclosed in braces, and they key: value pairs are separated by comma + space.
car: {brand: Audi, color: black, type: sedan}
Composite Collections
Collections can be combined:
List of Associative Arrays
- country: AU price: 6990000 - country: AT price: 4990000 - country: BE price: 4990000
The elements of an (associative array) list entry have the same indentation relative to each other, including the first one that follows the "-".
Associative Array of Associative Arrays
TODO, test:
command:
command-a:
option-1: value-1
option-2: value-2
command-b:
option-1: value-1
option-2: value-2
Multi-Line String Support
Embedding Multiple Documents in One File
It is possible to place more than one YAML documents into a single file. This is done by prefixing a new document with '---' and ending the document with '...'
---
document: 1
...
---
document: 2
...
In many cases, either '---' or '...' may be omitted. The optional "..." is useful for signaling an end in streamed communication without closing the pipe.
---
document: 1
---
document: 2
YAML is a Superset of JSON
Because YAML is a superset of JSON, any valid JSON document should be valid YAML. A YAML parser should understand JSON. See http://yaml.org/spec/1.2/spec.html#id2759572
JSON can be mixed into YAML, for the benefit of readability:
coffees: [ "Latte", "Cappuccino", "Espresso" ]
is equivalent with:
coffees:
- Latte
- Cappuccino
- Espresso
Conversion between YAML and JSON
Anchors, Aliases and Overrides
YAML anchors and aliases cannot contain the [, ], {, }, and , characters.
Anchor
The anchor is introduced with & and lets you mark a YAML item with the purpose of referring it later in the same document, and re-using its value with an aliases. Note that & must precede the item:
suffix: &default_suffix 'py'
This notation marks the string 'py' with the anchor default_suffix.
Alias
The value of an item that was previously marked with an anchor by using & can be inserted in the document by using the syntax *<anchor_name>. This syntax is called an alias.
For example:
suffix: &default_suffix 'py'
suffixes:
- 'java'
- 'sh'
- *default_suffix
is equivalent with:
suffix: 'py'
suffixes:
- 'java'
- 'sh'
- 'py'
Override
<<: