general data-formats

YAML (YAML)

yaml configuration data-format devops
Plain English

YAML is a way to write configuration files that is easier for humans to read than JSON. Instead of curly braces and brackets, YAML uses indentation and dashes. Docker Compose files, Kubernetes manifests, Ansible playbooks, and GitHub Actions workflows are all written in YAML. If you work in DevOps or infrastructure, you will read and write YAML every day.

Technical Definition

YAML (YAML Ain’t Markup Language) is a data serialization language designed for human readability. It is a superset of JSON (all valid JSON is valid YAML) with a cleaner, indentation-based syntax.

Data types:

  • Scalars: strings, numbers, booleans, null
  • Sequences (arrays): indicated by - prefix
  • Mappings (objects): key-value pairs with : separator
  • Multi-line strings: | (literal block, preserves newlines), > (folded, joins lines)

YAML vs. JSON:

FeatureYAMLJSON
CommentsYes (#)No
ReadabilityHigh (indentation)Medium (brackets)
Multi-line stringsNative (|, >)Escaped \n
Anchors/aliasesYes (& / *)No
Parsing speedSlowerFaster
Common useConfig filesAPIs, data exchange

Common pitfalls:

  • Indentation errors: YAML uses spaces only (never tabs). Inconsistent indentation breaks parsing.
  • Boolean coercion: yes, no, on, off, true, false are all booleans. Wrap in quotes if you mean the string: "yes".
  • Number coercion: 010 is octal (8), not decimal 10. Quote if needed: "010".
  • The Norway problem: country code NO is parsed as boolean false. Always quote country codes.

YAML syntax examples 

# Docker Compose (most common YAML use case)
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"        # Host:Container
    volumes:
      - ./html:/usr/share/nginx/html:ro
    environment:
      NGINX_HOST: bytesnation.com
      NGINX_PORT: "80"   # Quoted to prevent number coercion
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: app
      POSTGRES_PASSWORD: ${DB_PASS}  # Variable substitution
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

# Multi-line strings
description: |
  This preserves newlines.
  Each line is separate.

folded: >
  This joins lines into
  a single paragraph.

# Anchors and aliases (DRY)
defaults: &defaults
  restart: unless-stopped
  logging:
    driver: json-file
    options:
      max-size: "10m"

services:
  app:
    <<: *defaults    # Merge defaults
    image: myapp:latest
In the Wild

YAML is the configuration language of modern DevOps. Kubernetes manifests, Docker Compose files, Ansible playbooks, GitHub Actions workflows, Terraform variable files, and Helm charts are all YAML. The average infrastructure engineer reads more YAML than any other format. The most common YAML error is indentation: a single misplaced space can change the structure entirely, and the error messages are often unhelpful. YAML linters (yamllint) and schema validators catch these issues before deployment. The boolean coercion problem is a constant source of bugs: country codes, version strings, and configuration values that look like booleans get silently converted. Always quote values that might be ambiguous. Despite its quirks, YAML’s readability advantage over JSON for configuration files has made it the universal choice.

← Back to Dictionary