How to Format and Validate YAML (and Convert It to JSON)

YAML is the config format every developer loves to complain about. It looks friendly — just key-value pairs and indentation, no brackets, no semicolons — but it's also the format where one stray space can turn a perfectly good docker-compose.yml into a cryptic mapping values are not allowed here at 11pm on a Friday. We've all been there. This guide shows you how to format YAML properly, catch the mistakes that break it, and convert it to JSON when you need to hand data off to something that doesn't speak YAML.

Why YAML breaks so easily

Most data formats use matching brackets or delimiters to define structure, so a machine can always tell where one block ends and the next begins. YAML does the opposite: it uses indentation only. Two spaces means "this belongs inside the thing above me." That's elegant on paper and brutal in practice, because your eyes are terrible at distinguishing two spaces from three.

The result is that YAML errors are almost never in the place where the parser finally complains. You'll get an error on line 40 for a mistake you actually made on line 12, because a block opened by line 12 never got closed the way the parser expected. This is why a validator that points at the exact offending line — rather than the place the error finally surfaced — saves so much time.

The most common YAML mistakes

After years of debugging other people's configs (and our own), these are the five mistakes we see over and over:

1. Tabs instead of spaces

YAML forbids tabs for indentation, full stop. The problem is that your editor doesn't always tell you when a "space" is actually a tab, so you end up with a file that looks perfectly aligned and still fails to parse. Most IDEs have a "show whitespace" toggle — turn it on when you work with YAML, or configure the file type to insert spaces automatically.

2. Inconsistent indentation depth

Every level has to be indented by a consistent number of spaces — two is the convention, and it's what Docker Compose, Kubernetes, and Ansible all use. A file that switches from two spaces to three, or that indents a sibling at a slightly different depth, will throw a "bad indentation of a mapping entry" or simply nest things where you didn't intend.

3. Missing space after the colon

key: value works; key:value is a single scalar, not a key-value pair. It's an easy typo to make and an annoying one to spot, because it looks almost identical at a glance.

4. The "Norway problem" (yes/no as booleans)

This one is a classic. Under YAML 1.1, the words yes, no, on, and off are treated as true / false. So a line like country: no — which a Norwegian developer might reasonably write — silently becomes false. If you need the literal word, quote it: country: "no".

5. Unquoted values with special characters

Colons, #, and leading/trailing spaces inside a value all need quoting. A URL like https://example.com contains a colon followed by a non-space, which older parsers read as a nested mapping. When in doubt, wrap the value in quotes — it never hurts and it removes a whole class of ambiguity.

How to format and validate YAML step by step

Once you know what to look for, cleaning up a messy YAML file takes one paste into our free YAML Formatter:

• 1.Paste your YAML into the input box.
• 2.Click Format. The tool re-indents the document with consistent spacing and highlights the structure, so nested blocks are obvious at a glance.
• 3.Watch for the status message. If the YAML is valid, you'll see a green "Valid YAML/JSON" confirmation. If not, you'll get a red error telling you what's wrong and where to look.
• 4.Click Copy in the top-right of the output to grab the clean result.

Because the formatter re-indents as part of the format step, it also fixes the most common cause of "it worked on my machine but not in CI" — inconsistent whitespace — without you having to chase it manually.

Converting YAML to JSON (and back)

YAML and JSON represent almost the same data model — mappings, sequences, strings, numbers, booleans — so converting between them is lossless for the vast majority of real-world data. That's useful more often than you'd think:

• Handing config to a tool that only reads JSON — a test runner, an API endpoint, or a cloud function that expects a JSON body.
• Shrinking a config for humans — JSON is compact but noisy; YAML is the same data with all the braces and commas stripped out, which is why so many projects keep their canonical config in YAML.
• Comparing two configs — sometimes it's easier to diff two JSON documents than two YAML documents, because the structure is explicit.

The formatter handles both directions in one click — YAML to JSON and JSON to YAML — so you don't need yq, Python, or a Node script installed to do the conversion.

A real example: the misaligned docker-compose.yml

Here's a docker-compose.yml that someone pasted from Slack, complete with the indentation drift that crept in:

The db block is indented three spaces while everything else uses two. Docker Compose reads this as a syntax error, but the message it prints won't point at the three-space line — it'll complain about a mapping somewhere below. Paste it into the formatter and hit Format, and the document comes back aligned:

version: '3'
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
  db:
    image: postgres:13
    environment:
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: myapp

Same data, same keys, but now every block nests the way you intended — and docker compose up stops complaining.

Why it runs entirely in your browser

Config files are rarely harmless. A docker-compose.yml or a Kubernetes manifest routinely contains database passwords, API keys, internal hostnames, and the exact shape of your infrastructure — the last thing you want sitting in a log on someone else's server. That's why the YAML Formatter processes everything locally: your config is never uploaded, never stored, and never leaves your device. Paste a manifest with real secrets in it, and it stays on your machine.

Frequently asked questions

Working with JSON data too? Learn how to clean it up in How to Format and Validate JSON, or pull specific values out of it with How to Query JSON with JSONPath.