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

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.

Boolean scalar support:

a: true
a: Y
a: Yes
a: ON
b: false
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

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

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.

The following representations are equivalent for a string:

s1: bare words string
s2: "a double-quoted string"
s3: 'a single-quoted string'

All forms represented above are named "inline", in that the strings must be rendered on one line.

In the bare word format, characters cannot be escaped.

Double-quoted strings can have specific characters escaped with \. Double quotes can be escaped with \" and line breaks can be escaped with \n.

Single-quoted strings are "literal" strings, they do not use \ to escape characters. The only escape sequence is '' (two single quotes), which is decoded as a single '.

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

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

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

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 '|' and the subsequent multi-line lines must be indented with the same offset as the first line. Trailing white space is stripped. The new line characters are preserved.

This is correct multi-line (the multi-lines must be indented under 'data'):

data: |
  This is a
  multi-line
  text section

The value of data is equivalent with "This is a\nmulti-line\ntext selection\n".

This is NOT a correct mult-line, because the "mult-lines" are not correctly indented:

data: |
This is not
a correct multi-line

The "|" multi-line operator implies that a trailing newline will be added to the string. In the correct above example, the data value will be equivalent with "This is a\nmulti-line\ntext selection\n" - note the trailing new line. If we want the YAML processor to strip off the trailing newline, we should use "|-" instead of "|":

dataWithoutTrailingNewLine: |-
  This is a
  multi-line
  text section

The dataWithoutTrailingNewLine value is equivalent with "This is a\nmulti-line\ntext selection". Note the lack of trailing newline.

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

YAML support in Java

YamlBeans

snakeyaml