YAML Validator & Formatter

What the formatter changes and what it keeps

The formatter parses every document in the input and prints it again. Nested mappings and lists get two spaces per level, list items are indented under their key, and stray spacing after - is removed. Everything that carries meaning is kept: comments on their own lines and at the end of lines, single and double quotes, ~ for null, and the original spelling of values such as yes, 0755 or 1.10.

# before                      # after
name: DevToolGrid             name: DevToolGrid
tools:                        tools:
- json                          - json
-   yaml                        - yaml
mode: 0755                    mode: 0755

Keeping values as written matters because YAML versions disagree about them. A formatter that re-serialised 0755 as 755 would change a file mode from octal 493 to decimal 755 for any tool that reads YAML 1.1. Numbers in exponent or hexadecimal form may be normalised, for example 0x1F to 0x1f, which does not change their value.

YAML validator error messages

The validator reports the first problem with its position. These are the ones people hit most, with the exact messages:

a: 1
	b: 2            Tabs are not allowed as indentation at line 2, column 1

a: [1, 2
b: 3             Flow sequence in block collection must be sufficiently indented
                 and end with a ] at line 2, column 1

key: value: x    Nested mappings are not allowed in compact mappings at line 1, column 6

a: 1
a: 2             Map keys must be unique at line 2, column 1

YAML forbids tab characters for indentation, and editors that insert tabs are the classic cause of a file that looks right and does not parse. A colon followed by a space starts a mapping, so a value that contains : , such as a time or a sentence, must be quoted. Duplicate keys are an error in YAML 1.2; some older parsers silently keep the last value instead, which hides configuration mistakes.

Indentation rules

Indentation defines structure in YAML: items at the same level must start in the same column, and a child must be indented further than its parent. The number of spaces is up to you, as long as it is consistent within a block; two is the common convention and what the formatter outputs.

List items under a key may be indented or start in the same column as the key; both are valid, and the formatter indents them for readability. The error to watch for is a list item or key that is one space off. It either causes a parse error or, worse, attaches the value to a different parent than intended, which is still valid YAML. Check the formatted output: if a key ends up under the wrong parent, the input was indented wrongly.

The Norway problem and other type surprises

YAML guesses types for unquoted values, and the rules changed between versions. In YAML 1.1, used by PyYAML and many older tools, yes, no, on and off are booleans, so the country code NO becomes false, and a YAML 1.1 parser reads the on: key of a GitHub Actions workflow as the boolean true. YAML 1.2 only treats true and false as booleans.

country: NO        # YAML 1.1: false          YAML 1.2: "NO"
mode: 0755         # YAML 1.1: 493 (octal)    YAML 1.2: 755
version: 1.10      # a float: 1.1, not the string "1.10"
zip: 01234         # YAML 1.1: octal 668     YAML 1.2: 1234
id: 1e3            # the number 1000

The safe habit is to quote any value that must stay a string: version numbers, ZIP and phone codes, country codes, and anything with a leading zero. Quoting is never wrong, and the formatter keeps your quotes.

Multiple documents, anchors and comments

A file can contain several documents separated by ---, as in Kubernetes manifests that define a Deployment and a Service together. The validator checks each document and keeps the separators. Anchors (&defaults) and aliases (*defaults) let one block reuse another, and Docker Compose files often use the merge key <<: *defaults; the formatter keeps them rather than expanding them.

Validation here means syntax. It does not know that Kubernetes requires apiVersion, or that GitHub Actions expects runs-on. For schema checks, use the ecosystem's tool: kubectl apply --dry-run=server, docker compose config, actionlint, or an editor with the YAML language server and JSON Schema.

YAML linting on the command line

pip install yamllint
yamllint config.yaml                 # syntax plus style rules (line length, indentation)

python3 -c 'import sys, yaml; yaml.safe_load(open(sys.argv[1]))' config.yaml
yq '.' config.yaml                   # parses and pretty-prints

yamllint also flags style issues, such as trailing spaces and inconsistent indentation, that are valid YAML but make diffs noisy. In code, always load untrusted YAML with a safe loader, such as yaml.safe_load in Python, because full loaders can construct arbitrary objects.

The validator runs in your browser. Configuration files often contain hostnames, credentials and internal URLs, and nothing you paste is uploaded or stored.

Frequently asked questions

How do I validate YAML online?

Paste the YAML into the validator. Valid YAML is shown reformatted; invalid YAML shows the error message with the line and column where parsing failed.

Does the formatter remove comments?

No. Comments, quotes, null markers and document separators are kept. Only indentation and spacing are normalised.

Why are tabs not allowed in YAML?

The YAML specification forbids tabs for indentation because their width is ambiguous. Replace them with spaces; most editors can convert tabs automatically.

Why does my YAML value turn into true or false?

YAML 1.1 parsers treat yes, no, on and off as booleans. Quote such values, for example country: "NO", to keep them as strings in every parser.

Does the validator check Kubernetes or Docker Compose schemas?

No, it checks YAML syntax only. Use kubectl apply --dry-run=server or docker compose config to validate against those schemas.

How many spaces should YAML indentation use?

Any consistent number works; two spaces is the common convention and what the formatter outputs. Items at the same level must start in the same column.