What Is YAML: a simple explanation of the configuration file format

What YAML is and why spaces actually matter

If you work with anything modern — Docker Compose, GitHub Actions, Kubernetes, Ansible — you will run into YAML. At first it looks simple: keys, colons, values. But then something does not work and you spend two hours hunting the problem until you realize: an extra space in the indentation.

YAML (YAML Ain’t Markup Language) is a text format for data and configuration. Its main idea: be human-friendly. JSON is readable too, but YAML is even more readable — if you know the rules.

Core syntax rules

Keys and values

name: ITAcademy
port: 8080
debug: false

Simple: key, colon, space, value. The space after the colon is mandatory. name:ITAcademy without a space is an error.

Lists

tags:
  - frontend
  - backend
  - devops

Each list item starts with - (dash and space).

Nested structures

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
  db:
    image: postgres:17
    environment:
      POSTGRES_PASSWORD: secret

Nesting is determined by space indentation (not tabs!). Usually 2 spaces per level.

Multiline text

description: >
  This is a multiline text
  that gets joined into one line.

long_text: |
  This is multiline text
  that preserves line breaks.

> — joins lines into one. | — keeps line breaks.

Why YAML is better than JSON

{
  "services": {
    "web": {
      "image": "nginx",
      "ports": ["8080:80"]
    }
  }
}

services:
  web:
    image: nginx
    ports:
      - "8080:80"

YAML: no quotes around keys, no curly braces, no commas between list items. Much more readable for a human.

Why YAML is worse than JSON

Spaces matter. An extra space changes the meaning or breaks parsing, and this kind of error is hard to spot.
No tabs. Only spaces. If your editor inserts tabs — confusion.
Type inference can surprise you. yes becomes true, no becomes false, 1.0 becomes a number, 1.0.0 stays a string. You have to be careful.

Common mistakes

1. Tabs instead of spaces

YAML requires spaces. Period. If your editor inserts tabs — configure it.

2. Wrong number of spaces

services:
    web:        # 4 spaces
      image:    # 6 spaces — still child of web, but unclear

Better to fix 2 spaces per level and stick to it.

3. Forgetting the space after the colon

image:nginx    # ✗ Error
image: nginx   # ✓ Correct

4. Not quoting special characters

title: "This: is important"    # ✓ Quotes preserve the colon
command: >-                    # ✓ Multiline block
  nginx
  -c /etc/nginx/nginx.conf

Conclusion / action plan

YAML is not hard, but it demands precision. Spaces matter, and that is both its strength (readability) and its weakness (errors).

Here is what to do next:

Open a docker-compose.yml or .github/workflows/test.yml and read it line by line.
Notice indentation: each nested structure has more spaces.
Try writing a simple YAML file and validate it with an online validator.
Make sure your editor inserts spaces, not tabs.

Once you can read YAML without hints, you understand more configurations than you think.