YAML Cheat Sheet

1. Scalars & basic types

A YAML document is a tree of mappings (key: value) and sequences (lists). Scalars are the leaf values: strings, numbers, booleans, and null. Quotes around strings are optional unless the value could be misread as another type.

name: json-to-yaml         # string, no quotes needed
port: 8080                 # integer
ratio: 0.75                # float
enabled: true              # boolean
tags: null                 # null (also: ~)
note: "value: with colon"  # quote when the value contains : { } [ ] , & * # ? | - < > = ! % @ `

Comments start with # and run to the end of the line. JSON has no comments, which is one of the main reasons teams convert configs to YAML — see JSON vs YAML.

2. Lists & maps

A list item starts with a dash and a space. A map is a block of key: value pairs. Nesting is shown purely through indentation — always spaces, never tabs.

# A map whose values are a list and a nested map
services:
  - web        # list item (string)
  - worker
database:      # nested map
  host: db.internal
  port: 5432
  replicas:
    - east
    - west

Both forms also have a flow (inline) style that looks like JSON — handy for short values:

ports: [80, 443]
labels: { app: api, tier: backend }

3. Multi-line strings

The literal block scalar | keeps every newline. The folded scalar > folds newlines into spaces. Add - (|- / >-) to strip the final newline.

startup_script: |
  #!/bin/sh
  echo "line 1"
  echo "line 2"     # newlines preserved exactly

description: >
  This long sentence will be
  folded into a single line
  with spaces between words.

4. Anchors, aliases & merge keys

Define a node once with an anchor &name, reuse it with an alias *name, and merge an anchored map into another with the merge key <<. Great for DRY configs; note that some strict parsers disable them.

defaults: &defaults
  restart: always
  logging: json

web:
  <<: *defaults     # merges restart + logging
  image: nginx

worker:
  <<: *defaults
  image: sidekiq

5. Common gotchas

• The Norway problem. In YAML 1.1, no, yes, on, off parse as booleans, so the country code NO becomes false. Quote them: "NO".
• Tabs break parsing. Indentation must be spaces. A stray tab throws a parse error.
• Numbers that should be strings. Version 1.10 becomes the float 1.1; ZIP code 01234 may lose its leading zero. Quote them.
• Colons inside values. A value like time: 12:30 needs quoting: "12:30".
• Ports in Docker Compose. Keep port mappings quoted ("8080:80") to avoid base-60 parsing.

6. Converters by use case

Already have JSON? Skip the hand-editing. These free, browser-based converters produce YAML shaped for each specific tool:

Frequently Asked Questions