{"id":278,"library":"jsonschema","title":"jsonschema","description":"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.","status":"active","version":"4.26.0","language":"python","source_language":"en","source_url":"https://github.com/python-jsonschema/jsonschema","tags":["validation","json-schema","json","schema","draft-2020-12","draft-7","data-validation"],"install":[{"cmd":"pip install jsonschema","lang":"bash","label":"Core install"},{"cmd":"pip install \"jsonschema[format-nongpl]\"","lang":"bash","label":"With format checkers (non-GPL extras: date-time, email, hostname, ipv4/6, uri, uuid, etc.)"},{"cmd":"pip install \"jsonschema[format]\"","lang":"bash","label":"With all format checkers (includes GPL-licensed fqdn dependency)"}],"dependencies":[{"reason":"New $ref/registry resolution API replacing the deprecated RefResolver; pulled in automatically by jsonschema.","package":"referencing","optional":false},{"reason":"Bundles the official JSON Schema meta-schemas (Draft 3–2020-12) for runtime access; pulled in automatically.","package":"jsonschema-specifications","optional":false},{"reason":"Used internally to define validator data classes; pulled in automatically.","package":"attrs","optional":false},{"reason":"Required for 'hostname' format checking in the [format] extra (GPL-licensed).","package":"fqdn","optional":true},{"reason":"Required for 'iri' and 'iri-reference' format checking in the [format-nongpl] extra.","package":"rfc3987","optional":true},{"reason":"Required for 'duration' format checking in the [format-nongpl] extra.","package":"isoduration","optional":true}],"imports":[{"note":"Top-level convenience function; raises ValidationError on first failure. Use a versioned validator + iter_errors() for collecting all errors.","symbol":"validate","correct":"from jsonschema import validate"},{"note":"Also importable as jsonschema.exceptions.ValidationError. Catching the top-level alias is fine and stable public API.","symbol":"ValidationError","correct":"from jsonschema import ValidationError"},{"note":"Raised when the schema itself is invalid against its metaschema. Call Validator.check_schema(schema) proactively to surface this.","symbol":"SchemaError","correct":"from jsonschema import SchemaError"},{"note":"Prefer an explicit versioned validator over the generic validate() for production use; it lets you reuse the compiled validator object across many instances.","symbol":"Draft202012Validator","correct":"from jsonschema import Draft202012Validator"},{"note":"Still widely used; available alongside Draft4Validator, Draft6Validator, Draft201909Validator, Draft202012Validator.","symbol":"Draft7Validator","correct":"from jsonschema import Draft7Validator"},{"note":"Must be passed explicitly as format_checker=FormatChecker() to activate format assertion; without it, 'format' keywords are informational only.","symbol":"FormatChecker","correct":"from jsonschema import FormatChecker"},{"note":"RefResolver is deprecated since v4.18.0. Replace with referencing.Registry passed as the registry= kwarg to the validator constructor.","wrong":"from jsonschema import RefResolver","symbol":"RefResolver","correct":"from referencing import Registry\nfrom referencing.jsonschema import DRAFT202012"},{"note":"Setting items on an ErrorTree (ErrorTree.__setitem__) is deprecated since v4.20.0. Populate via the constructor instead.","symbol":"ErrorTree","correct":"from jsonschema.exceptions import ErrorTree"}],"quickstart":{"code":"from jsonschema import Draft202012Validator, FormatChecker, ValidationError\n\nschema = {\n    \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n    \"type\": \"object\",\n    \"properties\": {\n        \"name\": {\"type\": \"string\"},\n        \"price\": {\"type\": \"number\", \"minimum\": 0},\n        \"email\": {\"type\": \"string\", \"format\": \"email\"},\n    },\n    \"required\": [\"name\", \"price\"],\n}\n\n# Reuse the validator object for efficiency (avoid re-creating per call)\n# Pass format_checker to activate 'format' keyword assertions;\n# without it, 'format' is purely informational and never raises.\nvalidator = Draft202012Validator(schema, format_checker=FormatChecker())\n\ngood = {\"name\": \"Widget\", \"price\": 9.99, \"email\": \"user@example.com\"}\nbad  = {\"name\": \"Widget\", \"price\": \"free\", \"email\": \"not-an-email\"}\n\n# validate() raises on the FIRST error; use iter_errors() for all errors.\ntry:\n    validator.validate(good)\n    print(\"good instance: valid\")\nexcept ValidationError as exc:\n    print(f\"Unexpected error: {exc.message}\")\n\nall_errors = list(validator.iter_errors(bad))\nfor err in all_errors:\n    # err.path holds the JSON path to the failing field\n    field = \" -> \".join(str(p) for p in err.absolute_path) or \"<root>\"\n    print(f\"[{field}] {err.message}\")\n\n# Schema validity check (raises SchemaError if the schema is malformed)\nDraft202012Validator.check_schema(schema)\n","lang":"python","description":"Validate a dict against a JSON Schema, collect all errors with a versioned validator, and demonstrate format checking."},"warnings":[{"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)`.","message":"jsonschema.RefResolver is deprecated since v4.18.0 and will be removed in a future major release. The resolver= constructor kwarg is also deprecated.","severity":"breaking","affected_versions":">=4.18.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Use jsonschema.validators.extend() or jsonschema.validators.create() to produce custom validator classes instead of inheriting directly.","message":"Subclassing validator classes (Draft7Validator, Draft202012Validator, etc.) has been explicitly warned against since v4.12.0 and is not public API.","severity":"deprecated","affected_versions":">=4.12.0"},{"fix":"Use Validator.iter_errors(instance) to lazily yield every error, or Validator.is_valid(instance) for a simple boolean check without exceptions.","message":"validate() raises only the FIRST ValidationError encountered and stops. All subsequent errors in the same instance are silently dropped.","severity":"gotcha","affected_versions":"all"},{"fix":"Upgrade to Python 3.10+ (the current requires-python floor). If you must stay on 3.8, pin jsonschema<4.24.0.","message":"Python 3.8 support was dropped in v4.24.0. Pinning to <4.24.0 is required to maintain 3.8 compatibility.","severity":"breaking","affected_versions":">=4.24.0"},{"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.","message":"jsonschema does not fill in 'default' values from the schema into validated instances. The 'default' keyword is purely decorative metadata during validation.","severity":"gotcha","affected_versions":"all"},{"fix":"Pass all sub-errors at construction time: ErrorTree(errors=list_of_errors). Do not mutate the tree after creation.","message":"ErrorTree.__setitem__ (mutating an ErrorTree after construction) is deprecated since v4.20.0.","severity":"deprecated","affected_versions":">=4.20.0"}],"env_vars":null,"search_vec":"'-09':23 '-12':26,71 '-2020':70 '-7':73 '2019':22 '2020':25 '3':18 '3.10':35 '4':19 '4.26.0':32 '6':20 '7':21 'backward':52 'backwards-compat':51 'becom':61 'carri':58 'compat':53 'complet':6 'compliant':10 'current':28 'data':75 'data-valid':74 'deprec':59 'draft':17,69,72 'expect':48 'follow':37 'frequent':42 'github':44 'json':11,65,67 'json-schema':64 'jsonschema':1,2 'major':55 'may':57 'minor':45 'python':15,34 'releas':30,36,46 'remov':62 'requir':33 'schema':12,66,68 'semant':38 'ship':41 'spec':9 'spec-compli':8 'stabl':29 'support':16 'valid':13,63,76 'version':39,56 'via':43","created_at":"2026-03-28T05:38:24.893517+00:00","updated_at":"2026-04-16T15:57:20.301740+00:00","problems":[{"fix":"Ensure 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.","cause":"This `ValidationError` occurs when the JSON instance being validated is missing a property that is marked as `required` in the JSON Schema.","error":"'property_name' is a required property"},{"fix":"Correct 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.","cause":"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.","error":"jsonschema.exceptions.SchemaError: 'keyword' is not a valid JSON Schema keyword"},{"fix":"Either 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'`.","cause":"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.","error":"ImportError: No module named 'jsonschema.compat'"},{"fix":"Instead 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.","cause":"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.","error":"ImportError: cannot import name 'validate' from 'jsonschema'"},{"fix":"Verify 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.","cause":"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.","error":"jsonschema.exceptions.RefResolutionError: Unresolvable JSON pointer: 'some/path'"}],"ecosystem":"pypi","meta_description":null,"install_score":95,"quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"4.26.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/python-jsonschema/jsonschema","docs":"https://python-jsonschema.readthedocs.io/","changelog":"https://github.com/python-jsonschema/jsonschema/blob/main/CHANGELOG.rst","pypi":"https://pypi.org/project/jsonschema/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":"verified"}}