YAML

Getting Started

Introduction

YAML is a data serialisation language designed to be directly writable and readable by humans

YAML does not allow the use of tabs
Must be space between the element parts
YAML is CASE sensitive
End your YAML file with the .yaml or .yml extension
YAML is a superset of JSON
Ansible playbooks are YAML files {.marker-round}

Scalar types {.row-span-2}

n1: 1            # integer
n2: 1.234        # float

s1: 'abc'        # string
s2: "abc"        # string
s3: abc          # string

b: false         # boolean type

d: 2015-04-05    # date type

↓ Equivalent JSON

{
  "n1": 1,
  "n2": 1.234,
  "s1": "abc",
  "s2": "abc",
  "s3": "abc",
  "b": false,
  "d": "2015-04-05"
}

Use spaces to indent. There must be space between the element parts.

Variables

some_thing: &VAR_NAME foobar
other_thing: *VAR_NAME

↓ Equivalent JSON

{
  "some_thing": "foobar",
  "other_thing": "foobar"
}

Comments

# A single line comment example

# block level comment example
# comment line 1
# comment line 2
# comment line 3

Multiline strings

description: |
  hello
  world

↓ Equivalent JSON

{ "description": "hello\nworld\n" }

Inheritance {.row-span-2}

parent: &defaults
  a: 2
  b: 3

child:
  <<: *defaults
  b: 4

↓ Equivalent JSON

{
  "parent": {
    "a": 2,
    "b": 3
  },
  "child": {
    "a": 2,
    "b": 4
  }
}

Reference {.row-span-2}

values: &ref
  - Will be
  - reused below

other_values:
  i_am_ref: *ref

↓ Equivalent JSON

{
  "values": [
    "Will be",
    "reused below"
  ],
  "other_values": {
    "i_am_ref": [
      "Will be",
      "reused below"
    ]
  }
}

Folded strings

description: >
  hello world

↓ Equivalent JSON

{ "description": "hello world\n" }

Two Documents

---
document: this is doc 1
---
document: this is doc 2

YAML uses --- to separate directives from document content.

YAML Collections

Sequence

- Mark McGwire
- Sammy Sosa
- Ken Griffey

↓ Equivalent JSON

[
  "Mark McGwire",
  "Sammy Sosa",
  "Ken Griffey"
]

Mapping

hr:  65       # Home runs
avg: 0.278    # Batting average
rbi: 147      # Runs Batted In

↓ Equivalent JSON

{
  "hr": 65,
  "avg": 0.278,
  "rbi": 147
}

Mapping to Sequences

attributes:
  - a1
  - a2
methods: [getter, setter]

↓ Equivalent JSON

{
  "attributes": ["a1", "a2"],
  "methods": ["getter", "setter"]
}

Sequence of Mappings

children:
  - name: Jimmy Smith
    age: 15
  - name: Jimmy Smith
    age: 15
  -
    name: Sammy Sosa
    age: 12

↓ Equivalent JSON

{
  "children": [
    {"name": "Jimmy Smith", "age": 15},
    {"name": "Jimmy Smith", "age": 15},
    {"name": "Sammy Sosa", "age": 12}
  ]
}

Sequence of Sequences

my_sequences:
  - [1, 2, 3]
  - [4, 5, 6]
  -
    - 7
    - 8
    - 9
    - 0

↓ Equivalent JSON

{
  "my_sequences": [
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9, 0]
  ]
}

Mapping of Mappings

Mark McGwire: { hr: 65, avg: 0.278 }
Sammy Sosa: { hr: 63, avg: 0.288 }

↓ Equivalent JSON

{
  "Mark McGwire": {
    "hr": 65,
    "avg": 0.278
  },
  "Sammy Sosa": {
    "hr": 63,
    "avg": 0.288
  }
}

Nested Collections

Jack:
  id: 1
  name: Franc
  salary: 25000
  hobby:
    - a
    - b
  location: { country: "A", city: "A-A" }

↓ Equivalent JSON

