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.

List

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

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}

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

String

Strings do not require quotation.

Multi-line Support

http://www.yaml.org/spec/1.2/spec.html#id2795688

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.

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

The '>' character followed by a new line folds all the new lines, after removing trailing white space. Explain difference between | and >, below. Something must be different.

data: >
   This is another
   multi-line
   text section

Data Types

YAML auto-detects the datatype

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

Boolean scalar support:

a: true
a: Y
a: Yes
a: ON

b: false
b: n

YAML support in Java

YamlBeans

snakeyaml