What Is YAML? – Definition and How It Works

Informational P2 what is yaml

Learn what YAML is, how indentation defines structure, which implicit typing rules cause bugs, and when to prefer it over JSON.

YAML is a human-readable data serialisation format. It is a superset of JSON, uses indentation for structure, and is the default choice for configuration files across most modern tooling.

1. The Shape

service:
  name: collector
  replicas: 3
  enabled: true
  sources:
    - name: example
      url: https://example.com
      timeout: 30
    - name: other
      url: https://other.example.com
comment: >
  Folded block scalars join lines
  into a single string.

Mappings, sequences, and scalars — the same model as JSON, with far less punctuation.

2. Why It Is Used for Configuration

Readable. No braces, quotes, or commas cluttering the structure.
Comments, which JSON does not support and configuration badly needs.
Multi-line strings through block scalars.
Anchors and aliases, allowing a block to be defined once and reused.

3. The Implicit Typing Problem

YAML infers types from unquoted values, and the rules produce genuine surprises.

Written	Interpreted as
`yes`, `no`, `on`, `off`	Booleans in older versions
`1.0`	A float, not the string
`08`	Invalid, or an unexpected number
`2026-08-18`	A date object in some parsers
`NO` (a country code)	A boolean in older versions

The last one is the classic: a country code interpreted as false. Quoting values that should be strings prevents all of these.

4. Indentation Is Structure

Nesting is expressed by indentation, and tabs are forbidden. A single misplaced space changes which parent a key belongs to, and the result is often valid YAML with the wrong meaning.

That is why configuration errors in YAML frequently produce a confusing runtime failure rather than a parse error.

5. Anchors and Aliases

defaults: &defaults
  timeout: 30
  retries_disabled: true

production:
  <<: *defaults
  url: https://example.com

Powerful for reducing repetition, and worth using sparingly: heavily aliased configuration becomes hard to read, which defeats the reason YAML was chosen.

6. Security

Some parsers support constructing arbitrary objects from YAML, which allows code execution when parsing untrusted input.

Always use the safe loading function of whichever library you use. This is a well-known vulnerability class, and the fix is one function name.

7. YAML Versus JSON

Aspect	YAML	JSON
Readability	Higher	Lower for humans
Comments	Yes	No
Implicit typing	Yes — a hazard	No
Whitespace-sensitive	Yes	No
Parsing speed	Slower	Faster
Machine interchange	Less common	Standard

The division in practice: YAML for files people edit, JSON for data machines exchange.

8. Summary

YAML is an indentation-based, human-friendly serialisation format with comments, multi-line strings, and reuse through anchors — which is why configuration lives in it.

Quote anything that should be a string, never use tabs, always parse untrusted input with the safe loader, and keep machine-to-machine payloads in JSON.