jsonref
jsonref is a library for automatic dereferencing of JSON Reference objects for Python.
Decision gist · record as of 2026-08-14
Yes, if you work with JSON Reference specs or JSON Schema. It's a small, dependency-free library with permissive licensing and no known vulnerabilities. The aging maintenance status is a minor concern, but recent repository activity and stable API suggest it works as intended for its narrow use case. Install it when you need transparent $ref resolution; skip it if you're manually parsing JSON without references.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires Python 3.7 or later.
- Low friction—pure Python wheel with no runtime dependencies.
- Maintenance is aging: last release was 2023-01-16, though the repository remains active with a recent commit on 2025-04-21.
License · maintenance · safety
MIT (permissive) — MIT license is permissive; you can use this package freely in commercial and proprietary projects with minimal restrictions.
last release 2023-01-16 (1306 days) · last repo commit 2025-04-21 · 153 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 95,277,791 downloads/mo, #356 on PyPI
Alternatives
Verify before relying
pip install jsonref
import jsonref
json_str = '{"real": [1, 2, 3], "ref": {"$ref": "#/real"}}'
data = jsonref.loads(json_str)
print(data["ref"]) # [1, 2, 3]- Whether lazy evaluation performance characteristics are documented or tested at scale.
- Current maintenance cadence and what the gap since 2023-01-16 signals about active development.
What it is and what it does
jsonref is a Python library that resolves JSON Reference objects (the $ref pointers defined in the JSON Reference spec) into the data they point to. When you load a JSON document with references, jsonref replaces those pointers with proxy objects that behave like the referenced data, but the actual dereferencing happens lazily—only when you access the data. This means you can work with large or circular reference structures without upfront resolution overhead.
The library has no runtime dependencies and works by wrapping referenced values in transparent proxy objects. You can access the underlying reference object via __reference__ or the dereferenced data via __subject__, and the proxies support all normal operations (iteration, mutation, type checks) on the target data. It's commonly used in JSON Schema validation, API documentation parsing, and any workflow where you need to follow $ref pointers without manually resolving them.
Use it for
- Parse OpenAPI/Swagger specifications that use $ref to modularize schema definitions across files.
- Load JSON Schema documents with internal cross-references without manually resolving each pointer.
- Handle recursive data structures where a JSON object references itself, creating circular references.
- Build configuration systems where config files reference shared definitions via JSON pointers.
- Process linked JSON documents in REST APIs where responses use $ref to avoid duplication.
Worth the install?
AI-flagged interpretation of the facts on this page. Verify before relying on it.
Yes, if you work with JSON Reference specs or JSON Schema.
It's a small, dependency-free library with permissive licensing and no known vulnerabilities. The aging maintenance status is a minor concern, but recent repository activity and stable API suggest it works as intended for its narrow use case. Install it when you need transparent $ref resolution; skip it if you're manually parsing JSON without references.
Install
jsonref on PyPI
Before you install
Low friction—pure Python wheel with no runtime dependencies. Maintenance is aging: last release was 2023-01-16, though the repository remains active with a recent commit on 2025-04-21.
Requires Python 3.7 or later.
License in practice
MIT license is permissive; you can use this package freely in commercial and proprietary projects with minimal restrictions.
Quickstart
pip install jsonref
import jsonref
json_str = '{"real": [1, 2, 3], "ref": {"$ref": "#/real"}}'
data = jsonref.loads(json_str)
print(data["ref"]) # [1, 2, 3]Verify before relying
- Whether lazy evaluation performance characteristics are documented or tested at scale.
- Current maintenance cadence and what the gap since 2023-01-16 signals about active development.
Package facts
| License | MIT permissive |
| Python support | Supports the current Python release >=3.7 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | None |
| Maintenance | Aging 1,306 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 95,277,791 / month, #356 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
Evidence: jsonref-1.1.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 dereferencing”
- jsonrefjsonref dereferences JSON Reference objects transparently, replacing…
- jsonschema-specProvides an object-oriented interface to traverse and dereference…
- jsonschema-pathProvides object-oriented path-based access to JSON Schema documents,…
Give your agent the search over MCP, or paste the wish link into any chat.
Similar packages
Resolves JSON references according to JSON Schema and related specifications, providing a standard way to handle $ref pointers in JSON documents.
Provides an object-oriented interface to traverse and dereference JSONSchema documents, treating them as navigable paths with automatic resolution of $ref pointers.
Provides a dict-like interface to JSONSchema documents that lazily resolves `$ref` references, supporting both local and remote schemas with optional YAML support.
Resolves JSON Pointers according to RFC 6901, allowing you to identify and access specific nodes within a JSON document using pointer syntax.
Install it if you need RFC 6901 JSON Pointer support; the small footprint and active maintenance make it a safe, straightforward choice.
Provides object-oriented path-based access to JSON Schema documents, with support for traversing schema structures and resolving references on demand.
Converts JSON Schema definitions to Pydantic v2 models at runtime, enabling dynamic validation and serialization of data against JSON Schema specifications.
However, it is in Alpha status (first release 2025-11-12), so expect potential API changes and test thoroughly before using in production.
See also lazy-object-proxy · jsonmerge · json-schema-to-pydantic · sphinx-jsonschema