Validate YAML with JSON Schema: The Type Safety Net for Config Files
Bottom line: A YAML file that parses cleanly is not a YAML file that is correct: country: NO is not a string in a YAML 1.1 parser, and version: 1.10 silently becomes the float 1.1. This guide explains why JSON Schema can validate YAML, the CLI and editor paths that put it into practice, how a schema would have caught the real Norway country-code incident, and the three things schema validation cannot do.

Bottom line: YAML 1.2 is a strict superset of JSON, so JSON Schema validates the parsed data structure, not the file format — write the schema once and it covers both JSON and YAML data. That is exactly why it can catch incidents where the parser silently changes a type.
A clean
yaml.safe_loadproves the file is legal YAML. It does not provecountry: NOis still a string — under a YAML 1.1 parser it becamefalselong before your code saw it.
One: Parsing cleanly ≠ config is correct — a real incident first
An e-commerce team added Norway to their shipping countries: one line, NO, appended to a list in an Ansible group_vars file. It passed review and shipped. A week later Norway had produced zero orders — the JSON file on the servers read "DK", false, "SE". Ansible parses its variable files with PyYAML, a YAML 1.1 parser, so NO was the boolean false from the moment the file was read; the to_json filter wrote it out faithfully. The template rendered, the JSON was valid, nothing complained — only the checkout service kept refusing every Norwegian customer because NO was not in the list.
The common thread in incidents like this: every syntax-level tool is green while the data layer is already wrong. The table below shows measured type drift under PyYAML 6.0.3; YAML 1.2 parsers fix only part of it:
| You write | YAML 1.1 reads | YAML 1.2 reads | You wanted |
|---|---|---|---|
country: NO |
false |
"NO" |
"NO" |
version: 1.10 |
float 1.1 |
float 1.1 |
"1.10" |
zip: 02134 |
octal 1116 |
decimal 2134 |
"02134" |
mode: 0755 |
decimal 493 |
decimal 755 |
493 or "0755" |
ports: ["22:22"] |
sexagesimal 1342 |
"22:22" |
"22:22" |
The root fix is quoting every code-like string. But quoting relies on people remembering; a schema relies on machines checking — which is why YAML deserves a JSON Schema.
Two: Why JSON Schema can govern YAML
The YAML 1.2 specification says it outright: the primary goal of 1.2 was making YAML a strict superset of JSON, and a 1.2 parser reads ordinary JSON unchanged. Since both formats parse into the same data structures, the file extension is meaningless to a validator. The whole pipeline is three steps:
- Parse the YAML file into objects/arrays;
- Load the JSON Schema;
- Validate the data against the schema — errors or pass.
Note that step one does not require serializing YAML into JSON text and parsing it again; any language's YAML library hands the validator a ready-made data structure. The schema itself can also be written in YAML (yq -P schema.json > schema.yaml converts in one command), but keeping it in JSON is the safer default — tooling compatibility is better, and every schema in the schemastore.org catalog is JSON.
Three: Three CLI paths that work today
Take a config.yaml where the schema requires name and version, demands a semver-shaped version, and insists countries is an array of two-letter uppercase strings:
# config.yaml
name: checkout
version: "1.4.2"
countries:
- DK
- NO
- SE
Python (jsonschema + PyYAML):
import json, yaml
from jsonschema import validate
data = yaml.safe_load(open("config.yaml", encoding="utf-8"))
schema = json.load(open("schema.json", encoding="utf-8"))
validate(instance=data, schema=schema)
Node (js-yaml + Ajv):
import Ajv from "ajv";
import yaml from "js-yaml";
import fs from "fs";
const schema = JSON.parse(fs.readFileSync("schema.json", "utf8"));
const data = yaml.load(fs.readFileSync("config.yaml", "utf8"));
const validate = new Ajv().compile(schema);
if (!validate(data)) console.error(validate.errors);
Pure pipe (yq + ajv-cli):
yq -o=json config.yaml | ajv validate -s schema.json -d -
# Or check-jsonschema, which consumes YAML directly
pip install check-jsonschema
check-jsonschema --schemafile schema.json config.yaml
The three paths differ only at the parse step: the first two are explicit two-liners, the pipe streams through, and check-jsonschema does the YAML→JSON conversion internally. The schema file is the same in all three.
Four: Real-time validation in the editor: modeline and SchemaStore
Red Hat's YAML extension (built on yaml-language-server) has roughly 30 million installs on VS Code and supports JSON Schema draft-04/07/2019-09/2020-12. Three ways to hook it up:
# Option one: a modeline — the first line of the file points at the schema
# yaml-language-server: $schema=./schema.json
name: checkout
// Options two and three: .vscode/settings.json, by file name or glob
{
"yaml.schemas": {
"./schema.json": ["config/*.yaml", "*.config.yaml"],
"https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml"
}
}
yaml.schemaStore.enable is on by default: common files such as package.json, GitHub workflows, and docker-compose get associated with the schemastore.org catalog automatically, with zero configuration. Schema description fields become completion hints and hover text, and missing required properties get red squiggles — config errors move from "debug after deploy" to "the moment you type". This also explains why SchemaStore rather than some "YAML schema standard": YAML has no official schema standard, and JSON Schema is the de facto one.
Five: How a schema would have caught the Norway problem
Back to the NO incident from section one. Give countries an item-level schema:
{
"type": "object",
"required": ["name", "version", "countries"],
"properties": {
"countries": {
"type": "array",
"items": { "type": "string", "pattern": "^[A-Z]{2}$" }
}
}
}
The false PyYAML produced is not a string, so type: string fails immediately; even if some parser had read it as lowercase "no", the pattern still blocks it. Add an enum allowlist for stricter control. The same schema runs in CI through the CLI paths of section three and in the editor through the modeline of section four — one contract at both ends.
The division of labor with yamllint deserves a sentence: yamllint's truthy rule (only true/false accepted, every other boolean-like spelling flagged) governs writing style, catching flag: yes at the lint layer; JSON Schema governs data shape, regardless of which parser you use. The incident team ended up with all three: quote the strings, run yamllint truthy in the pipeline, and assert two-letter strings in the template. The two defense layers do not overlap; they complement each other.
Six: Batch-validating Kubernetes manifests
The Kubernetes API is described by OpenAPI, and the kubernetes-json-schema project converts it into standard JSON Schema. Kubeconform uses that registry for batch validation: on a 4-core laptop, 35,139 files and 50,714 resources under kubeconform -ignore-missing-schemas -n 8 -summary finished in 6.7 seconds, versus 35 seconds for kubeval on the same task. The standard Helm move is render first, validate second:
helm template my-app ./charts/my-app > rendered.yaml
kubeconform -strict -summary -kubernetes-version 1.28.0 rendered.yaml
-strict rejects fields the schema does not define (typos surface early); CRD resources can be skipped with -ignore-missing-schemas or served a custom registry via -schema-location.
Seven: What schema validation cannot do: three boundaries
- Parser version drift happens at the parse layer. The schema sees the parse result: the
NOPyYAML read is alreadyfalse, and the schema can only contain that bogus value withtype/pattern. The root fix remains quoting; do not expect a schema to fix a parser. - Logic errors are out of scope. A misspelled selector or a K8s selector pointing at a nonexistent label — the schema knows shapes, not semantics. Those need admission webhooks, OPA policies, or
kubectl apply --dry-run=server. - Duplicate keys silently win. Many YAML parsers accept duplicate keys without a warning (last one wins), so the schema receives data that already lost a key. yamllint's
key-duplicatesrule or parse hooks are the detectors.
Pre-deploy checklist: quote code-like strings → run yamllint (truthy + key-duplicates) → JSON Schema validation in both CI and editor → cluster resources additionally pass --dry-run=server. With these four steps, the Norway incident from section one does not survive past step two on this pipeline.
FAQ
Can JSON Schema directly validate YAML files?
Yes — but it validates the data the file parses into, not the file itself. YAML 1.2 is a strict superset of JSON, both parse into the same data structures, so one schema serves JSON and YAML alike. Pick any of the four paths — Python, Node, the yq pipe, or check-jsonschema — without manually converting formats first.
What is SchemaStore and how do I use it?
schemastore.org is a JSON Schema catalog (catalog.json) holding schemas for hundreds of common config files: package.json, GitHub workflows, docker-compose, and so on. Editors with YAML/JSON language support associate files with it automatically, or you can map URLs manually in yaml.schemas. You can also submit your project's own schema to the catalog.
Do yamllint and JSON Schema validation overlap?
No. yamllint checks writing style (indentation, line length, truthy, duplicate keys) at the text layer; JSON Schema checks data structure (types, required, enums, patterns) at the data layer. The Norway incident fix list used both: the truthy rule catches spellings like flag: yes, while the schema catches a false that ended up inside an array of strings.
For Kubernetes, kubeconform or kubectl dry-run?
Different jobs. Kubeconform is offline and batch, needs no cluster, and belongs in CI to catch structural errors; dry-run=server talks to a real API server and surfaces admission-webhook and quota issues, but requires cluster access. The standard combo: kubeconform in CI, then one --dry-run=server pass before deploy — keep both layers.
After writing the schema, paste the JSON converted from your YAML into the online JSON validator to see the errors first; for how to write schema keywords, see the JSON Schema guide; to keep a schema watched by tests in CI, read JSON Schema contract testing; for everyday JSON↔YAML conversion use the JSON YAML XML converter.