YAML Lint and Format

Est. read: 6 minDeveloper

YAML file icon representing validated configuration

Summary

Definition: YAML linting validates syntax, structure, and optional style rules.

Why it matters: Valid-looking YAML can still be structurally wrong or unsafe.

Pitfall: Formatting invalid YAML can mask the real error.

Guide start

YAML is indentation-sensitive and feature-rich. Linting validates correctness and safety.
Formatting should only be applied after the file is valid.

Key terms

YAML: A human-readable data format using indentation for structure.
Linting: Automated checks for syntax, structure, and rules.
Formatter: A tool that rewrites valid YAML consistently.
Scalar: A single YAML value like a string or number.
Implicit typing: Automatic value type inference by YAML parsers.

If you need...

Need	Use
Check correctness	YAML Lint
Improve readability	YAML Formatter
Validate structure	Schema validation
Convert formats	YAML and JSON tools

Safe default

Lint first, fix structural issues, then format for readability.

How YAML lint works

YAML linters parse the document according to the YAML specification.
They report syntax errors, structural problems, and optional safety or style issues.

If a lint error points to a valid-looking line, the real problem is often above it.

YAML lint vs YAML format

Lint vs Format

Lint

Checks validity and structure.

Format

Rewrites spacing and layout.

Common YAML lint errors

Tabs used for indentation.
Inconsistent indentation levels.
Missing colons after keys.
Duplicate keys in a map.
Ambiguous unquoted scalars.

Common mix-up: Formatting fixes errors. Formatting assumes valid YAML.

Quick example

Example

This YAML fails due to inconsistent indentation.

Broken YAML

services:
  api:
   image: api:latest
  web:
    image: web:latest

Example

Indentation is consistent and valid.

Fixed YAML

services:
  api:
    image: api:latest
  web:
    image: web:latest

YAML versions and typing

YAML 1.2 aligns typing with JSON. YAML 1.1 treats values like yes or 0123 differently.

Practical usage

Safe workflow

Run a YAML linter.
Fix syntax and structural errors.
Re-run lint until clean.
Format the YAML.

Use YAML Lint to validate correctness.
Use YAML Formatter after lint passes.

Practical check

No tabs used for indentation.
No duplicate keys.
Lint passes with no errors.
Formatter output is readable.

FAQ

Why does YAML lint fail when JSON works? YAML adds indentation, comments, and typing rules that JSON does not have.

Should I quote every value? Quote values when ambiguity or implicit typing could change meaning.

Is YAML formatting safe? Yes, but only after the YAML passes linting.

Guide end - You can now lint YAML, fix structural issues, and format files safely.Back to top