YAML Formatter

What is a YAML Formatter?

YAML puts all its meaning in whitespace, which is great until a file has been edited by four people with four different editor configs. You end up with a manifest indented three spaces in one block and five in the next, list items that hang at odd offsets, and a review diff full of noise that has nothing to do with the change. This page takes whatever you paste and writes it back out with consistent two-space indentation, one style throughout.

Under the hood it is js-yaml: yaml.load() turns your text into a plain JavaScript value, then yaml.dump() serialises that value again with indent: 2, lineWidth: 100 and noRefs: true. That round trip is why the formatting is genuinely uniform — the output is generated fresh from the data rather than patched in place. It also parses to the YAML 1.2 core schema, so what you see is what a modern parser sees.

The same round trip is why comments do not survive. js-yaml keeps no record of them — they exist in the text, not in the data — so the formatted output has none. It also normalises quoting ('internet' becomes internet) and expands anchors and aliases into duplicated blocks. If your YAML is documented with # notes, treat this tool as a way to inspect and tidy a copy, not as a replacement for the file in your repo. There is no setting that changes this; preserving comments requires a parser that keeps a concrete syntax tree, which js-yaml does not.

Everything runs in the browser tab. Nothing is uploaded, cached, or logged — which matters here more than on most pages, because YAML is exactly where registry credentials, database passwords, and API tokens tend to live.

How to Format YAML

1. Paste or Upload Your YAML – Drop a manifest, playbook, compose file, or CI pipeline into the left panel, or use Upload to load a .yaml / .yml file from disk.
2. Read the Output as It Appears – There is no Format button. A 300 ms debounce re-parses after you stop typing, so the right panel always reflects what is in the editor right now.
3. Check What Changed Besides Indentation – Scan for missing # comments, quotes that were dropped, and anchors that were expanded into repeated blocks. All three are expected; none of them are recoverable from the output.
4. Fix Errors Using the Reported Line – A broken document produces a message like Invalid YAML (line 12, column 5): bad indentation of a mapping entry. Count to that line in the left editor — the cause is almost always there or one line above.
5. Copy or Download – Copy puts the formatted YAML on your clipboard; Download saves it as formatted.yaml. Diff it against the original before you commit, so the comment removal is a decision rather than a surprise.

Pro Tip: Point your editor at the file instead when comments matter. Set "editor.insertSpaces": true and "editor.tabSize": 2 for YAML and you get consistent indentation while you type, with every comment intact. Use this page for the files you did not write — a config someone pasted into a ticket, a generated manifest, a snippet from a wiki.

Example

A subscriber provisioning file with drifting indentation. On the right, the same document at a uniform two spaces — and note what else moved: the two # comments are gone, and 'Unlimited 5G' lost its now-unnecessary quotes. The quoted "NO" and "1.20" keep their quotes, because dropping them would change their type.

# provisioning defaults
subscriber:
     msisdn: "447700900142"
     plan:      'Unlimited 5G'
     roaming: true
     country: "NO"   # keep Norway
     firmware: "1.20"
radio:
       cellId: 21453
       rsrp: -92

subscriber:
  msisdn: '447700900142'
  plan: Unlimited 5G
  roaming: true
  country: 'NO'
  firmware: '1.20'
radio:
  cellId: 21453
  rsrp: -92

Read This Before You Overwrite Anything

Comments are the main reason teams pick YAML over JSON. The # leave qci at 9 until the core upgrade line next to a value is often the only place that decision is written down. A load/dump round trip deletes every one of them, and no amount of care on your side changes that — the parser hands back data, and data has no comments attached.

So the safe workflow is: format a copy, read it, fix what the reformatting revealed, and apply that fix to the original file by hand. What is genuinely lost if you paste the output over your source: every # comment including the license header; deliberate quoting styles such as single quotes or block scalars where a plain scalar would do; and anchors and aliases, which are expanded so that one shared block becomes five identical copies. Key order and blank-line grouping survive key order but not the blank lines.

If a note has to survive machine processing, promote it to a real key — _note: "keep qci at 9 until the core upgrade" is data, and data round-trips fine. And if you need true comment-preserving reformatting, you need a library that keeps a concrete syntax tree, such as eemeli's yaml package, or your editor's own YAML formatter, which edits the text in place instead of regenerating it.

