YAML Formatter & Validator

YAML is a data format designed to be written and read by people. It carries the same shapes as JSON — mappings, sequences, scalars — but expresses nesting with indentation rather than brackets, and it allows comments.

1# YAML                        JSON2name: api                    {3replicas: 3                    "name": "api",4ports:                         "replicas": 3,5  - 8080                       "ports": [8080, 8443]6  - 8443                     }

That difference is why nearly every configuration format of the last decade chose it: Kubernetes, Docker Compose, GitHub Actions, GitLab CI, Ansible, Helm. These are files people edit by hand, and comments explaining why a value is what it is matter more than parsing speed. A scheduled job in one of them is still a bare cron expression inside a YAML string, with nothing in the file to say what it means.

The cost is that YAML is genuinely complicated. It has six ways to write a scalar, two collection styles, anchors and aliases, tags, multiple documents in one file, and typing rules that guess what you meant. Most YAML problems come from that last one.

A YAML formatter rewrites a file with consistent indentation, spacing and quoting, without changing what it means. The document that comes out holds exactly the data that went in.

1name:   api2ports:3    - 80804    -   84435labels: {app: api,tier: backend}

1name: api2ports:3  - 80804  - 84435labels: { app: api, tier: backend }

Why it matters more in YAML than in most formats: indentation is the structure. In JSON a stray space is invisible; in YAML it decides which block a key belongs to. Consistent formatting is how you see that a key is nested one level deeper than you thought.

It also makes diffs honest. When everyone’s editor formats the same way, a changed line in a manifest is a changed value — not someone’s editor reflowing the file around it — so a diff of two versions shows only what somebody meant to change.

A YAML validator reads a file and reports what is wrong with it before something downstream tries to use it. That timing is the whole value.

A broken Kubernetes manifest fails at kubectl apply. A broken workflow fails after you push. A broken Compose file fails when the stack comes up — sometimes in front of people. Every one of those loops is minutes long, and every one of them is avoidable by checking the syntax locally first.

Two findings here are worth more than the rest, because nothing else reports them:

• Duplicate keys. Most parsers keep the last one and say nothing. The earlier value is discarded silently — which is how a config file stops doing what it visibly says.
• An alias with no anchor. The file parses. It then throws the moment anything reads the data, so it passes a naive syntax check and fails at deploy time.

What this does not do is check a schema. It will tell you a Kubernetes manifest is valid YAML; it will not tell you that replicas was spelled replica. That needs kubectl --dry-run=server, and the two checks are complementary rather than alternatives.

The file is parsed into a tree that keeps not only the data but where every comment sat and how every scalar was written. The tree is then written back out with consistent indentation.

Keeping the comments is the hard part, and the reason most YAML libraries cannot format: a parser that produces plain JavaScript objects has already thrown them away. Preserving them needs the parse to retain the syntax as well as the meaning.

Some things are deliberately never touched, because rewriting them would change what the file says:

• Block scalars. Inside a | literal block every line break is content. Re-indenting a multi-line script in a CI file changes the script.
• Anchors and aliases.An alias is expanded into duplicated content by naive formatters, turning a small file into a large one and losing the author’s intent. They stay as references.
• Quoting that carries meaning. "1.10" is a string and 1.10 is the number 1.1. Removing those quotes would silently change a version number.

The guarantee is tested rather than asserted: for every sample and every combination of options, the tool parses the input and the output and compares the data. If formatting ever changed a value, a type, or the order of a list, that test fails.

Indentation rules

Indentation is YAML’s only way of expressing nesting. Every key in the same mapping needs the same indentation, and a nested block needs more than its parent. Tabs are forbidden outright — a tab has no defined width, so the same file would nest differently in different editors.

Mapping and sequence validation

A mapping entry needs a key, a colon, and a space after the colon. A sequence item needs a dash and a space. Both are checked, along with the case that catches people out: a key and its colon must be on the same line, so a missing colon shows up as “a key spans more than one line” on the line after the mistake.

Anchors and aliases

An anchor &name labels a node; an alias *name refers back to it; a merge key <<: *name folds one mapping into another. All three are resolved. An alias with no matching anchor is reported as an error, which most parsers do not do.

Multi-document validation

A single file can hold several documents separated by ---, which is how a Kubernetes manifest ships a Deployment, a Service and a ConfigMap together. Each is parsed and validated independently, and every finding says which document it came from.

Tags

!Ref and !GetAtt are not YAML — they are CloudFormation intrinsics written as YAML tags. A generic parser reports them as unresolved, on every line, in a template that is perfectly correct. This tool recognises the CloudFormation and Ansible tag sets and names them instead, because a validator that lights up a working file teaches people to ignore it.

• Mappings and sequences, nested to any depth, in both block and flow style.
• Anchors and aliases, kept as references rather than expanded.
• Merge keys. <<: *defaults is resolved — without it, the key is read as one literally named << and the merged values are simply absent.
• Literal blocks (|) keep every line break. This is how multi-line shell scripts live inside a pipeline.
• Folded blocks (>) join their lines with spaces — for long prose that should read as one paragraph.
• All scalar types: strings, integers, floats, booleans, null, dates, and every quoting style.
• Multiple documents separated by ---, with ... end markers.
• Comments, preserved with their placement.

Tabs instead of spaces

The most common YAML error there is, and the least obvious, because a tab looks like spaces. YAML forbids tabs in indentation entirely. Set your editor to insert spaces for .yaml files and the problem never recurs.

Bad indentation

1spec:2  replicas: 33   selector:      # one space too many4     app: api

Every key at the same level needs the same indentation. A single extra space makes a key part of a different block — sometimes legally, which is worse, because the file parses and means something else.

Missing colon

The error usually points at the line after the mistake, reported as a key spanning more than one line: the parser is still looking for the colon it never found.

Duplicate keys

1env:2  LOG_LEVEL: debug3  LOG_LEVEL: info    # the first one is silently discarded

Invalid lists

A sequence item needs a dash and a space. -itemis the string “-item”, not a list entry — and it parses cleanly, so nothing complains until the value turns out to be the wrong shape.

Implicit typing

1country: NO        # false, under YAML 1.1 rules — the "Norway problem"2version: 1.10      # the number 1.1 — the trailing zero is gone3enabled: yes       # boolean true, not the string "yes"4port: 08           # an invalid octal number

Quote anything that is meant to be a string, and every one of these disappears.

• Use spaces, never tabs. Configure your editor once, per file type, and stop thinking about it.
• Two spaces per level, consistently. YAML nests deeply and four runs out of line quickly. What matters more than the number is that it never changes within a file.
• Quote anything that must stay a string. Versions, country codes, ports, booleans-as-text, anything with a leading zero. This is the single highest-value habit in YAML.
• Validate before deploying. Locally, in a pre-commit hook, and in CI. A syntax error found in an editor costs seconds; the same error found by a pipeline costs minutes and a broken build.
• Comment the surprising, not the obvious. # replicas above replicas: helps nobody. # 3 minimum for the rolling update to work is the reason someone will need in six months.
• Use anchors for genuine reuse, sparingly. They remove duplication, and a file with a dozen of them is harder to read than the repetition would have been.
• Keep files small and split by concern. Multi-document files are supported everywhere; one enormous manifest is harder to review than five focused ones.
• Never commit secrets. YAML config sits in version control by definition. Use a secret store and reference it.