← All articles
Updated May 29, 202613 min read

YAML Formatter: Re-Indent and Validate

Format YAML without hiding config bugs: fix indentation, catch parser errors, handle anchors, comments, type coercion, sorting, and YAML-to-JSON output.

YAML looks forgiving until one extra space changes a deployment file. A YAML formatter helps by parsing the file, rebuilding the indentation, and reporting the first syntax error with a useful line and column. That is great for Kubernetes manifests, GitHub Actions workflows, Docker Compose files, OpenAPI snippets, Ansible playbooks, and app config that people still edit by hand.

The important detail: YAML formatting is not just "make it pretty." Most formatters load the YAML into a data model and dump it back out. The parsed data should stay the same, but comments, blank-line layout, quote style, anchors, aliases, and flow-vs-block style may not survive exactly. Treat formatting as a safe step for data-oriented config, and be more careful when the YAML file is also documentation.

This guide uses the same practical behavior as the YAML tool on this site: parse with js-yaml in JSON_SCHEMA mode, format YAML with 2-space indentation, optionally sort keys, report parser line/column errors, and convert the parsed value to JSON when needed.

The Short Version

Task Use a YAML formatter? Watch for
Fix mixed indentation before a code review Yes The file must parse first
Normalize Kubernetes or Docker Compose config Yes Comments and anchors may be rewritten or dropped
Find the line causing a YAML parse failure Yes The reported line is the parser's best failure point, not always the root cause
Enforce team style in CI Pair with a linter A formatter is not a full style policy
Convert YAML to JSON for an app Yes, after validation YAML-only features do not round-trip to JSON
Preserve comments, exact blank lines, and quote choices Use caution Parse-and-dump formatters are data-oriented

If you only remember one rule: format after the file parses, lint after it formats, and quote any value that must stay a string.

What a YAML Formatter Actually Does

A YAML formatter usually follows this pipeline:

  1. Parse the YAML text.
  2. Build an internal value: objects, arrays, strings, numbers, booleans, and nulls.
  3. Dump that value back to YAML with consistent options.
  4. If parsing fails, return the syntax reason plus a line and column.

For example, this file is valid but messy:

server:
    host: api.example.com
    ports:
    - 8080
    - 8443
database: {name: app, pool: 5}

A formatter can rewrite it into a predictable shape:

server:
  host: api.example.com
  ports:
    - 8080
    - 8443
database:
  name: app
  pool: 5

The values did not change. The representation did. That distinction matters when you review diffs: a formatting-only PR should show indentation and layout changes, not new keys, deleted services, or changed scalar values.

How This Site Formats YAML

The YAML tool on fixjson.org is intentionally conservative and browser-local:

  • It parses YAML with js-yaml.
  • It uses JSON_SCHEMA, so the result stays close to JSON-compatible types.
  • Format YAML dumps YAML with 2-space indentation.
  • It uses a 120-character line width.
  • Sort keys sorts object keys when you want stable diffs.
  • To JSON converts the parsed YAML value to pretty-printed JSON.
  • Parser errors include line and column information, and the editor highlights the failing line.
  • Tool input is processed in the browser, which is useful for internal config that should not be uploaded.

The implementation detail is worth knowing because "YAML formatter" can mean different things in different tools. Some tools preserve comments. Some rewrite them. Some use YAML 1.1 typing. Some use YAML 1.2-style typing. Some preserve anchors. Some expand them. If your config is business-critical, test with the same parser your runtime uses.

Formatting Is Not Repair

A formatter can normalize valid YAML. It cannot always fix invalid YAML because it may not know what structure you intended.

This is invalid:

server:
  host: api.example.com
    port: 443

The formatter can tell you the parser got stuck near port, but it cannot safely choose between these two meanings:

server:
  host: api.example.com
  port: 443

server:
  host:
    name: api.example.com
    port: 443

One version makes port a sibling of host; the other nests it under host. Those are different data models. A good formatter should stop and show the error instead of guessing.

The Indentation Rules That Cause Most Bugs

YAML's block style uses indentation for scope. That is why the same visible keys can mean different data when they move by two spaces.

Use spaces, not tabs

Tabs are not valid indentation in YAML. A file like this fails:

server:
<TAB>host: api.example.com

The practical fix is boring and reliable: configure your editor to insert spaces in .yml and .yaml files, then run a formatter before committing.

Keep siblings at the same depth

These keys are siblings:

image: nginx:1.27
ports:
  - 80

These are not:

