---
id: pytest-schema
version: "0.1.2"
license: MIT
license_treatment: permissive
maintenance: dormant
---

# pytest-schema — 👍 Validate return values against a schema-like object in testing

License: permissive · Maintenance: dormant · Downloads: 113.4K/mo

## What it is and what it does

pytest-schema is a pytest plugin that wraps the schema library to validate Python data structures—typically API responses, config objects, or parsed JSON—against declarative schema definitions in test assertions. It provides functions like schema(), exact_schema(), and like_schema() that compare actual data against a template defining expected types, nested structures, optional fields, and custom validation rules (regex, enums, lambdas). When data matches the schema, the assertion passes; when it doesn't, a SchemaError is raised with details about the mismatch.

The package is designed for testing REST endpoints, webhooks, or any code that returns structured data. You define a schema once—a plain Python dict with types and validators—then reuse it across multiple tests. It handles optional fields, nested objects, lists, and custom predicates, making it useful for regression testing API contracts or validating config file parsing without writing repetitive type checks.

Use it for:

- Validate JSON responses from REST API endpoints match expected structure and types in integration tests.
- Test that config file parsing produces the correct nested dict/list structure with proper type conversions.
- Ensure backwards compatibility by checking that new API versions still satisfy older schema constraints.
- Validate webhook payloads or event data conform to a contract before processing in business logic.
- Check that data transformations (e.g., ORM queries, ETL pipelines) produce correctly typed and shaped output.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Validates function return values and API responses against schema definitions in pytest tests, using the schema library to check data structure, types, and constraints.

Yes, if you need lightweight schema validation in pytest tests and don't require active maintenance. The package is stable and low-friction to install, but its dormant status (910 days since last release) means it won't receive updates for new pytest or Python versions. Use it for straightforward response validation; consider alternatives if you need ongoing support or complex JSON Schema features.

## Install

pip install pytest-schema
uv add pytest-schema
poetry add pytest-schema

## Installing pytest-schema

Before you install: Low friction install with only two runtime dependencies (pytest and schema). Dormant maintenance status—last release was 910 days ago with no recent commits, though the repository is not archived and the package is marked Production/Stable.

License in practice: MIT license permits use in proprietary and open-source projects with minimal restriction; you must include a copy of the license and copyright notice.

Quickstart:

pip install pytest-schema

from pytest_schema import schema

article_schema = {"id": int, "title": str, "completed": bool}

def test_endpoint(test_client):
    response = test_client.get("/api/article/1")
    assert schema(article_schema) == response

Verify before relying:

- Whether the schema library's validation rules and error messages are sufficient for your test reporting needs.
- Current compatibility with modern pytest versions and whether dormant status affects future pytest updates.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: dormant
- Downloads: 113.4K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pytest response validation, schema validation testing, api response schema check, data structure validation pytest, json schema testing, type checking test assertions, endpoint response validation, api-testing, schema-validation

[View on SkillFed](https://skillfed.io/packages/pytest-schema) · [View on PyPI](https://pypi.org/project/pytest-schema/)