YAML for Developers: Syntax, Indentation and Common Pitfalls

Published · Updated

YAML is the configuration language of Kubernetes, Docker Compose, GitHub Actions and many other tools. It is pleasant to read, but its reliance on indentation and its automatic typing cause errors that are hard to spot by eye. This guide covers the syntax you need and the pitfalls to watch for.

Mappings, lists and indentation

A mapping is a set of key: value pairs. A list (sequence) is a set of items that start with - . Nesting is shown by indentation, using spaces only.

app: shop
replicas: 2
ports:
  - 80
  - 443
database:
  host: db.internal
  port: 5432

Any consistent number of spaces works, but two per level is the common convention. Items in the same mapping or list must line up exactly.

Scalars and automatic typing

Unquoted values are typed automatically. The tools on this site use js-yaml 4, which follows the YAML 1.2 core schema:

Unquoted valueParsed as (YAML 1.2)
42integer
3.14float
true / falseboolean
null or ~null
yes / no / on / offstring in YAML 1.2 (boolean in older YAML 1.1 parsers)
2024-01-05timestamp (js-yaml also reads unquoted dates; written as an ISO date-time in JSON)
"42"string, because it is quoted

Different tools use different YAML versions, so a value like no (the country code for Norway, for instance) can be a string in one tool and false in another. Quote any value that must stay text. Version numbers are a classic trap: version: 1.10 becomes the float 1.1.

Multi-line strings

literal: |
  Line one
  Line two
folded: >
  These lines are
  joined with spaces.

| keeps line breaks exactly. > folds lines into one, turning single line breaks into spaces. Add - (as in |-) to remove the final line break.

Anchors, aliases and merge keys

Anchors (&name) label a node and aliases (*name) reuse it. The merge key << copies a mapping into another, which many tools support for shared defaults:

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

When YAML is converted to JSON, anchors and aliases are expanded into full copies, since JSON has no references.

Comments

Comments start with # and run to the end of the line. They are not part of the parsed data, so any tool that parses and rewrites YAML, including the YAML Formatter, drops them.

Common pitfalls and their errors

MistakeTypical js-yaml messageFix
Tab used for indentationtab characters must not be used in indentationReplace tabs with spaces
Item indented one space too far or too littlebad indentation of a mapping entryLine items up exactly
Same key twiceduplicated mapping keyRemove or rename one
Colon followed by a space inside a valueincomplete explicit mapping pair or a nested mapping errorQuote the value: "time: 10:30"
Value starts with a special character such as * or &unidentified alias or unexpected anchorQuote the value

The YAML Validator reports these with a line and column, and YAML to JSON shows exactly how each value was typed.

YAML and JSON

YAML 1.2 is designed as a superset of JSON, so most JSON documents are also valid YAML. Converting is common: use YAML to JSON when a tool needs JSON, and JSON to YAML to make JSON easier to edit by hand.

Frequently asked questions

Why does YAML not allow tabs?

The specification forbids tabs for indentation to avoid ambiguity, since a tab can display as different widths in different editors.

Is YAML a superset of JSON?

YAML 1.2 was designed to be, so most JSON parses as YAML. There are rare edge cases, but in practice JSON is valid YAML.

How do I keep a value like 1.10 as text?

Quote it: version: "1.10".

Related guides