check-jsonschema

Common errors

• Schema validation errors were encountered.
  <file_path>::<json_path>: '<value>' is not valid under any of the given schemas

  cause An instance file contains data that does not conform to the rules defined in the provided JSON schema.
  fix Review the error message to identify the specific part of the instance data that is invalid (e.g., incorrect type, missing required field, value outside allowed range) and modify the instance file to adhere to the schema. You may also need to adjust the schema if the current validation rule is unintended.

• FileNotFoundError: [Errno 2] No such file or directory: '<file_path>'

  cause The command-line tool cannot find the specified schema file or one of the instance files because the path provided is incorrect or the file does not exist.
  fix Verify that the file path provided for `--schemafile` or any instance file is correct and that the file exists in the specified location. Use absolute paths or ensure the relative path is correct from the directory where `check-jsonschema` is executed.

• ModuleNotFoundError: No module named 'jsonschema.compat'

  cause This error typically occurs when a dependency, often an older version of the `jsonschema` library itself, tries to import a module (`jsonschema.compat`) that was removed in `jsonschema` version 4.0 and later.
  fix Downgrade the `jsonschema` package to a version below 4.0 using `pip install 'jsonschema<4.0'` or ensure all installed packages that depend on `jsonschema` are compatible with the latest version.

• <file_path>::<json_path>: '<value>' is not a 'date'

  cause The data in the instance file that is expected to be a `date` (as per the schema's `format: date` keyword) does not adhere to the RFC3339 date format.
  fix Ensure the value in the instance file matches the `YYYY-MM-DD` format for dates as required by the JSON Schema `date` format. If `date-time` validation is failing unexpectedly, consider that `format` validation is often optional and can be disabled if not strictly required, or ensure your `jsonschema` library version correctly implements it for `date-time`.

• check-jsonschema hook not running for .meta files

  cause When `check-jsonschema` is used as a pre-commit hook, it might not validate files with custom extensions (like `.meta`) because pre-commit's default `types` filter doesn't recognize them as JSON or YAML.
  fix Modify your `.pre-commit-config.yaml` to explicitly include the custom file type. You can do this by overriding the `types` or `files` arguments for the `check-jsonschema` hook, for example, by adding `types_or: []` and `files: ^data/.*\.meta$` to match files by name regardless of their detected type.

Warnings

• breaking Python 3.9 support has been dropped.
  Fix: Ensure your environment uses Python 3.10 or newer. Upgrade your Python version or pin check-jsonschema to a version prior to 0.37.0 if Python 3.9 is required.
• breaking Verbose output levels for the CLI have changed. Previously, `-v` showed checked filenames; now, `-v` shows all errors without filenames, and `-vv` (or higher) is required to display filenames checked.
  Fix: If you relied on `-v` to see filenames, adjust your scripts or commands to use `-vv` instead for that output.
• gotcha When using check-jsonschema as a pre-commit hook with custom schemas, ensure the schema paths are correct relative to the repository root or accessible via defined `$schema` IDs. Incorrect paths or unreachable references will lead to validation errors.
  Fix: Verify that your `pre-commit` hook configuration correctly points to schemas, especially if they are not vendored. Use the `--schema` argument with a correct relative path if validating against a local schema, or ensure your schema's `$id` is properly set up for external resolution.
• gotcha check-jsonschema defaults to validating against vendored schemas for common config types (e.g., GitHub Workflows, Dependabot). If you have a custom schema with the same filename or an unconventional path, it might be ignored or validated against the wrong schema.
  Fix: Always explicitly specify your custom schema using `--schema your-custom-schema.json` if it's not one of the vendored types or if you need to override the default. For `pre-commit` hooks, configure a specific hook to point to your custom schema.

Install

• pip install check-jsonschema Install via pip
• pip install pre-commit && pre-commit install Install pre-commit (if not already)

Imports

• main

  from check_jsonschema.main import main

  check-jsonschema is primarily a CLI tool and a pre-commit hook. Direct programmatic import and execution of its internal `main` function is not a common use case and is generally discouraged in favor of the CLI.

Quickstart

The primary use of check-jsonschema is through its command-line interface or as a pre-commit hook. First, define your JSON schema and the data you wish to validate. Then, run the `check-jsonschema` command specifying the schema and data files. For automated checks, configure it in your `.pre-commit-config.yaml` file, using its built-in hooks for common configuration files or a custom hook for your own schemas.

# 1. Create a schema file (e.g., 'my_schema.json')
# echo '{"type": "object", "properties": {"name": {"type": "string"}}, "required": ["name"]}' > my_schema.json

# 2. Create a data file to validate (e.g., 'my_data.json')
# echo '{"name": "John Doe"}' > my_data.json

# 3. Run validation via CLI
# check-jsonschema --schema my_schema.json my_data.json

# 4. Integrate with pre-commit (add to .pre-commit-config.yaml)
#    - repo: https://github.com/python-jsonschema/check-jsonschema
#      rev: '0.37.1'
#      hooks:
#        - id: check-dependabot
#        - id: check-github-workflows