🟨 YAML for real-world config, data files, and automation

Learn YAML deeply
without the usual footguns

This tutorial is designed to teach the full practical YAML syntax: indentation, scalars, lists, maps, multiline strings, anchors, aliases, merge keys, tags, multi-document files, and the mistakes that break production configs.

12Core sections

40+Examples

6Real configs

1Big cheat sheet

Start learning → Jump to cheat sheet

app:
  name: yaml-atlas
  enabled: true
  ports:
    - 8080
    - 8443
  database:
    host: db.local
    retries: 3

spaces: yes
tabs: absolutely not

: - & * | >

What you will learn

How YAML is structured, how each scalar style behaves, and how to read and write configs confidently.

What this avoids

No shallow “YAML is just indentation” treatment. This covers the weird parts too, including quoting rules, booleans, anchors, merge behavior, and multiline traps.

Best use case

Use YAML when humans need to read and edit structured data. Reach for JSON, TOML, or another format when machine strictness matters more than friendliness.

Foundations

Start with the mental model first. YAML is a way to represent nested data structures using indentation and a few compact syntax forms.

What YAML is

A human-friendly data serialization language.
Usually used for configuration, infrastructure, CI pipelines, manifests, and content files.
Capable of representing objects/maps, arrays/lists, strings, numbers, booleans, nulls, and more.

What YAML is not

Not programming code.
Not indentation-tolerant. Whitespace matters.
Not ideal when you want zero ambiguity.

The data model

mapping = key/value object

sequence = ordered list

scalar = single value

If you understand those three pieces, the rest is mostly syntax details and edge cases.

basic-shape.yaml

# Mapping at the top level
app:
  name: YAML Atlas
  version: 1.0
  debug: true
  maintainers:
    - Athy
    - Oracle

Core syntax

These are the pieces you will use most often.

Indentation rules Mappings / objects Sequences / arrays Scalars & types Strings & multiline text Comments

1. Indentation rules

YAML uses spaces to show nesting. Use spaces only. Do not use tabs.

A child value must be indented farther than its parent key. Consistency matters more than a specific number of spaces, but two spaces is the common convention.

valid.yaml

server:
  host: localhost
  port: 8080
  ssl:
    enabled: true

broken.yaml

server:
 host: localhost
   port: 8080

Tabs are a common source of invalid YAML.
You can indent by 2 or 4 spaces, but stick to one style in the file.
Nested list items and nested objects follow the same indentation logic.

2. Mappings / objects

A mapping is a set of key/value pairs. Think JSON object or dictionary.

mapping.yaml

database:
  host: db.example.com
  port: 5432
  username: app_user
  password: secret

Keys

Usually plain strings.
End with a colon.
Can point to a scalar, list, or nested mapping.

Inline mapping

{ name: Sam, role: admin, active: true }

Inline syntax is valid, but block style is usually easier to read.

3. Sequences / arrays

A sequence is an ordered list. Each item starts with a dash and a space.

list.yaml

features:
  - auth
  - billing
  - analytics

list-of-objects.yaml

users:
  - name: Athy
    role: owner
  - name: Oracle
    role: assistant

A list item can itself contain nested keys, but those nested keys must line up under that list item.

4. Scalars and common value types

A scalar is a single value like text, a number, true/false, or null.

scalars.yaml

plain_text: hello
integer: 42
float: 3.14
boolean_true: true
boolean_false: false
empty_value: null
also_empty: ~
string_number: "42"
string_boolean: "true"
date_like: "2026-05-13"

Important: different YAML parsers may interpret unquoted values differently, especially booleans, dates, and special words. When you need exact string behavior, quote it.

5. Strings and multiline text

YAML has several string styles. This is one of the most important parts to learn well.

Plain strings

title: Hello world

No quotes needed if the text is simple and unambiguous.

Single-quoted

title: 'Literal text'

Useful when you want backslashes treated literally.

Double-quoted

title: "Line
Break"

Supports escape sequences like and .

literal-block.yaml

message: |
  line one
  line two
  line three

| keeps line breaks.

folded-block.yaml

message: >
  line one
  line two
  line three

> folds most line breaks into spaces.

chomping.yaml

keep_trailing_newline: |
  hello
strip_trailing_newline: |-
  hello
keep_extra_newlines: |+
  hello

6. Comments

Comments start with #.

comments.yaml

# top-level comment
app:
  name: yaml-atlas # inline comment
  debug: false

Do not place comments where they break indentation logic.
A hash inside a quoted string is just text, not a comment.

Advanced YAML

These features matter once you are writing larger config files or DRYing up repeated structures.

7. Anchors and aliases

Anchors let you name a block. Aliases let you reuse it.

anchors.yaml

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

