YAML List Syntax: Block, Flow and Lists of Objects

November 11, 2026 · 10 min read

YAML List Syntax: Block Lists, Flow Arrays and Lists of Objects

A YAML list is an ordered set of values, written either as one - item per line or as comma-separated items inside square brackets. Both styles parse to the same array. Below, each form sits next to the JSON it produces, followed by the same patterns in GitHub Actions, Docker Compose and Kubernetes files.

YAML List Basics: Block Sequences With a Dash

The YAML spec calls a list a sequence, and most programming languages load it as an array. In block style, each item gets its own line and starts with a dash plus a space. Items keep their order, and a whole file can be nothing but a list.

- apple
- banana
- cherry

That file loads as this JSON array:

["apple", "banana", "cherry"]

The space after the dash isn't optional. The YAML 1.2.2 spec requires white space between the - indicator and the value, which is why -42 reads as a negative number instead of an entry. Items can be strings, numbers, booleans, null, objects or other lists, and one list can mix them. Long text fits too: put a | or > block scalar right after the dash.

A YAML list looks like a Markdown bullet list, but it's data for a program, not formatting for a reader. For rendered bullets in a document, see our guide to Markdown lists.

Flow Style YAML Arrays in Square Brackets

Flow style writes a YAML array the way JSON does: square brackets with commas between items. Plain words don't need quotes.

fruits: [apple, banana, cherry]
ports: [80, 443]
{ "fruits": ["apple", "banana", "cherry"], "ports": [80, 443] }

A flow sequence can span several lines while the brackets stay open. The spec also allows a trailing comma, and its own Example 7.13 uses [ one, two, ]. Some characters carry meaning inside brackets. Quote any item that contains a comma, a bracket or brace, a colon followed by a space, or a # with a space before it.

We prefer block style for anything longer than three items or any item with structure. Flow style earns its place for short scalar lists such as tags, branch names and version numbers. Markdown front matter is the classic case:

tags: [yaml, config, devops]

Static site generators add their own rules on top, which the array section of our front matter guide covers. Obsidian adds rules for tags and links, covered in our Obsidian front matter guide.

Indenting a YAML List Under a Key

When a list belongs to a key, write the key and a colon on one line and the items below it. You can indent the dashes, or keep them at the same column as the key. Both are valid:

fruits:
  - apple
  - banana
vegetables:
- carrot
- leek
{ "fruits": ["apple", "banana"], "vegetables": ["carrot", "leek"] }

The spec permits the second form because people read the dash itself as indentation. Kubernetes examples usually keep dashes level with the key, while GitHub's workflow examples indent them. Either works, so pick one per file and stick with it.

Indent with spaces only. The spec forbids tab characters in indentation, and PyYAML rejects them with a "cannot start any token" error. If you're arriving from Markdown, where indentation controls list nesting and code blocks, our Markdown indentation guide explains how those rules work.

How Do You Write a YAML List of Objects?

A list of objects is the shape you'll meet most in config files. Python calls it a list of dictionaries and JSON calls it an array of objects, but it's the same structure. Start each object with a dash, then line up its other keys with the first key, not with the dash.

services:
  - name: web
    image: nginx
    port: 80
  - name: db
    image: postgres
    port: 5432
{
  "services": [
    { "name": "web", "image": "nginx", "port": 80 },
    { "name": "db", "image": "postgres", "port": 5432 }
  ]
}

The same YAML array of objects fits on one line in flow style: [{name: web, port: 80}, {name: db, port: 5432}]. It's legal, but it gets hard to read past two keys per object.

In Python, yaml.safe_load turns that file into a list of dictionaries you can index like any other:

import yaml

with open("services.yaml") as f:
    data = yaml.safe_load(f)

print(data["services"][0]["name"])  # web

Indentation decides which object each key belongs to, so small slips change the data. An extra dash splits one object into two: - name: web followed by - port: 80 loads as two separate objects, each with a single key. Move a key back to the dash's column and it falls out of the list entirely, which usually ends in a parse error. Our YAML format cheat sheet covers the indentation rules for the rest of a file.

Nested Lists: Lists of Lists and Lists Inside Objects

A list item can itself be a list. In block style, you can put a second dash right after the first, which the spec calls compact notation:

