pytest-jsonschema

pytest-jsonschema is a plugin for pytest designed to facilitate JSON Schema validations within your test suites. This tool enables you to validate JSON files, strings, and Python objects against predefined JSON Schemas, ensuring your data adheres to expected formats.

The package bundles a set of commonly used schemas — for pyproject.toml, package.json, GitHub Actions workflows, docker-compose.yml and more — so you can assert that the configuration files in your own repository are valid, without any network access at test time.

Installation

Install pytest-jsonschema from PyPI:

pip install pytest-jsonschema

Or, with uv:

uv add --dev pytest-jsonschema

The plugin registers itself with pytest automatically; no configuration is required.

Usage

The package introduces three pytest fixtures for validating JSON data. Each takes a schema_name from the bundled schemas and returns True when the data is valid.

schema_validate_file

Validates a file on disk. The format is inferred from the file extension:

from pathlib import Path


def test_package_json_is_valid(schema_validate_file):
    path = Path("package.json")
    assert schema_validate_file(path=path, schema_name="package")

Because the format is inferred, this also works for the TOML and YAML files the bundled schemas cover:

from pathlib import Path


def test_pyproject_is_valid(schema_validate_file):
    assert schema_validate_file(path=Path("pyproject.toml"), schema_name="pyproject")


def test_workflow_is_valid(schema_validate_file):
    path = Path(".github/workflows/ci.yml")
    assert schema_validate_file(path=path, schema_name="github-workflow")

Pass file_type explicitly when the extension does not match the content.

schema_validate_string

Validates a string. There is no filename to infer from, so file_type is required:

from pathlib import Path


def test_package_json_is_valid(schema_validate_string):
    data = Path("package.json").read_text()
    assert schema_validate_string(data=data, schema_name="package", file_type="json")

schema_validate

Validates an already-parsed Python object — a dict or a list:

import json
from pathlib import Path


def test_package_json_is_valid(schema_validate):
    data = json.loads(Path("package.json").read_text())
    assert schema_validate(data=data, schema_name="package")

Supported file formats

schema_validate_file and schema_validate_string accept the following file_type values:

Available schemas

Pass one of these as schema_name:

repository.toml has two specifications, and they are not interchangeable: a file without a spec_version key, or with spec_version = "1", is spec 1 and declares packages as [backend.package] / [frontend.package] tables; spec_version = "2" declares them as a flat [[package]] array. Pick the schema that matches the file:

from pathlib import Path
from pytest_jsonschema.loaders import data_from_file


def test_repository_toml_is_valid(schema_validate_file):
    path = Path("repository.toml")
    spec = str(data_from_file(path).get("spec_version", "1"))
    schema_name = "repository-v2" if spec.startswith("2") else "repository-v1"
    assert schema_validate_file(path=path, schema_name=schema_name)

The bundled copies are refreshed with make update-schemas.

Requirements

• Python >= 3.10
• pytest >= 6.2.0

Contributing

To contribute to pytest-jsonschema, please follow these steps:

1. Clone the repository:

   git clone git@github.com:collective/pytest-jsonschema.git
   

2. Install the package for development:

   make install
   

3. Format the codebase:

   make format
   

4. Run the linters and type checks:

   make lint
   

5. Run the tests:

   make test
   

   To stop on the first error and open a pdb session:

   uv run pytest -x --pdb
   

6. Add a change log entry under news/, named <issue-number>.<type>, where type is one of breaking, feature, bugfix, internal, documentation or tests. Preview the result with make changelog.

Run make help to see every available target. Testing is conducted using pytest.

License

pytest-jsonschema is licensed under the MIT License.