YAML - Daniel Lyons' Notes

Key-Value Pairs:
```
key: value
```
A colon and a space separate the key from its value.
Indentation:
Uses spaces for indentation; tabs are not allowed. Indentation is crucial for defining structure.
```
parent:
  child: value
  another_child: another_value
```

Comments:
Start with #.

# This is a full line comment
key: value # This is an end-of-line comment

Data Types

YAML natively supports three basic data types: Scalars, Sequences (arrays/lists), and Mappings (dictionaries/objects).

1. Scalars (Single Values)

Strings:
Can be plain (unquoted) or quoted. Quotes are needed for special characters, leading/trailing spaces, or to ensure a string interpretation (e.g., yes, no, numbers).

plain_string: This is a plain string
quoted_string_single: 'This is a single-quoted string with a colon: inside'
quoted_string_double: "This is a double-quoted string with special characters like \n (newline)"
number_as_string: "123" # Interpreted as a string, not an integer

Numbers:
Integers, floats.

integer: 123
float: 123.45
negative_number: -50
hexadecimal: 0x3F # Represents 63
octal: 0o77 # Represents 63
exponential: 1.2e-3

Booleans:
true, false, True, False, TRUE, FALSE, yes, no, Yes, No, YES, NO, on, off, On, Off, ON, OFF.
```
is_active: true
is_admin: No
```
Null:
null, Null, NULL, ~ (tilde).
```
empty_value: null
another_empty: ~
```

Dates and Times:
ISO 8601 format.

date: 2023-10-27
datetime: 2023-10-27T10:30:00Z
datetime_offset: 2023-10-27 10:30:00 -07:00

2. Sequences (Lists/Arrays)

Represented by hyphens followed by a space. Each item is on a new line and indented.

fruits:
  - Apple
  - Banana
  - Orange

Inline (flow style) sequence:

colors: [Red, Green, Blue]

1. Top-Level List or Direct Child of a Mapping Key:

When a list is at the very top level of a YAML document, or when it's a direct value of a mapping key, its items are simply marked with a hyphen, and no extra indentation is required between the hyphen and the list item content. The key is that the hyphen itself aligns with the parent's indentation level or the document's start.

# Top-level list
- item 1
- item 2
- item 3

# List as a direct child of a mapping key
my_list:
- Apple
- Banana
- Cherry

In this case, the - is the indentation indicator, aligning with my_list:'s level.

2. Nested Lists (List within a List):

When you have a list inside another list, the nested list's items do need to be further indented relative to their parent list item. This is where the "indentation is crucial" rule really applies to differentiate levels.

shopping_cart:
  - item: Milk
	quantity: 1
  - item: Bread
	quantity: 2
	ingredients:
	  - Flour
	  - Water
	  - Yeast
  - item: Eggs
	quantity: 12

In the example above, Flour, Water, and Yeast are indented relative to ingredients:.

3. List Items with Nested Mappings/Structures:

If a list item itself contains a mapping or another complex structure, that structure must be indented relative to its parent list item.

people:
  - name: Alice
	age: 30
	city: New York
  - name: Bob
	age: 25
	city: London

Here, name, age, and city are indented under the - that defines Alice and Bob's entries.

3. Mappings (Dictionaries/Objects)

Standard key-value pairs.

person:
  name: Alice
  age: 30
  city: New York

Inline (flow style) mapping:

user: {id: 101, status: active}

Advanced Features

Multi-line Strings

Literal Block (|): Preserves newlines and most whitespace.

poem: |
  This is the first line.
  This is the second line.

  This is the third line, with a blank line above.

Folded Block (>): Folds newlines into spaces, preserving blank lines.

message: >
  This is a very long sentence
  that will be folded into a single line.

  This paragraph will remain separate.

Chomping Indicators: Control how trailing newlines are handled.
- |-: Strips all trailing newlines.
- |+: Keeps all trailing newlines.
- |: Keeps one trailing newline (default for literal).
- >-: Strips all trailing newlines.
- >+: Keeps all trailing newlines.
- >: Keeps one trailing newline (default for folded).
Example:
```
stripped_text: |-
  Line 1
  Line 2

kept_text: |+
  Line 1
  Line 2
```

Anchors and Aliases (`&`, `*`)

Reuse content by defining an anchor (&) and then referencing it with an alias (*).

default_settings: &common_settings
  theme: dark
  notifications: true

user_config:
  <<: *common_settings # Merges default_settings here
  username: johndoe
  notifications: false # Overrides notification setting

The <<: merge key is used specifically for merging mapping nodes.

Tags (`!!`)

Explicitly specify a data type.

price: !!float "19.99"
binary_data: !!binary |
  R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==

Directives

%YAML and %TAG are used at the beginning of a document.

%YAML 1.2
%TAG !t! tag:example.com,2023:
---
document_start: true

Multiple Documents in a Single File

Separated by ---. An optional ... can signify the end of a document.

---
# Document 1
title: Report A
version: 1.0
---
# Document 2
title: Report B
version: 2.0
...

YAML

Interactive graph

On this page

Basic Syntax