{"id":305,"library":"referencing","title":"Referencing","description":"Referencing is a Python library that facilitates JSON referencing, enabling efficient handling of JSON references within Python applications. The current version is 0.37.0, released on March 28, 2026. The library maintains a regular release cadence, with updates addressing compatibility and feature enhancements.","status":"active","version":"0.37.0","language":"python","source_language":"en","source_url":"https://github.com/python-jsonschema/referencing","tags":["JSON","schema","references","Python"],"install":[{"cmd":"pip install referencing","lang":"bash","label":"Install referencing"}],"dependencies":[{"reason":"Provides backported type hints for older Python versions","package":"typing-extensions","optional":false}],"imports":[{"note":"The correct import path is directly from the referencing package.","wrong":"from referencing.registry import Registry","symbol":"Registry","correct":"from referencing import Registry"},{"note":"Import Resource directly from the referencing package.","wrong":"from referencing.resource import Resource","symbol":"Resource","correct":"from referencing import Resource"}],"quickstart":{"code":"from referencing import Registry, Resource\n\n# Create a new registry\nregistry = Registry()\n\n# Define a JSON schema with a reference\nschema = {\n    \"$id\": \"https://example.com/person.schema.json\",\n    \"type\": \"object\",\n    \"properties\": {\n        \"name\": {\"type\": \"string\"},\n        \"age\": {\"type\": \"integer\"},\n        \"address\": {\"$ref\": \"https://example.com/address.schema.json\"}\n    }\n}\n\n# Register the schema\nresource = Resource.from_contents(schema)\nregistry.register(resource)\n\n# Retrieve the registered schema\nretrieved_schema = registry.contents(\"https://example.com/person.schema.json\")\nprint(retrieved_schema)","lang":"python","description":"This example demonstrates how to create a registry, define a JSON schema with a reference, register the schema, and retrieve it from the registry."},"warnings":[{"fix":"Upgrade your Python environment to version 3.10 or later.","message":"Dropped support for Python 3.9 in version 0.37.0.","severity":"breaking","affected_versions":"0.37.0 and later"},{"fix":"Assign unique \"$id\" fields to each schema before registration.","message":"Ensure that schemas registered with the Registry have unique \"$id\" fields to avoid conflicts.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Register all referenced schemas in the registry before resolving references.","message":"When using references, ensure that the referenced schemas are registered in the registry to resolve them correctly.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Add an explicit `$schema` keyword to your schema, for example, `\"$schema\": \"https://json-schema.org/draft/2020-12/schema\"`, to declare its specification. Alternatively, ensure the schema structure is implicitly recognizable by the `referencing` library if you intend to omit `$schema`.","message":"The `referencing` library could not determine the specification of the provided schema. This typically occurs when the schema lacks a `$schema` keyword or uses a specification that the library does not implicitly recognize.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T12:58:09.570Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"pip install referencing","cause":"The 'referencing' library is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'referencing'"},{"fix":"from referencing.jsonschema import DRAFT202012","cause":"JSON Schema draft constants like 'DRAFT202012' are located within the 'referencing.jsonschema' submodule, not directly in the top-level 'referencing' module.","error":"AttributeError: module 'referencing' has no attribute 'DRAFT202012'"},{"fix":"import referencing\ndoc = {\"type\": \"object\"}\nresource = referencing.Resource.from_doc(doc)\n# For JSON Schema specific resources:\n# from referencing.jsonschema import DRAFT202012\n# schema_resource = DRAFT202012.create_resource(doc)","cause":"The 'referencing.Resource' constructor expects specific 'Anchor' objects and content, not a raw dictionary or document. To create a resource from a Python dictionary (representing a JSON document), use the 'Resource.from_doc()' static method or a draft-specific 'create_resource()' method.","error":"TypeError: Resource.__init__() missing 1 required positional argument: 'content'"},{"fix":"Ensure that the resource containing the referenced definition is correctly added to the 'referencing.Registry' with a resolvable base URI or ID, and that the reference path itself is valid for the registered resource.","cause":"The requested reference (e.g., a JSON Pointer or URI) cannot be resolved because the target document or definition is not present in the 'referencing.Registry' or the reference path is incorrect.","error":"referencing.exceptions.Unresolvable: Could not resolve reference"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":3.8,"disk_size":"20.3M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":3.8,"disk_size":"20M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.2,"mem_mb":3.9,"disk_size":"22.4M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.16,"mem_mb":3.9,"disk_size":"22M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.14,"mem_mb":3.8,"disk_size":"14.2M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.14,"mem_mb":3.8,"disk_size":"14M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":3.7,"disk_size":"13.5M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":3.5,"disk_size":"14M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.11,"mem_mb":3.8,"disk_size":"19.8M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":3.8,"disk_size":"20M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}