How to represent arrays in YAML: 2026 guide

Arrays#

Arrays are one of the most fundamental data structures in programming. They are used to store multiple values in a single variable and are available in almost all programming languages, including Perl, Python, PHP, Java, C#, Ruby, and JavaScript. In simple terms, an array is a list of items that allows us to group data together and access each item by its index.

Why arrays matter?

Arrays are essential for efficiently handling collections of data. They allow us to:

• Group data: Arrays are ideal for holding collections of similar items (e.g., a list of colors, names, or numbers).

• Access items quickly: Arrays provide quick access to individual elements via indexing.

• Manipulate data easily: Operations such as sorting, filtering, and iterating over arrays are straightforward.

Arrays in YAML: Block vs. flow sequences#

YAML is a human-readable data serialization format often used for configuration files, data storage, and communication between different systems. YAML supports arrays in two main styles:

Block sequence#

The block sequence style of YAML uses hyphens or dashes to (-) to represent arrays. A hyphen (-) followed by white space ( ) represents an element of an array. When you enter the dashes, you need to ensure that all items are at the same indentation level.See the code example below to understand this better.

Example#

Flow sequence#

The flow sequence style of YAML uses brackets and commas to represent arrays.

See the code example below to understand this better.

Example#

Both the block and flow sequence styles are equivalent, but the choice between them often depends on the context and personal preference.

Arrays of objects in YAML#

In many configuration files, an array doesn't simply contain strings or numbers. Instead, each array element is an object (called a mapping in YAML) with multiple key-value pairs. This structure is widely used in Kubernetes manifests, Docker Compose files, GitHub Actions workflows, and Ansible playbooks.

For example, the following YAML defines an array of users:

The same structure in JSON looks like this:

Arrays of objects make YAML easy to read while still representing structured data.

Nested arrays in YAML#

YAML also supports arrays inside other arrays, often referred to as nested or multi-dimensional arrays. These are useful when representing grouped values or hierarchical data.

Here's an example:

Nested arrays also appear in CI/CD pipelines, matrix testing, and deployment configurations where multiple combinations of operating systems, languages, or environments need to be defined.

Because indentation determines structure in YAML, each nested array must remain consistently aligned.

Creating arrays in YAML using Python#

In Python, a YAML array is a list. An array (or list) is an ordered collection of items, which can be of any type. In YAML, an array is typically represented with hyphens (-), and the values can be strings, integers, or other data types.

Real-world examples of YAML arrays#

You'll encounter YAML arrays in many modern development tools and infrastructure platforms.

GitHub Actions#

Arrays are commonly used to define workflow steps.

Docker Compose#

Arrays define exposed ports.

Kubernetes#

Arrays are frequently used for containers within a pod specification.

Learning these common patterns makes it much easier to read and write YAML files used in real software projects.

Best practices for YAML arrays#

YAML is designed to be human-readable, but small formatting mistakes can make a configuration file invalid. Following a few best practices helps avoid common errors.

• Use spaces instead of tabs. YAML does not allow tabs for indentation.

• Keep indentation consistent. Every item in a sequence should align at the same indentation level.

• Use block sequences for long lists. Hyphen-based arrays are easier to read and maintain than inline arrays.

• Use flow sequences for short values. Inline arrays ([red, green, blue]) work well for compact lists.

• Quote ambiguous values such as yes, no, on, off, dates, or numbers when you want them treated as strings.

• Represent empty arrays explicitly using [] when a configuration requires a list but no values are currently defined.

Following these conventions improves readability and helps prevent YAML parsing errors.

Conclusion#

Arrays are essential for organizing and manipulating data in many programming languages, and understanding how to represent them in different formats like YAML is a valuable skill for developers. Whether you're using arrays in programming languages like Python or JavaScript, or serializing data in YAML for configuration files, understanding how to structure and work with arrays is crucial.