Introduction to YAML

YAML is a human-friendly data serialization language. It is mostly used for configuration files, but it can represent the same basic structures as JSON: mappings, sequences, and scalar values.

This page is a condensed and refreshed version of my older Introduction to YAML guide. It targets YAML 1.2 and the current 1.2.2 specification revision.

The essentials

A YAML file is plain Unicode text. Use UTF-8. Use spaces for indentation, never tabs. The amount of indentation is flexible, but every item at the same level must align.

Comments start with # unless the character is inside a quoted string.

# This line is ignored
debug: false # This part is ignored too
name: '#not-a-comment'

YAML is sensitive to whitespace. Two spaces per level is a common convention because it stays readable without making deeply nested files too wide.

Mappings

Mappings associate keys with values. They are comparable to objects in JSON, dictionaries in Python, or associative arrays in PHP.

project: arthak.fr
public: true
port: 8080

Nested mappings are created with indentation:

server:
  host: 127.0.0.1
  port: 8080
  tls:
    enabled: false

A compact flow style also exists:

server: { host: 127.0.0.1, port: 8080 }

Use the block style for most configuration. Flow style is useful for short values that naturally belong on one line.

Sequences

Sequences are ordered lists. Each item starts with a dash followed by a space.

languages:
  - French
  - English
  - YAML

A sequence can contain mappings:

services:
  - name: website
    port: 8080
  - name: api
    port: 3000

It can also use the compact flow syntax:

languages: [French, English, YAML]

Scalars and quoting

A scalar is a single value: a string, number, boolean, null, date-like value, or another value recognized by the parser.

name: Arthak
age: 37
enabled: true
empty: null

Quote strings when their intended type could be ambiguous or when they contain syntax-significant characters.

version: '1.0'
answer: 'true'
channel: '#general'
time: '12:30'

Single quotes preserve most characters literally. To include a single quote, double it:

message: 'It''s valid YAML'

Double quotes support escape sequences such as \n, \t, and Unicode escapes.

message: "First line\nSecond line"

YAML 1.1 versus 1.2

Older YAML 1.1 parsers may interpret values such as yes, no, on, and off as booleans. YAML 1.2 limits booleans in its core schema to true and false.

For portable configuration, use true and false, and quote words that must remain strings.

legacy_answer: 'yes'
modern_answer: true

Multiline strings

Use | when line breaks are meaningful:

description: |
  First line.
  Second line.

Use > when wrapped lines should become a single paragraph:

description: >
  This text is written across several lines
  but is normally loaded as one paragraph.

Chomping indicators control trailing line breaks:

keep_all: |+
  Text

strip_all: |-
  Text

+ keeps trailing newlines. - removes them. Without an indicator, YAML keeps one final newline.

Multiple documents

A YAML stream can contain several documents. Three dashes start a new document. Three dots can explicitly end one.

---
name: first
---
name: second
...

Many tools expect exactly one document per file, so only use streams when the consuming application documents support for them.

Anchors, aliases, and merge keys

Anchors mark reusable nodes with &. Aliases reference them with *.

defaults: &defaults
  retries: 3
  timeout: 10

production:
  settings: *defaults

The merge key syntax is widely implemented and commonly used to extend mappings:

defaults: &defaults
  retries: 3
  timeout: 10

production:
  <<: *defaults
  timeout: 30

Anchors and aliases are part of YAML. The << merge key comes from a YAML 1.1 language-independent type and is not defined by the YAML 1.2 core specification. Parser support varies. Prefer explicit configuration when interoperability matters.

Tags and explicit types

Tags identify the type of a node. Standard tags begin with !!.

integer: 123
string: !!str 123
float: !!float 123

Applications can define custom tags:

release: !version 2.4.0

Custom tags are application-specific. A generic YAML parser may preserve or reject them without knowing how to construct the target object.

Variables do not exist in YAML

YAML has no native variable or interpolation system.

This syntax is only meaningful if the application loading the file implements it:

home: ${HOME}

Environment variables, templates, includes, and expressions belong to tools built around YAML, not to YAML itself. Docker Compose, GitHub Actions, Ansible, Helm, and other systems each add their own semantics.

Do not assume a feature supported by one YAML-based tool exists in another.

Common mistakes

Tabs

Tabs are not valid indentation. Configure the editor to insert spaces.

Missing space after a colon

# Wrong or interpreted unexpectedly
port:8080

# Correct
port: 8080

Accidental comments

# The value becomes "dark"
theme: dark # experimental

# The hash is part of the value
channel: '#design'

Duplicate keys

port: 8080
port: 3000

Mapping keys must be unique. Some parsers reject duplicates; others silently keep one value. Treat duplicates as errors.

Trusting implicit types

Quote identifiers, versions, dates, and values with leading zeroes when they must remain strings.

postal_code: '01230'
release: '2026-07-17'
version: '1.20'

Parsing untrusted YAML unsafely

Some libraries can construct application objects from tags. When loading untrusted content, use the parser's safe-loading mode and disable arbitrary object construction.

Validate against the real consumer

A file can be valid YAML and still be invalid for the application using it.

Validation has three layers:

1. Syntax: can a YAML parser read it?
2. Schema: does it contain the expected keys and value types?
3. Application: does the target tool accept the available options and semantics?

Use the same parser and version in development, tests, and production. Add schema validation when configuration becomes important enough to break deployments.

YAML or something else?

Use YAML when humans regularly edit structured configuration and comments are useful.

Use JSON when strict interoperability, a smaller syntax, or direct browser tooling matters most.

Use TOML for relatively shallow configuration where explicit types and predictable parsing are priorities.

Use a programming language when the configuration needs complex conditions, loops, imports, or reusable logic. Recreating a language inside YAML usually makes the system harder to understand.

Practical checklist

• Save as UTF-8.
• Indent with spaces only.
• Keep indentation consistent.
• Prefer block mappings and sequences.
• Quote ambiguous strings.
• Use true, false, and null for portable core values.
• Avoid duplicate keys.
• Do not expect variables or templates from YAML itself.
• Check anchor, merge-key, and tag support in the target parser.
• Validate syntax, schema, and application behavior.
• Use safe loading for untrusted input.

Sources and further reading

• YAML 1.2.2 specification
• YAML resources index
• YAML Test Suite
• Original Introduction to YAML repository
• YAML organization on GitHub