YAML Validator: Find and Fix Syntax Errors Before They Break Your Pipeline

YAML is the configuration language that runs modern infrastructure. Docker Compose, Kubernetes, GitHub Actions, Ansible, Terraform, Cloudflare Workers, and dozens of other tools use YAML for configuration. It is everywhere.

It is also surprisingly easy to break. A single wrong indent, a missing colon, or a tab character where a space should be will crash your entire pipeline. And the error messages from YAML parsers are often cryptic. "mapping values are not allowed here" at line 47 does not tell you much when line 47 looks perfectly fine.

The YAML Validator parses your YAML and shows you exactly where the error is, with human-readable explanations. Paste your config, fix the highlighted issues, and know it will parse correctly before you push.

The Five YAML Mistakes Everyone Makes

After years of YAML config files, the same mistakes show up over and over.

1. Tabs instead of spaces. YAML does not allow tab characters for indentation. Period. Your editor might look like it is using 2 spaces, but if it is actually inserting a tab, YAML will reject it. Configure your editor to insert spaces for YAML files.

2. Inconsistent indentation. If your first level uses 2 spaces, every level must use 2 spaces. Mixing 2-space and 4-space indentation within the same file causes parsing errors that are hard to spot visually.

3. Missing colon after a key. name value is not valid YAML. It must be name: value. The colon and space after it are both required. A colon without a space (name:value) is technically valid but will be parsed as the key name:value with no value.

4. Unquoted special characters. Values containing :, #, {, }, [, ], or & need to be quoted. description: Use the # symbol will break because # starts a comment. Write description: "Use the # symbol" instead.

5. Boolean gotcha. YAML interprets yes, no, true, false, on, off as booleans. If you have a country code no (Norway) or a key on, YAML will parse them as boolean values unless you quote them: country: "no".

The YAML Validator catches all five of these and tells you exactly which line to fix.

YAML Indentation: The Rules That Actually Matter

YAML uses indentation to define structure, like Python. But unlike Python, where you can usually see the indentation in your code, YAML indentation errors in config files are often invisible.

The rules:

• Use spaces only (never tabs)
• Be consistent within a file (pick 2 or 4 spaces and stick with it)
• Child elements must be indented more than their parent
• Sibling elements must be at the same indentation level
• Lists use - (dash + space) at the same indentation as the key they belong to

Here is a correct example:

`yaml server: host: localhost port: 8080 features: - auth - logging - metrics database: name: myapp pool: 10 `

And here is the same content with a subtle error:

`yaml server: host: localhost port: 8080 features: - auth - logging - metrics `

The extra space before - logging makes it a child of auth instead of a sibling. This is valid YAML, but it produces a completely different data structure than intended. The validator will parse it, but the result will not match what you expected.

This is why validation matters even when the YAML is technically parseable. Compare the parsed output against your intent.

Multi-line Strings: Block Scalars Explained

YAML has multiple ways to handle multi-line text, and picking the wrong one leads to subtle bugs.

Literal block scalar (|): preserves newlines exactly as written. Each line break in the YAML becomes a newline in the parsed value.

`yaml script: | echo "hello" npm install npm run build `

Parsed value: echo "hello"\nnpm install\nnpm run build\n

Folded block scalar (>): joins lines with spaces, treating newlines as whitespace (like HTML). Blank lines create actual newlines.

`yaml description: > This is a long description that spans multiple lines but will be joined into one paragraph. `

Parsed value: This is a long description that spans multiple lines but will be joined into one paragraph.\n

Chomping indicators: Add - to strip the trailing newline, or + to keep all trailing newlines.

• | and >: single trailing newline (default)
• |- and >-: no trailing newline
• |+ and >+: keep all trailing newlines

For CI/CD scripts, you almost always want | (literal block) because you need those newlines to separate commands. For descriptions and documentation in config files, > (folded) produces cleaner single-paragraph text.

Paste your YAML into the YAML Validator and check the parsed output to see exactly how your multi-line strings are being interpreted.

Validating GitHub Actions, Docker Compose, and Kubernetes YAML

Generic YAML validation catches syntax errors, but each tool has its own schema with required fields, valid values, and structural rules.

GitHub Actions (.github/workflows/*.yml): Requires on (trigger), jobs, and each job needs runs-on and steps. Common errors: misspelling runs-on as runs_on, using with parameters that do not exist for an action, or referencing secrets with the wrong syntax.

Docker Compose (docker-compose.yml or compose.yml): Requires services at the top level. Each service needs at least image or build. Common errors: wrong port format (should be "8080:80" with quotes because of the colon), missing version field (no longer required in Compose V2 but some tools still expect it).

Kubernetes (deployments, services, configmaps): Requires apiVersion, kind, and metadata. The spec section varies by resource type. Common errors: wrong apiVersion for the resource type, missing labels that selectors depend on, incorrect container port definitions.

The YAML Validator validates the YAML syntax. For schema-specific validation, use the tool's own validation command: docker compose config, kubectl --dry-run=client, or GitHub's Actions linting.

A good workflow: validate YAML syntax first (catch indentation, quoting, and structure errors), then validate against the tool's schema.

YAML vs JSON: When to Use Which

YAML and JSON represent the same data structures. You can convert between them losslessly (with minor formatting differences). So why do we have both?

YAML advantages: Easier to read and write by hand. Supports comments. Less punctuation (no curly braces or commas). Better for configuration files that humans edit frequently.

JSON advantages: Simpler parsing (fewer edge cases). Native in JavaScript/browsers. Stricter format (less ambiguity). Better for data exchange between systems.

Use YAML for: Configuration files, CI/CD pipelines, infrastructure-as-code, Kubernetes manifests, Ansible playbooks. Anything humans read and edit regularly.

Use JSON for: API responses, data storage, package manifests (package.json, tsconfig.json), anything consumed primarily by code rather than humans.

If you need to convert between them, the JSON Validator and JSON Formatter handle the JSON side. Many YAML validators also offer a "convert to JSON" option so you can see the exact data structure your YAML produces.

FAQ

Why does YAML not allow tabs?

The YAML specification explicitly prohibits tab characters for indentation. The reason is that different editors display tabs at different widths (2, 4, or 8 spaces), which means the visual indentation would not match the logical indentation. By requiring spaces only, YAML ensures that what you see matches what the parser sees.

Can YAML have comments?

Yes. Use # for comments. Everything after # on a line is ignored by the parser. This is one of YAML's advantages over JSON, which has no comment syntax. Use comments to explain non-obvious configuration values.

What does "mapping values are not allowed here" mean?

This error usually means you have a colon in a value that is not quoted. For example, title: Welcome: A Guide breaks because the parser sees Welcome as a key. Fix it with quotes: title: "Welcome: A Guide".

How do I handle special characters in YAML values?

Wrap the value in double quotes. Double-quoted strings support escape sequences (\n, \t, \"). Single-quoted strings treat everything literally except '' (escaped single quote). When in doubt, use double quotes.

Can I merge or reuse sections in YAML?

Yes. YAML supports anchors (&name) and aliases (name) for reusing blocks, and merge keys (<<: name) for combining mappings. This is useful for DRY configuration but makes the YAML harder to read. Use it sparingly.