jsonschema

Common errors

Warnings

Install

Install compatibility verified last tested: 2026-05-12

Imports

• 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
  wrong

  from jsonschema import RefResolver

  correct

  from referencing import Registry
  from referencing.jsonschema import DRAFT202012

  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.

Quickstart verified last tested: 2026-04-23

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)