check-jsonschema: Validate YAML Against a Schema

check-jsonschema --schemafile schema.json data.yaml validates YAML or JSON against a JSON Schema and exits non-zero on failure.

check-jsonschema is a Python CLI (also a pre-commit hook) that validates config and workflow files against a schema, with handy built-in schemas for common CI files.

What it does

check-jsonschema (the check-jsonschema package) parses one or more instance files as JSON or YAML and validates them against a JSON Schema you supply with --schemafile, a URL with --schemafile, or a named built-in with --builtin-schema. It prints the offending path and message and exits 1 on any violation.

Common usage

Terminal

pipx install check-jsonschema

# validate a data file against a local schema
check-jsonschema --schemafile config.schema.json config.yaml

# validate GitHub Actions workflows with the built-in schema
check-jsonschema --builtin-schema vendor.github-workflows \
  .github/workflows/*.yml

# validate against a remote schema (SchemaStore)
check-jsonschema \
  --schemafile https://json.schemastore.org/dependabot-2.0.json \
  .github/dependabot.yml

Options

Flag	What it does
--schemafile <path\|url>	JSON Schema to validate against
--builtin-schema <name>	Use a bundled schema, e.g. vendor.github-workflows
--no-cache	Do not cache a downloaded remote schema
--data-transform <t>	Preprocess input (e.g. azure-pipelines)
--fill-defaults	Apply schema defaults before validating
--traceback-mode short\|full	Control error verbosity

In CI

Add it to .pre-commit-config.yaml and run pre-commit run check-jsonschema in CI, or call the CLI directly on .github/workflows/*.yml. A non-zero exit fails the job, so a malformed workflow or Dependabot file is caught before merge instead of on the default branch.

Common errors in CI

A failure prints error: .github/workflows/ci.yml::$.jobs.build.runs-on: 'ubuntu-latst' is not one of [...] style messages ending with a non-zero exit. Failed to download schema means a remote --schemafile URL is unreachable (proxy or offline runner); vendor the schema locally. command not found: check-jsonschema means it is not on PATH; install with pipx or pip install check-jsonschema. got an unexpected schema name means a bad --builtin-schema value; run check-jsonschema --help for the list.