YAML & Config

YAML Lists and Arrays: Syntax and Examples

YAML calls ordered collections sequences. Block-style lists use a dash for each item; flow-style lists use square brackets.

Published Aug 24, 2026

Create a block-style YAML list

features:
  - search
  - export

Lists of strings, numbers and booleans

The parser assigns scalar types according to its YAML rules, so quote values when a string must remain unambiguous.

values:
  - ready
  - 3
  - true

Lists of objects

services:
  - name: api
    port: 8080
  - name: worker
    port: 9090

Nested lists

Each nested sequence is indented beneath its parent item.

matrix:
  - - linux
    - node20
  - - windows
    - node20

Flow-style arrays with [ ]

Flow style is compact for short values but becomes difficult to scan when items are long or deeply nested.

targets: [linux, windows, macos]

Lists inside mappings and mappings inside lists

A mapping key can own a sequence, and each sequence item can itself be a mapping. Indentation, not visual alignment alone, establishes those relationships.

Common indentation mistakes

Misaligning a dash with its sibling items.
Failing to indent child keys beneath a list item.
Accidentally turning a child key into a sibling mapping.

Try YAML list formatting

Use the parser-backed formatter to distinguish valid structure from indentation errors.

Try the example

Format a list of mappings

Each service is one block-sequence item with nested keys.

services:
  - name: api
    port: 8080
  - name: worker
    port: 9090

Expected result: Valid YAML with two service objects.

Try the example

Inspect nested flow sequences

A block sequence contains two short flow-style arrays.

matrix:
  - [linux, node20]
  - [windows, node20]

Expected result: Valid YAML with a two-row matrix.

Try a real sequence

Format your YAML list

Validate block and flow sequences with the local YAML formatter.

Open in YAML Formatter →