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.
Examples - Scalars
EXAMPLE 1
YAML
server_name: "demo"
replica_count: 3
health_check_enabled: true
EXAMPLE 2
YAML
environment: production
max_connections: 100
An unquoted value that does not match another scalar type (i.e., production) is treated as string.
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.
Examples - Mappings
EXAMPLE 1
YAML
application:
name: "demo"
enabled: true
Explanation: The key application is a top-level entry. The keys name and enabled are both indented by two spaces, indicating that they belong to application.
EXAMPLE 2
YAML
database:
host: db.example.com
port: 5432
An unquoted value that does not match another scalar type (i.e., db.example.com) is treated as a string.
COMMON ERROR
Indentation errors are the most common cause of YAML failures.
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:
Example - Block Style *
EXAMPLE 1
YAML
server:
name: demo
ports:
- 80
- 443
The sequence is the value of ports. The items 80 and 443 are items of that sequence.
EXAMPLE 2
YAML
users:
- name: Achilles
role: Warrior
- name: Odysseus
role: Strategist
The value of users is a sequence. The sequence contains two items. Each item's value is a mapping.
EXAMPLE 3
YAML
regions:
- - us-east-1a
- us-east-1b
- us-east-1c
- - eu-west-1a
- eu-west-1b
Flat and nested sequences represent different structures, from which application behavior emerges.
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 }).
Example - Flow Style *
EXAMPLE 1
YAML
server: { name: demo, ports: [80, 443] }
EXAMPLE 2
YAML
users: [{ name: Achilles, role: Warrior }, { name: Odysseus, role: Strategist }]
EXAMPLE 3
YAML
regions: [[us-east-1a, us-east-1b, us-east-1c], [eu-west-1a, eu-west-1b]]
Comments, ignored by YAML parsers, provides configuration intent and context. Comments begin with # and may appear on their own line or after a value.
Examples - Comments
EXAMPLE 1
YAML
# Integration rate-limiting rules
integrations:
rate_limit_per_minute: 120 # Throttles outbound API calls
EXAMPLE 2
YAML
# 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.
Examples - Start and End Markers
EXAMPLE 1
YAML
---
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
...
EXAMPLE 2
YAML
---
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.
Examples - Anchors and Aliases
EXAMPLE 1
YAML
default_port: &port 443
service_a:
port: *port
service_b:
port: *port
Explanation: The anchor &port is attached to the scalar value 443, and the alias *port reuses that same scalar value.
EXAMPLE 2
YAML
common_settings: &settings
timeout: 30
retries: 3
api_service:
settings: *settings
worker_service:
settings: *settings
Explanation: The anchor &settings is attached to a mapping composed of the key-value pairs timeout: 30 and retries: 3, and the alias *settings reuses that entire mapping.
EXAMPLE 3
YAML
default_ports: &ports
- 80
- 443
frontend:
ports: *ports
backend:
ports: *ports
Explanation: The anchor &ports is attached to a sequence composed of the items 80 and 443, and the alias *ports reuses that entire sequence.
FAQs
What are key-value pairs?
A YAML file is made of pairs. Each pair has a key and a value, with the value belonging to the key that precedes it. The key tells the system what the value represents, and the value provides the actual data associated with that key.
A key appears before the colon. The value appears after the colon.
EXAMPLE
Explanation: In this line, name is the key, and demo is the value.
Keys can group other key-value pairs, with the nested pairs collectively forming the value of the parent key.
EXAMPLE
YAML
application:
name: demo
enabled: true
Explanation: application is the parent key. The value of application is not a single scalar, but rather a group of nested key-value pairs.
What are scalars?
A scalar refers to a single, indivisible value. YAML supports the following scalar types:
String ("demoSvr")
Integer (443)
Float (1.5)
Boolean (true, false)
Null (null)
Quoted values are always treated as strings. Unquoted values that do not match another type are treated as strings.
