Referencing

0.37.0 verified Tue May 12 auth: no python install: verified quickstart: stale

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.

pip install referencing

Common errors

error ModuleNotFoundError: No module named 'referencing' ↓

cause The 'referencing' library is not installed in the current Python environment.

fix

pip install referencing

error AttributeError: module 'referencing' has no attribute 'DRAFT202012' ↓

cause JSON Schema draft constants like 'DRAFT202012' are located within the 'referencing.jsonschema' submodule, not directly in the top-level 'referencing' module.

fix

from referencing.jsonschema import DRAFT202012

error TypeError: Resource.__init__() missing 1 required positional argument: 'content' ↓

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.

fix

import 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)

error referencing.exceptions.Unresolvable: Could not resolve reference ↓

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.

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.

Warnings

breaking Dropped support for Python 3.9 in version 0.37.0. ↓

fix Upgrade your Python environment to version 3.10 or later.

gotcha Ensure that schemas registered with the Registry have unique "$id" fields to avoid conflicts. ↓

fix Assign unique "$id" fields to each schema before registration.

gotcha When using references, ensure that the referenced schemas are registered in the registry to resolve them correctly. ↓

fix Register all referenced schemas in the registry before resolving references.

gotcha 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. ↓

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`.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.12s 20.3M

3.10 slim (glibc) - - 0.09s 20M

3.11 alpine (musl) - - 0.20s 22.4M

3.11 slim (glibc) - - 0.16s 22M

3.12 alpine (musl) - - 0.14s 14.2M

3.12 slim (glibc) - - 0.14s 14M

3.13 alpine (musl) - - 0.13s 13.5M

3.13 slim (glibc) - - 0.13s 14M

3.9 alpine (musl) - - 0.11s 19.8M

3.9 slim (glibc) - - 0.10s 20M

Imports

Registry
wrong
```
from referencing.registry import Registry
```
correct
```
from referencing import Registry
```
The correct import path is directly from the referencing package.

Resource

wrong

from referencing.resource import Resource

correct

from referencing import Resource

Import Resource directly from the referencing package.

Quickstart stale last tested: 2026-04-23

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)