YAML Empty List Syntax Explained With Examples

YAML is a tiny language for writing data in a way humans can read. It shows up in config files, app settings, CI pipelines, Kubernetes files, and many other places. One small but mighty thing in YAML is the empty list. It says, “This is a list, but it has nothing inside yet.”

TLDR: In YAML, an empty list is written as []. For example, pets: [] means the key pets exists, and its value is a list with zero items. Do not write only pets: if you mean an empty list, because that usually means null. Use [] when you want to be clear.

What Is a YAML List?

A YAML list is a group of items. Think of it like a shopping basket. It can hold apples, bananas, and cookies. Or it can hold absolutely nothing, which is sad, but valid.

A normal YAML list often uses dashes:

fruits:
  - apple
  - banana
  - mango

Here, fruits is a list with three items. Each item starts with a dash. YAML likes clean spacing, so the items are indented under the key.

Lists can also be written in a shorter style:

fruits: [apple, banana, mango]

This is called flow style. It looks a lot like JSON. Same meaning. Different outfit.

So, What Is an Empty List?

An empty list is a list with no items. Zero. Nada. The list exists, but it is empty.

In YAML, the clearest empty list syntax is:

items: []

This means:

• items is a key.
• The value of items is a list.
• The list has no items in it.

It is like saying, “I have a backpack, but the backpack is empty.” The backpack still exists. It is not missing. It is not unknown. It is just empty.

The Most Common Empty List Syntax

Use square brackets with nothing inside:

users: []

This is the most common and safest way to write an empty list in YAML.

Here are more examples:

tags: []
plugins: []
allowed_ips: []
favorite_movies: []

Each value is an empty list. Your program can read these keys and know they are ready for list items later.

This is useful in config files. You may not want plugins yet. But you still want to say, “Plugins belong here.”

Empty List vs Missing Value

This part is very important. Put on your tiny YAML helmet.

These two examples are not always the same:

pets: []

and:

pets:

The first one means pets is an empty list.

The second one usually means pets is null. In simple words, it means “no value.” Not an empty list. Just nothing.

That difference matters.

• pets: [] means “there are pets, but the list is empty.”
• pets: means “pets has no value.”

Some tools may treat these differently. A program might expect a list. If it gets null, it may grumble. It may crash. It may make a tiny angry robot noise.

Why Use an Empty List?

You use an empty list when a setting should be a list, but you do not have items yet.

For example:

project:
  name: Space Sandwich
  contributors: []

This says the project has a name. It also has a contributors list. But nobody has joined yet. Poor Space Sandwich.

Later, you can add people:

project:
  name: Space Sandwich
  contributors:
    - Nina
    - Omar
    - Kai

The structure stays the same. Only the list content changes.

Empty Lists Inside Objects

YAML often stores objects. An object is a group of keys and values. In YAML, it is usually called a mapping.

Here is an object with empty lists:

server:
  name: test-server
  ports: []
  allowed_users: []
  blocked_ips: []

This is easy to read. The server has no ports listed. No allowed users. No blocked IPs. It is a very relaxed server. Maybe too relaxed.

Empty Lists Inside Lists

You can also place empty lists inside other lists. Yes, lists can contain lists. YAML is flexible like a yoga cat.

groups:
  - []
  - [admin, editor]
  - []

This means groups is a list with three items:

1. An empty list.
2. A list with two items.
3. Another empty list.

This is less common in normal config files. But it is valid YAML.

Empty List in a Kubernetes File

YAML is very popular in Kubernetes. Empty lists appear there often.

apiVersion: v1
kind: Pod
metadata:
  name: tiny-pod
spec:
  containers: []

This says containers is an empty list. In real Kubernetes, a Pod needs containers to run. So this example might not be useful in production. But it shows the syntax clearly.

A more practical example could be:

metadata:
  name: my-service
  labels: {}
  annotations: []

Careful here. {} is an empty object, not an empty list. [] is an empty list. They look like tiny twins, but they are different creatures.

Empty List vs Empty Object

This is another common mix-up.

• [] means an empty list.
• {} means an empty object.

Look at this:

shopping_cart: []
customer_info: {}

The shopping cart is a list. It can later contain products.

The customer info is an object. It can later contain fields like name, email, or address.

shopping_cart:
  - bread
  - milk

customer_info:
  name: Ana
  email: ana@example.com

Use [] when order and multiple items matter. Use {} when you need named fields.

Can You Write an Empty Block List?

A block list normally uses dashes:

colors:
  - red
  - blue

But if there are no items, there are no dashes to write. So this does not really work as an empty block list:

colors:

That means null in many YAML parsers. It does not clearly mean an empty list.

So use this instead:

colors: []

It is short. It is clear. It makes parsers happy. Happy parsers make happy developers.

Common Mistakes

Here are some classic YAML banana peels.

• Mistake: Writing tasks: when you mean an empty list.
  Better: Write tasks: [].
• Mistake: Using {} for a list.
  Better: Use [] for lists.
• Mistake: Adding spaces inside confusingly.
  Better: items: [] is simple and clean.
• Mistake: Assuming every tool treats empty values the same.
  Better: Be explicit with [].

Fun Real-Life Examples

Here is a game character with no items:

player:
  name: Zippy
  level: 1
  inventory: []

Zippy has no sword. No shield. Not even a suspicious mushroom.

Here is a blog post with no tags:

post:
  title: My First Post
  tags: []

The tag list exists. It is just empty for now.

Here is a music playlist with no songs:

playlist:
  name: Monday Energy
  songs: []

That playlist has a bold name and zero vibes. Add songs quickly.

Best Practice

If a value should be a list, always make it a list. Even when it is empty.

Use this:

notifications: []

Not this:

notifications:

This makes your YAML easier to understand. It also helps tools read your file correctly. Future you will be grateful. Future you may even send snacks.

Final Thoughts

The YAML empty list syntax is simple: []. That tiny pair of brackets says, “This is a list with nothing inside.” It is different from null. It is also different from an empty object, {}.

When in doubt, be clear. If you mean an empty list, write []. YAML will understand. Your tools will understand. And your config files will look neat, tidy, and slightly adorable.