YAML Gotchas: The Traps Everyone Falls Into

1
2
3
4
5

# What you wrote
country: NO

# What YAML parsed
country: false

1
2

country: "NO"
enabled: "yes"  # If you mean the string "yes"

1
2
3
4
5

# What you wrote
port: 0800

# What YAML parsed
port: 512  # Interpreted as octal!

1
2

port: 800      # Remove leading zero
port: "0800"   # Or quote it

1
2
3
4
5

# What you wrote
version: 1.0

# What YAML parsed
version: 1  # Float, loses the .0

1
2
3
4
5

# What you wrote  
version: 3.10

# What YAML parsed
version: 3.1  # Trailing zero dropped

1
2

version: "1.0"
version: "3.10"

1
2
3
4
5

# What you wrote
password: 1e10

# What YAML parsed
password: 10000000000.0  # Scientific notation!

1

password: "1e10"

1
2
3
4

script: |
  echo "line 1"
  echo "line 2"
  echo "line 3"

1
2
3
4

description: >
  This is a long
  description that will
  become one line.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Keep final newline (default)
text: |
  content

# Strip final newline
text: |-
  content

# Keep all trailing newlines
text: |+
  content

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# Valid
parent:
  child: value

# Invalid (tabs)
parent:
	child: value  # TAB character - will fail

# Invalid (inconsistent)
parent:
  child1: value
   child2: value  # 3 spaces instead of 2

1
2
3
4
5
6

# These are all different
key1:        # null
key2: ""     # empty string
key3: null   # explicit null
key4: ~      # also null
key5: "null" # the string "null"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# Define anchor
defaults: &defaults
  adapter: postgres
  host: localhost

# Use alias
development:
  <<: *defaults
  database: dev_db

production:
  <<: *defaults
  database: prod_db
  host: prod-server

1
2
3
4
5
6
7
8
9

development:
  adapter: postgres
  host: localhost
  database: dev_db

production:
  adapter: postgres
  host: prod-server  # Overridden
  database: prod_db

1
2
3
4

# These need quotes
"key:with:colons": value
"key with spaces": value
"key#with#hashes": value

1
2
3

# This is a comment
key: value  # This is also a comment
key2: "value # but this is part of the string"

1
2
3
4
5
6
7
8
9

- true
- True
- TRUE
- yes
- Yes
- YES
- on
- On
- ON

1
2
3
4
5
6
7
8
9

- false
- False
- FALSE
- no
- No
- NO
- off
- Off
- OFF

1
2
3
4
5

# Broken
message: Error: something went wrong

# Fixed
message: "Error: something went wrong"

1
2
3
4
5
6
7

# These become datetime objects
date1: 2024-01-15
date2: 2024-01-15 10:30:00

# These stay strings
date3: "2024-01-15"
date4: 15-01-2024  # Not ISO format

1
2
3
4
5

# Safe
version: "1.0"
country: "NO"
port: "0800"
password: "1e10"

1
2
3
4
5
6
7

# yamllint
pip install yamllint
yamllint config.yml

# Or in CI
- name: Lint YAML
  run: yamllint -c .yamllint.yml .

1
2
3
4
5
6

extends: default
rules:
  line-length:
    max: 120
  truthy:
    check-keys: true

1
2
3
4
5
6
7
8

# Kubernetes
kubectl apply --dry-run=client -f config.yml

# Docker Compose
docker compose config

# Ansible
ansible-playbook --syntax-check playbook.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# JSON Schema for YAML
$schema: "https://json-schema.org/draft/2020-12/schema"
type: object
properties:
  version:
    type: string
  port:
    type: integer
required:
  - version

1
2
3
4
5
6

import yaml

# See what YAML actually parsed
with open('config.yml') as f:
    data = yaml.safe_load(f)
    print(repr(data))

1
2

# One-liner
python3 -c "import yaml; print(yaml.safe_load(open('config.yml')))"

1
2
3
4
5

# Pretty print
yq . config.yml

# Check specific value type
yq '.port | type' config.yml