YAML ⇄ JSON

YAML (YAML Ain't Markup Language, originally "Yet Another Markup Language") is a text format for structured data designed to be read and written by humans first. It's a superset of JSON — every JSON document is valid YAML — with the goal of expressing the same structures through indentation, minimal punctuation and natural quoting instead of braces and commas.

It exists because JSON is fine for machines and awkward for people: no comments, mandatory quotes on keys and string values, and braces everywhere. YAML's sweet spot is configuration files — CI pipelines, Docker Compose, Kubernetes manifests, GitHub Actions — where a human writes the file once, maintains it by hand, and a machine parses it forever after.

The visible differences: YAML uses indentation for nesting instead of {}, lists are written with a leading dash instead of [ ], and strings don't need quotes unless they'd otherwise be ambiguous (a plain yes, true or 123 gets interpreted as a boolean or number, so quote it when you mean the string). Keys and values are separated by a colon and space, not a colon alone — name: value, never name:value.

The deeper difference is typing: JSON has one string type, one number type, booleans and null; YAML inherits a richer scalar type system from its data-modeling roots — on/off/yes/no are booleans by default (YAML 1.1; YAML 1.2 narrowed this), null/~/empty all mean null, and 0o17, 0x1F and 1_000_000 are numbers. When converting YAML to JSON, every scalar has to be pinned to a JSON type, which is why quoting discipline matters so much in YAML.

YAML nesting is expressed entirely by indentation, and — unlike Python — tabs are illegal; spaces only, and the exact count matters. Two-space increments are the norm, but the real rule is consistency: sibling values must align exactly, children must be indented further than their parent. One space of difference is a parse error or, worse, a silent restructure — a key that's a sibling instead of a child changes the document's meaning.

The failure modes are predictable: copy-pasting a block from a document that used different indentation, mixing tabs and spaces (editors are the usual culprit — configure them to insert spaces for YAML), and trailing spaces after a dash that get misread. Good editors highlight YAML structure and validate on save; that's not a luxury, it's the defense against a class of bugs that are invisible until parse time.

YAML has a feature JSON can't express: references. An anchor (&name) marks a node for reuse, and an alias (*name) inserts a reference to it anywhere else in the document — no copy-pasting shared config blocks. Conversion to JSON resolves the references, so an aliased block appears fully expanded in the JSON output; the reference structure is lost, but the data is identical.

Multi-line strings are where YAML genuinely outshines JSON for humans: a literal block (|) preserves newlines exactly as written, a folded block (>) folds newlines into spaces (ideal for paragraphs), and plain multi-line scalars flow across lines without escape sequences. JSON, by contrast, represents newlines as \n inside a single-line string — readable to a parser, hostile to a human editing a long text value.

In practice you meet YAML as the language of configuration ecosystems: GitHub Actions workflows, Docker Compose files, Kubernetes manifests, Ansible playbooks, CloudFormation, and most CI systems. The pattern is always the same — a human authors and reviews the file; the system parses it at deploy or runtime; and the cost of a mistake surfaces as a failed deploy rather than a friendly error, which is why the strict validation in this tool (line-numbered errors) matters more than it would for a scratch format.

The habits that keep YAML config safe: validate before you deploy, keep anchors and aliases simple (deep alias chains are hard to read and harder to debug), quote anything that could be misread as a number or boolean, and resist the urge to hand-roll YAML when a JSON config would do — JSON's strictness is a feature when no human needs to edit the file, and every YAML file is eventually edited by a human.