Install & Compatibility
Where this runs
tested against v0.37.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.95 runs
installs and imports cleanly · install 0.0s · import 0.134s · 20.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.4s · import 0.120s · 20MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Registry
✓ from referencing import Registry
✗ from referencing.registry import Registry
The correct import path is directly from the referencing package.
Resource
✓ from referencing import Resource
✗ from referencing.resource import Resource
Import Resource directly from the referencing package.
This example demonstrates how to create a registry, define a JSON schema with a reference, register the schema, and retrieve it from the registry.
from referencing import Registry, Resource
# Create a new registry
registry = Registry()
# Define a JSON schema with a reference
schema = {
"$id": "https://example.com/person.schema.json",
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "integer"},
"address": {"$ref": "https://example.com/address.schema.json"}
}
}
# Register the schema
resource = Resource.from_contents(schema)
registry.register(resource)
# Retrieve the registered schema
retrieved_schema = registry.contents("https://example.com/person.schema.json")
print(retrieved_schema)
Debug
Known issues
breakingDropped support for Python 3.9 in version 0.37.0.fixUpgrade your Python environment to version 3.10 or later.
affects: 0.37.0 and later
gotchaEnsure that schemas registered with the Registry have unique "$id" fields to avoid conflicts.fixAssign unique "$id" fields to each schema before registration.
affects: All versions
gotchaWhen using references, ensure that the referenced schemas are registered in the registry to resolve them correctly.fixRegister all referenced schemas in the registry before resolving references.
affects: All versions
gotchaThe `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.fixAdd 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`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'referencing'
The 'referencing' library is not installed in the current Python environment.
fixpip install referencing
AttributeError: module 'referencing' has no attribute 'DRAFT202012'
JSON Schema draft constants like 'DRAFT202012' are located within the 'referencing.jsonschema' submodule, not directly in the top-level 'referencing' module.
fixfrom referencing.jsonschema import DRAFT202012
TypeError: Resource.__init__() missing 1 required positional argument: 'content'
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.
fiximport referencing
doc = {"type": "object"}
resource = referencing.Resource.from_doc(doc)
# For JSON Schema specific resources:
# from referencing.jsonschema import DRAFT202012
# schema_resource = DRAFT202012.create_resource(doc) referencing.exceptions.Unresolvable: Could not resolve reference
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.
fixEnsure 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.
Upgrade
Version history
0.37.0latest on PyPI · released Oct 13, 2025
Audit
Dependencies
typing-extensionsrequiredProvides backported type hints for older Python versions