YAML Validator

Why YAML is harder than it looks

YAML's appeal is that a simple document needs almost no syntax. The cost is that the parser has to infer a great deal, and most YAML problems come from it inferring something other than what you meant.

Indentation is structure, and it must be spaces - tabs have never been legal, which is why an editor set to insert them produces errors that look like nothing is wrong. Indentation is also relative rather than fixed, so a block indented four spaces and a sibling indented two are a genuine error rather than a style inconsistency.

On top of that, the same data can be written several ways. Block style and flow style, quoted and unquoted scalars, three ways to write null. None of this matters until a value falls into the gap between them, and then it matters a lot.

The implicit typing traps

An unquoted scalar is typed by its shape, and the shapes overlap with things people write as strings.

Version numbers are the classic. Unquoted 1.10 is a float, and floats have no trailing zero, so it becomes 1.1 and your dependency pin silently points somewhere else. Anything with a leading zero has the same problem in reverse: 0755 is the number 755 under YAML 1.2, not an octal file mode, and you need 0o755. Long digit strings - phone numbers, account references, IDs - lose their leading zeros and, past sixteen digits, their precision.

The booleans are the famous one. YAML 1.1 treated yes, no, on, off, y and n as booleans, which is where the Norway problem comes from: a country list containing NO turns into a list containing false. YAML 1.2 core narrowed this to true and false only, which is what this tool follows, but plenty of software in the wild still uses 1.1 parsers - Ruby's Psych and older PyYAML among them - so the safe habit is to quote anything you mean as a string.

Also worth knowing: null can be written null, ~, or nothing at all, so a key with an empty value is a null rather than an empty string. And in YAML 1.1, 22:22 parses as a sexagesimal number rather than a time.

Multi-line strings

Two block scalar indicators cover almost every case, and choosing wrongly is a common source of broken configuration.

The pipe keeps your line breaks exactly as written. This is what you want for a shell script, a certificate, an embedded config file, or anything where the line structure is meaningful. The greater-than sign folds instead: single newlines become spaces and blank lines become newlines, which is right for a long paragraph of prose you want to wrap in the source without wrapping in the value.

Both take a chomping indicator that controls the trailing newline. Plain keeps exactly one, a minus strips all of them, and a plus keeps every one. The minus form matters when a trailing newline would break what consumes the value - a token, a key, an argument - and the plus form when you need the whitespace preserved exactly.

The content is indented relative to the key, and that indentation is stripped from the value. A line indented further than the rest keeps its extra spaces, which is how a script inside a manifest keeps its own structure.

Anchors, aliases and merge keys

An anchor marks a node with & and an alias refers to it with *, letting a document reuse a value it defined earlier. In a CI configuration or a compose file this is what removes the repetition between near-identical jobs or services, and it is one of the genuinely good reasons to be writing YAML rather than JSON.

The merge key, written <<: *base, goes further by folding the keys of an anchored mapping into the current one so you can override a few. It is worth knowing that this is not part of YAML 1.2 core - it is a separate specification that most parsers implement and a few do not, so it is not universally safe.

All of this disappears on conversion to JSON, necessarily. Aliases are resolved into real values before conversion, so an anchor referenced three times becomes three copies of the data rather than three references. Comments go too, since JSON has none. Converting a heavily-anchored configuration to JSON and back therefore gives you a document that means the same thing and is much longer, and this is a one-way trip in terms of readability.

Quoting: when it matters and which quote to use

An unquoted scalar is typed by its shape, so quoting is how you say this is text. Single quotes are literal apart from a doubled single quote meaning one apostrophe: no escapes are processed, so 'C:\path\to' is exactly that string. Double quotes process escapes, so \n becomes a newline and a literal backslash has to be doubled.

The rule that avoids most trouble: use single quotes by default, double quotes only when you need an escape sequence, and quote anything that could be read as another type. That covers version numbers, values that are only digits, anything starting with a zero, and the words yes, no, on and off.

A few characters force quoting wherever they appear in a value: a colon followed by a space, a hash preceded by a space, and a leading &, *, !, %, @ or backtick. A value that begins with a curly brace or a bracket starts flow style, so a Jinja or Helm template like {{ .Values.name }} must be quoted or the parser reads it as a nested mapping.

The mistakes that break Kubernetes and CI files

Indentation of list items is the first. A sequence under a key may be indented or aligned with the key, and both are legal, but the items in one sequence must agree with each other. Mixing them inside a file that has been edited by several people produces an error whose reported line is often somewhere else entirely.

Multi-document files are the second. Three dashes separate documents, and a tool that reads only the first will silently ignore everything after the separator - which is how a Kubernetes manifest applies the Deployment and not the Service. kubectl handles multiple documents; plenty of scripts using a language's default load function do not, and need the load-all variant.

The third is the empty value. A key with nothing after the colon is null, not an empty string and not an empty map, so a block of configuration that has been commented out but left with its key present parses as a null where the consumer expected an object. Nulls and empty strings behave differently in every templating system built on top of YAML.

Validating YAML against a schema

A parser tells you the file is syntactically valid. A schema tells you the contents make sense, and for anything operational that is the more useful check. Because YAML maps onto the same data model as JSON, JSON Schema works directly on it, which is what most editors use to give completions and inline errors in a Kubernetes manifest or a GitHub Actions file.

In a pipeline, specialised validators go further than a generic schema: kubeconform checks manifests against the Kubernetes API schemas for a target version, yamllint enforces style and catches indentation and duplicate-key issues, and most CI systems can validate their own configuration file locally before you push it.

Duplicate keys are worth calling out separately. Most parsers accept them and keep the last, silently discarding the first - so a value set twice in a long file appears to be ignored. Linters flag it; the language runtime usually will not.

Templating over YAML, and why it hurts

Helm, Ansible and most CI systems generate YAML from templates, which means a text templating language producing a whitespace-sensitive format. The results are predictable: an inserted value at the wrong indentation, a multi-line string that flattens a block, a conditional that removes a line and leaves a dangling key.

Two habits reduce the pain. Render before you apply - helm template, or the equivalent dry run - and read the output as YAML rather than trusting the template. And use the indentation helpers the tool provides, such as Helm's nindent, rather than counting spaces in the template by hand.

The deeper alternative is to generate YAML from data rather than from text: produce a structure in a real language and serialise it, so the indentation is the serialiser's problem. That is what CDK8s, Pulumi and several configuration languages such as CUE and Dhall exist to do, and it removes an entire category of failure.

Secrets, comments and what survives conversion

YAML configuration files are where secrets most often end up in a repository, usually as a value someone meant to remove before committing. Keeping them out is a workflow decision - environment variables, a secret manager, or encrypted files with SOPS or sealed secrets - and scanning the repository for what is already there is worth doing once, remembering that history retains anything ever committed.

Comments are the other thing worth protecting. They are the only documentation many configuration files have, and they do not survive a conversion to JSON, or a round trip through a program that loads and re-serialises the file. Tools that edit YAML in place while preserving comments exist - ruamel.yaml in Python, yq for command-line edits - and they are the right choice for scripted changes to a file people maintain.

The same goes for anchors. Converting to JSON expands every alias into a copy, so a configuration built around shared blocks comes back much longer and with the structure that made it maintainable gone. It means the same thing to a machine and rather less to the next person who edits it.