YAML Syntax Cheat Sheet

YAML is an indentation-based data format that expresses the same structures as JSON. Spaces mark nesting (never tabs), # starts a comment, and every JSON document is also valid YAML. Check any file with the YAML Validator, and convert with the YAML to JSON Converter or JSON to YAML Converter. The results below were produced by running the snippets through a YAML 1.1 parser.

Scalars

Strings need quotes only when they would otherwise be read as another type or contain special characters such as : or #.

Lists and mappings

Lists use - per item (block style) or [a, b] (flow style). Mappings use key: value or {k: v}. Indent with spaces; keep the width consistent.

fruits:
  - apple
  - banana
  - cherry
short: [1, 2, 3]
server:
  host: localhost
  port: 8080
  tags: {env: dev, debug: true}

Parsed: {"fruits": ["apple", "banana", "cherry"], "short": [1, 2, 3]} and {"server": {"host": "localhost", "port": 8080, "tags": {"env": "dev", "debug": true}}}.

Multi-line strings

| keeps line breaks as written; > folds line breaks into spaces. The trailing newline is kept by default.

literal: |
  line one
  line two
folded: >
  line one
  line two

Parsed: {"literal": "line one\nline two\n", "folded": "line one line two\n"}.

Anchors, aliases and merge

&name defines an anchor, *name reuses it and <<: *name merges a mapping into another. The merge key is supported by many but not all parsers.

base: &base
  retries: 3
  timeout: 30
prod:
  <<: *base
  timeout: 60

Parsed: {"base": {"retries": 3, "timeout": 30}, "prod": {"retries": 3, "timeout": 60}}.

Multiple documents and comments

Separate documents in one file with ---; end with ... if needed. Comments start with # and run to the end of the line.

---
name: one
---
name: two

Gotchas

Different YAML versions read some plain values differently. YAML 1.1 treats yes, no, on and off as booleans and a leading zero as octal; YAML 1.2 does not. Quote any value that must stay a string.