YAML Gotchas Worth Knowing

Tabs Are Illegal for Indentation

Not discouraged — illegal. The spec forbids tab characters in indentation, and every conformant parser rejects them. The cruel part is that a tab-indented file looks perfectly aligned in your editor, so you stare at correct-looking YAML while the parser insists it is broken. This page checks for a leading tab before parsing and tells you the exact line, instead of letting js-yaml report a confusing "bad indentation" two lines later. Fix it by configuring your editor to expand tabs to spaces for .yaml and .yml.

Indentation Is the Syntax

In JSON, braces define structure and whitespace is decoration. In YAML the whitespace is the structure, so a single extra space moves a key from one parent to another and the file still parses — it just means something different. That is the dangerous class of bug: not a crash, but a value silently attached to the wrong block. Formatting helps because once everything is at a uniform two spaces, a key sitting at the wrong depth is visible at a glance. Also note that list items may sit at the same column as their parent key, which trips people up but is perfectly legal.

The Norway Problem: country: NO

YAML 1.1 treats yes, no, on, off, y and n as booleans. So country: NO — Norway's ISO 3166 code — parses as false, and a country list quietly loses a member. YAML 1.2 narrowed booleans to true and false, and js-yaml follows 1.2, so this page keeps NO as a string. Do not rely on that: PyYAML, Ruby's Psych, and older Go YAML libraries still follow 1.1, and your file will probably be read by one of them. Quote it — country: "NO" — and every parser on earth agrees.

Unquoted Version Strings Lose Digits

version: 1.20 is not a string, it is the float 1.20, and the float 1.20 is the number 1.2 — the trailing zero carries no arithmetic meaning. Format that file and it comes back as version: 1.2, which is a different release. Same trap catches long identifiers: an unquoted 19-digit iccid exceeds JavaScript's safe integer range and comes back with the tail rounded off. Anything that is an identifier rather than a quantity — versions, ICCIDs, IMSIs, MSISDNs, ZIP codes, build numbers — belongs in quotes.

YAML Is a Superset of JSON

Any valid JSON document is already valid YAML 1.2, so you can paste JSON into the left panel and this formatter will happily turn it into block-style YAML. Handy when you want to read an API response with fewer braces, or when you are not sure which format a snippet is. It also explains why so many tools accept one --values flag for both. Going the other way is not symmetric: YAML has comments, anchors, multi-document streams, and non-string keys, none of which JSON can express — see YAML to JSON for what that costs.

Common Use Cases

Cleaning Up a Kubernetes Manifest

Manifests accumulate mixed indentation faster than most files because they get copied out of blog posts, generated by templates, and hand-edited under pressure. Formatting one gives you a single consistent style, so the next diff shows only what actually changed. Do it on a copy: the # owned by the payments team line above a namespace is exactly the kind of comment you do not want to silently delete. The Kubernetes object docs explain the fields once the shape is readable.

Making Sense of a Pasted Config

Someone drops a snippet into a ticket and the indentation has been mangled by the chat client. Rather than fixing it by eye, paste it here — if it parses, you get a clean version and you know the structure is sound; if it does not, you get a line number to argue about. This is where the formatter earns its keep, because a snippet from a ticket has no comments worth protecting.

Reviewing a CI Pipeline Before It Runs

A GitHub Actions or GitLab CI file that fails to parse costs you a full push-and-wait cycle to find out. Formatting it locally is a two-second check that the document is well formed and that every step sits at the depth you meant. If two versions need comparing, format both the same way first — then an online text comparison tool shows real changes instead of whitespace noise.

Normalising Files Before a Diff

Two configs that behave identically can diff badly because one uses four-space indentation and quotes every string. Run both through the formatter and the diff collapses to the handful of lines that genuinely differ. Just remember both outputs are comment-free, so use them for reading, not for committing.

Key Features

