YAML Reference

v1.0.0

Browse YAML syntax with live parsed-value previews, gotchas, and encoding patterns.

21 entries found

Strings

Basics

Strings can be unquoted, single-quoted, or double-quoted.

YAML

name: Alice
greeting: 'Hello, World!'
path: "/usr/local/bin"
note: "Tab\there"

Parsed Result

{ name: "Alice", greeting: "Hello, World!", path: "/usr/local/bin", note: "Tab\there" }

Numbers

Basics

Integers, floats, hex, and octal literals.

YAML

integer: 42
negative: -7
float: 3.14
scientific: 1.5e6
hex: 0xFF
octal: 0o17

Parsed Result

{ integer: 42, negative: -7, float: 3.14, scientific: 1500000, hex: 255, octal: 15 }

Booleans

Basics

YAML 1.1 treats many words as booleans. YAML 1.2 only recognises true/false.

YAML

yaml11_true: yes
yaml11_false: no
strict_true: true
strict_false: false
on_is_bool: on
off_is_bool: off

Parsed Result

# YAML 1.1: yes/no/on/off/y/n = boolean
# YAML 1.2 (JSON-compatible): only true/false

⚠ In YAML 1.1, 'NO', 'YES', 'ON', 'OFF', 'y', 'n' are all booleans. Quote them if you mean the string.

Null Values

Basics

Null can be represented as null, ~, or an empty value.

YAML

explicit: null
tilde: ~
empty:

Parsed Result

{ explicit: null, tilde: null, empty: null }

Comments

Basics

Comments start with # and run to the end of the line.

YAML

# Full-line comment
name: Alice  # Inline comment
age: 30

Parsed Result

{ name: "Alice", age: 30 }

Anchors & Aliases

Basics

Reuse values with anchors (&) and aliases (*).

YAML

defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults
  url: https://api.example.com

staging:
  <<: *defaults
  url: https://staging.example.com

Parsed Result

# production and staging both inherit timeout: 30, retries: 3

Mappings (Objects)

Collections

Key-value pairs. Nested mappings use indentation.

YAML

server:
  host: localhost
  port: 8080
  tls:
    enabled: true
    cert: /etc/ssl/cert.pem

Parsed Result

{ server: { host: "localhost", port: 8080, tls: { enabled: true, cert: "/etc/ssl/cert.pem" } } }

Sequences (Arrays)

Collections

Ordered lists. Each item starts with '- '.

YAML

fruits:
  - apple
  - banana
  - cherry

# Inline / flow style
colors: [red, green, blue]

Parsed Result

{ fruits: ["apple", "banana", "cherry"], colors: ["red", "green", "blue"] }

Nested Structures

Collections

Mix of mappings and sequences.

YAML

services:
  - name: web
    image: nginx:latest
    ports:
      - "80:80"
  - name: db
    image: postgres:16
    environment:
      POSTGRES_DB: mydb

Parsed Result

# Array of objects with nested arrays/objects

Flow Style

Collections

Compact inline notation for small structures.

YAML

# Flow style mapping
point: {x: 1, y: 2}

# Flow style sequence
tagsArray: [web, api, v2]

# Mixed
host: {ip: "10.0.0.1", ports: [80, 443]}

Parsed Result

# Flow style is equivalent to block style, just more compact

Literal Block (|)

Multiline

Preserves newlines exactly. Trailing newline is kept.

YAML

message: |
  Hello,
  World!
  This is line 3.

Parsed Result

{ message: "Hello,\nWorld!\nThis is line 3.\n" }

Folded Block (>)

Multiline

Newlines become spaces (text wrapping). Blank lines become newlines.

YAML

description: >
  This is a long
  sentence that wraps
  onto multiple lines.

  New paragraph here.

Parsed Result

{ description: "This is a long sentence that wraps onto multiple lines.\nNew paragraph here.\n" }

Chomping Modifiers

Multiline

|-, >- strip final newline. |+, >+ keep all trailing newlines.

YAML

strip: |-
  No trailing newline

keep: |+
  Keeps all trailing newlines

Parsed Result

# |-  → strip final newline
# |+  → keep all trailing newlines
# |   → keep exactly one trailing newline (default)

Multi-document

Advanced

One YAML file can contain multiple documents separated by ---.

YAML

---
name: doc1
value: 1
---
name: doc2
value: 2
...

Parsed Result

# Two separate YAML documents in one file
# '...' marks end of document (optional)

Explicit Tags

Advanced

Override YAML type inference with !!

YAML

string_number: !!str 42
bool_string: !!str true
int_float: !!int 3.14
coerce: !!float "1"

Parsed Result

{ string_number: "42", bool_string: "true", int_float: 3, coerce: 1.0 }

Environment Variables

Advanced

Docker Compose and some tools support $VAR or ${VAR} substitution.

YAML

version: "3.8"
services:
  web:
    image: myapp:${IMAGE_TAG:- latest}
    environment: 
 - PORT=${ PORT: -3000 }

Parsed Result

# ${ VAR: -default } uses default if VAR is unset
# ${ VAR:? error} fails if VAR is unset

The Norway Problem / Boolean Trap

Gotchas

Country codes and other two-letter words interpreted as booleans in YAML 1.1.

YAML

# YAML 1.1 parses these as booleans!
country: NO   # → false!
flag: YES     # → true!
control: ON   # → true!

Parsed Result

# Always quote: country: "NO", flag: "YES"

⚠ Always quote two-letter country codes and any word that could be a boolean: NO/YES/ON/OFF/Y/N/TRUE/FALSE.

Tabs Not Allowed

Gotchas

YAML prohibits tab characters for indentation. Use spaces only.

YAML

# WRONG — tab indented(will cause parse error) 
server: 
	host: localhost  # ← TAB

# CORRECT — space indented
server: 
  host: localhost  # ← 2 spaces

Parsed Result

# Use 2 or 4 spaces consistently.Never tabs.

⚠ Configure your editor to expand tabs to spaces for .yml/.yaml files.

Colon Requires Space

Gotchas

A colon must be followed by a space to be a key-value separator.

YAML

# WRONG — no space after colon inside unquoted string
url: http://example.com  # Safe (: in quoted context)
ratio: 1:2               # Parsed as string "1:2" -- OK

# Always quote URLs to be safe
url: "http://example.com"

Parsed Result

# 'key:value' (no space) → treated as a string
# 'key: value' (with space) → mapping

⚠ Quote anything with a colon to avoid ambiguity: url: 'http://example.com'

Duplicate Keys

Gotchas

Duplicate keys in a mapping are ambiguous. Most parsers take the last value.

YAML

config:
  timeout: 30
  timeout: 60  # ← duplicate key!
  host: localhost

Parsed Result

# Result: { timeout: 60, host: "localhost" }
# First value silently discarded — always avoid duplicate keys

⚠ Most YAML parsers silently accept duplicate keys and take the last value. Use a strict parser in production.

Special Characters

Gotchas

These characters have special meaning and may need quoting: : { } [ ] , # & * ? | > ! % @ `

YAML

# Safe: plain string
name: Alice

# Needs quoting: starts with special char
template: "Hello, {name}!"
regex: ": ^\\d{3}$"
message: "#top"  # would be a comment without quotes

Parsed Result

# When in doubt, quote the value.

⚠ Quote strings that start with or contain: : { } [ ] , # & * ? | > ! % @ `