---
id: json-ref-dict
version: "0.7.2"
license: MIT
license_treatment: permissive
maintenance: abandoned
---

# json-ref-dict — Python dict-like object which abstracts resolution of JSONSchema references

License: permissive · Maintenance: abandoned · Downloads: 544.6K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: abandoned
- Downloads: 544.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

jsonschema reference resolution, lazy schema reference loading, json schema $ref dict, resolve jsonschema references, schema reference abstraction, schema-resolution, json-processing

[View on SkillFed](https://skillfed.io/packages/json-ref-dict) · [View on PyPI](https://pypi.org/project/json-ref-dict/)