YAML Syntax Guide: A Complete Reference

Q: Is YAML case-sensitive?

Yes. YAML keys and values are case-sensitive. Name: Alice and name: Alice are different keys. This is a common source of bugs when working with Kubernetes or Docker Compose configurations.

Q: What is the maximum nesting depth in YAML?

The YAML specification doesn't define a maximum depth, but most parsers limit it to prevent stack overflow. Python's PyYAML defaults to 100 levels. In practice, keep nesting under 5-6 levels for readability.

Q: Can I use comments in YAML?

Yes. YAML supports single-line comments starting with #. Comments can appear on their own line or after a value. Block comments (multi-line) are not supported — each line needs its own #.

Q: What's the difference between | and > in YAML?

The pipe | preserves literal newlines (each line break is kept). The greater-than > folds newlines into spaces (paragraph style). Use | for code blocks and > for long descriptions.

Q: How do I represent a date in YAML?

YAML automatically recognizes ISO 8601 date formats: 2024-01-15 or 2024-01-15T10:30:00Z. To keep a date-like value as a string, wrap it in quotes: version: "2024-01".

YAML (YAML Ain't Markup Language) is the most popular configuration language in the DevOps world. From Kubernetes manifests to CI/CD pipelines, understanding YAML syntax is essential for every modern developer.

What Makes YAML Different?

Unlike JSON or XML, YAML uses indentation (spaces, never tabs) to represent structure. This makes it incredibly readable for humans but also means a single misplaced space can break your entire file. That's why our YAML formatter is so valuable — it catches these issues instantly.

YAML Basic Building Blocks

Scalars (Simple Values)

Scalars are the simplest YAML values: strings, numbers, booleans, and null.

# Strings (quotes are optional unless containing special characters)
name: John Doe
description: "Value with: special chars"
multiline: |
  This text spans
  multiple lines
  with preserved newlines.
folded: >
  This text will be
  folded into a single
  line with spaces.

# Numbers
age: 30
price: 19.99
scientific: 1.2e3

# Booleans (YAML 1.2: only true/false)
enabled: true
debug: false

# Null
middle_name: null

Mappings (Key-Value Pairs)

Mappings are the core of YAML — they map keys to values using colons.

person:
  name: Alice
  age: 28
  address:
    street: 123 Main St
    city: San Francisco
    zip: 94105

Sequences (Lists/Arrays)

Sequences are ordered lists, denoted by dashes.

# Simple list
fruits:
  - apple
  - banana
  - orange

# List of objects
users:
  - name: Alice
    role: admin
  - name: Bob
    role: developer

# Inline list syntax
tags: [yaml, devops, kubernetes]

Advanced YAML Features

Anchors and Aliases

Anchors (&) let you mark a node for reuse. Aliases (*) reference that node. This is perfect for DRY configuration.

defaults: &defaults
  timeout: 30
  retries: 3

service-a:
  <<: *defaults
  name: service-a

service-b:
  <<: *defaults
  name: service-b
  timeout: 60  # Override

Multi-Document Files

YAML files can contain multiple documents separated by ---. This is common in Kubernetes manifests and Ansible playbooks.

---
apiVersion: v1
kind: Service
metadata:
  name: my-service
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment

Data Types and Tags

YAML supports explicit type tags using !! notation, though they're rarely needed in practice.

explicit-string: !!str 2024
explicit-int: !!int "42"
explicit-float: !!float "3.14"
binary: !!binary R0lGODdh...

Common YAML Pitfalls

Tabs vs Spaces: YAML never allows tabs for indentation. Use spaces only.
Inconsistent Indentation: Pick a consistent indent level (2 or 4 spaces) and stick with it.
Colon Spacing: Always add a space after the colon: key: value not key:value.
Boolean Ambiguity: YAML 1.1 accepts yes/no/on/off as booleans. YAML 1.2 only accepts true/false. Always use true/false to avoid surprises.
Multiple Documents: Remember that --- starts a new document and ... ends one.

YAML in Practice

YAML is the backbone of modern infrastructure configuration:

Kubernetes: Every resource (Deployment, Service, ConfigMap) is defined in YAML.
Docker Compose: docker-compose.yml defines multi-container applications.
Ansible: Playbooks and inventory files use YAML.
GitHub Actions: Workflow definitions in .github/workflows/*.yml.
OpenAPI/Swagger: API specifications in YAML format.
Helm Charts: Kubernetes package manager uses YAML templates.

YAML vs JSON: When to Use Which

YAML and JSON are closely related — YAML is actually a superset of JSON, meaning every valid JSON file is also valid YAML. However, they serve different purposes in practice.

Choose YAML when: you need human-readable configuration files, comments for documentation, or anchors/aliases for DRY configs. YAML is the standard for Kubernetes, Docker Compose, CI/CD pipelines, and Ansible.

Choose JSON when: you're building APIs, exchanging data between systems, or working with JavaScript applications. JSON is faster to parse programmatically and has unambiguous type handling.

For a deeper comparison including TOML, check out our YAML vs JSON vs TOML guide.

YAML 1.2 vs 1.1: Key Differences

Most tools now follow YAML 1.2 (released 2009), but some older parsers still use YAML 1.1. The differences matter when you encounter unexpected type coercion:

Booleans: YAML 1.1 accepts yes/no/on/off/true/false. YAML 1.2 only accepts true/false. Always use true/false for compatibility.
Octal numbers: YAML 1.1 uses 0777 prefix. YAML 1.2 uses 0o777 prefix.
String "NO"/"Yes": In YAML 1.1, these are parsed as booleans. In YAML 1.2, they remain strings.
Null values: Both versions accept null and ~. YAML 1.1 also treats empty values as null.

When in doubt, quote ambiguous values: answer: "yes" ensures it's always treated as a string regardless of parser version.

YAML Best Practices

Always use spaces for indentation. Configure your editor to insert spaces (2 or 4 per level). Never mix tabs and spaces.
Quote strings that could be misinterpreted. Values like "true", "1.0", "NO", or version numbers like "1.20" should be quoted to prevent type coercion.
Use comments liberally. YAML supports # comments. Use them to explain non-obvious configuration choices.
Keep nesting shallow. Deeply nested YAML is hard to read and error-prone. Flatten structures where possible using dot notation or separate files.
Use anchors for repeated blocks. Instead of copying configuration, use &anchor and *alias with merge keys <<:.
Validate before committing. Use our YAML validator to catch syntax errors before pushing configuration to production.
Use descriptive key names. Prefer database_connection_timeout over db_to. Clarity beats brevity in configuration.

History and Evolution of YAML

YAML was created by Clark Evans in 2001, with the first release (YAML 1.0) published in 2004. The name was originally "Yet Another Markup Language" but was later changed to "YAML Ain't Markup Language" to emphasize its data-oriented nature. The language was designed to address perceived shortcomings in XML and other configuration formats of the time.

YAML 1.1 arrived in 2005 and became the version implemented by most early parsers, including Python's PyYAML. YAML 1.2, released in 2009, was a significant cleanup that removed ambiguous type coercion rules (like the Norway Problem with yes/no being parsed as booleans). Most modern tools now support YAML 1.2, though some legacy systems still use 1.1 behavior.

The adoption of YAML accelerated dramatically with the rise of DevOps and cloud-native computing. Docker chose YAML for Compose files, Kubernetes adopted it for all resource manifests, and CI/CD platforms like GitHub Actions and GitLab CI made YAML the standard for pipeline definitions. Today, YAML is arguably the most widely used configuration language in software infrastructure.

YAML Tools and Libraries

Every major programming language has YAML support. Here are the most widely used libraries:

Python: PyYAML (YAML 1.1) and ruamel.yaml (YAML 1.2). PyYAML is the most common; ruamel.yaml preserves comments and formatting.
JavaScript/TypeScript: js-yaml is the standard parser. yaml (by Eemeli Aro) is a modern alternative with YAML 1.2 support and round-trip preservation.
Go: gopkg.in/yaml.v3 is the official Go YAML package, used throughout the Kubernetes ecosystem.
Rust: serde_yaml integrates with the serde serialization framework.
Java: SnakeYAML is the most common; Jackson YAML provides an alternative.
Ruby: Psych is built into the standard library.

For command-line work, yq (by Mike Farah) is an essential tool — it's like jq but for YAML files. You can query, filter, and transform YAML directly from the terminal. Combined with our online YAML formatter, you have options for both local and browser-based YAML processing.

YAML Security Considerations

YAML deserialization can be a security risk if you parse untrusted input. Many YAML libraries support arbitrary object construction through tags like !!python/object or !!java.lang.Runtime. An attacker could craft a YAML file that executes arbitrary code when parsed.

To stay safe:

Never parse untrusted YAML with unsafe loaders. In Python, use yaml.safe_load() instead of yaml.load(). In Ruby, use YAML.safe_load.
Validate YAML before processing. Use our YAML validator to check syntax before feeding files into production systems.
Pin parser versions. Different YAML library versions may interpret ambiguous values differently. Lock your dependency versions.
Be cautious with !! tags. If your use case doesn't require explicit type tags, configure your parser to reject them.

The YAML 1.2 specification was designed with security in mind — it removed many of the implicit type resolutions that made YAML 1.1 vulnerable to unexpected behavior. If you're choosing a YAML library, prefer one that defaults to YAML 1.2 semantics.

Frequently Asked Questions

Is YAML case-sensitive?

Yes. YAML keys and values are case-sensitive. Name: Alice and name: Alice are different keys. This is a common source of bugs when working with Kubernetes or Docker Compose configurations.

What is the maximum nesting depth in YAML?

The YAML specification doesn't define a maximum depth, but most parsers limit it to prevent stack overflow. Python's PyYAML defaults to 100 levels. In practice, keep nesting under 5-6 levels for readability.

Can I use comments in YAML?

Yes. YAML supports single-line comments starting with #. Comments can appear on their own line or after a value. Block comments (multi-line) are not supported — each line needs its own #.

What's the difference between | and > in YAML?

The pipe | preserves literal newlines (each line break is kept). The greater-than > folds newlines into spaces (paragraph style). Use | for code blocks and > for long descriptions.

How do I represent a date in YAML?

YAML automatically recognizes ISO 8601 date formats: 2024-01-15 or 2024-01-15T10:30:00Z. To keep a date-like value as a string, wrap it in quotes: version: "2024-01".

Quick Format Any YAML

Writing YAML by hand? Paste it into our free YAML formatter for instant validation, formatting, and JSON conversion — all processed locally in your browser with zero server upload. You can also explore common YAML errors to avoid costly mistakes in your configurations.