CodeCraft
← Back to Blog
DevOps2026-04-17·13 min read

YAML Explained: The Human-Friendly Configuration Language

#yaml#devops#kubernetes#docker#configuration
C
CodeCraft Team· Engineering

YAML (YAML Ain't Markup Language) has become the default choice for configuration files in modern software development. From Docker Compose and Kubernetes manifests to GitHub Actions workflows and Ansible playbooks, YAML is everywhere. Its human-readable syntax is both its greatest strength and the source of some of the most frustrating bugs developers encounter.

This guide covers YAML syntax from basics to advanced features, the critical gotchas that trip up even experienced developers, comparison with JSON and TOML, and best practices for writing maintainable YAML in production environments.

What is YAML and Why Was It Created?

YAML was created in 2001 as an alternative to XML for configuration files and data serialization. The name originally stood for "Yet Another Markup Language" but was later retroactively changed to "YAML Ain't Markup Language" to emphasize that it's a data serialization language, not a document markup language.

The design goals were:

- Human readability: Use indentation and natural syntax instead of XML's verbose tags

- Language-native data structures: Map directly to lists, dictionaries, and scalars in every programming language

- Superset of JSON: Any valid JSON document is also valid YAML (YAML 1.2+)

YAML is used in:

- Container orchestration: Kubernetes manifests, Docker Compose

- CI/CD: GitHub Actions, GitLab CI, CircleCI, Drone

- Configuration management: Ansible, Puppet, SaltStack

- Application config: Spring Boot, Ruby on Rails, Symfony

- Static site generators: Jekyll, Hugo, Gatsby frontmatter

YAML Syntax Fundamentals

YAML documents use indentation for structure (spaces only — no tabs). Here are the key building blocks:

Scalars (strings, numbers, booleans, null):

name: Alice           # string (no quotes needed)
age: 30               # integer
price: 9.99           # float
active: true          # boolean
nothing: null         # null (also: ~)
multiline: |          # literal block (preserves newlines)
  Line 1
  Line 2
folded: >             # folded block (newlines become spaces)
  This is a long
  sentence that wraps

Mappings (key-value pairs, like JSON objects):

person:
  name: Alice
  age: 30
  address:
    city: Shanghai
    zip: "200000"    # quotes force string type

Sequences (lists, like JSON arrays):

fruits:
  - apple
  - banana
  - cherry

# Inline (flow) style:
fruits: [apple, banana, cherry]

Comments: Use # for single-line comments (JSON doesn't support comments):

# This is a configuration for the web server
server:
  port: 8080  # default HTTP port

YAML Data Types and the Norway Problem

YAML's automatic type inference is convenient but can cause surprising bugs. The most infamous is the "Norway Problem":

countries:
  - GB  # → string "GB"
  - US  # → string "US"
  - NO  # → boolean false!!! (YAML 1.1 parsed "NO" as false)

YAML 1.1 (used by many older parsers) treated NO, no, Yes, YES, on, Off etc. as booleans. YAML 1.2 fixed this — only true and false (case-insensitive) are booleans.

Common type gotchas:

version: 1.0      # float → 1.0 (not string "1.0"!)
port: 8080        # integer
zip_code: 01234   # integer 1234 (leading zero stripped!)
hex: 0x1A         # integer 26
octal: 0o17       # integer 15 (YAML 1.2), or 017 in YAML 1.1

# Always quote values that look like numbers but should be strings:
zip_code: "01234"   # string "01234" ✓
version: "1.0"      # string "1.0" ✓
api_key: "0123456"  # string ✓

The "boolean strings" issue in Docker/Kubernetes:

env:
  DEBUG: true   # parsed as boolean true, but env vars are strings!
  DEBUG: "true" # correct — string "true"

Advanced YAML: Anchors, Aliases, and Merges

YAML provides powerful features for eliminating repetition in large configuration files.

**Anchors (&) and aliases (*)** allow you to define a value once and reference it multiple times:

defaults: &defaults
  timeout: 30
  retries: 3
  log_level: info

production:
  <<: *defaults       # merge all keys from defaults
  log_level: warning  # override specific keys
  host: prod.example.com

staging:
  <<: *defaults
  host: staging.example.com

Multiple documents in a single file (separated by ---):

---  # Document 1
name: Alice
---  # Document 2
name: Bob

Explicit typing with YAML tags:

integer: !!int "42"
float: !!float "3.14"
string: !!str 42        # force integer to string
binary: !!binary |
  R0lGODlh...           # base64 encoded binary data

YAML vs JSON vs TOML: When to Use Each

YAML:

✓ Best readability for complex nested structures

✓ Supports comments

✓ Multi-line strings

✓ Anchors and aliases for DRY configuration

✗ Whitespace-sensitive (tabs cause errors)

✗ Implicit type coercion causes bugs

✗ Parsing is complex (many edge cases)

→ Best for: Kubernetes, CI/CD, Ansible, application config

JSON:

✓ Universal — every language can parse it

✓ No ambiguity — explicit types via delimiters

✓ Superset of YAML 1.2

✗ No comments

✗ Verbose for deeply nested data

✗ No multi-line strings

→ Best for: API responses, package.json, data interchange

TOML:

✓ Very readable for flat or two-level configuration

✓ Explicit types — no ambiguity

✓ Supports comments

✗ Poor support for deeply nested structures (gets verbose)

✗ Smaller ecosystem than YAML/JSON

→ Best for: Rust (Cargo.toml), Python (pyproject.toml), simple app config

# Cargo.toml example
[package]
name = "my-app"
version = "1.0.0"

[dependencies]
serde = { version = "1.0", features = ["derive"] }

YAML in Kubernetes and Docker Compose

Kubernetes and Docker Compose are the most common places developers encounter YAML professionally.

Kubernetes Deployment example:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  labels:
    app: my-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: my-app
        image: my-app:1.2.3
        ports:
        - containerPort: 8080
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: db-secret
              key: url
        resources:
          requests:
            memory: "64Mi"
            cpu: "250m"
          limits:
            memory: "128Mi"
            cpu: "500m"

Docker Compose example:

version: "3.9"
services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - api

  api:
    build: .
    environment:
      - NODE_ENV=production
      - DB_HOST=postgres
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: ${DB_PASSWORD}  # from .env file
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U admin"]
      interval: 10s
      timeout: 5s
      retries: 5

YAML Best Practices and Common Mistakes

Always use spaces, never tabs: YAML strictly forbids tabs for indentation. Configure your editor to display tabs and convert them to spaces automatically.

Quote strings that look like other types:

# Risky — type depends on parser version:
enabled: yes     # boolean in YAML 1.1, string in 1.2

# Safe:
enabled: "yes"   # always a string
enabled: true    # always a boolean

Validate YAML before deploying: Use yamllint for linting and kubeval (for Kubernetes) to catch structural errors:

yamllint config.yaml
kubeval deployment.yaml

Use explicit document separators in multi-document files:

---
kind: Deployment
# ...
---
kind: Service
# ...

Avoid deeply nested anchors: While anchors reduce repetition, overly complex anchor hierarchies make files hard to understand. Consider splitting into multiple files instead.

Use a YAML-aware editor: VS Code with the YAML extension (Red Hat) provides schema validation, autocomplete, and hover documentation for Kubernetes, Docker Compose, and GitHub Actions.

YAML's readability makes it the right choice for configuration files that humans frequently edit, but its implicit type coercion and whitespace sensitivity require careful attention. The Norway Problem and boolean string gotchas have caused real production incidents — always quote ambiguous values and validate your YAML files before deploying. Use our free YAML ↔ JSON Converter to instantly convert between YAML and JSON format. Supports nested structures, arrays, and complex configurations — all processed locally in your browser.