YAML Basics

Last updated: January 09, 2026

The YAML format is used to define configuration data. Instead of relying on complex syntax, YAML expresses structure through indentation and layout.

YAML File Structure and Indentation Rules

Scalars

The simplest YAML structure is a key-value pair whose value is a scalar (i.e., an indivisible value). Scalar values must appear on the same line as their corresponding keys. A single space must follow the colon, before the value.

server_name: "demo"
replica_count: 3
health_check_enabled: true

environment: production
max_connections: 100

Mappings

Values may be in the form of mappings (one or more key-value pairs). Indentation shows that nested key-value pairs belong to the parent key. Nested key-value pairs at the same level must use the same indentation.

application:
  name: "demo"
  enabled: true

database:
  host: db.example.com
  port: 5432

Sequences and Nested Structures

A sequence is a single value composed of an ordered collection of items, which may be a scalar, a mapping, or another sequence. This type of value can be written in two styles:

• Block Style: Each sequence item (- ) appears on a new line starting with a hyphen and a space. All content indented more than the hyphen's indentation level belongs to that sequence item. Indentation of sibling sequence items must be consistent.

server:
  name: demo
  ports:
    - 80
    - 443

users:
  - name: Achilles
    role: Warrior
  - name: Odysseus
    role: Strategist

regions:
  - - us-east-1a
    - us-east-1b
    - us-east-1c
  - - eu-west-1a
    - eu-west-1b

• Flow Style: Sequences are enclosed in square brackets and separated by commas ([value1, value2]). When a sequence item is a mapping, its key-value pairs are enclosed in curly braces and separated by commas ({ key1: value1, key2: value2 }).

server: { name: demo, ports: [80, 443] }

users: [{ name: Achilles, role: Warrior }, { name: Odysseus, role: Strategist }]

regions: [[us-east-1a, us-east-1b, us-east-1c], [eu-west-1a, eu-west-1b]]

Comments

Comments, ignored by YAML parsers, provides configuration intent and context. Comments begin with # and may appear on their own line or after a value.

# Integration rate-limiting rules
integrations:
  rate_limit_per_minute: 120  # Throttles outbound API calls

# Evidence retention policy
evidence:
  retention_days: 90  # Automatically purges evidence after retention period

Start and End Markers

YAML documents may include explicit start (---) and end (...) markers. Each document in a multi-document YAML file is treated as an independent YAML file, even though they share the same physical file.

---
task: backup
target: database
schedule: daily
...

---
task: cleanup
target: logs
schedule: weekly
...

---
task: upgrade
target: api
scheduled_at: 2027-01-01T09:00:00  # in UTC
...

---
environment: staging
servers:
  - host: api.staging.demo.com
    port: 443
  - host: worker.staging.demo.com
    port: 8080
...

---
environment: production
servers:
  - host: api.prod.demo.com
    port: 443
  - host: worker.prod.demo.com
    port: 8080
...

---
environment: maintenance
servers:
  - host: legacy.prod.demo.com
    port: 80
...

A document ends implicitly when a new --- marker appears or when the file ends. Therefore, ... markers may be omitted.

Anchors and Aliases

Anchors and aliases, together, reduce duplication by allowing reuse of configuration values. An anchor (&) defines a reusable value, and an alias (*) inserts the entire anchored value, regardless of whether it is a scalar, mapping, or sequence.

default_port: &port 443

service_a:
  port: *port

service_b:
  port: *port

common_settings: &settings
  timeout: 30
  retries: 3

api_service:
  settings: *settings

worker_service:
  settings: *settings

default_ports: &ports
  - 80
  - 443

frontend:
  ports: *ports

backend:
  ports: *ports

FAQs

name: demo

application:
  name: demo
  enabled: true