# YAML Quick Reference

*Scalars, sequences, mappings, anchors, multi-line*

> Source: YAML Specification (yaml.org) · MIT

## Syntax

### Basic Rules

| Command | Description |
|---------|-------------|
| `Indentation` | Spaces only (no tabs), consistent depth |
| `#` | Comment (to end of line) |
| `---` | Document start marker |
| `...` | Document end marker |
| `Case sensitive` | Keys and values are case-sensitive |

### Minimal Example

```
---
name: Alice
age: 30
active: true
```

## Scalars

### Scalar Types

| Command | Description |
|---------|-------------|
| `hello` | String (unquoted) |
| `"hello"` | String (double-quoted, allows escapes) |
| `'hello'` | String (single-quoted, literal) |
| `42 / 3.14` | Number (integer / float) |
| `true / false` | Boolean |
| `null / ~` | Null value |
| `2026-03-26` | Date (ISO 8601) |

### Quoting Rules

```
plain: no quotes needed
special: "colon: and hash # need quotes"
escape: "line\nnewline"
literal: 'no \n escaping here'
```

## Sequences

### Block Sequence

```
fruits:
  - apple
  - banana
  - cherry
```

### Flow Sequence (Inline)

```
colors: [red, green, blue]
matrix: [[1, 2], [3, 4]]
```

### Sequence of Objects

```
users:
  - name: Alice
    role: admin
  - name: Bob
    role: user
```

## Mappings

### Block Mapping

```
server:
  host: localhost
  port: 8080
  debug: false
```

### Flow Mapping (Inline)

```
point: {x: 10, y: 20}
```

### Complex Keys

```
? [first, second]
: "compound key value"
```

## Anchors & Aliases

### Define & Reuse

```
defaults: &defaults
  timeout: 30
  retries: 3
production:
  <<: *defaults
  timeout: 60
```

### Reference

| Command | Description |
|---------|-------------|
| `&name` | Define an anchor |
| `*name` | Reference (alias) an anchor |
| `<<` | Merge key — merge mapping into current |

## Multi-line Strings

### Block Scalars

| Command | Description |
|---------|-------------|
| `\| (literal)` | Preserves newlines exactly |
| `> (folded)` | Folds newlines into spaces |
| `\|+ (keep)` | Literal, keep trailing newlines |
| `\|- (strip)` | Literal, strip trailing newlines |
| `>- (fold+strip)` | Folded, strip trailing newlines |

### Literal Block

```
script: |
  echo "line one"
  echo "line two"
```

### Folded Block

```
description: >
  This long text will be
  folded into a single line
  with spaces.
```

## Tags

### Type Tags

| Command | Description |
|---------|-------------|
| `!!str 42` | Force value to string "42" |
| `!!int "42"` | Force value to integer 42 |
| `!!float 1` | Force value to float 1.0 |
| `!!bool "true"` | Force value to boolean |
| `!!null ""` | Force value to null |
| `!!binary` | Base64-encoded binary data |

### Tag Example

```
port: !!str 8080
enabled: !!bool "yes"
version: !!float 3
```

## Common Patterns

### Docker Compose

```
services:
  web:
    image: nginx:alpine
    ports: ["80:80"]
    environment:
      NODE_ENV: production
```

### GitHub Actions

```
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
```

### Tips

| Command | Description |
|---------|-------------|
| `yamllint` | Lint YAML for syntax and style |
| `yq` | Command-line YAML processor (like jq) |
| `Avoid Norway` | NO is boolean false — quote country codes |
| `Avoid !!python` | Never load untrusted YAML with unsafe loaders |