YAML Guide

YAML trades strict punctuation for human-readable configuration

YAML is popular in infrastructure and tooling because it keeps common configuration patterns readable, especially when files are edited directly by people.

Core concepts

A few conventions explain most of the format.

Key/value pairs

The basic unit is a key followed by a colon and a value.

name: Jane Doe

Indentation

Whitespace defines hierarchy, so consistent spacing matters.

parent:\n child: value

Lists

Sequences use a leading dash on each item.

- item-one

Comments

Comment lines begin with # and are ignored by parsers.

# deployment settings

Advanced features

YAML can express richer authoring patterns than JSON.

Multi-line strings

Use | to preserve line breaks or > to fold lines into a single paragraph.

Anchors and aliases

Reuse shared values to avoid duplication in larger config files.

Typed values

Parsers can infer many scalar types, and explicit tags can override that behavior.

Config-first ergonomics

The format is especially comfortable for manifests, CI pipelines, and deployment descriptors.

Best practices

Small consistency rules prevent a lot of broken config.

Use spaces only. Tabs are not valid indentation in YAML.
Keep a space after each colon, for example key: value.
Be careful with strings that contain special characters like :, #, or braces.
Quote values when you want to avoid accidental type coercion.
Stay consistent with indentation depth across the file.

YAML vs JSON

Feature	YAML	JSON
Primary strength	Human-readable config	Compact interchange format
Comments	Supported	Not supported
Syntax style	Indentation-based	Braces and brackets
Typical use	Infra manifests and config files	APIs and application data

Example config

docker-compose.yaml

version: "3.8"
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    environment:
      - NODE_ENV=production

database:
  adapter: postgresql
  host: localhost
  timeout: 5000