---

title: YAML date: 2020-12-29 18:26:55 background: bg-[#b42e28] tags: - config - format categories: - Programming intro: | This is a quick reference cheat sheet for understanding and writing YAML format configuration files. plugins: - copyCode

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 {.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

Collection indicators {.row-span-2}

Alias indicators

Special keys

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}

Misc indicators

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

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

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

Also see

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