image: nginx:1.27
  ports:
    - 80

The second snippet does not mean "image with ports." It is malformed because ports is indented under a scalar string. Formatters catch this quickly because the parser has no valid structure to build.

Align list items under their parent

This is the common style:

services:
  api:
    ports:
      - 8080
      - 8443

Some YAML styles allow less-indented sequences, but mixing styles across a repo makes reviews harder. Pick one convention. For most JavaScript and web projects, 2 spaces with list dashes under the parent key is the least surprising.

Flow Style vs Block Style

YAML supports both block style and flow style. Flow style looks like JSON:

ports: [80, 443]
labels: {app: api, tier: backend}

Block style is easier to scan once the file grows:

ports:
  - 80
  - 443
labels:
  app: api
  tier: backend

Formatters often prefer block style because it produces cleaner diffs. Changing one port in a block list touches one line. Changing one value in a dense flow mapping can make the whole line noisy.

Keep flow style for tiny values where compactness genuinely helps, such as a short coordinate pair or a one-line test fixture. For deployment and CI config, block style usually wins.

Sorting Keys: Useful, But Not Always

Sort keys is helpful when YAML is generated or when you want deterministic diffs:

zebra: true
api:
  timeout: 30
  retries: 3
alpha: true

Sorted output:

alpha: true
api:
  retries: 3
  timeout: 30
zebra: true

That is nice for generated config, snapshots, and files where humans do not rely on local grouping.

Do not blindly sort hand-authored files where order carries meaning for readers. A GitHub Actions workflow is easier to review when related keys stay together: name, on, permissions, jobs. Alphabetical order can move on away from the rest of the execution context and make the file technically clean but harder to understand.

Type Traps: Formatting Can Reveal Them, Not Decide Them

Formatting preserves the parsed value. It does not preserve your intention if the parser inferred a different type than you expected.

In this site's JSON-oriented parser mode:

country: NO
enabled: on
id: 007
active: true
empty: null
date: 2026-07-18

The parsed JSON-like value is:

{
  "country": "NO",
  "enabled": "on",
  "id": 7,
  "active": true,
  "empty": null,
  "date": "2026-07-18"
}

The risky one here is 007: as a number, it loses the leading zeros. Other YAML parsers, especially older YAML 1.1 configurations, may also treat words like yes, no, on, off, or date-like values differently.

Quote string-like values when exact text matters:

country: "NO"
enabled: "on"
id: "007"
date: "2026-07-18"

This is especially important for country codes, ZIP codes, account IDs, feature flags stored as strings, semantic versions, dates that must remain text, and large integers that may exceed JavaScript's safe integer range after conversion to JSON.

Comments, Anchors, and Aliases

This is where "the data is unchanged" needs a footnote.

YAML comments are not part of the parsed data model:

# used by the public API
timeout: 30

A parse-and-dump formatter can output:

timeout: 30

The runtime value is the same. The human note is gone.

Anchors and aliases are also authoring tools:

defaults: &defaults
  retries: 3
  timeout: 30
api: *defaults
worker: *defaults

A JSON-oriented dump may inline repeated values:

defaults:
  retries: 3
  timeout: 30
api:
  retries: 3
  timeout: 30
worker:
  retries: 3
  timeout: 30

Again, the resulting data is usually fine for an app. It is not the same source file from a maintainer's point of view. If anchors, aliases, comments, custom tags, or exact style are important, use a style-preserving formatter or a linter instead of a data-oriented converter.

Multi-Line Strings: Literal vs Folded

YAML has two common block scalar styles:

literal: |
  line one
  line two

folded: >
  line one
  line two

The literal style keeps line breaks. The folded style turns most line breaks into spaces. A formatter may preserve the resulting string value while changing how the string is written. That is acceptable for many config values, but dangerous for shell scripts, certificates, private keys, Markdown snippets, or anything where line breaks are meaningful.

For values like this, inspect the formatted output before copying it into production:

script: |
  set -e
  npm ci
  npm test

If the formatted result changes a block string into quoted text with escape sequences, the parsed value may still be equivalent, but the file may become harder for humans to maintain.

Formatter vs Validator vs Linter

These tools overlap, but they solve different problems.

Tool What it answers Example use
Validator "Does this YAML parse?" Find the line that breaks a pasted config
Formatter "Can this valid YAML be rewritten consistently?" Normalize indentation before a PR
Linter "Does this match our team's style rules?" Enforce line length, truthy values, comments, and key order in CI
Converter "What is the JSON value behind this YAML?" Feed a YAML config to JSON-only code

