YAML

YAML is a data description language similar to JSON, but with human readability in mind.

There are two fundamental data container types making up a data structure: lists and maps. All other data is scalar, meaning a single data items.

A list is a sequence of data items, one after another. Maps are an unordered set of data items with an associated key. Since lists and maps can be nested, they themselves become data items. In YAML, both can be written in two notations: either the block style or the flow style. The two styles can be chosen for every data item indivdually and can be mixed freely.

Values

Simple values (scalar values) can have the following types:

• string
• integer
• floating point
• boolean
• null value

String

A sequence of characters is normally taken as a string. However, if a different data type is detected, that data type is returned to the program. To force a sequence of characters to be interpreted as a string, it can be quoted with either single quote or double quotes:

- '123' # would be taken as integer otherwise
- "2.4" # would be taken as floating point value otherwise
- 'yes' # would be taken as a boolean otherwise

Strings containing the following characters have to be quoted: [ ] { } ~ & * | > ! # @ % `.

Integer

A number without decimal point:

- 200
- -123

Floating point

A number with decimal point:

- 1.2
- -3.4

Boolean

Either a value for true:

- true
- yes
- on

or a value for false:

- false
- no
- off

Null value

One of these:

- ~
- null

Lists

A list in block style:

- item 1
- item 2
- item 3

A list in flow style:

[item 1, item 2, item3]

or:

[
    item 1,
    item 2,
    item 3
]

In flow style, tokens can be formatted freely with white space, where as in block style, the line format must be kept.

Nested lists

Lists can be nested:

-
    - Item 1a
    - Item 1b
-
    - Item 2a
    - Item 2b

or:

[
    [Item 1b, Item 1b],
    [Item 2a, Item 2b]
]

or a mix of block and flow style:

- [Item 1a, Item 1b]
- [Item 2a, Item 2b]

Maps

A map in block style:

First name: Jack
Last name: Miller
Email: jack.miller@gmail.com

A map in flow style:

{First name: Jack, Last name: Miller, Email: jack.miller@gmail.com}

Again, as with lists in flow style, white space can be used to format the data:

{
    First name: Jack,
    Last name: Miller,
    Email: jack.miller@gmail.com
}

Nested maps

Nested maps in block style:

Key1: Value1
Key2:
    Key2a: Value2a
    Key2b: Value2b

In flow style:

{
    Key1: Value1,
    Key2: {
        Key2a: Value2a,
        Key2b, Value2b
    }
}

Nesting lists and maps

A list of maps in block style:

-
    Key1a: Value1a
    Key1b: Value1b
-
    Key2a: Value2a
    Key2b: Value2b

In flow style:

[{Key1a: Value1a, Key1b: Value1b}, {Key2a: Value2a, Key2b: Value2b}]

A map of lists in block style:

Key1:
    - Item 1a
    - Item 1b
Key2:
    - Item 2a
    - Item 2b

In flow style:

{Key1: [Item 1a, Item 1b], Key2: [Item 2a, Item 2b]}

Quoting

Certain characters are used in YAML to make up the syntax for data definitions. Also, certains words are used to denote certain data values. These are: [ ] { } , : - and ~. Reserved words are: null, true, false, yes, no, on and off.

When writing data items containing the reserved characters or as the character sequence of the reserved words, a data value has to be written in either single or double quotes:

- "Item [1]"
- 'Item {2}'
- 'null'
- 'yes'