A pre-commit hook that validates JSON files contain valid $schema references and validates the JSON data against the referenced schema.

Note: This repository serves as a workaround for python-jsonschema/check-jsonschema#310 - a feature request to add validation of $schema references in JSON files.

• Validates that JSON files contain a $schema key (gracefully skips by default)
• Loads and validates the referenced JSON Schema (supports both local files and URLs)
• Validates JSON data against the schema
• --strict flag to make missing $schema fail validation
• --expand-env-vars flag to enable environment variable expansion in $schema paths (e.g. "${SCHEMA_DIR}/my-schema.json")
• Exits with non-zero code on errors but checks all files before exiting
• Integrates with pre-commit hooks

1. Install dependencies:

   uv sync

2. Add to your .pre-commit-config.yaml:

   repos:
     - repo: https://github.com/thiagowfx/check-json-schema-meta
       rev: main
       hooks:
         - id: check-json-schema-meta

One-shot preview (trial):

pre-commit try-repo https://github.com/thiagowfx/check-json-schema-meta check-json-schema-meta --all

Basic configuration in .pre-commit-config.yaml:

repos:
  - repo: https://github.com/thiagowfx/check-json-schema-meta
    rev: main  replace with the latest tag
    hooks:
      - id: check-json-schema-meta

With strict mode enabled:

repos:
  - repo: https://github.com/thiagowfx/check-json-schema-meta
    rev: main  # replace with the latest tag
    hooks:
      - id: check-json-schema-meta
        args: ['--strict']

With environment variable expansion enabled:

repos:
  - repo: https://github.com/thiagowfx/check-json-schema-meta
    rev: main  # replace with the latest tag
    hooks:
      - id: check-json-schema-meta
        args: ['--expand-env-vars']

Run pre-commit hooks:

# Install pre-commit hooks
pre-commit install

# Run only this specific hook
pre-commit run [--all-files] check-json-schema-meta

# Default behavior - gracefully skip files without $schema
uv run check-json-schema-meta file1.json file2.json

# Strict mode - fail on missing $schema
uv run check-json-schema-meta --strict file1.json file2.json

• --strict: Make missing $schema fail validation. By default, files without $schema are gracefully skipped.
• --expand-env-vars: Expand environment variables in $schema paths.

Run tests:

uv run pytest

• Python 3.9+
• check-jsonschema package