jsonschema

Warnings

• breaking jsonschema.RefResolver is deprecated since v4.18.0 and will be removed in a future major release. The resolver= constructor kwarg is also deprecated.
  Fix: Replace RefResolver with a referencing.Registry object and pass it as the registry= kwarg: `from referencing import Registry; from referencing.jsonschema import DRAFT202012; registry = Registry().with_resource('http://example.com', DRAFT202012.create_resource({...})); Draft202012Validator(schema, registry=registry)`.
• gotcha format keywords (e.g. 'email', 'date-time', 'uri') are NEVER validated unless you explicitly pass format_checker=FormatChecker(). Without it, format is purely informational and invalid values silently pass.
  Fix: Pass format_checker=FormatChecker() to validate() or the validator constructor. Also install the [format-nongpl] or [format] extras so the underlying checker packages (e.g. email-validator, rfc3339-validator) are present.
• deprecated Subclassing validator classes (Draft7Validator, Draft202012Validator, etc.) has been explicitly warned against since v4.12.0 and is not public API.
  Fix: Use jsonschema.validators.extend() or jsonschema.validators.create() to produce custom validator classes instead of inheriting directly.
• gotcha validate() raises only the FIRST ValidationError encountered and stops. All subsequent errors in the same instance are silently dropped.
  Fix: Use Validator.iter_errors(instance) to lazily yield every error, or Validator.is_valid(instance) for a simple boolean check without exceptions.
• breaking Python 3.8 support was dropped in v4.24.0. Pinning to <4.24.0 is required to maintain 3.8 compatibility.
  Fix: Upgrade to Python 3.10+ (the current requires-python floor). If you must stay on 3.8, pin jsonschema<4.24.0.
• gotcha jsonschema does not fill in 'default' values from the schema into validated instances. The 'default' keyword is purely decorative metadata during validation.
  Fix: If you need default-filling behavior, write a custom validator using jsonschema.validators.extend() that handles the 'default' keyword, or use a separate post-validation step.
• deprecated ErrorTree.__setitem__ (mutating an ErrorTree after construction) is deprecated since v4.20.0.
  Fix: Pass all sub-errors at construction time: ErrorTree(errors=list_of_errors). Do not mutate the tree after creation.

Install

• pip install jsonschema Core install
• pip install "jsonschema[format-nongpl]" With format checkers (non-GPL extras: date-time, email, hostname, ipv4/6, uri, uuid, etc.)
• pip install "jsonschema[format]" With all format checkers (includes GPL-licensed fqdn dependency)

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

  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

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)