service_a:
  <<: *defaults
  host: a.example.com

service_b:
  <<: *defaults
  host: b.example.com
  timeout: 60

&defaults defines an anchor.
*defaults references it.
<<: is the merge key commonly used to merge mappings.

8. Tags and explicit typing

YAML supports tags that explicitly describe the type of a value.

tags.yaml

port: !!int "8080"
enabled: !!bool "true"
name: !!str 123

You will not use tags every day, but they help when parser inference is not giving you what you want.

9. Multiple documents in one file

YAML can contain multiple documents separated by ---. Some tools, like Kubernetes, rely on this heavily.

multi-doc.yaml

---
kind: ConfigMap
metadata:
  name: app-config
---
kind: Service
metadata:
  name: app-service

... can explicitly end a document, though many files omit it.

10. Flow style

YAML also supports inline “flow” style similar to JSON.

flow-map.yaml

user: { name: Athy, role: owner }

flow-seq.yaml

ports: [80, 443, 8080]

This is valid, but use it sparingly. Block style is usually easier to maintain.

Real-world examples

This is where YAML becomes less abstract and more useful.

Docker Compose style

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
    environment:
      APP_ENV: production

GitHub Actions style

name: CI
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

Kubernetes style

apiVersion: v1
kind: Pod
metadata:
  name: demo
spec:
  containers:
    - name: app
      image: nginx

Application config style

logging:
  level: info
  file: /var/log/app.log
features:
  signup: true
  beta_dashboard: false

Common mistakes that bite people

Tabs

Many parsers reject them outright.

Unquoted booleans

yes, on, or date-like values may be interpreted unexpectedly depending on the parser.

Misaligned indentation

One extra space can move data into a different object.

Colon confusion

Plain strings containing a colon can need quoting.

Multiline assumptions

| and > behave differently; do not treat them as interchangeable.

Too much cleverness

Anchors are useful, but overusing them can make a file harder to read than duplication would.

Best practices

Use 2 spaces per level unless the target project already uses another style.
Quote strings when ambiguity is possible.
Prefer block style over inline flow style for maintainability.
Keep anchors simple and local.
Validate with a linter or parser instead of trusting your eyes.
Know your tool’s YAML version and parser behavior.

Tooling and validation

YAML is friendlier when your editor and linter catch mistakes early.

🧰

VS Code YAML extension

Add schema support, validation, autocomplete, and better editing ergonomics.

✅

yamllint

Use it to catch indentation problems, style issues, and common syntax errors.

🔍

Schema validation

For formats like Kubernetes or GitHub Actions, schema-aware tooling is much better than syntax checks alone.

🐧

Quick setup ideas

Lint files

yamllint your-file.yaml

Validate with the real tool

docker compose config
kubectl apply --dry-run=client -f manifest.yaml

Use schemas in the editor

# Example: map YAML files to their schema in your editor config

YAML cheat sheet

A compact reference you can come back to later.

Structure

key: value → mapping entry
- item → list item
indent with spaces, not tabs

Strings

plain: hello
single quoted: 'hello'
double quoted: "hello"
literal block: |
folded block: >

Special values

true / false
null / ~
quote if you need exact string semantics

Reuse

&name → anchor
*name → alias
<<: *name → merge mapping

Multiple documents

--- starts a document
... can end one

Golden rule

If a value could be misunderstood by a parser or a human, quote it and keep the structure boring.

You now know the practical YAML surface area

At this point you should be able to read and write most YAML files you will meet in the wild: CI configs, Docker Compose, Kubernetes manifests, app settings, content metadata, and templated config with anchors.

The remaining challenge is not memorizing more syntax. It is learning the parser and conventions of the tool you are working with.

Learn YAML deeplywithout the usual footguns

What you will learn

What this avoids

Best use case

Foundations

What YAML is

What YAML is not

The data model

Core syntax

1. Indentation rules

2. Mappings / objects

Keys

Inline mapping

3. Sequences / arrays

4. Scalars and common value types

5. Strings and multiline text

Plain strings

Single-quoted

Double-quoted

6. Comments

Advanced YAML

7. Anchors and aliases

8. Tags and explicit typing

9. Multiple documents in one file

10. Flow style

Real-world examples

Docker Compose style

GitHub Actions style

Kubernetes style

Application config style

Common mistakes that bite people

Tabs

Unquoted booleans

Misaligned indentation

Colon confusion

Multiline assumptions

Too much cleverness

Best practices

Tooling and validation

VS Code YAML extension

yamllint

Schema validation

Quick setup ideas

YAML cheat sheet

Structure

Strings

Special values

Reuse

Multiple documents

Golden rule

You now know the practical YAML surface area

Learn YAML deeply
without the usual footguns