Understanding Spaces and Indentation in Azure DevOps YAML Pipelines

 

When working with Azure DevOps YAML pipelines, one of the most important concepts to understand is indentation. Unlike programming languages that use braces ({}) or brackets ([]) to define structure, YAML relies entirely on spaces to represent hierarchy.

Even a small indentation mistake can completely change how Azure DevOps interprets your pipeline.

---

Why Indentation Matters

Azure DevOps uses indentation to determine:

• Parent-child relationships between pipeline sections

• Which properties belong to an object

• Which items belong to a list/collection

In simple terms:

Indentation defines structure in YAML

---

Basic Rule

Use consistent spaces to nest child elements under parent elements.

Recommended standard:

• Use 2 spaces per indentation level

• Never use tabs

---

Correct Indentation Example

pool:
  vmImage: ubuntu-latest

What This Means

• pool is the parent object

• vmImage is a property inside pool

Equivalent JSON:

{
  "pool": {
    "vmImage": "ubuntu-latest"
  }
}

---

Example with Pipeline Steps

steps:
  - script: dotnet build
    displayName: Build Project

Structure Explanation

• steps is a collection/list

• - indicates a new item in the list

• script and displayName belong to the same step object

Equivalent JSON:

{
  "steps": [
    {
      "script": "dotnet build",
      "displayName": "Build Project"
    }
  ]
}

---

Common Indentation Mistakes

Mistake #1: Property Not Nested Properly

steps:
  - script: dotnet build
  displayName: Build Project

Why It’s Wrong

displayName is aligned with steps, so Azure DevOps treats it as a root-level property instead of part of the step.

Incorrect interpretation:

{
  "steps": [
    {
      "script": "dotnet build"
    }
  ],
  "displayName": "Build Project"
}

---

Mistake #2: Missing Indentation Under Parent

pool:
vmImage: ubuntu-latest

Why It’s Wrong

vmImage is not nested inside pool.

---

Mistake #3: Over-Indentation

steps:
  - script: dotnet build
      displayName: Build Project

Why It’s Wrong

displayName is indented too far and YAML parser cannot determine the correct structure.

---

Visualizing YAML Hierarchy

Consider the following example:

stages:
  - stage: Build
    jobs:
      - job: BuildJob
        steps:
          - script: echo Hello

Hierarchy:

stages
└── stage
    └── jobs
        └── job
            └── steps
                └── script

Each deeper level in the hierarchy requires additional indentation.

---

Tips for Avoiding Indentation Errors

1. Keep Sibling Properties Aligned

steps:
  - script: dotnet restore
    displayName: Restore

  - script: dotnet build
    displayName: Build

---

2. Use Spaces, Not Tabs

Tabs may cause YAML parsing errors.

Configure your editor to:

• Insert spaces when pressing Tab

• Show whitespace characters

---

3. Ask Yourself This While Writing YAML

For every line:

“What does this belong to?”

• If it belongs to the parent → indent under parent

• If it belongs to list item → align with sibling properties

• If root-level → no indentation

---

Common Azure DevOps Errors Caused by Indentation Issues

Indentation mistakes often produce errors like:

• Unexpected value

• A mapping was not expected

• While parsing a block mapping

• Bad indentation of a mapping entry

When you see these errors, check indentation first.

---

Final Thoughts

Indentation is the foundation of YAML in Azure DevOps. Once you understand that:

• Indentation = hierarchy

• Dash (-) = list item

• Aligned properties = siblings in same object

Writing and debugging pipelines becomes much easier.

---

Key Takeaway

Think of YAML indentation as the equivalent of braces in code.

Mastering indentation will help you write cleaner, more reliable Azure DevOps pipelines and troubleshoot YAML errors much faster.