jsonref

jsonref is a small Python library that automatically resolves JSON Reference ($ref) pointers embedded in JSON documents, so consuming code can work with a data structure as if references had already been replaced with their referent data — without eagerly walking or mutating the whole document.

What You Get

• jsonref.loads/load drop-in replacements for json.loads/load that resolve $ref pointers
• Lazy proxy objects (JsonRef) that defer dereferencing until first access
• Recursive reference support, producing recursive Python data structures where needed
• Access to both the resolved value (subject) and the original reference object (reference)

Common Use Cases

• Resolving $ref pointers in JSON Schema documents before validation or codegen
• Loading OpenAPI/Swagger specs that split definitions across $ref-linked JSON fragments
• Working with any JSON Reference-based config or data format without pre-flattening it
• Building tooling that needs to distinguish original references from resolved values via proxy introspection

Under The Hood

Architecture - jsonref/__init__.py implements a custom JSON object hook that intercepts $ref keys during parsing and replaces them with JsonRef proxy instances; proxytypes.py implements the lazy-proxy machinery (LazyProxy/CallbackProxy) using __subject__/__reference__ attributes so proxies behave transparently as their underlying list/dict/scalar type via Python’s data model. Tech Stack - Zero runtime dependencies, pure Python 3.7+, built directly on the standard-library json module (no schema-specific parsing); dev dependencies are limited to pytest, flake8, and black, with pdm-backend as the build system. Code Quality - Well covered by a focused test suite split by concern (test_proxies.py, test_jsonref.py, test_jsonref_errors.py, test_json_loader.py, test_api.py), plus Coveralls-tracked coverage and GitHub Actions CI; the library is stable and small (about 836 lines total) with sparse but sufficient docstrings, though it has seen no commits since April 2025. API Design - The API is intentionally a near drop-in replacement for json.load/json.loads, minimizing the learning curve; the lazy-proxy design keeps memory/CPU cost low for large documents where not every reference is used, at the cost of some surprise for callers unfamiliar with proxy-object semantics (e.g. type() on a resolved ref differs from isinstance() checks).