Referencing

0.37.0 · active · verified Sat Mar 28

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.

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.

Install

pip install referencing Install referencing

Imports

Registry
```
from referencing import Registry
```
The correct import path is directly from the referencing package.
Resource
```
from referencing import Resource
```
Import Resource directly from the referencing package.

Quickstart

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)

view raw JSON →