YAML Syntax Tutorial: A Practical Introduction

YAML (YAML Ain't Markup Language) is a human-readable data serialization format used extensively in configuration files, CI/CD pipelines, and infrastructure-as-code. If you work with Docker Compose, Kubernetes, GitHub Actions, or Ansible, you're already using YAML daily. This tutorial covers everything you need to write YAML confidently.

Why YAML?

YAML's primary advantage is readability. Compare the same data in JSON and YAML:

JSON:

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "debug": true,
    "allowed_origins": ["http://localhost:3000", "https://example.com"]
  }
}

YAML:

server:
  host: localhost
  port: 8080
  debug: true
  allowed_origins:
    - http://localhost:3000
    - https://example.com

YAML achieves the same structure with less punctuation. No braces, no brackets for simple cases, no mandatory quoting. This makes configuration files easier to read and edit by hand.

Basic Data Types

Scalars

YAML automatically infers types from values:

string: hello world          # String (no quotes needed)
quoted: "hello world"        # Explicit string
integer: 42                  # Integer
float: 3.14                  # Float
boolean: true                # Boolean (true/false, yes/no, on/off)
null_value: null             # Null (also ~ or empty)
date: 2025-01-15             # Date (ISO 8601)

Common pitfall: Values like yes, no, on, off are interpreted as booleans. If you mean the string "yes", quote it: "yes".

Strings and Quoting

Strings rarely need quoting, but some cases require it:

plain: This is a plain string
single: 'Preserves \n as literal backslash-n'
double: "Interprets \n as newline"
colon: "value: with colon needs quotes"
hash: "value # with hash needs quotes"

Multiline Strings

YAML has two multiline styles:

Literal block (|) — preserves line breaks:

description: |
  This is line one.
  This is line two.
  
  This is line four (after blank line).

Folded block (>) — joins lines with spaces:

description: >
  This is a long paragraph
  that will be folded into
  a single line.

Add - to strip trailing newlines (|-, >-) or + to keep them (|+, >+).

Collections

Lists (Sequences)

# Block style
fruits:
  - apple
  - banana
  - cherry

# Flow style (inline)
fruits: [apple, banana, cherry]

Maps (Mappings)

# Block style
person:
  name: Alice
  age: 30
  city: London

# Flow style
person: {name: Alice, age: 30, city: London}

Nested Structures

departments:
  - name: Engineering
    lead: Alice
    members:
      - Bob
      - Charlie
  - name: Design
    lead: Diana
    members:
      - Eve

Anchors and Aliases

Anchors (&) and aliases (*) let you reuse values:

defaults: &defaults
  adapter: postgres
  host: localhost
  port: 5432

development:
  database: dev_db
  <<: *defaults

production:
  database: prod_db
  <<: *defaults
  host: db.example.com  # Override the default

The << merge key incorporates all properties from the anchor. Properties defined after the merge override the anchored values. Read more about advanced anchor patterns in our YAML anchors and aliases guide.

Multiple Documents

A single YAML file can contain multiple documents separated by ---:

---
# Document 1: Config
apiVersion: v1
kind: ConfigMap
---
# Document 2: Service
apiVersion: v1
kind: Service

This is commonly used in Kubernetes manifests.

Common Pitfalls

1. Indentation Errors

YAML uses spaces, never tabs. Inconsistent indentation is the most common error:

# WRONG - mixed indentation
server:
  host: localhost
    port: 8080  # Error: unexpected indentation

# CORRECT
server:
  host: localhost
  port: 8080

Use our YAML Formatter to automatically fix indentation issues.

2. The Norway Problem

Country codes like NO (Norway) are interpreted as boolean false:

# WRONG
countries:
  - NO  # Interpreted as false!
  - SE
  - DK

# CORRECT
countries:
  - "NO"
  - SE
  - DK

3. Unquoted Special Characters

Colons, hashes, and brackets in values need quoting:

# WRONG
message: Error: file not found
url: http://example.com  # Might break

# CORRECT
message: "Error: file not found"
url: "http://example.com"

4. Version Number Gotcha

Version numbers like 1.0 are parsed as floats:

# WRONG
version: 1.0  # Becomes 1 (float)

# CORRECT
version: "1.0"  # String

Validating YAML

Always validate your YAML before deploying. Syntax errors in YAML can cause cryptic failures in applications. Our YAML Validator checks syntax instantly, highlighting the exact line and column of any errors.

For a deeper dive into the differences between YAML and JSON, see our YAML vs JSON comparison.

FAQ

How many spaces should I use for YAML indentation?

Two spaces is the most common convention, used by Kubernetes, Docker Compose, GitHub Actions, and most DevOps tools. Some projects use four spaces. The key rule is consistency within a file — never mix indentation levels.

Can YAML include comments?

Yes, YAML supports single-line comments with #. There is no multi-line comment syntax. Comments are stripped during parsing and not available in the loaded data structure.

Related Resources

• YAML Formatter — Format and beautify YAML files
• YAML vs JSON — When to use which format
• YAML for Docker Compose — Docker-specific YAML patterns