YAML Dictionaries and Maps

Dictionaries are the backbone of every YAML file. A dictionary (the YAML spec calls it a mapping) is a collection of key: value pairs. Nesting them by indentation is how you build the tree structure of a Kubernetes manifest, a CI pipeline, or an application config. This guide covers the syntax, nesting, lists of dictionaries, flow style, and the errors to avoid.

Basic key-value pairs

name: yamlchecker
version: "2.1.0"
debug: false
port: 8080

A colon followed by a space separates key from value. The space is required: name:yamlchecker is a single string, not a pair. Values are typed by inference, so false is a boolean and 8080 is a number, while "2.1.0" stays a string because of the quotes.

Nested dictionaries

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

Indentation defines the hierarchy. Two spaces per level is the convention; four is fine as long as every sibling key uses the same amount. In JSON this is {"server": {"host": "0.0.0.0", "port": 8080, "tls": {...}}}.

Flow style

server: { host: 0.0.0.0, port: 8080 }
empty: {}

Braces let you write a small dictionary on one line, and are the only way to write an empty one. Flow style is useful for short inline values but the YAML formatter expands it to block style for readability.

Lists of dictionaries

databases:
  - name: primary
    host: db1.internal
    port: 5432
  - name: replica
    host: db2.internal
    port: 5432

The first key follows the dash, and the rest align under it. This pattern appears everywhere: Kubernetes containers, Compose services (as a dictionary of dictionaries), and CI steps. See YAML arrays for more.

Dictionary of dictionaries

When each item has a natural unique name, a dictionary keyed by that name is often clearer than a list:

services:
  web:
    image: nginx:1.27
    ports: ["80:80"]
  db:
    image: postgres:16

Docker Compose uses this shape. Lookups by name are simple, but order is not guaranteed to matter to the consumer.

Keys: what is allowed

• Keys are usually plain strings: name, max_retries, nginx.conf.
• Keys may contain spaces: first name: Ada.
• Quote keys that start with special characters or that YAML would type-convert: "on": push (GitHub Actions), "1.0": stable.
• Non-string keys (numbers, booleans) are legal in YAML but are converted to strings by JSON and by many languages, so avoid them.
• Complex keys using ? syntax exist but are almost never used in practice.

Null and empty values

a:          # null
b: null     # null
c: ~        # null
d: ""       # empty string
e: {}       # empty dictionary

Merging dictionaries

To share a base dictionary across several others, use an anchor with the merge key:

base: &base
  retries: 3
  timeout: 30

fast:
  <<: *base
  timeout: 5

Details and caveats are in the guide to YAML anchors and aliases.

Common mistakes

Inconsistent indentation

server:
  host: 0.0.0.0
   port: 8080     # error: indented one space more than host

Missing space after the colon

host:0.0.0.0     # the whole line is one string

Duplicate keys

port: 8080
port: 9090       # error in strict parsers

Unquoted values with colons

url: http://example.com    # fine: no space after the colon in the value
time: 12: 30               # error: ": " inside the value starts a new pair

Tabs

Indent with spaces only.

All of these are reported with the line number by the YAML validator. To inspect the exact structure and types your dictionary produced, use the YAML parser.