subschema 0.0.1

A conservative JSON Schema subschema prover

subschema

subschema is a conservative prover for JSON Schema subschema checks.

For JSON Schemas lhs and rhs, lhs <: rhs means every JSON instance that validates against lhs also validates against rhs.

The PyPI package, Python import package, and CLI command are named subschema.

Install

pip install subschema

For local development:

uv sync --locked --group dev
uv run pytest -q
uv run ruff check .

CLI

subschema lhs.json rhs.json

The command prints whether lhs.json <: rhs.json.

Finite expensive proof products can be enabled explicitly:

subschema --endeavor --max-work 20000 --timeout-ms 3000 lhs.json rhs.json

max_work and timeout_ms are only accepted with --endeavor. A value of -1 means unlimited for that control.

Python API

from subschema import Dialect, is_subschema

lhs = {"type": "integer"}
rhs = {"type": "number"}

print(is_subschema(lhs, rhs, dialect=Dialect.DRAFT202012))

Available public entrypoints:

• is_subschema(lhs, rhs, *, dialect=None, proof_options=None, endeavor=False, max_work=None, timeout_ms=None)
• is_equivalent(lhs, rhs, *, dialect=None, proof_options=None, endeavor=False, max_work=None, timeout_ms=None)
• meet_schemas(lhs, rhs, *, dialect=None, proof_options=None, endeavor=False, max_work=None, timeout_ms=None)
• join_schemas(lhs, rhs, *, dialect=None, proof_options=None, endeavor=False, max_work=None, timeout_ms=None)
• canonicalize_schema(schema, *, dialect=None)

Dialects

Draft 2020-12 is the default dialect for calls without an explicit dialect or $schema declaration. Older dialects can be selected by passing dialect=... or by using a $schema declaration.

Supported dialects:

• Draft 4
• Draft 6
• Draft 7
• Draft 2019-09
• Draft 2020-12

The prover is intentionally conservative. Unsupported, unbounded, recursive, or exhausted proof fragments are reported instead of being silently approximated.

Acknowledgement

This project is a rewrite based on IBM's jsonsubschema project and may retain portions of its source code. Credit to IBM and contributors.

License

Apache License 2.0. See LICENSE.