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
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 "---".
An optional "..." can be used at then of the file - useful for signaling an end in streamed communication without closing the pipe.
YAML is a superset of JSON, so a YAML parser should understand JSON. See http://yaml.org/spec/1.2/spec.html#id2759572
Comments
# This is a comment
Scalars
a: 10
Types are auto-detected, see Data Types.
Data Types
YAML auto-detects the datatype. A good rule when writing YAML is to quote strings and allow implicit type conversion for everything else.
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
Boolean Support
true and false must not be enclosed in quotes to be recognized as booleans.
Boolean scalar support:
a: true a: Y a: Yes a: ON b: false b: n
String
Strings do not require quotation, but it is recommended to quote them, to explicitly specify they are strings and type inference should not be attempted.
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 Support
Literal Style
Multi-line strings can be written using the '|' character followed by a new line. To be considered multi-line content, the first line under the '|'-terminated line must be indented on a level deeper that the line containing the '|'. Trailing white space is stripped. The new line characters are preserved.
This is correct multi-line (the mult-lines must be indented under 'data'):
data: |
This is a
multi-line
text section
This is NOT a correct mult-line, because the "mult-lines" are not correctly indented:
data: |
This is not
a correct multi-line
Folded Style
The '>' character followed by a new line folds all the new lines, after removing trailing white space and new lines.
data: >
This is another
multi-line
text section
but in the final form
it will be just one long string
without new lines