YAML Arrays and Lists

A YAML array, formally called a sequence, is an ordered list of values. There are two ways to write one: block style, with a dash before each item, and flow style, with square brackets like JSON. This guide shows both, along with nesting, lists of objects, and the indentation mistakes that trip people up.

Block style (dash per item)

fruits:
  - apple
  - banana
  - cherry

Each item starts with - (dash, space). The items can be indented under the key or aligned with it; both are valid:

fruits:
- apple
- banana

Most style guides and formatters indent the items, which is what the YAML formatter produces.

Flow style (square brackets)

fruits: [apple, banana, cherry]
ports: [80, 443]
empty: []

Flow style is compact and is the only way to write an empty list. Items are separated by commas, and strings only need quotes if they contain commas, brackets, or other special characters.

Lists of different types

mixed:
  - text
  - 42
  - 3.14
  - true
  - null
  - [nested, list]
  - key: value

Nested arrays

matrix:
  - [1, 2, 3]
  - [4, 5, 6]

# Block style equivalent
matrix:
  -
    - 1
    - 2
    - 3
  - - 4
    - 5
    - 6

The - - 4 form starts an inner list on the same line as the outer item. It is valid but hard to read; flow style is clearer for nested lists of scalars.

Lists of dictionaries (objects)

This is the most common structure in real config files. The first key of each object goes right after the dash, and the remaining keys line up under it:

users:
  - name: Ada
    email: ada@example.com
    admin: true
  - name: Grace
    email: grace@example.com
    admin: false

In JSON this is {"users": [{"name": "Ada", ...}, {"name": "Grace", ...}]}. Kubernetes containers, Compose ports, and CI steps all use this shape:

containers:
  - name: web
    image: nginx:1.27
    ports:
      - containerPort: 80

Read more about mappings in the guide to YAML dictionaries.

Multiline strings inside lists

steps:
  - |
    echo "first"
    echo "second"
  - run: |
      npm ci
      npm test

See YAML multiline strings for the details of | and >.

Common mistakes

Missing space after the dash

fruits:
  -apple      # this is the string "-apple", not a list item

Misaligned keys in a list of objects

users:
  - name: Ada
  email: ada@example.com   # error: email is not part of the Ada object

The email key must be indented two more spaces to align with name.

Mixing block and flow style badly

ports: [80, 443
  - 8080]                  # error: cannot mix styles inside brackets

Tabs for indentation

YAML forbids tabs in indentation. Convert them to spaces.

Every one of these produces a clear error in the YAML validator, which highlights the offending line. To confirm the structure you built is what you intended, view it in the YAML parser or convert it with the YAML to JSON converter.