For a serious repo, combine them:

yamllint .
yq -P '.' config.yaml

yamllint catches style issues beyond parsing, such as duplicate keys, trailing spaces, line length, and truthy values. yq is useful when you need command-line YAML transformations or YAML-to-JSON conversion in scripts.

A Safe Review Workflow

When a YAML change matters, avoid mixing functional edits and formatting in one diff.

Use this sequence:

  1. Validate the original file.
  2. Format it without changing values.
  3. Commit or review the formatting-only diff.
  4. Make the actual config change.
  5. Validate again.
  6. Run the tool that consumes the YAML.

For example:

# inspect the parsed value
yq -o=json '.' docker-compose.yml

# lint style
yamllint docker-compose.yml

# run the consumer's own config check when available
docker compose config

The last command is the most important one. A generic YAML parser can tell you whether the file is valid YAML. It cannot tell you whether a Kubernetes field, Docker Compose service, GitHub Actions permission, or CI matrix option is valid for that product.

Format YAML or Convert YAML to JSON?

Format YAML when the file remains a human-edited source file:

  • CI workflow files
  • Docker Compose files
  • Kubernetes manifests
  • Ansible playbooks
  • App config with comments
  • Documentation examples

Convert YAML to JSON when another program needs JSON:

  • Browser code that only accepts JSON
  • API clients and test fixtures
  • Build steps that normalize config before loading it
  • Tools that compare structured data as JSON

YAML 1.2 was designed so JSON fits inside YAML, but the reverse is not always true in practice. YAML comments, anchors, aliases, document separators, custom tags, and style choices do not have direct JSON equivalents.

Format and Validate YAML in Your Browser

Use fixjson's YAML validator and formatter when you want a quick local pass before committing or sharing a snippet. Paste YAML, click Format YAML to normalize indentation, or click To JSON to inspect the parsed value as JSON.

The browser workflow is useful for pasted config, support tickets, internal examples, and quick debugging because the payload does not need to leave your machine. Still, treat secrets carefully. Redact API keys, tokens, private keys, customer records, and production logs before putting them into any web page, screenshot, chat, or ticket.

Frequently Asked Questions

What does a YAML formatter do?

A YAML formatter parses YAML and writes it back with consistent indentation, spacing, line wrapping, and sometimes sorted keys. If the YAML does not parse, it should report the syntax error instead of guessing a structure.

Does formatting YAML change my data?

It should not change the parsed data, but it can change the source representation. Comments, blank lines, quote style, anchors, aliases, and flow-vs-block style may be rewritten or lost by parse-and-dump formatters.

Why does my YAML fail to parse?

The usual causes are tabs used for indentation, sibling keys at different depths, list items under the wrong parent, unclosed flow collections, or unquoted values that start with YAML indicator characters such as :, -, ?, or #.

Should I use 2 spaces or 4 spaces for YAML?

Use the style your project already uses. Two spaces are common for web, CI, Kubernetes, and Docker examples. The important rule is consistency: sibling keys and list items must line up under the same parent.

Should I sort YAML keys?

Sort keys for generated config, snapshots, and deterministic diffs. Avoid automatic sorting when humans rely on a meaningful order, such as GitHub Actions files where name, on, permissions, and jobs are usually grouped for readability.

Why did 007 become 7 after formatting or converting?

The parser treated 007 as a number, so the leading zeros were not part of the parsed value. Quote IDs, ZIP codes, country codes, versions, dates, and large integers when they must remain exact strings.

Are YAML comments preserved by a formatter?

Not always. Data-oriented formatters parse YAML into values and dump those values back out, so comments may disappear. Use a style-preserving formatter or a linter workflow when comments are part of the file's maintenance value.

Should I format YAML or convert it to JSON?

Format YAML when people will keep editing the file. Convert it to JSON when a program or API needs JSON. If the YAML uses comments, anchors, custom tags, or multiple documents, keep YAML as the source of truth.

Related Tools & Guides

Sources

  • YAML 1.2.2 specification - YAML syntax, indentation, block/flow collections, schemas, anchors, comments, and JSON compatibility.
  • js-yaml - JavaScript YAML parser/dumper used by this site's YAML tooling.
  • yamllint documentation - YAML linting rules beyond parsing and formatting.
  • yq documentation - command-line YAML, JSON, XML, CSV, and properties processor.

Last reviewed July 2026.