YAML primer

YAML is a human-readable data serialization format, like JSON.

In fact, YAML is a superset of JSON: you can also write a barectf configuration in JSON.

YAML has many features which are outside the scope of the barectf documentation. This page is a simple introduction to the YAML 1.2 language.

YAML uses indentation for scoping, much like Python.

The root of a YAML document is a mapping.

Mapping

A YAML mapping is an unordered list of key-value pairs.

Within a mapping, : delimits the value from the key.

Example 1. A YAML mapping with four entries.

Castonguay: Huguette Delisle
Létourneau: Gaétan Delisle
Robitaille: Serge Paquette
Gonthier-Hyndman: Micheline Paquette

Example 2. A YAML mapping with a nested mapping.

title: C'est comme ça que je t'aime
country: Canada
language: French
release-date: 6 March 2020
cast:
  Castonguay: Huguette Delisle
  Létourneau: Gaétan Delisle
  Robitaille: Serge Paquette
  Gonthier-Hyndman: Micheline Paquette

You can also write a mapping on a single line, delimiting key-value pairs with ,, beginning with { and ending with }:

Example 3. A single-line YAML mapping with four entries.

{Marilyn: Huguette, François: Gaétan, Karine: Micheline, Patrice: Serge}

Example 4. A YAML mapping with a nested single-line mapping.

title: C'est comme ça que je t'aime
country: Canada
language: French
release-date: 6 March 2020
cast: {Marilyn: Huguette, François: Gaétan, Karine: Micheline, Patrice: Serge}

Although the keys of a mapping can be any value, barectf only uses strings.

Each key of a given mapping must be unique.

Sequence

A YAML sequence is an ordered list of values.

Each item begins with -.

Example 5. A YAML sequence with four items.

- Corvette Express
- Québec Deli
- Boulangerie Fanfare
- Marché Méli-Mélo

Example 6. A YAML sequence. The third item is a mapping.

- Le poète des temps gris
- Aidez-moi
- name: Granby
  album: Toutte est temporaire
  year: 2014
- La patente

You can also write a sequence on a single line, delimiting items with a comma (,), beginning with [ and ending with ]:

Example 7. A single-line YAML sequence with four items.

[Corvette Express, Québec Deli, Boulangerie Fanfare, Marché Méli-Mélo]

Example 8. A single-line YAML sequence. The third item is a single-line mapping.

[Le poète des temps gris, Aidez-moi, {name: Granby, year: 2014}, La patente]

Null, boolean, integer, and string values

The basic YAML scalar values which are of interest to write a barectf configuration are:

Null

null, Null, NULL, ~, or nothing.

In a barectf YAML configuration, a null value always means to use the default value.

Boolean

true, True, TRUE, false, False, or FALSE.

Integer

Anything matching these regular expressions:

[-+]?[0-9]+ (decimal)
0o[0-7]+ (octal)
0x[0-9a-fA-F]+ (hexadecimal)

Examples: 23, 0x45fc1, -17, 0o644.

String

Double-quoted or single-quoted sequence of characters, or unquoted sequence of characters when it doesn’t match the form of another value.

Examples:

"Whoever is happy will make others happy too."
'Life is either a daring adventure or nothing at all.'
Only a life lived for others is a life worthwhile.

Example 9. A YAML mapping with null, boolean, integer, and string values.

'null': null
booleans: [true, false]
integers: [23, 0x45fc1, -17, 0o644]
strings:
  - "Whoever is happy will make others happy too."
  - 'Life is either a daring adventure or nothing at all.'
  - Only a life lived for others is a life worthwhile

Comment

A YAML comment starts with # and ends at the end of the line.

Example 10. A YAML mapping with comments.

title: C'est comme ça que je t'aime

# This is actually a Québec production.
country: Canada

language: French
release-date: 6 March 2020
cast:
  Castonguay: Huguette Delisle
  Létourneau: Gaétan Delisle # also cowrote Série noire
  Robitaille: Serge Paquette
  Gonthier-Hyndman: Micheline Paquette

YAML primer

Mapping

Sequence

Null, boolean, integer, and string values

Comment

Tags