YAML Guide: Syntax, Common Errors, and When to Use It

YAML is the default configuration language of the modern toolchain — CI pipelines, Docker Compose, Kubernetes manifests, and countless framework configs. It is designed to be human-readable, which is both its superpower and its trap: because it looks like plain text, its strict syntax rules catch people off guard.

The one rule that matters: indentation

YAML uses indentation (spaces, never tabs) to express structure. A mapping's values are indented under their keys, and the indentation level defines nesting. Inconsistent indentation is the number one source of YAML errors, and because the error often surfaces at parse time far from the actual problem, it is also the most frustrating one. Pick two spaces and never mix in tabs.

Core syntax

• Mappings — key-value pairs with key: value (note the space after the colon)
• Nested mappings — indent the child keys under the parent
• Arrays — a list of items prefixed with - , either at the same indentation or nested
• Inline forms — key: [a, b, c] for arrays and key: {a: 1} for maps, mirroring JSON

Example:

server: host: api.example.com ports: - 443 - 8443 env: production

Scalar types: beware implicit typing

YAML guesses types from the text. true and false become booleans, numbers become numbers, and null, ~, or an empty value becomes null. That implicit typing is convenient and dangerous: a value like yes can be read as a boolean in some YAML versions, and an ID like 00123 may become the number 123. When a value must stay a string, quote it: "yes" or "00123".

Strings and quoting

Plain (unquoted) strings are the default and work for most values. Quote values that contain special characters — colons followed by spaces, leading special characters, or text that could be misread as another type. Double quotes process escape sequences like ; single quotes treat everything literally. Multi-line strings use | (literal block) or > (folded block) after the key.

Common errors

• Tabs instead of spaces — illegal in YAML indentation
• Inconsistent nesting — sibling keys at different indent levels break the mapping
• Missing space after the colon — key:value is invalid
• Unquoted special values — yes, no, null, and numbers get coerced
• Duplicate keys — later entries silently override earlier ones in most parsers
• Confusing - (array item) with a plain hyphen in text — quote text that starts with a dash

YAML vs JSON

YAML and JSON are different syntaxes for the same data model: JSON documents are valid YAML 1.2, and most YAML tooling can emit JSON. YAML wins for human-written configuration because comments are supported and the syntax is lighter. JSON wins for machine-to-machine data, where its strictness is a feature and there is no indentation to get wrong. If a config grows complex enough that YAML's implicit typing starts causing bugs, some teams switch to JSON or a typed alternative — but for most config files, YAML's readability is worth its quirks.

Validate before you commit

YAML errors surface when a tool tries to parse the file, sometimes minutes into a deploy. Validate before committing: YAML Validator parses your document in the browser and reports the line of any syntax error, with the file never leaving your device. Fix indentation and quoting issues before they reach the pipeline — and if you are also working with JSON, the JSON Formatter covers that format the same way.