What are YAML's indentation rules? How to avoid common indentation errors?

YAML indentation rules are the most important and error-prone part of its syntax. Correctly understanding and using indentation is the foundation for writing valid YAML files.

Basic YAML Indentation Rules

1. Use Spaces, Not Tabs

YAML strictly prohibits using Tab characters for indentation; spaces must be used.

yaml
# ✅ Correct: Using space indentation
server:
  host: localhost
  port: 8080

# ❌ Error: Using tab indentation (will cause parsing error)
server:
	host: localhost
	port: 8080

2. Consistent Indentation Levels

Elements at the same level must have the same indentation amount.

yaml
# ✅ Correct: Consistent indentation
database:
  host: db.example.com
  port: 5432
  name: myapp

# ❌ Error: Inconsistent indentation
database:
  host: db.example.com
    port: 5432  # Too much indentation
  name: myapp

3. Recommended Indentation Amount

Although YAML doesn't mandate a specific number of spaces, 2 spaces is recommended as the standard indentation.

yaml
# Recommended: 2-space indentation
config:
  server:
    host: localhost
    port: 8080
  database:
    type: postgresql
    ssl: true

Indentation in Different Structures

1. Map Indentation

yaml
# Basic map
person:
  name: Alice
  age: 30
  address:
    street: Main St
    city: Beijing
    country: China

2. List Indentation

yaml
# List items with same indentation
fruits:
  - apple
  - banana
  - orange

# Nested lists
matrix:
  - - 1
    - 2
    - 3
  - - 4
    - 5
    - 6

3. Mixed Structure Indentation

yaml
# Map containing list
user:
  name: Bob
  skills:
    - Python
    - JavaScript
    - Go

# List containing maps
employees:
  - name: Carol
    role: Developer
  - name: Dave
    role: Designer

Common Indentation Errors

1. Mixing Spaces and Tabs

yaml
# ❌ Error: Mixing spaces and tabs
config:
  setting1: value1
  	setting2: value2  # Tab indentation

2. Mismatched Indentation

yaml
# ❌ Error: Inconsistent indentation at same level
server:
  host: localhost
    port: 8080  # Too much indentation

3. Missing Space After Colon

yaml
# ❌ Error: Missing space after colon
name:Alice  # Should be name: Alice

4. Multi-line String Indentation Error

yaml
# ❌ Error: Inconsistent content indentation in multi-line string
description: |
  This is line 1
    This is line 2  # Inconsistent indentation
  This is line 3

Indentation Debugging Techniques

1. Editor Configuration

Configure YAML files to use 2-space indentation in your editor:

VS Code Configuration:

json
{
  "[yaml]": {
    "editor.insertSpaces": true,
    "editor.tabSize": 2,
    "editor.detectIndentation": false
  }
}

2. Using YAML Validation Tools

bash
# Validate YAML file with yamllint
yamllint config.yaml

# Validate with Python
python -c "import yaml; yaml.safe_load(open('config.yaml'))"

3. Visualize Indentation

Enable show whitespace characters in YAML-supporting editors to clearly see indentation structure.

Best Practices

1. Always use 2-space indentation
2. Configure editor to auto-convert tabs to spaces
3. Maintain consistent indentation at same level
4. Use YAML linter for validation
5. Unify indentation standards across team
6. Use YAML Schema to validate file structure

Practical Example

yaml
# Complete YAML configuration example
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
  namespace: production
data:
  server:
    host: api.example.com
    port: 443
    tls:
      enabled: true
      cert_path: /etc/ssl/certs
  database:
    type: postgresql
    host: db.example.com
    port: 5432
    name: appdb
    pool:
      min: 5
      max: 20
  features:
    - authentication
    - rate_limiting
    - logging
    - monitoring
  logging:
    level: info
    format: json
    outputs:
      - type: console
        level: debug
      - type: file
        path: /var/log/app.log
        rotation:
          max_size: 100M
          max_age: 30d