json-ref-dict

What it is and what it does

json-ref-dict wraps JSONSchema documents in a dict-like object that transparently resolves `$ref` references on access rather than upfront. This allows you to work with schemas as if all references were already expanded, even when they span multiple files or remote URLs, without loading the entire document into memory first.

The package handles local filesystem paths, HTTP(S) URLs, and YAML or JSON formats (YAML requires PyYAML to be installed separately). It also provides a `materialize()` function to eagerly resolve all references into a plain dict if you need to cache or persist the result. The lazy resolution model means you can work with potentially infinite or circular schema structures without explicit reference-chasing code.

Use it for:

• Load and navigate complex JSONSchema specifications that split definitions across multiple files without manually resolving each reference.
• Build schema validation tools that need to follow `$ref` pointers transparently while keeping memory usage low.
• Cache or persist a fully-resolved schema by materializing a RefDict into a plain dictionary for later use.
• Work with remote JSONSchema definitions (e.g., from json-schema.org) as if they were local, with references resolved on demand.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides a dict-like interface to JSONSchema documents that lazily resolves `$ref` references, supporting both local and remote schemas with optional YAML support.

No. The package is in abandoned maintenance (no releases in over a year, only 11 stars), and its Python support is unspecified beyond a 2019 test claim for Python 3.6. While the core idea is sound and the MIT license is permissive, the lack of active maintenance and unclear compatibility with current Python versions make it a risky choice for new projects. Consider alternatives that are actively maintained.

Install

json-ref-dict on PyPI

pip install json-ref-dict

uv add json-ref-dict

poetry add json-ref-dict

Installing json-ref-dict

Before you install

Low install friction with a single runtime dependency (jsonpointer). However, the package is in abandoned maintenance status with no releases since 2023-08-06 and only 11 repository stars, suggesting limited active use or community support.

License in practice

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

Quickstart

from json_ref_dict import RefDict

schema = RefDict("master.yaml#/definitions")
resolved = schema["remote_ref"]  # Lazily resolves $ref

PyYAML is optional; without it, only JSON documents can be loaded. Package is tested for Python 3.6 but current Python support is unspecified.

Verify before relying

• Whether the package works reliably with modern Python versions beyond 3.6
• Current state of cyclical reference handling and whether it causes issues in practice
• Performance characteristics with large or deeply nested schemas

Package facts

Evidence: json_ref_dict-0.7.2-py3-none-any.whl

Tags

More Software Development packages