referencing
JSON Referencing + Python
Decision gist · record as of 2026-08-14
Yes, if you are building or extending JSON Schema, OpenAPI, or AsyncAPI tooling and need a standard, implementation-agnostic way to resolve references. The MIT license, low install friction, and top-100 popularity indicate it is a mature, widely-trusted component. The aging maintenance status (305 days since last release) is not a blocker for stable use, but monitor for security updates. No known vulnerabilities.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires Python 3.10 or later (CPython or PyPy).
- Low install friction with three lightweight runtime dependencies (attrs, rpds-py, typing-extensions).
- Maintenance status is aging—last release was 305 days ago—so expect slower response to issues, though the package is stable enough for production use.
License · maintenance · safety
MIT (permissive) — MIT license is permissive; you can use, modify, and distribute this package with minimal restrictions, making it safe for both open-source and commercial projects.
last release 2025-10-13 (305 days)
0 known vulnerabilities (OSV.dev, 2026-08-14) · 545,376,376 downloads/mo, #69 on PyPI
Alternatives
Verify before relying
pip install referencing
from referencing import Registry, Resource
resolver = Registry().with_resource(
uri="https://example.com/schema",
resource=Resource.from_contents({"type": "object"})
).resolver("https://example.com/schema")- Whether the package actively resolves remote HTTP(S) references or only handles local/registry-based resolution.
- Performance characteristics when resolving deeply nested or circular reference structures.
- Whether async reference resolution is supported or only synchronous.
What it is and what it does
referencing is a JSON reference resolver that implements the JSON Schema specification's approach to handling $ref pointers. It decouples reference resolution logic from any particular JSON Schema validator or document parser, making it reusable across different tools and frameworks that work with JSON Schema, OpenAPI, or AsyncAPI.
The package provides a Registry-based system where you can register JSON resources and then resolve references against them. It handles the mechanics of looking up references, managing URI resolution, and returning the referenced content in a standardized way. With three lightweight dependencies (attrs, rpds-py, typing-extensions) and low install friction, it's designed to be embedded in larger JSON Schema tooling rather than used standalone.
Use it for
- Build a JSON Schema validator that needs to resolve $ref pointers without reimplementing reference logic.
- Create an OpenAPI or AsyncAPI parser that must follow external schema references.
- Implement a JSON document validator that supports both local and remote schema references.
- Develop tooling that needs to traverse and resolve references within a collection of JSON schemas.
- Add reference resolution to a code generator that consumes JSON Schema definitions.
Worth the install?
AI-flagged interpretation of the facts on this page. Verify before relying on it.
Yes, if you are building or extending JSON Schema, OpenAPI, or AsyncAPI tooling and need a standard, implementation-agnostic way to resolve references.
The MIT license, low install friction, and top-100 popularity indicate it is a mature, widely-trusted component. The aging maintenance status (305 days since last release) is not a blocker for stable use, but monitor for security updates. No known vulnerabilities.
Install
referencing on PyPI
Before you install
Low install friction with three lightweight runtime dependencies (attrs, rpds-py, typing-extensions). Maintenance status is aging—last release was 305 days ago—so expect slower response to issues, though the package is stable enough for production use.
Requires Python 3.10 or later (CPython or PyPy).
License in practice
MIT license is permissive; you can use, modify, and distribute this package with minimal restrictions, making it safe for both open-source and commercial projects.
Quickstart
pip install referencing
from referencing import Registry, Resource
resolver = Registry().with_resource(
uri="https://example.com/schema",
resource=Resource.from_contents({"type": "object"})
).resolver("https://example.com/schema")Verify before relying
- Whether the package actively resolves remote HTTP(S) references or only handles local/registry-based resolution.
- Performance characteristics when resolving deeply nested or circular reference structures.
- Whether async reference resolution is supported or only synchronous.
Package facts
| License | MIT permissive |
| Python support | Supports the current Python release >=3.10 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 3 packagesattrsrpds-pytyping-extensions |
| Maintenance | Aging 305 days since the last release |
| First released | |
| Downloads | 545,376,376 / month, #69 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 3 - AlphaIntended Audience :: DevelopersOperating System :: OS IndependentProgramming Language :: PythonProgramming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.14Programming Language :: Python :: Implementation :: CPythonProgramming Language :: Python :: Implementation :: PyPyTopic :: File Formats :: JSONTopic :: File Formats :: JSON :: JSON Schema |
Evidence: referencing-0.37.0-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “json reference resolution”
- referencingResolves JSON references according to JSON Schema and related…
- jsonrefjsonref dereferences JSON Reference objects transparently, replacing…
- jsonpointerResolves JSON Pointers according to RFC 6901, allowing you to…
Give your agent the search over MCP, or paste the wish link into any chat.
More JSON packages
jsonschema validates Python data structures against JSON Schema specifications, raising exceptions when validation fails or iterating through all errors found.
Install it if you need to validate JSON or JSON-like data structures.
Provides JSON Schema metaschemas, vocabularies, and specification files packaged as a Python-accessible Registry for runtime schema validation and reference resolution.
Install it if you are building validation tooling or using a validator that depends on it; it adds negligible friction.
A fast JSON parser that converts bytes into Python objects, offering tuning options for string caching, partial parsing, duplicate key detection, and float representation.
Install only if performance or parsing control (partial mode, duplicate detection, float precision) matters for your use case.
Generates country- and subdivision-specific government holiday calendars on demand, supporting 250 country codes with optional language localization and holiday categories.
GenSON generates JSON Schema documents from JSON objects and can merge multiple schemas together, inferring a unified schema that describes the common structure of your data.
jsonschema-rs validates JSON data against JSON Schema documents using a Rust-backed implementation for high performance, supporting drafts 4 through 2020-12 with customizable format validators and keywords.
Install it if you validate JSON frequently or need to support multiple schema drafts.
See also json-ref-dict · jsonpointer · jsonref · jsonschema-spec · jsonschema-path · json-source-map · sphinx-jsonschema · resolvelib · oelint-parser