YAML Empty List Syntax Explained With Examples

YAML is popular because it makes structured data feel almost like plain writing. But that friendly appearance can be deceptive: tiny differences in indentation, brackets, or null values can change the meaning of a configuration file. One of the most common small details developers run into is how to represent an empty list correctly.

TLDR: In YAML, the standard and clearest way to write an empty list is []. You can use it for keys that should contain a list but currently have no items, such as users: []. Avoid leaving the value blank unless you actually mean null, because an empty value is not the same as an empty list. Empty lists are especially common in configuration files, API responses, CI pipelines, and Kubernetes manifests.

What Is an Empty List in YAML?

A list in YAML is an ordered collection of items. Lists are also called sequences in YAML terminology. A normal YAML list might look like this:

fruits:
  - apple
  - banana
  - orange

Here, fruits contains three values. But sometimes a field is expected to contain a list even when there are no values to include yet. That is where an empty list comes in.

The most common syntax is:

fruits: []

This means: “The key fruits exists, and its value is a list, but the list currently contains zero items.”

The Recommended Empty List Syntax

The simplest, most widely recognized way to define an empty list in YAML is with square brackets:

items: []

This is called flow style syntax. YAML supports two common styles for lists:

• Block style: Uses hyphens and line breaks.
• Flow style: Uses square brackets, similar to JSON arrays.

For example, these two lists are equivalent:

# Block style
items:
  - one
  - two

# Flow style
items: [one, two]

When the list has no items, flow style becomes especially convenient:

items: []

Trying to write an empty block-style list usually leads to confusion because block lists rely on list items marked with hyphens. If there are no items, there are no hyphens to write. That is why [] is the cleanest and least ambiguous choice.

Empty List vs Null Value

One of the biggest mistakes in YAML is assuming that a blank value means the same thing as an empty list. It does not.

items:

In many YAML parsers, this means that items has a value of null. In other words, the value is missing or undefined. That is different from saying the value is a list with no elements.

Compare these examples:

items: []     # Empty list
items: null   # Null value
items:        # Usually also null

This distinction matters because applications often validate data types. If a program expects items to be a list, then [] is valid, while null may trigger an error.

For example, a configuration system might accept this:

plugins: []

But reject this:

plugins:

The first says “there are no plugins.” The second says “the plugins value is not defined.” That difference may look small, but in automated systems it can be significant.

Empty List as a Nested Value

Empty lists often appear inside larger YAML structures. You might see them nested under mappings, inside arrays of objects, or in deeply layered configuration files.

project:
  name: website redesign
  contributors: []
  tags: []

In this example, the project has no contributors and no tags yet. Those fields are still present, and their expected type is clear.

You can also use empty lists inside a list of maps:

teams:
  - name: engineering
    members:
      - Alice
      - Ravi
  - name: marketing
    members: []

The marketing team exists, but its members list is empty. This is much clearer than omitting the members key entirely, especially if the consuming application expects every team object to contain the same fields.

Empty Lists in Real Configuration Files

Empty lists are not just a theoretical YAML feature. They appear in many real-world systems, including deployment tools, automation pipelines, application settings, and API schemas.

For example, in a CI configuration file, you may want to define a job that currently has no dependencies:

build:
  stage: build
  dependencies: []
  script:
    - npm install
    - npm run build

Here, dependencies: [] explicitly communicates that the job has no dependency list. This can be better than leaving the key out, because it documents the intention.

In Kubernetes-style configuration, empty lists may appear in fields for arguments, volumes, environment variables, or initialization containers:

container:
  name: app
  image: example/app:latest
  env: []
  args: []

This tells the system that env and args are both lists, but neither contains entries.

JSON Compatibility

One helpful way to understand YAML empty lists is through JSON. YAML is designed to be a superset of JSON, which means JSON syntax is generally valid YAML. In JSON, an empty array is written as:

[]

So this YAML:

users: []

is conceptually the same as this JSON:

{
  "users": []
}

This compatibility is one reason the square-bracket syntax feels natural to developers who already work with JavaScript, APIs, or JSON files.

Common Mistakes to Avoid

Although the syntax is simple, empty lists can still create problems when used carelessly. Watch out for these common mistakes:

• Using a blank value instead of []: A blank value usually means null, not an empty list.
• Mixing indentation styles: YAML is indentation-sensitive, so misplaced spaces can alter the structure.
• Adding a hyphen with no value: A line like - may create a null item, not an empty list.
• Omitting a required key: If a schema requires a list field, leaving it out may fail validation.

For instance, this does not define an empty list:

items:
  -

Instead, it often means items is a list containing one null value. That is very different from a list containing no values at all.

When Should You Use an Empty List?

Use an empty list when the field is supposed to be a list, but there are currently no entries. This is useful when you want to preserve a predictable structure or satisfy a schema.

Good use cases include:

• Defining users, roles, permissions, or groups before values are added.
• Setting optional configuration sections to an empty state.
• Returning API data where a collection has no results.
• Creating templates that other people will later fill in.
• Making data types explicit for validators and parsers.

For example:

response:
  status: success
  results: []

This is better than omitting results if clients always expect that field to be present.

Best Practices for YAML Empty Lists

To keep your YAML clear and reliable, follow a few practical rules:

• Prefer [] for empty lists. It is concise, readable, and widely supported.
• Do not use blank values unless you intentionally want null.
• Be consistent across your files and team conventions.
• Validate your YAML when working with strict schemas or deployment systems.
• Use comments sparingly if an empty list might look surprising.

allowed_hosts: [] # No hosts are currently allowed

A short comment like this can remove ambiguity, especially in shared configuration files.

Final Thoughts

YAML empty list syntax is simple: write []. The important part is understanding what it means and how it differs from null, missing keys, or lists containing empty values. In configuration files, that clarity can prevent validation errors, deployment issues, and confusing application behavior.

Whenever a field should be a list but has no items yet, use []. It is small, explicit, and one of the easiest ways to make your YAML more predictable.