What Is YAML?

If you've configured a Kubernetes deployment, a GitHub Actions workflow, or a Docker Compose file, you've written YAML — even if nobody explained what it actually is first. Here's the short definition, the syntax that trips people up, and where you'll keep running into it.

The short definition

YAML is a human-readable data serialization format — a way to represent structured data (objects, lists, strings, numbers) as plain text, without the braces and brackets a format like JSON needs. It's maintained at yaml.org, currently at spec revision 1.2.2. The name is a recursive acronym — YAML Ain't Markup Language — which is itself a correction: it originally stood for "Yet Another Markup Language" when it launched in 2001, before its creators renamed it to make the point that YAML is for data, not documents.

The syntax, at a glance

YAML uses indentation to show structure, the same way Python does — there's no closing brace to tell you where a block ends, just consistent whitespace:

name: api-server
port: 8080
replicas: 3
tags:
  - production
  - backend
env:
  DEBUG: "false"
  REGION: us-east-1

A colon-and-space separates a key from its value (name: api-server), a hyphen-and-space starts each item in a list (- production), and nesting is expressed purely by how far a line is indented — not by any bracket or tag. Strings usually don't need quotes at all; you only reach for them when a value could otherwise be misread as something else — a number, a boolean, or (as with DEBUG above) a token that looks like one.

YAML vs. JSON

These two are close enough that every valid JSON document is also valid YAML — YAML's spec includes JSON's brace-and-bracket "flow style" as one of its supported notations, alongside the indentation-based "block style" most people mean when they say YAML. The practical difference is readability and features: YAML supports comments (#) and multi-document files, and drops JSON's required quotes and commas — which is exactly why config-heavy formats favor it, and exactly why it's pickier to parse correctly. Whitespace that looks identical can mean different things depending on whether it's spaces or a tab, or how many spaces a sibling key uses. For the full comparison — anchors and aliases, typing, and a real security difference — see JSON vs YAML.

The mistakes that actually bite

• Tabs are invalid for indentation. YAML requires spaces; a single stray tab character produces a parse error, not a silent misread — verified spec behavior, not a lint preference.
• Inconsistent indentation between sibling keys is a parse error too, not just a style complaint — every key at the same nesting level needs the same number of leading spaces.
• The "Norway problem." Under the older YAML 1.1 rules, unquoted no, yes, on, off, and even the country code NO get silently parsed as booleans instead of strings — notorious for turning Norway's ISO code into false in a country list. YAML 1.2's core schema fixed this (those tokens are strings again), but plenty of parsers — including some still defaulting to 1.1 rules — haven't caught up, so quoting anything that looks like a yes/no/on/off token is the safe habit regardless of which schema you're on.
• Multi-document files use a bare --- on its own line to separate documents in a single file — easy to miss if you're only expecting one document and a tool silently only reads the first.

That's the short list — for the mistakes that parse cleanly into the wrong value instead of erroring at all (disappearing leading zeros, an unquoted & or * at the start of a value, null vs. empty string), see Common YAML Mistakes.

Where you'll run into it

YAML is the default configuration format for most of the modern infrastructure tooling stack: Kubernetes manifests, Docker Compose files, GitHub Actions and GitLab CI pipelines, Ansible playbooks, and countless application config files that outgrew a flat .env. If you work with any of those, reading and writing YAML by hand is essentially unavoidable — which is exactly why a parse error in the wrong place is so easy to introduce and so annoying to spot by eye.

For the Kubernetes-specific version of this — apiVersion, kind, the reconciliation model, and why manifests look the way they do — see Kubernetes YAML Explained.

Try it yourself

Paste a file into YAML Validator to catch syntax errors, duplicate keys, tab indentation, and the Norway-problem ambiguity before they cause a confusing failure somewhere downstream. Once it's valid, YAML Formatter re-indents it to a consistent width with comments preserved. Both run entirely in your browser.