What YAML is, the syntax that bites, and when JSON is the better choice

YAML is the configuration language of modern infrastructure — every CI pipeline, Kubernetes manifest and Docker Compose file is written in it — chosen because it reads like an outline rather than a wall of braces. It also has a reputation for surprising its users, deservedly. This guide covers the syntax, the traps, and why converting it to JSON is often the fastest way to find out what a file actually says.

What YAML is

YAML ("YAML Ain't Markup Language", 2001) is a data serialisation format for the same data JSON holds — maps, lists, strings, numbers, booleans, null — with a syntax built on indentation and minimal punctuation. YAML 1.2 (2009) is a strict superset of JSON: any JSON document is valid YAML. The goal was human readability for files people edit by hand; the cost is a specification far larger than JSON's and behaviours that depend on it.

The syntax

name: Pikkit
version: 2
tags:
  - tools
  - guides
build:
  command: python3 scripts/build_pages.py
  env:
    NODE_ENV: production
description: |
  A multi-line block.
  Line breaks are kept.
summary: >
  A folded block where
  line breaks become spaces.
enabled: true
retries: null

Key: value pairs make maps; lines starting with - make lists; nesting is by indentation (spaces only, consistently); # starts a comment. Strings rarely need quotes, which is convenient until it isn't. --- separates multiple documents in one file.

The traps

• The Norway problem. In YAML 1.1, unquoted no, yes, on, off, y and n are booleans — so a list of country codes containing NO becomes false. YAML 1.2 fixed this, but many parsers still implement 1.1. Quote anything that could be misread.
• Numbers that aren't. 3.10 becomes 3.1; 0777 may become octal; 1e3 becomes 1000; version: 1.0 loses its zero. Quote version strings.
• Colons and hashes in values. A value containing ": " or " #" needs quoting or the parser splits it.
• Tabs. Indentation must be spaces; a tab is a syntax error, and editors that auto-insert tabs produce baffling failures.
• Indentation drift. One level off silently moves a key into or out of a map. This is the commonest CI failure.
• Anchors and merges (&defaults, *defaults, <<:) reduce repetition and make files hard to read; use sparingly.

A converter makes every one of these visible: turn the YAML into JSON and look at what the parser understood.

Where YAML is used

GitHub Actions, GitLab CI, CircleCI; Kubernetes and Helm; Docker Compose; Ansible; OpenAPI specs; static-site front matter (What Markdown is, the syntax that matters, and where it works files often start with a YAML block); and application config in many languages. It is rarely used as a data interchange format between programs — that's JSON — or for anything written by a machine and never read by a person.

YAML versus JSON, and converting

JSON (What JSON is, and where it trips people up) is strict, unambiguous, universally parsed and painful to edit by hand: no comments, quotes everywhere, trailing commas forbidden. YAML is the reverse. Rule of thumb: YAML for files humans write and maintain, JSON for anything programs exchange or generate. Converting between them is lossless for data (comments and anchors don't survive to JSON); YAML to JSON and JSON to YAML do it in the browser, and the JSON formatter validates the result. TOML and INI are the other hand-edited options, simpler than YAML and used by Rust, Python packaging and older Windows software.