- - a
  - b
- - c

That loads as [["a", "b"], ["c"]]. For grids and matrices, flow lists inside a block list read more clearly:

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

Lists also sit inside objects that are list items themselves. Here each user carries a roles list, once in flow style and once in block style:

users:
  - name: ana
    roles: [admin, editor]
  - name: raj
    roles:
      - viewer
{
  "users": [
    { "name": "ana", "roles": ["admin", "editor"] },
    { "name": "raj", "roles": ["viewer"] }
  ]
}

YAML Lists in Real Config Files: GitHub Actions, Docker Compose and Kubernetes

Most lists in YAML that you'll write by hand live in CI workflows and deployment manifests. Each tool expects a list in specific fields, and its reference docs name them.

GitHub Actions

In a workflow, on.push.branches takes a list of branch names or patterns, each strategy.matrix variable takes a list of values, and steps is a list of objects. The workflow syntax reference documents all three.

on:
  push:
    branches: [main, 'releases/**']
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.12', '3.13']
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-python@v7
        with:
          python-version: ${{ matrix.python-version }}
      - run: pytest

Every step opens with a dash, and with belongs to the second step because it lines up with uses. The versions are quoted for a reason: an unquoted 3.10 in that list would load as the number 3.1.

Docker Compose

In Compose, ports is a list of strings. The Compose services reference says to quote HOST:CONTAINER pairs to avoid YAML's base-60 number parsing. We checked with PyYAML 6.0.3, and an unquoted 22:22 came back as the integer 1342.

services:
  web:
    image: nginx
    ports:
      - "8080:80"
      - "2222:22"
    environment:
      - APP_ENV=production
      - DEBUG=false

The environment field accepts either a map or a list of KEY=value strings, so the list above could also be written as APP_ENV: production lines. In map form, quote DEBUG: "false", because the Compose docs ask for boolean values in quotes.

Kubernetes

A pod's spec.containers field is a list of objects, and each container's ports is a nested list of objects. The Kubernetes docs write both with dashes level with their keys:

spec:
  containers:
  - name: nginx
    image: nginx:1.14.2
    ports:
    - containerPort: 80

That loads as one container object whose ports value is [{"containerPort": 80}].

How Do You Write an Empty List in YAML?

Write []. Block style has no way to express a sequence with zero items, so the flow form is the only option.

plugins: []
excludes:
aliases: ~
{ "plugins": [], "excludes": null, "aliases": null }

A key with nothing after it is null, not an empty list, and ~ is null too. The difference matters when code loops over the value. Python happily iterates over an empty list, but iterating over None raises a TypeError. If the tool treats a missing key as an empty list, leaving the key out is tidier; otherwise, write [] explicitly.

Five Mistakes That Break a YAML List

Dropping the space after the dash. On its own, -item loads as the string -item, not as a list entry. After other entries in a list, PyYAML stops with a "could not find expected ':'" error instead.

Indenting with tabs. Editors that insert tab characters produce files the parser rejects. Set your editor to insert spaces for .yaml and .yml files.

Mixing entries and keys at one level. A key can hold a list or a map, never both:

fruits:
  - apple
  colour: red

PyYAML reports expected <block end> here. Move colour up a level, or make it part of an item.

Unquoted items that change type. - 3.10 loads as 3.1 under any YAML version. YAML 1.1 parsers such as PyYAML, which calls itself a complete 1.1 parser, also read - no and - off as false and - 0755 as the octal number 493. Quote items that must stay text: - "3.10", - "no".

A colon and space inside an item. - note: check logs becomes an object with a note key. Write - "note: check logs" to keep the whole thing as one string.

There's one thing no style guide fixes: a file alone doesn't tell you whether the tool reading it applies YAML 1.1 or 1.2 typing. That depends on its parser, so quoting ambiguous values is the safe default. Our YAML to JSON guide shows how different parsers type the same values.

A YAML list comes down to a few rules: a dash and a space per item, brackets for short lists, aligned keys for objects, and [] when empty. Quote anything that could pass for a number or boolean. For front matter, the front matter generator builds YAML, TOML or JSON blocks in your browser. Write the README that explains your config in the editor, free and with no account needed.