YAML Syntax Guide

What is YAML?

YAML is a data format that is made to be easy to read and write by hand. It is used for configuration files in tools such as Kubernetes, Docker Compose, GitHub Actions, Ansible and OpenAPI. It holds the same kinds of data as JSON, which are objects, arrays, text, numbers, booleans and null, but it uses indentation and plain words and not braces and quotes. Most JSON files are also valid YAML.

Indentation

Indentation shows the structure. Use spaces, never tabs, and use the same number of spaces for the same level. Two spaces is the usual choice.

server:
  host: localhost
  port: 8080

Mappings (key and value)

A mapping is a set of keys with values, written as key, a colon, a space and the value. The space after the colon is required.

name: Ada
age: 36
address:
  city: London
  country: UK

Sequences (lists)

Each item of a list starts with a dash and a space.

langs:
  - JavaScript
  - Python
users:
  - name: Ada
    role: admin
  - name: Bob
    role: editor

Scalars: text, numbers, booleans and null

Quotes

Text does not need quotes, but quotes are needed when the text would be misread. Double quotes allow escape sequences such as \n, single quotes do not, and a single quote inside single quotes is written twice.

plain: hello
single: 'it''s fine'
double: "line one\nline two"
time: "12:30"       # quoted, because of the colon
version: "1.10"     # quoted, so that it stays 1.10

Multi-line text

literal: |
  Line one
  Line two
folded: >
  These lines are
  joined into one line.
stripped: |-
  No newline at the end

The pipe sign keeps the line breaks. The greater-than sign folds the lines into one line. A minus after it removes the final line break, and a plus keeps all the trailing line breaks.

Comments

A comment starts with a hash sign. If it is after a value, it needs a space before the hash. YAML has no multi-line comments, so put a hash at the start of each line.

# The port to listen on
port: 8080   # default

Flow style

Short collections can be written in one line, as in JSON.

point: {x: 1, y: 2}
colors: [red, green, blue]

Anchors, aliases and merge keys

An anchor, written &name, marks a value, and an alias, written *name, reuses it. A merge key, written <<, copies a mapping into another one, which is a common way to share settings.

defaults: &defaults
  restart: always
  logging: json

web:
  <<: *defaults
  image: nginx

worker:
  <<: *defaults
  image: app

Several documents in one file

Three dashes start a new document. Kubernetes files use this to hold several objects in one file.

kind: Service
---
kind: Deployment

The common mistakes

• Tabs. Not allowed in indentation.
• Inconsistent indentation. Keys of the same level must line up exactly.
• No space after the colon. key:value is one piece of text, not a mapping.
• A colon inside a value. Quote it: message: "Error: not found".
• Duplicate keys. Most tools keep only the last one.
• Unquoted special words. In older parsers yes, no, on and off are booleans, and the country code NO becomes false.
• Numbers that are not numbers. A version 1.10 is read as 1.1, and 0755 may be read as a different number. Quote them.
• A value that starts with a special character. A text starting with *, &, !, %, @, a backtick, a brace or a bracket must be quoted.

YAML versions

The current version is YAML 1.2, from 2009. Many tools still use parsers that follow YAML 1.1, which has more kinds of booleans and reads leading zeros as octal numbers. If your file must work everywhere, quote the values that could be read two ways.

Tools

Check a file with the YAML validator, tidy it with the YAML formatter, expand compact YAML with the beautifier, and convert with YAML to JSON and JSON to YAML.