referencing

JSON Referencing + Python

referencing Permissive license MIT AGING v0.37.0 released 2025-10-13

Install

referencing on PyPI

pip

pip install referencing

uv

uv add referencing

poetry

poetry add referencing

Package facts

License	MIT (permissive)
Python support	supports the current Python release (>=3.10)
Install friction	low — pure-Python wheel
Runtime dependencies	3 — attrs, rpds-py, typing-extensions
Maintenance	aging — 304 days since the last release
First released	2022-11-21
Popularity	one of the 100 most-downloaded packages on PyPI (30-day window, as of 2026-08-13)
Known vulnerabilities	none known (OSV.dev, checked 2026-08-13)

Evidence: referencing-0.37.0-py3-none-any.whl

Keywords: asyncapi, json, jsonschema, openapi, referencing

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

About referencing

from the package's own PyPI description — quoted content, verbatim

=============== referencing ===============

.. |PyPI| image:: https://img.shields.io/pypi/v/referencing.svg :alt: PyPI version :target: https://pypi.org/project/referencing/

.. |Pythons| image:: https://img.shields.io/pypi/pyversions/referencing.svg :alt: Supported Python versions :target: https://pypi.org/project/referencing/

.. |CI| image:: https://github.com/python-jsonschema/referencing/workflows/CI/badge.svg :alt: Build status :target: https://github.com/python-jsonschema/referencing/actions?query=workflow%3ACI

.. |ReadTheDocs| image:: https://readthedocs.org/projects/referencing/badge/?version=stable&style=flat :alt: ReadTheDocs status :target: https://referencing.readthedocs.io/en/stable/

.. |pre-commit| image:: https://results.pre-commit.ci/badge/github/python-jsonschema/referencing/main.svg :alt: pre-commit.ci status :target: https://results.pre-commit.ci/latest/github/python-jsonschema/referencing/main

An implementation-agnostic implementation of JSON reference resolution.

See the documentation <https://referencing.readthedocs.io/>_ for more details.

Read as markdown · JSON record · Source repository · Homepage · Docs

AI interpretation — verify before relying

AI-generated interpretation of the package facts above; every digit, version, license, or vulnerability id it cites is grounded in the facts already shown on this page

Resolves and manages JSON references across documents, enabling implementation-agnostic handling of `$ref` and related constructs used in JSON Schema, OpenAPI, and AsyncAPI specifications.

Low friction: pure Python wheel with only three lightweight runtime dependencies (attrs, rpds-py, typing-extensions). Maintenance status is aging—304 days since last release—but the package is stable and widely used in the top 100 PyPI tier.

MIT license permits unrestricted use, modification, and distribution with minimal attribution requirements, making it suitable for both open-source and proprietary projects.

Usage

pip install referencing

from referencing import Registry, Resource

registry = Registry().with_resource(
    uri="https://example.com/schema",
    resource=Resource.from_contents({"type": "object"})
)

Requires Python 3.10 or later.

Verdict: Stable, permissively licensed package for JSON reference resolution with minimal dependencies and strong adoption. Aging maintenance (304 days since release) is typical for mature, feature-complete libraries; no known vulnerabilities. Safe for production use in JSON Schema and OpenAPI tooling.

Needs verification

Whether the 304-day release cycle reflects intentional stability or reduced maintenance capacity
Performance characteristics under high-volume reference resolution workloads

json reference resolutionjson schema $ref handlingopenapi reference resolverjsonschema reference managementjson document linking