Last updated: April 28, 2026
YAML Syntax Reference & Cheat Sheet
The complete YAML 1.2 syntax in one page. Scalars, sequences, mappings, indentation, comments, anchors, multiline strings, and a full cheat-sheet example you can paste into any project.
Written by Mohan Raj Kolavi.
Quick answer
YAML uses indentation with spaces (never tabs) to express structure. Map entries are key: value pairs. List items start with -. Strings, numbers, booleans and nulls work as expected. Comments start with #. Multiline strings use | (literal) or > (folded). Reuse blocks with anchors (&) and aliases (*). Multiple documents in one file are separated by ---.
Scalars
A scalar is a single value: a string, number, boolean, or null. YAML auto-detects the type from the form of the value, with quoted strings always typed as string:
# Scalars: strings, numbers, booleans, nulls title: Quick start # plain string (no quotes) quoted: "Hello, world" # double-quoted - allows escapes literal: 'C:\Users\me' # single-quoted - all literal count: 42 # integer ratio: 3.14 # float hex: 0xFF # hexadecimal integer exp: 6.022e23 # scientific notation enabled: true # boolean (also: yes, on) disabled: false # boolean (also: no, off) empty: null # null (also: ~ or unset) date: 2026-04-28 # ISO date timestamp: 2026-04-28T10:30:00Z
- Plain (unquoted) strings are easiest, but YAML auto-detects type. Anything that looks like a number or boolean will be parsed as such.
- Double-quoted strings support C-style escape sequences (
\n,\t,\\). Use them when you need embedded newlines or Unicode escapes. - Single-quoted strings treat all content as literal. The only escape is two single quotes for one single quote. Use them for Windows paths and regex.
Sequences (lists / arrays)
YAML supports two list styles. Block style is one item per line with a leading hyphen; flow style uses square brackets inline:
# Sequences (lists/arrays)
fruits: # block style
- apple
- banana
- cherry
ports: [80, 443, 8080] # flow style (inline)
nested:
- name: Web
port: 80
- name: API
port: 8080
See YAML arrays and lists for nested lists, lists of maps, and dictionary patterns.
Mappings (maps / dictionaries)
A mapping is a set of key-value pairs. Like sequences, mappings come in block and flow styles:
# Mappings (maps/dicts/objects)
server: # block style
host: localhost
port: 8080
inline: { host: localhost, port: 8080 } # flow style
Indentation rules
Indentation is the only way YAML expresses nesting. Three rules cover almost every case:
- Spaces only. Tabs are rejected by every YAML 1.2 parser.
- Be consistent. Pick 2 spaces (most common) or 4 and stick to it within a file.
- Indent strictly more than the parent. A child must indent past its parent's first character, not just its key.
# Indentation defines structure
parent:
child:
grandchild: value # 2 spaces per level (most common)
sibling: value
another_child: value
parent2: value
Comments
Comments begin with # and run to the end of the line. There is no block-comment syntax - prefix every line you want to disable:
# Comments start with # and run to end of line service: api # comments can also be inline # version: 1.0 # entire line commented out
The full reference, including how comments interact with block scalars, is on the YAML comments page.
Multiline / block scalars
For long strings, use a block scalar. The literal style (|) keeps newlines as written. The folded style (>) folds newlines into spaces:
# Block scalars for multiline strings literal: | Line 1 Line 2 Line 3 folded: > These three lines fold into a single paragraph with spaces. stripped: |- # |- removes trailing newlines No trailing newline here.
Full reference, including chomping indicators (-, +) and the indent indicator, on the multiline strings page.
Anchors and aliases
Reuse data across a file with an anchor (&name) and an alias (*name). The merge key (<<:) merges an aliased mapping into the current mapping; sibling keys override merged values:
# Anchors and aliases for reuse defaults: &defaults retries: 3 timeout: 30 development: <<: *defaults # merge keys database: app_dev production: <<: *defaults database: app_prod timeout: 60 # local key overrides merged value
Deep dive on the YAML anchors page, including the deep-merge gotcha.
Multiple documents
A single .yaml file can hold many documents, separated by a line containing only ---. Each is parsed independently:
# Multiple documents in one file (separated by ---) apiVersion: v1 kind: Namespace metadata: name: production --- apiVersion: v1 kind: ConfigMap metadata: name: app-config data: LOG_LEVEL: info
Full cheat sheet
One file covering every syntax feature on this page. Paste it into the YAML validator to see the parser's view, or convert it with the YAML to JSON tool to see the resolved structure:
# YAML Cheat Sheet - one file covering everything
# Strings
plain_string: hello
double_quoted: "with \n escapes"
single_quoted: 'literal \n'
# Numbers and booleans
count: 100
price: 19.99
enabled: true
ratio: ~ # null
# Lists
tags: # block list
- alpha
- beta
inline_tags: [alpha, beta] # flow list
# Maps
address: # block map
street: "123 Main"
city: Springfield
inline: { x: 1, y: 2 } # flow map
# Multiline strings
description: |
Line 1
Line 2
summary: >
Folded lines
become spaces.
# Comments
# This entire line is a comment.
api: v1 # inline comment
# Anchors
defaults: &defaults
retries: 3
production:
<<: *defaults
region: us-east-1
Validate your YAML
The fastest way to confirm syntax is correct: drop the file into the YAML validator. For comparison with JSON, see YAML vs JSON. For language-specific quirks, the YAML in Python page covers PyYAML and ruamel.yaml.
Frequently Asked Questions
What is the basic syntax of YAML?
YAML uses indentation (spaces, never tabs) to express structure. Maps are 'key: value' pairs, lists use a leading hyphen and space ('- item'), and nested structures indent two spaces deeper than their parent. Comments start with #. The current spec is YAML 1.2.
How do you write a list in YAML?
Two styles. Block style uses a hyphen and a space at the start of each line: '- apple', '- banana'. Flow style uses square brackets inline: '[apple, banana]'. Both produce the same array at parse time. Use block style for readable, multi-line lists.
How do you write a key-value pair in YAML?
Write the key, a colon, a space, then the value: 'name: alice'. The space after the colon is required by the spec. For nested values, indent the child two spaces under the key. For values with special characters, wrap them in single or double quotes.
Can you use tabs in YAML?
No. The YAML 1.2 specification forbids tabs for indentation. Always use spaces. Most parsers reject any file containing a tab in indentation with a clear error. Configure your editor to convert tabs to spaces inside .yaml files.
What characters need to be quoted in YAML?
Quote a string when it contains special characters (#, &, *, !, |, >, %, @, `, comma, colon followed by space), starts with a YAML-reserved character (-, ?, :), or could be misread as a different type (numbers like '10', booleans like 'yes', or 'null'). When in doubt, quote it.
How do you write a multiline string in YAML?
Use a block scalar. The literal style (pipe, |) preserves newlines exactly. The folded style (greater-than, >) folds newlines into spaces, producing a single paragraph at parse time. Both keep the body indented two spaces under the key.
What is the difference between flow style and block style YAML?
Block style uses indentation and one item per line - easy for humans to read and version-control. Flow style uses brackets and braces inline, like JSON - compact but harder to diff. Most config files use block style; flow is useful for short inline lists or when embedding YAML in another format.
How do you add comments to YAML?
Start a comment with # and write text until the end of the line. Comments can take an entire line or appear after a value (with at least one space before the #). YAML does not have block-comment syntax - to comment out multiple lines, prefix each line with #.
What is the file extension for YAML?
Both .yaml and .yml are valid. The official recommendation since YAML 1.2 is .yaml, but .yml is widespread on Windows-derived tooling. They are byte-for-byte identical in content; only the extension differs. See our YAML vs YML page for the full tool support matrix.
How do you separate multiple documents in a single YAML file?
Use a line containing only three hyphens (---) between documents. Each section is parsed as an independent document, so you can ship a Namespace, Deployment, Service, and ConfigMap together in a single file and apply them in order.
How do I check if my YAML syntax is valid?
Drop the file into an online YAML validator like ours - it parses with a YAML 1.2-compliant library and reports errors with line and column numbers. Locally, use 'yamllint file.yaml' or load the file in Python with yaml.safe_load to confirm it parses.
What is YAML 1.1 vs YAML 1.2?
YAML 1.2 (the current spec, since 2009) is the alignment with JSON - YAML 1.2 is a strict superset of JSON. YAML 1.1 is the earlier spec; its main practical difference is the 'Norway problem' where 'NO' parses as a boolean. Modern parsers default to 1.2; quote any string that could be misread.