Składnia YAML i walidacja: Częste błędy i jak je naprawić

YAML (YAML Ain't Markup Language) is the go-to configuration format for Docker, Kubernetes, CI/CD pipelines, and countless other tools. Despite its human-friendly syntax, YAML is surprisingly easy to get wrong. This guide covers the most common YAML errors and how to fix them.

Where YAML Is Used

• Docker Compose (docker-compose.yml)
• Kubernetes manifests
• GitHub Actions / GitLab CI workflows
• Ansible playbooks
• Configuration files (Prettier, ESLint, etc.)

Basic YAML Syntax Rules

Indentation

YAML uses spaces (never tabs) for indentation. The number of spaces must be consistent within the same level:

# ✅ Correct (2-space indentation)
server:
  host: localhost
  port: 8080
  database:
    name: myapp
    pool: 10

# ❌ Wrong (tab characters or inconsistent spaces)
server:
	host: localhost    # Tab character - INVALID!
   port: 8080        # 3 spaces - inconsistent!

Key-Value Pairs

Keys and values are separated by a colon followed by a space:

# ✅ Correct
name: John Doe
port: 8080

# ❌ Wrong - missing space after colon
name:John Doe

Multi-line Strings

YAML offers two block scalar styles for multi-line strings:

# | (literal block) - preserves newlines
description: |
  This is line one.
  This is line two.
  Each newline is preserved.

# > (folded block) - folds newlines to spaces
description: >
  This is a long paragraph
  that will be joined into
  a single line.

YAML Data Types

The "Norway Problem"

In YAML 1.1, `NO` (as in the country code for Norway) is interpreted as boolean `false`. This is because YAML 1.1 treats yes/no, on/off, true/false as booleans. Always quote country codes and similar values:

# ❌ YAML 1.1 interprets these as booleans!
country: NO        # → false
answer: yes        # → true
switch: on         # → true

# ✅ Fix: quote the values
country: "NO"      # → string "NO"
answer: "yes"      # → string "yes"
switch: "on"       # → string "on"

Collections: Lists and Maps

# List (sequence)
fruits:
  - apple
  - banana
  - cherry

# Nested map
database:
  host: localhost
  port: 5432
  credentials:
    user: admin
    password: secret

# Inline / Flow style
fruits: [apple, banana, cherry]
point: {x: 10, y: 20}

Top 10 Common YAML Errors

YAML vs JSON vs TOML

Validation Best Practices

• Always use a YAML linter in your CI/CD pipeline
• Configure your editor to show whitespace characters
• Use 2-space indentation (most common convention)
• Quote strings that could be misinterpreted (booleans, numbers with leading zeros)
• Use YAML schema validation for complex configurations
• Keep YAML files small and modular when possible

FAQ