jsonschema is the most complete and spec-compliant JSON Schema validator for Python, supporting Draft 3, 4, 6, 7, 2019-09, and 2020-12. The current stable release is 4.26.0 (requires Python ≥ 3.10). Releases follow semantic versioning and ship frequently via GitHub; minor releases are expected to be backwards-compatible while major versions may carry deprecations that become removals.
Install & Compatibility
Where this runs
tested against v4.26.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.975 runs
installs and imports cleanly · install 0.0s · import 2.074s · 28.1MB
glibcpy 3.10–3.975 runs
installs and imports cleanly · install 2.9s · import 1.860s · 28MB
26MB installed
● package 26MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
validate
✓ from jsonschema import validate
Top-level convenience function; raises ValidationError on first failure. Use a versioned validator + iter_errors() for collecting all errors.
ValidationError
✓ from jsonschema import ValidationError
Also importable as jsonschema.exceptions.ValidationError. Catching the top-level alias is fine and stable public API.
SchemaError
✓ from jsonschema import SchemaError
Raised when the schema itself is invalid against its metaschema. Call Validator.check_schema(schema) proactively to surface this.
Draft202012Validator
✓ from jsonschema import Draft202012Validator
Prefer an explicit versioned validator over the generic validate() for production use; it lets you reuse the compiled validator object across many instances.
Draft7Validator
✓ from jsonschema import Draft7Validator
Still widely used; available alongside Draft4Validator, Draft6Validator, Draft201909Validator, Draft202012Validator.
FormatChecker
✓ from jsonschema import FormatChecker
Must be passed explicitly as format_checker=FormatChecker() to activate format assertion; without it, 'format' keywords are informational only.
RefResolver
✓ from referencing import Registry
from referencing.jsonschema import DRAFT202012
✗ from jsonschema import RefResolver
RefResolver is deprecated since v4.18.0. Replace with referencing.Registry passed as the registry= kwarg to the validator constructor.
ErrorTree
✓ from jsonschema.exceptions import ErrorTree
Setting items on an ErrorTree (ErrorTree.__setitem__) is deprecated since v4.20.0. Populate via the constructor instead.
Validate a dict against a JSON Schema, collect all errors with a versioned validator, and demonstrate format checking.
from jsonschema import Draft202012Validator, FormatChecker, ValidationError
schema = {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {"type": "string"},
"price": {"type": "number", "minimum": 0},
"email": {"type": "string", "format": "email"},
},
"required": ["name", "price"],
}
# Reuse the validator object for efficiency (avoid re-creating per call)
# Pass format_checker to activate 'format' keyword assertions;
# without it, 'format' is purely informational and never raises.
validator = Draft202012Validator(schema, format_checker=FormatChecker())
good = {"name": "Widget", "price": 9.99, "email": "user@example.com"}
bad = {"name": "Widget", "price": "free", "email": "not-an-email"}
# validate() raises on the FIRST error; use iter_errors() for all errors.
try:
validator.validate(good)
print("good instance: valid")
except ValidationError as exc:
print(f"Unexpected error: {exc.message}")
all_errors = list(validator.iter_errors(bad))
for err in all_errors:
# err.path holds the JSON path to the failing field
field = " -> ".join(str(p) for p in err.absolute_path) or "<root>"
print(f"[{field}] {err.message}")
# Schema validity check (raises SchemaError if the schema is malformed)
Draft202012Validator.check_schema(schema)
Errors
Common errors & fixes
'property_name' is a required property
This `ValidationError` occurs when the JSON instance being validated is missing a property that is marked as `required` in the JSON Schema.
fixEnsure that the JSON instance includes all properties listed in the `required` array of your schema. For example, if your schema has `"required": ["name"]`, your instance must contain a `"name"` field.
jsonschema.exceptions.SchemaError: 'keyword' is not a valid JSON Schema keyword
This `SchemaError` indicates that the JSON Schema itself is invalid, often due to a typo in a keyword or using a keyword that is not recognized by the JSON Schema draft being used.
fixCorrect the misspelled keyword or ensure that all keywords used are valid for the JSON Schema draft specified (or implicitly used if `$schema` is omitted). Validate your schema against a linter or the official specification.
ImportError: No module named 'jsonschema.compat'
This error typically arises when code written for `jsonschema` version 3.x is run with `jsonschema` version 4.x or newer, as the `jsonschema.compat` module was removed in version 4.0.
fixEither update your code to remove reliance on the deprecated `compat` module and use equivalent functionalities available in `jsonschema` v4+, or downgrade `jsonschema` to a version less than 4.0 using `pip install 'jsonschema<4.0'`.
ImportError: cannot import name 'validate' from 'jsonschema'
This `ImportError` usually occurs because the `validate` function's direct import path changed in newer versions of the `jsonschema` library, or it's meant to be called differently.
fixInstead of `from jsonschema import validate`, you should import it from the `jsonschema` module directly if using `jsonschema.validate` (e.g., `import jsonschema` then `jsonschema.validate(instance, schema)`). In older versions where `validate` was a top-level function, ensure your environment's `jsonschema` version matches the expected API. If you are using a Validator class, you would call `validator.validate(instance)` instead.
jsonschema.exceptions.RefResolutionError: Unresolvable JSON pointer: 'some/path'
This error signifies that a `$ref` keyword in your JSON Schema could not be resolved. This often happens if the path in the `$ref` is incorrect, the referenced definition doesn't exist, or there are issues with resolving local or remote URIs.
fixVerify the `$ref` path to ensure it correctly points to an existing definition within the current schema (e.g., `#/definitions/myDefinition`) or a valid external schema. Ensure any external schemas are accessible and correctly specified. Consider using `RefResolver` for complex reference handling if necessary.
Audit
Dependencies
referencingrequiredNew $ref/registry resolution API replacing the deprecated RefResolver; pulled in automatically by jsonschema.
jsonschema-specificationsrequiredBundles the official JSON Schema meta-schemas (Draft 3–2020-12) for runtime access; pulled in automatically.
attrsrequiredUsed internally to define validator data classes; pulled in automatically.
fqdnoptionalRequired for 'hostname' format checking in the [format] extra (GPL-licensed).
rfc3987optionalRequired for 'iri' and 'iri-reference' format checking in the [format-nongpl] extra.
isodurationoptionalRequired for 'duration' format checking in the [format-nongpl] extra.