YAML Formatter

Significant indentation and the tab error

Unlike JSON, YAML uses indentation to express structure — there are no braces or brackets in block style. Two spaces of extra indent on a line mean "this is a child of the line above." Get the indent wrong and you change the data model, not the cosmetics.

Per the YAML 1.2.2 specification (Section 5.5), YAML recognizes two whitespace characters: space and tab. Tabs are permitted inside scalar content and comments, but they must never be used for indentation. Mixing a tab into indented block context is one of the most common YAML errors — many editors silently insert tabs when you press Tab, and the parser rejects the file with a message that does not obviously point at whitespace.

• Use spaces only — never tabs — for indentation
• Be consistent: pick one indent width (2 spaces is the de facto standard) and stick to it within a file
• A single extra space can move a key into the wrong parent without any syntax error

Scalars, collections, and anchors

YAML has two collection kinds: mappings (key: value pairs, like a JSON object) and sequences (dashed lists, like a JSON array). A scalar is a single leaf value — a string, number, boolean, or null. Scalars are mostly unquoted, but quoting matters for values that look like something else: version: 1.0 parses as a float, while version: "1.0" stays a string, and answer: "yes" avoids the YAML 1.1 boolean coercion that turned yes into true.

For reuse within a single document, YAML supports anchors and aliases. Define a block with &defaults and reference it elsewhere with *defaults. This is invaluable for DRY config (a shared service template referenced by multiple environments), though it cannot cross document boundaries.

# Mapping, sequence, scalar, anchor, alias — all in one
defaults: &defaults
  retries: 3
  timeout: 30
services:
  web:
    <<: *defaults      # merges the anchored mapping
    port: 8080
  db:
    <<: *defaults
    port: 5432

YAML is a strict JSON superset

A primary goal of YAML 1.2 was to make YAML a strict superset of JSON: every valid JSON document is also a valid YAML document, parseable to the same data model. That is why this tool can convert between the two losslessly — JSON is just YAML written in "flow style," with explicit braces and brackets and double-quoted strings.

The reverse is not always true. YAML features that have no JSON equivalent — comments, anchors and aliases, multi-document streams separated by ---, and tags — cannot survive a round-trip to JSON. Converting such a file to JSON strips those constructs, which is fine for handing config to a JSON-only consumer but destructive if you plan to edit the result as YAML later.