YAML Formatter

What formatting actually does

The document is parsed into data and written back out with consistent indentation and spacing. That is a stronger operation than reindenting text, and it has two consequences worth knowing before you paste something important.

First, a malformed document cannot be formatted — it fails with a parse error, which makes the formatter a validator by side effect. Second, comments are lost. Comments are not part of the data, so the round trip through the parser drops them. Your original file is never modified — the result is a new document — but if the comments matter, keep the original.

The Norway problem, and other values that change meaning

This is the single most surprising thing about YAML, and it is the reason a config can parse cleanly and still be wrong. YAML 1.1 treats a set of bare words as booleans: yes, no, on, off, y, n, true, false. So a list of country codes does this:

countries:
  - NO      # becomes false
  - SE
  - "NO"    # stays the string "NO"

Norway’s country code becomes the boolean false. The fix is always the same: quote it. Related traps in the same family —

• version: 1.20 is the number 1.2. Trailing zeros are lost, and version numbers with two dots (1.2.3) are strings while ones with a single dot are numbers, so a list of versions can have mixed types.
• port: 08 is an error and mode: 0644 is not what you think — a leading zero means octal in YAML 1.1.
• time: 12:30 can be read as a sexagesimal number rather than a string.
• An empty value is null, not an empty string. name: with nothing after it does not mean name: "".

YAML 1.2 narrowed the boolean list to just true/false, but which version applies depends on the parser reading your file, not on the file itself. Quoting anything that should be a string is the only portable answer.

Indentation rules

Tabs are forbidden as indentation. Not discouraged — forbidden by the specification, and every parser rejects them. This is the most common hard failure, and it is invisible in most editors:

server:
	port: 8080     # tab — rejected by every YAML parser
server:
  port: 8080     # two spaces — correct

The number of spaces is up to you as long as it is consistent within a block; two is the convention. Formatting here always emits spaces, which is why there is no tab option — it would produce a file most tools reject.

Colons and other characters that need quoting

A colon followed by a space ends a key, so it cannot appear unquoted in a value:

title: Report: Q3     # invalid — second colon ends the key
title: "Report: Q3"  # valid

The same applies to a value starting with @, `, %, *, &, !, { or [ — all are reserved characters. A # preceded by a space starts a comment anywhere in a line, which is how URLs with fragments get silently truncated.

Anchors and aliases are left alone

YAML can define a value once with an anchor (&name) and reference it elsewhere (*name). Formatting does not introduce them: repeated values are written out in full. A formatter that helpfully deduplicated your config would hand back a document you did not recognise, which is the opposite of what tidying is for.

Multi-document files

A single file can hold several documents separated by ---, which is standard in Kubernetes manifests. Formatting works on one document at a time, so split a multi-document file first. The --- at the top of a single-document file is optional and purely conventional.

If you want to check rather than tidy

Formatting fails on an invalid document, so it doubles as a syntax check. But if checking is the whole job, the YAML Validator reports the error without producing a reformatted document — and if you need to see what your YAML actually parsed to, converting it to JSON is the fastest way to catch a Norway problem, because JSON has no bare booleans to hide behind.