In YAML, an empty list is a small detail with surprisingly big consequences. Whether you are writing a configuration file, defining CI/CD pipelines, describing Kubernetes resources, or storing application settings, the difference between “nothing has been specified” and “this is intentionally an empty list” can change how software behaves.
TLDR: A YAML empty list is usually written as [], which clearly means “this value is a list with no items.” You can also represent an empty block-style list by assigning a key but providing no list entries, though this can be less explicit and may be interpreted differently depending on the parser or application. For best results, use [] when you want to be clear, consistent, and friendly to both humans and machines.
What Is an Empty List in YAML?
YAML is a human-readable data serialization format commonly used for configuration files. A list, also called a sequence, stores multiple ordered values. For example:
fruits:
- apple
- banana
- orange
Here, fruits is a list containing three items. But sometimes you need a list that currently contains no items. That is where an empty list comes in.
The most common and recommended syntax is:
fruits: []
This tells the parser that fruits exists and its value is a list, but the list has zero elements.
Basic YAML Empty List Syntax
YAML supports two broad styles for collections: flow style and block style. Empty lists are most often written in flow style.
1. Flow Style Empty List
users: []
This is compact, readable, and widely understood. It is equivalent to an empty array in JSON:
{
"users": []
}
This format is ideal when you want to make the data type obvious. Anyone reading the file can immediately see that users is intended to be a list.
2. Empty List as a Standalone Value
You can also have an empty list as the entire YAML document:
[]This is valid YAML. It represents a document whose root value is an empty list. While not as common in configuration files, it can be useful in generated data, API responses, or test fixtures.
3. Empty List Inside a Nested Structure
Empty lists often appear inside maps, also known as dictionaries or objects:
project:
name: Website Redesign
contributors: []
milestones:
- planning
- launch
In this example, contributors is an empty list, while milestones contains two items. This structure is clear and predictable.
Empty List vs Null: Why the Difference Matters
One of the most common YAML mistakes is confusing an empty list with null. These values are not the same.
items: []
This means items is an empty list.
items:
This often means items is null, depending on the parser. In many YAML parsers, a key without a value is treated as a null value.
There is also an explicit null syntax:
items: null
or:
items: ~
The practical difference is important. An application expecting a list may safely loop over [], but it may crash or behave differently when it receives null. For example, a program may understand plugins: [] as “do not load any plugins,” while plugins: null might mean “use default plugins” or “value not provided.”
Block Style and Empty Lists
Normal YAML lists are often written in block style:
roles:
- admin
- editor
- viewer
But what does an empty block-style list look like? The answer is: there is no commonly preferred block notation that is as clear as []. You might see something like this:
roles:
However, as mentioned earlier, that usually indicates null, not an empty list. Because of this ambiguity, avoid using a blank value when you mean an empty list.
If you want roles to be an empty sequence, write:
roles: []
It is shorter and far less likely to be misunderstood.
Empty Lists in Common Real-World YAML Files
Empty lists appear frequently in configuration files. Here are a few practical examples.
Kubernetes Example
In Kubernetes manifests, many fields expect lists. An empty list can be used to intentionally disable or omit entries.
apiVersion: v1
kind: Pod
metadata:
name: example-pod
spec:
containers:
- name: app
image: nginx
env: []
Here, env: [] means the container has no environment variables defined.
CI/CD Pipeline Example
In a pipeline configuration, an empty list may mean no dependencies, no services, or no exclusions.
job:
script:
- npm test
dependencies: []
This explicitly says the job has no dependencies. That can be clearer than leaving the field out, especially in large configuration files where defaults may be complex.
Application Settings Example
settings:
enabled_features: []
blocked_users: []
allowed_origins:
- https://example.com
This configuration says that there are currently no enabled features and no blocked users, while one allowed origin is configured.
When Should You Use an Empty List?
An empty list is useful when the presence of the key matters. Use it when you want to communicate that the value is intentionally list-shaped, even though it currently has no entries.
- Use an empty list to override defaults: Some systems apply default list values when a key is missing. Setting
[]may tell the system to use no values instead. - Use it to document intent: A field like
reviewers: []tells readers that reviewers are supported but none are assigned yet. - Use it for schema consistency: If a field is always supposed to be a list, using
[]keeps the data structure predictable. - Use it in generated YAML: Tools that output YAML often include empty lists to preserve type information.
When Should You Omit the Key Instead?
Sometimes, leaving out the key is better than including an empty list. This depends on the application consuming the YAML.
For example:
notifications: []
may mean “notifications are configured but empty,” while omitting notifications entirely may mean “use the system default.”
Before choosing, ask: Does the application treat missing, null, and empty list differently? If the answer is yes, choose carefully. Configuration-heavy tools often assign different meanings to each.
Best Practices for YAML Empty Lists
To avoid confusion and create reliable YAML files, follow these practices:
- Prefer
[]for empty lists. It is the clearest and most portable syntax. - Do not rely on blank values. A key with no value usually means
null, not an empty list. - Be consistent across your file. If similar fields are lists, represent empty ones the same way.
- Check the schema or documentation. Some tools require a list, while others allow the field to be omitted.
- Use comments when intent is not obvious. For example:
plugins: [] # Intentionally disabled
A short comment can prevent future maintainers from wondering whether the list is empty by accident.
Common Mistakes to Avoid
The biggest mistake is assuming these three examples are equivalent:
items: []
items:
items: null
They are not equivalent. The first is an empty list. The second and third usually represent null. Another common mistake is using an empty string instead of an empty list:
items: ""
This creates a string, not a list. If your application expects a sequence, this can cause validation errors or unexpected behavior.
Also be careful with indentation. YAML is indentation-sensitive, and misplaced spaces can change the meaning of your file. For example:
items:
[]
This may not be interpreted the way you expect. The safer and more conventional form is:
items: []
Final Thoughts
YAML empty lists are simple, but they carry important meaning. Writing [] tells both humans and software that a value is deliberately a list with no items. This is different from null, different from an empty string, and often different from omitting the key altogether.
When in doubt, be explicit. Use [], keep your formatting consistent, and check how your YAML-consuming tool interprets empty, missing, and null values. A tiny pair of brackets can make your configuration cleaner, safer, and much easier to understand.