• Consistent Two-Space Indentation – Output is regenerated with indent: 2, so nesting depth is uniform from the first line to the last.
• Honest About Comment Loss – The notice sits above the editor, not buried in an FAQ, because pasting the output over a documented config is a real way to lose work.
• Tab Detection – Indent with a hard tab and you get a message naming the line, instead of a cryptic indentation complaint from the parser.
• Real Line and Column Numbers – js-yaml reports 0-based positions; this page adds one before showing them, so the number matches your editor's gutter.
• Anchors Expanded, References Resolved – noRefs: true means the output has no &anchor / *alias indirection to chase while reading.
• Runs Entirely in Your Browser – No upload, no server, no logging. Safe for files that contain secrets.

Frequently Asked Questions

Why did the formatter delete my comments?

Because formatting is a round trip: yaml.load() converts your text into plain data, and yaml.dump() writes new text from that data. Comments live in the text, not in the data, so they are gone by the time the output is written. This is a property of js-yaml, not a setting — there is no flag to turn on. Keep the original file and apply fixes to it by hand, or use a comment-preserving library such as yaml if you need reformatting in an automated pipeline.

What else changes besides indentation?

Three things. Quoting is normalised — unnecessary quotes are dropped and quotes are added where a plain scalar would be ambiguous. Anchors and aliases are expanded, so a block shared five times becomes five copies. And blank lines used for visual grouping disappear. Key order is preserved (sortKeys: false), and no value is changed — a string stays a string, a number stays a number.

Why does my file fail with a tab error?

YAML forbids tab characters in indentation, full stop. Any editor configured to insert a hard tab will produce a file that looks correctly aligned and refuses to parse in every conformant tool. This page checks the leading whitespace of each line before parsing and names the first offending line, because js-yaml's own message often points somewhere else. Tabs inside a value are fine; it is only indentation that is illegal.

Does formatting change my values?

No. Formatting rewrites the presentation, not the data. But be aware that YAML's type inference already happened when your file was written: an unquoted 1.20 was a float before it reached this page, so it comes out as 1.2. That is not the formatter changing your value — it is the formatter showing you what your file has always meant. Quote it in the source if you wanted a string.

Can I format multi-document YAML?

The formatter reads the first document in a ----separated stream, because a load/dump pair produces a single document. If you need every document formatted, split the file on the --- markers and format each part separately, then reassemble. Multi-document streams are common in Kubernetes bundles, so it is worth checking whether your file has more below the fold.

Is JSON accepted as input?

Yes. YAML 1.2 is a strict superset of JSON, so a JSON document parses cleanly and comes back as block-style YAML with two-space indentation. It is a quick way to read a dense API response. For the deliberate conversion with its own page and options, see JSON to YAML.

Why is the line number in the error one off from what js-yaml prints?

It is not — it is corrected. YAMLException.mark.line and .column are both 0-based, so the raw values are one lower than your editor's gutter. This page adds one to each before displaying, so the number you read is the number you scroll to.

Is my data safe?

Yes. Parsing and formatting run entirely in your browser with js-yaml. Nothing is transmitted, stored, or logged. That matters for YAML specifically — Helm values files, CI configs, and Ansible vars are where credentials tend to sit.

What indentation does the output use?

Two spaces per level, which is the community convention and what Kubernetes, GitHub Actions, and Docker Compose examples all use. Lines wrap at 100 characters. If your team standardises on four spaces, format here for readability and re-indent in your editor before committing.

Related Tools

• YAML Validator – Check a document parses and see the error line without rewriting anything.
• YAML to JSON – Convert a config to JSON for jq, schema validation, or an API body.
• JSON to YAML – The reverse trip — turn a JSON payload into readable block-style YAML.
• YAML to Table – Render a list-shaped YAML file as a sortable table to sanity-check the data.
• JSON Formatter – Same idea for JSON — and JSON has no comments to lose.

Useful Resources

• YAML 1.2.2 Specification – The official spec — the place to settle arguments about indentation and types.
• js-yaml – The parser behind this page, including every option used by the formatter.
• yaml (eemeli) – The comment-preserving alternative, for when a round trip must keep the notes.
• YAML Multiline Strings – A visual cheatsheet for the pipe, folded, and chomping indicators.
• YAML Lint – A second opinion when you suspect the problem is your parser, not your file.
• Kubernetes Objects – What the fields in a manifest mean once the indentation is readable.