referencing

referencing is a small, implementation-agnostic Python library for resolving $ref/JSON reference-style pointers across specifications — JSON Schema, OpenAPI, AsyncAPI, or any custom hypermedia format that uses the same referencing pattern. It grew out of the jsonschema project as a standalone, spec-agnostic replacement for ad hoc reference-resolution code, providing an explicit Registry and Resource model for tracking which documents are known, how they relate, and how a reference should be dereferenced within that registry.

Because reference resolution semantics differ subtly between specifications (JSON Schema’s own dialects handle $id/$anchor/$ref differently across draft versions, for example), referencing models this as pluggable “specifications” rather than hardcoding one behavior — the referencing.jsonschema module supplies JSON Schema-specific specs for each draft, while the core referencing package stays specification-neutral. It has become foundational infrastructure: it’s a direct dependency of jsonschema itself and is pulled in, often transitively, by huge swaths of the Python ecosystem that validate JSON Schema or OpenAPI documents.

What You Get

• A Registry for tracking resources and resolving references across documents without global mutable state
• Pluggable Specification objects that encode format-specific referencing rules (e.g. per-draft JSON Schema semantics)
• Built-in JSON Schema draft support (Draft 4 through the latest) via referencing.jsonschema
• A retrieval hook for lazily fetching external references (e.g. over the network or from a local store)
• Conformance against the shared json-schema-org test suite via a bundled test corpus

Common Use Cases

• Resolving $ref pointers when validating JSON Schema documents across mixed draft versions
• Building an OpenAPI or AsyncAPI tool that needs correct, spec-aware reference resolution
• Implementing a custom hypermedia or config format that uses JSON-reference-style pointers
• Replacing ad hoc, hand-rolled $ref resolution code with a tested, spec-agnostic library

Under The Hood

Architecture - The core model lives in referencing/_core.py (~730 lines): a Registry is an immutable-by-convention mapping of URIs to Resource objects, and resolving a reference walks that registry via a Resolver that is scoped to the current document, correctly handling nested $id/base-URI changes. referencing/jsonschema.py (~640 lines) supplies Specification instances for each JSON Schema draft, encoding how $ref, $anchor, and $dynamicRef behave differently release to release, while referencing/retrieval.py provides an extension point for fetching not-yet-known external resources on demand.

Tech Stack - Modern, minimal-dependency Python (targeting 3.13+ classifiers) built with hatchling/hatch-vcs, using attrs internally (referencing/_attrs.py) for its core data classes, and managed with uv for dependency locking and nox for task automation.

Code Quality - referencing/tests/ contains dedicated suites for core resolution logic, JSON Schema-specific behavior, the retrieval hook, and exception handling, plus test_referencing_suite.py, which runs the library against the shared, cross-implementation json-schema-org test suite (suite/ submodule) — meaning correctness is validated against the same conformance tests other JSON Schema implementations use, not just hand-written unit tests.

API Design - The public surface is deliberately small: construct a Registry, add Resources, and call .resolver()/.resolve(); because the library models referencing as immutable value objects rather than mutable global state, integrating it requires understanding its registry/resource vocabulary upfront, which is a small but real learning curve for a library whose job is otherwise conceptually simple.