What the validator checks
It reads the whole file with a YAML 1.2 parser and reports anything that stops it:
- Tabs or inconsistent spaces used for indentation.
- Brackets, braces and quotes that are never closed.
- A key without a colon, or two colons on one line where a value was expected.
- A value that starts with a character YAML reserves, such as
@, a backtick or%. - Duplicate keys in one mapping.
- Aliases (
*name) that refer to an anchor (&name) that is not defined earlier in the same document. - Invalid escape sequences in double quoted text.
If there are several problems, the first is shown in full and up to eight more are listed with their line and column. Later problems are sometimes side effects of the first, so fix from the top.
Valid YAML that does not mean what you think
A file can be valid and still not say what you intended. The validator cannot see your intent, but it flags the cases YAML versions disagree on:
- yes, no, on, off. YAML 1.1 parsers, such as PyYAML, read them as booleans. YAML 1.2 reads plain text. The country code
NOfor Norway turning intofalseis the classic example. - Numbers with a leading zero.
0755is octal 493 in YAML 1.1 and decimal 755 in YAML 1.2. - Values like 22:22 or 1:30. YAML 1.1 reads them as base 60 numbers. Docker documents this for port mappings, and recommends quoting
"HOST:CONTAINER"ports for that reason. - key:value with no space. It is valid, but it is a single text value, not a key with a value.
Quote a value ("NO", "0755") when you want text under every parser.
Syntax is not a schema
Files such as GitHub Actions workflows, Kubernetes manifests, docker compose files and OpenAPI documents are YAML, but each has its own rules about which keys exist and what values they take. This tool checks the YAML underneath and nothing about those rules, so a misspelled key such as enviroment passes.
Check the syntax here first, because a schema aware tool cannot start until the YAML parses. To tidy a file that already passes, use the YAML formatter.
Reading the report
Top level says whether each document is a mapping, a list or a single value. Values counts every text value, including keys. Anchors and Aliases count the &name and *name markers, which let one part of a file be reused in another. Nesting depth counts how many mappings and lists are open at the deepest point.