YAML Arrays, Lists, and Dictionaries: Complete Guide (2026)

Q: How do you write a list in YAML?

Block style uses a dash and space at the start of each item, with consistent indentation: `- apple` on one line, `- banana` on the next. Flow style puts items in square brackets on a single line: `[apple, banana, cherry]`. Both produce the same parsed array.

Q: What is the difference between a YAML list and a YAML array?

Nothing. YAML uses the term 'sequence' in the spec, but 'list' and 'array' are interchangeable in everyday usage. They map to a Python list, a JavaScript array, or a Go slice depending on the parser language.

Q: How do I create a YAML dictionary?

A YAML dictionary (also called a mapping) is a set of key-value pairs at the same indent level. Block style uses 'key: value' on each line; flow style uses curly braces and commas: `{a: 1, b: 2}`. Both forms are interchangeable.

Q: Can I have a list of dictionaries in YAML?

Yes - this is the most common YAML shape, used in Kubernetes manifests, GitHub Actions steps, and Compose services. Each list item begins with a dash, then key-value pairs indented two spaces under it.

Q: How do I write a nested array in YAML?

Indent the inner list two spaces under its parent dash. Or use flow style for the inner list: `- [1, 2, 3]`. Mixing block and flow is allowed but block style is more readable for deep nesting.

Q: Does YAML support variables?

Not natively. The closest equivalents are anchors (&name) and aliases (*name), which let you reuse a value defined earlier. The merge key (<<: *anchor) splices a map's contents into another map, which is the canonical 'shared defaults' pattern.

Q: How do I represent an empty list or map in YAML?

Use empty flow syntax: `[]` for an empty list, `{}` for an empty map. Plain `key:` with no value parses as null, not as an empty container.

Q: Can YAML lists contain mixed types?

Yes. A list can hold strings, numbers, booleans, maps, or other lists in any combination. Most consuming code expects homogeneous lists, so keep types consistent unless you have a reason not to.

Q: How does YAML decide if `- 5` is a string or a number?

By scalar style and content. Unquoted values are parsed by type detection rules - `5` becomes an integer, `5.0` a float, `true/false` a boolean, and unrecognized tokens become strings. Quote a value with single or double quotes to force it to be a string: `- '5'`.

Q: Can I have duplicate keys in a YAML map?

The YAML 1.2 spec says no, but many parsers silently accept duplicates and keep the last value. Don't rely on this - validate your YAML to catch unintended duplicates before they cause confusing bugs.

Block-style list

The most common form. Each list item starts on its own line with - (dash + space) and consistent indentation:

block.yaml

# Block style - one item per line, dash + space prefix
fruits:
  - apple
  - banana
  - cherry

Flow-style list (array)

The same data on a single line:

flow.yaml

# Flow style - same data, single line, comma-separated
fruits: [apple, banana, cherry]

Flow style is compact and JSON-compatible. Use it for short, simple lists. Switch to block style as soon as the list grows or contains nested structures.

Nested arrays (lists of lists)

nested.yaml

# Lists of lists - indent nested levels two spaces
matrix:
  - [1, 2, 3]
  - [4, 5, 6]
  - [7, 8, 9]

# Or block style for the inner lists too
groups:
  - - admin
    - editor
  - - viewer
    - guest

List of maps (most common shape)

Kubernetes containers, GitHub Actions steps, and Compose services all use this pattern. Each list item is a map:

list-of-maps.yaml

# Each item is itself a map - the most common shape
servers:
  - host: api.example.com
    port: 443
    primary: true
  - host: api-backup.example.com
    port: 443
    primary: false

YAML dictionaries (mappings)

dictionary.yaml

# YAML calls maps "mappings". They are Python dicts / JS objects.
database:
  host: db.example.com
  port: 5432
  credentials:
    username: app_user
    password: ${DB_PASSWORD}

# Flow form (single line)
limits: { cpu: 500m, memory: 256Mi }

YAML "variables" pattern

YAML has no native variable syntax. The idiomatic substitute is an anchor (&name) plus alias (*name) plus merge key (<<:) for shared defaults across maps:

variables.yaml

# YAML has no native "variables" - use anchors and aliases instead
defaults: &defaults
  timeout: 30
  retries: 3
  log_level: info

production:
  <<: *defaults
  host: prod.example.com

staging:
  <<: *defaults
  host: staging.example.com
  log_level: debug   # Override one field

Some tools (Ansible, GitHub Actions) also support template-style variables like {{ var }} on top of YAML, but those are tool features, not YAML features. See our anchors and aliases guide for the full pattern.

Empty lists, empty maps, and null

empty.yaml

# Empty list
tags: []

# Empty map
metadata: {}

# Null value (three valid forms)
description: null
description: ~
description:

An empty list is []; an empty map is {}. A bare key: with no value is null, not an empty list or map. This trips up many beginners.

When to use block vs flow

Block: default for any list or map larger than a few items, or whenever you want comments alongside data.
Flow: short, scalar-only lists and maps where a single line is more readable. Common for tags, port lists, and inline limits.
Mix freely: YAML allows block and flow to be nested either way. Stay consistent within a file for readability.

YAML syntax reference — full grammar with all node types.
YAML anchors, aliases, and merge keys — the variables idiom in depth.
YAML multiline strings — block scalars for long values inside list items.
YAML validator — instant syntax check for your sequences and mappings.

Frequently Asked Questions

How do you write a list in YAML?