{
  "Jack": {
    "id": 1,
    "name": "Franc",
    "salary": 25000,
    "hobby": ["a", "b"],
    "location": {
      "country": "A",
      "city": "A-A"
    }
  }
}

Unordered Sets

set1: !!set
  ? one
  ? two
set2: !!set { "one", "two" }

↓ Equivalent JSON

{
  "set1": { "one": null, "two": null },
  "set2": { "one": null, "two": null }
}

Sets are represented as a Mapping where each key is associated with a null value

Ordered Mappings

ordered: !!omap
  - Mark McGwire: 65
  - Sammy Sosa: 63
  - Ken Griffy: 58

↓ Equivalent JSON

{
  "ordered": [
    { "Mark McGwire": 65 },
    { "Sammy Sosa": 63 },
    { "Ken Griffy": 58 }
  ]
}

YAML Reference

Terms

Sequences aka arrays or lists
Scalars aka strings or numbers
Mappings aka hashes or dictionaries {.marker-round}

Based on the YAML.org refcard.

Document indicators


`%`	Directive indicator
`---`	Document header
`...`	Document terminator

Collection indicators {.row-span-2}


`?`	Key indicator
`:`	Value indicator
`-`	Nested series entry indicator
`,`	Separate in-line branch entries
`[]`	Surround in-line series branch
`{}`	Surround in-line keyed branch

Alias indicators


`&`	Anchor property
`*`	Alias indicator

Special keys


`=`	Default “value” mapping key
`<<`	Merge keys from another mapping

Scalar indicators

| | | | ----- | --------------------------------- | --------------------------------------------- | ----------- | | '' | Surround in-line unescaped scalar | | " | Surround in-line escaped scalar | | | | Block scalar indicator | | > | Folded scalar indicator | | - | Strip chomp modifier ( | -or>-) | | + | Keep chomp modifier ( | +or>+) | | 1-9 | Explicit indentation modifier ( | 1or>2).
Modifiers can be combined ( | 2-, >+1) |

Tag Property (usually unspecified) {.col-span-2}


`none`	Unspecified tag (automatically resolved by application)
`!`	Non-specific tag (by default, `!!map`/`!!seq`/`!!str`)
`!foo`	Primary (by convention, means a local `!foo` tag)
`!!foo`	Secondary (by convention, means `tag:yaml.org,2002:foo`)
`!h!foo`	Requires `%TAG !h! <prefix>` (and then means `<prefix>foo`)
`!<foo>`	Verbatim tag (always means `foo`)

Misc indicators


`#`	Throwaway comment indicator
`@	Both reserved for future use

Core types (default automatic tags) {.row-span-2}


`!!map`	`{Hash table, dictionary, mapping}`
`!!seq`	`{List, array, tuple, vector, sequence}`
`!!str`	Unicode string

Escape Codes {.row-span-3}

Numeric

\x12 (8-bit)
\u1234 (16-bit)
\U00102030 (32-bit)

{.cols-2 .marker-none}

Protective

\\ (\)
\" (”)
\ ( )
\<TAB> (TAB)

{.cols-3 .marker-none}

C

\0 (NUL)
\a (BEL)
\b (BS)
\f (FF)
\n (LF)
\r (CR)
\t (TAB)
\v (VTAB)

{.cols-3 .marker-none}

Additional

\e (ESC)
\_ (NBSP)
\N (NEL)
\L (LS)
\P (PS)

{.cols-3 .marker-none}

More types


`!!set`	`{cherries, plums, apples}`
`!!omap`	`[one: 1, two: 2]`

Language Independent Scalar Types {.col-span-2}


`{~, null}`	Null (no value).
`[1234, 0x4D2, 02333]`	[Decimal int, Hexadecimal int, Octal int]
`[1_230.15, 12.3015e+02]`	[Fixed float, Exponential float]
`[.inf, -.Inf, .NAN]`	[Infinity (float), Negative, Not a number]
`{Y, true, Yes, ON}`	Boolean true
`{n, FALSE, No, off}`	Boolean false

Also see

YAML Reference Card (yaml.org)
Learn X in Y minutes (learnxinyminutes.com)
YAML lint online (yamllint.com)