Skip to main content

YAML

Getting Started​

Introduction​

YAML is a data serialization 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

Scalar types​

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​

parent: &defaults
  a: 2
  b: 3

child:
  <<: *defaults
  b: 4

↓ Equivalent JSON​

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

Reference​

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

Based on the YAML.org refcard.

Document indicators​

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

Collection indicators​

?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)​

noneUnspecified tag (automatically resolved by application)
!Non-specific tag (by default, !!map/!!seq/!!str)
!fooPrimary (by convention, means a local !foo tag)
!!fooSecondary (by convention, means tag:yaml.org,2002:foo)
!h!fooRequires %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)​

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

Escape Codes​

Numeric​

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

Protective​

  • \\ (\)
  • \" (")
  • \ ( )
  • \<TAB> (TAB)

C​

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

Additional​

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

More types​

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

Language Independent Scalar Types​

{~, 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​