What is YAML? The complete guide to YAML syntax and use cases

YAML — short for "YAML Ain't Markup Language" — is a human-readable data serialization format. Unlike markup languages designed to describe document structure, YAML is designed to represent data in a way that people can read and write directly. It is widely used for configuration files, CI/CD pipelines, container orchestration, and exchanging data between programming languages. This guide covers what YAML is, how its syntax works, where it is used, and the security pitfalls to watch out for.

What YAML is and why it exists

YAML was first published in 2001 and its current stable version is YAML 1.2.2 (October 2021). It was designed with five core goals in order of priority: readability by humans, compatibility with the data structures of dynamic programming languages, portability between programming languages, support for one-pass processing, and expressiveness. The result is a format that looks clean on screen and maps naturally to the objects, arrays, and primitives that programs work with — making it far more pleasant to write than JSON for hand-edited configuration.

YAML sits between JSON (machine-optimized) and natural language (human-optimized). Valid JSON is always valid YAML, but YAML adds features that JSON lacks: comments, multi-line strings, anchors and aliases for reusing values, and a more forgiving syntax that lets you omit quotes in many cases.

YAML syntax basics

Key-value pairs and scalars

The fundamental unit in YAML is a key-value pair. A key is a string, followed by a colon and a space, then a value:

app_name: my-service
version: "1.0"
port: 8080

Keys are case-sensitive. Values can be strings, numbers, booleans, or null.

Strings do not always need quotes. YAML treats an unquoted word as a string:

environment: production

Quotes are required when a string contains special characters that YAML might misinterpret, or when you want to preserve leading or trailing spaces:

message: "Hello, world!"
multiline: "First line\nSecond line"

Single quotes preserve the literal value inside them (no escape sequences); double quotes allow escape sequences.

Numbers, booleans, and null

timeout: 30          # integer
rate: 3.14            # float
debug: true           # boolean (also: on, yes)
verbose: false        # boolean (also: off, no)
record: null          # null (also: ~)

Lists (arrays)

Lists use a dash and a space at the start of each item:

servers:
  - web-1
  - web-2
  - web-3

Or use inline syntax (JSON-compatible):

ports: [80, 443, 8080]

Dictionaries (objects)

Nested dictionaries use indentation (two spaces is the convention — never tabs):

database:
  host: db.example.com
  port: 5432
  name: myapp
  ssl: true

Comments

YAML supports comments that start with a # and continue to the end of the line:

# Production configuration
environment: production
max_connections: 100  # raised from default of 10

Comments are stripped when YAML is parsed, so they never appear in the resulting data structure.

Multi-line strings

YAML has two ways to write a string that spans multiple lines:

Folded style (>) treats newlines as spaces, producing a single logical line:

description: >
  This is a long description that spans
  multiple lines. YAML will collapse these
  into a single line of text.

Literal style (|) preserves newlines exactly as written:

script: |
  #!/bin/bash
  echo "Starting service"
  ./start.sh

Both styles remove the trailing newline unless you explicitly add it back.

Anchors and aliases

YAML lets you define a value once with an anchor (&) and reuse it with an alias (*):

defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults
  timeout: 60

The << merge key copies all key-value pairs from the aliased node. This is useful for base configurations that are shared across environments.

Where YAML is used

YAML appears in dozens of common developer tools:

• Docker Compose — docker-compose.yml defines multi-container applications.
• GitHub Actions — workflow files in .github/workflows/ are YAML.
• Kubernetes — every resource manifest (Deployment, Service, ConfigMap, Ingress) is YAML.
• Ansible — playbooks and roles use YAML to describe desired state.
• CircleCI, GitLab CI, Travis CI — all use YAML for pipeline definitions.
• Prometheus — prometheus.yml configures scrape targets and rules.
• Terraform (state files and some configurations) — though Terraform also uses HCL, Terraform state files are JSON, and provider configurations can be YAML in some contexts.
• OpenAPI / Swagger — API specifications are written in YAML.
• RSS feeds and many config files — YAML is a common choice for human-edited structured data.

YAML vs JSON vs TOML

TOML (Tom's Obvious, Minimal Language) is popular for application-level config (Rust's Cargo.toml). JSON is the standard for data interchange. YAML wins for configuration that humans read and write frequently.

Common YAML pitfalls and security notes

Indentation matters

YAML uses indentation to define structure. Mixing tabs and spaces, or inconsistent indentation, is a common source of errors. Always use spaces (two is the community convention) and configure your editor to show whitespace.

Type coercion is implicit

YAML parsers may coerce unquoted values:

yes: no      # if parser treats 'yes' as boolean, this is contradictory

Unquoted yes, no, on, off, true, false, null are interpreted as their respective types. Quote values when they are meant to be literal strings.

Unsafe YAML loading

Python's yaml.load() with an unsafe loader, Ruby's YAML.load, and similar can execute arbitrary Python/Ruby code through YAML tags:

# Dangerous — never do this with untrusted input:
yaml.load(user_yaml, Loader=yaml.SafeLoader)

Always use a safe loader when parsing untrusted YAML. Many YAML libraries have a safe mode by default; only use the unsafe loader for trusted, locally-produced configuration.

Template injection in CI/CD

CI/CD systems (GitHub Actions, GitLab CI) run YAML workflows. If part of the YAML is constructed from user input, a template injection attack is possible. For example, a workflow that reads an issue title and inserts it into a YAML step without sanitization can break out of the string and inject additional YAML keys.

Confusion with JSON

Since valid JSON is valid YAML, a YAML parser will silently parse a .json file. This is useful but can also be surprising: a misnamed file with YAML syntax may be interpreted as JSON or vice versa, depending on the tool.

FAQ

What is YAML used for in devops?

In devops, YAML is the standard format for configuration and pipeline definitions. Docker Compose, Kubernetes manifests, GitHub Actions, GitLab CI, Ansible playbooks, and Helm charts all use YAML. Its human-readable format makes it ideal for version-controlled configuration that teams review in pull requests.

How do I validate a YAML file?

Use a YAML parser in your language of choice — yaml npm package, PyYAML for Python, js-yaml for JavaScript, or the yq command-line tool. Online validators like yamllint.com can also catch syntax errors. Always validate YAML before applying it to a production system, especially CI/CD pipelines and Kubernetes manifests.

What are YAML anchors and aliases?

Anchors (&name) let you define a value once. Aliases (*name) reuse that value elsewhere in the same document. The merge key (<<) spreads an alias's key-value pairs into a mapping. Anchors are useful for reducing repetition in configuration files that share defaults across environments.

Is YAML secure to parse?

YAML parsers can be unsafe if you load untrusted input with a full-featured loader that can instantiate arbitrary objects. Always use a safe loader (SafeLoader in PyYAML, SafeConstructor in Ruby) when processing YAML from user input or external sources. Safe parsing prevents deserialization attacks where a malicious YAML payload executes code through specially crafted tags.