YAML Lists

A list in YAML is called a sequence. A sequence stores multiple values under one key. Think of it like a shopping list — each item appears on its own line, one below the other. Lists are one of the most used structures in YAML configuration files.

Why Use Lists in YAML?

Many real-world configurations need multiple values for a single setting. For example, a server might listen on multiple ports, a build system might need multiple dependencies, or a web app might support multiple allowed origins. Lists make it easy to store all those values together under one meaningful key.

Writing a YAML List – Block Style

The most common way to write a list in YAML uses a dash (-) followed by a space before each item. This is called the block sequence style.

fruits:
  - apple
  - mango
  - banana
  - grapes

Each item starts with a dash and a space. All items are indented under the key fruits. The key itself ends with a colon.

Writing a YAML List – Inline (Flow) Style

YAML also allows lists to be written on a single line using square brackets. This is called the flow sequence style.

fruits: [apple, mango, banana, grapes]

Both styles produce the same result. Block style is preferred for readability, especially when a list has many items or complex values.

Block vs Flow Style Comparison

# Block Style (easier to read)
colors:
  - red
  - green
  - blue

# Flow Style (compact, same result)
colors: [red, green, blue]

List Structure Diagram

+----------------------------------+
|  Key: fruits                     |
+----------------------------------+
|    - apple      ← Item 1         |
|    - mango      ← Item 2         |
|    - banana     ← Item 3         |
|    - grapes     ← Item 4         |
+----------------------------------+

List of Numbers

Lists are not limited to strings. Any scalar value can be a list item.

scores:
  - 85
  - 90
  - 78
  - 95

temperatures:
  - 36.5
  - 37.1
  - 38.0

List of Booleans

permissions:
  - true
  - false
  - true

Mixed-Type Lists

YAML allows different data types in the same list, although this is uncommon in practice.

mixed:
  - Alice
  - 30
  - true
  - null

List of Dictionaries (Most Common in DevOps)

One of the most powerful uses of YAML lists is storing a list of mappings (key-value groups). Each list item is a dictionary with multiple fields.

employees:
  - name: Alice
    role: Developer
    age: 28
  - name: Bob
    role: Designer
    age: 32
  - name: Carol
    role: Manager
    age: 35

Each item in the list is a full set of key-value pairs. The dash marks the beginning of each item. The keys inside each item are indented one level deeper.

List of Dictionaries Diagram

employees:
  │
  ├─ Item 1:  name: Alice
  │           role: Developer
  │           age: 28
  │
  ├─ Item 2:  name: Bob
  │           role: Designer
  │           age: 32
  │
  └─ Item 3:  name: Carol
              role: Manager
              age: 35

Nested Lists (List Inside a List)

A list item can itself be another list. This creates a nested list structure.

matrix:
  - - 1
    - 2
    - 3
  - - 4
    - 5
    - 6

This represents a 2D grid (matrix). The outer list has two items. Each item is itself a list of three numbers.

Real-World Example – GitHub Actions Workflow

GitHub Actions uses YAML lists to define multiple steps in a CI/CD pipeline.

steps:
  - name: Checkout code
    uses: actions/checkout@v3
  - name: Setup Node
    uses: actions/setup-node@v3
    with:
      node-version: 18
  - name: Install packages
    run: npm install
  - name: Run tests
    run: npm test

Each step is a list item. Each item has its own set of keys. This pattern appears in almost every GitHub Actions workflow file.

Real-World Example – Docker Compose Ports

services:
  web:
    ports:
      - "80:80"
      - "443:443"

The ports key holds a list of port mappings. Each item is a string that maps a host port to a container port.

Common Mistakes with Lists

Summary

• A YAML list (sequence) stores multiple values under one key
• Block style uses a dash and space before each item: - value
• Flow style uses square brackets: [value1, value2]
• List items can be strings, numbers, booleans, or full dictionaries
• Nested lists are possible by indenting a list inside another list
• Lists of dictionaries are widely used in tools like Docker and GitHub Actions