← All articles
Updated May 29, 20266 min read

YAML Formatter: Format, Re-Indent, and Validate YAML

A YAML formatter re-indents and normalizes YAML so it is readable and diff-friendly. Learn the indentation rules, type traps, and when to format vs convert to JSON.

YAML is whitespace-significant, so a stray tab or an inconsistent indent doesn't just look untidy — it changes the meaning or breaks the parse. A YAML formatter fixes that: it re-indents your YAML to a consistent depth, normalizes spacing, and (optionally) sorts keys, so the file is readable and produces clean diffs. This guide explains what a YAML formatter does, the indentation rules it enforces, the type traps to watch for, and when to format YAML versus convert it to JSON.

What a YAML Formatter Does

A formatter parses your YAML into a data structure and re-serializes it with consistent style. The data is unchanged — only the presentation is normalized:

  • Re-indents every level to a fixed width (commonly 2 spaces) and replaces tabs with spaces
  • Normalizes spacing around colons, list dashes, and inline collections
  • Optionally sorts keys for a canonical, diff-friendly ordering
  • Validates as a side effect — if it can't parse, you have a syntax error to fix first
# Before — mixed indentation, hard to scan
server:
    host: api.example.com
    ports:
    - 8080
    - 8443
database: {name: mydb, pool: 5}

# After — 2-space indent, normalized
server:
  host: api.example.com
  ports:
    - 8080
    - 8443
database:
  name: mydb
  pool: 5

Why Format YAML

  • Readability — CI pipelines, Kubernetes manifests, and Docker Compose files get deeply nested; consistent indentation makes them scannable.
  • Clean diffs and reviews — normalized formatting (and sorted keys) means a pull request shows only real changes, not whitespace noise.
  • Catching errors early — formatting only succeeds on valid YAML, so a formatter doubles as a quick validity check.
  • Consistency across a team — one style, applied automatically, instead of per-author indentation habits.

The Indentation Rules a Formatter Enforces

Most YAML errors are indentation errors, and they're exactly what a formatter standardizes:

  • Spaces only — never tabs. YAML forbids tab characters for indentation. A single tab is the most common "why won't this parse?" YAML bug.
  • Consistent depth. Sibling keys must be indented by the same number of spaces relative to their parent. A formatter rewrites everything to one fixed width.
  • List alignment. Items in a block sequence (-) line up under their key; a formatter normalizes whether the dash is indented or flush.

Type Traps When You Reformat

Formatting preserves data, but YAML's type inference can still surprise you when values are unquoted — worth knowing before you trust the output:

  • The "Norway problem." Unquoted NO, yes, on, off may be read as booleans, so the country code NO becomes false. Quote such values to keep them strings.
  • Leading zeros and big numbers.007 can lose its zeros if read as a number; very large integers can lose precision. Quote IDs that must stay strings.
  • Dates and timestamps. Some parsers coerce unquoted date-like strings into timestamp types. Quote them if you need the literal string.

Block Style vs Flow Style

YAML has two ways to write collections: block (indented, line-oriented) and flow (inline, JSON-like with [] / {}):

# block
ports:
  - 80
  - 443

# flow (same data)
ports: [80, 443]

Formatters typically normalize to block style for readability. Flow style is JSON-compatible — useful when embedding YAML inside JSON-only tooling — but harder to scan as nesting grows.

Anchors and Aliases: Reusable Snippets

& marks an anchor; * references it. Useful for sharing config across services without copy-paste, and formatters preserve them:

defaults: &defaults
  retries: 3
  timeout: 30
api:
  <<: *defaults
  url: https://api.example.com
worker:
  <<: *defaults
  url: https://worker.example.com

Note: anchors and aliases vanish when you convert to JSON — JSON has no reference type, so the values are inlined. Round-tripping YAML → JSON → YAML loses them.

Lint Beyond Parsing: yamllint

A formatter normalises shape; yamllint enforces a style guide (line length, key ordering, document start markers, truthy values, comment spacing). Pair them in CI: format first, then lint with the rules your team picks.

Format YAML vs Convert to JSON

Formatting keeps the file as YAML — best when humans will keep editing it. Converting to JSON is for when a program needs to consume it (most apps only parse JSON at runtime). Since YAML 1.2 is a strict superset of JSON, the conversion is lossless for data; see Convert YAML to JSON and JSON vs YAML for when to use each.

Format and Validate YAML in Your Browser

Paste your YAML into fixjson's YAML validator and formatter and click Format YAML to re-indent and normalize it, or To JSON to convert. It reports the exact line of any syntax error, and everything runs in your browser — no upload, which matters for config files that contain hosts, secrets, or internal settings.

Frequently Asked Questions

What does a YAML formatter do?

It parses your YAML and re-serializes it with consistent indentation and spacing (and optionally sorted keys), so the file is readable and diff-friendly. The data is unchanged — only the formatting is normalized.

Why does my YAML fail to parse?

Almost always indentation: a tab character (YAML forbids tabs for indentation) or sibling keys at inconsistent depths. A formatter rewrites everything to a single space-based width, which surfaces and fixes most of these.

Does formatting YAML change my data?

No — it only changes whitespace and key order. Watch unquoted values, though: YAML may infer types (the "Norway problem"), so quote values like NO or 007 that must stay strings.

Should I format YAML or convert it to JSON?

Format when humans keep editing the file; convert to JSON when a program consumes it. Many teams author YAML and convert to JSON at load time.

Related Tools & Guides