Install & Compatibility
Where this runs
tested against v0.7.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.134s · 17.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.126s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RefDict
✓ from json_ref_dict import RefDict
JsonRefDict
✓ from json_ref_dict import RefDict
✗ from json_ref_dict import JsonRefDict
The `JsonRefDict` alias for `RefDict` was removed in version 0.6.0. Use `RefDict` directly.
This quickstart demonstrates how to create a `RefDict` instance from a local YAML file containing JSON references, including local, remote, and back references. It shows how lazy loading works by accessing properties and includes cleanup of the temporary files created for the example.
import os
from json_ref_dict import RefDict
# Create dummy YAML files for the example
master_yaml_content = """
definitions:
foo:
type: string
local_ref:
$ref: '#/definitions/foo'
remote_ref:
$ref: 'other.yaml#/definitions/bar'
backref:
$ref: 'other.yaml#/definitions/baz'
"""
other_yaml_content = """
definitions:
bar:
type: integer
baz:
$ref: 'master.yaml#/definitions/foo'
"""
with open("master.yaml", "w") as f:
f.write(master_yaml_content)
with open("other.yaml", "w") as f:
f.write(other_yaml_content)
try:
# Initialize RefDict with a reference to a local YAML file and JSON pointer
schema = RefDict("master.yaml#/definitions")
# Accessing elements triggers lazy resolution
print("Type of local_ref:", schema["local_ref"]["type"])
print("Type of remote_ref:", schema["remote_ref"]["type"])
print("Type of backref:", schema["backref"]["type"])
# Materialize the document to a regular dict (optional)
# from json_ref_dict import materialize
# materialized_schema = materialize(schema)
# print("Materialized schema type:", type(materialized_schema))
except Exception as e:
print(f"An error occurred: {e}")
finally:
# Clean up dummy files
os.remove("master.yaml")
os.remove("other.yaml")
Errors
Common errors & fixes
from json_ref_dict import JsonRefDict
The alias `JsonRefDict` for the main `RefDict` class was removed in `json-ref-dict` version 0.6.0.
fixAlways use `RefDict` directly for imports and class instantiation: `from json_ref_dict import RefDict`.
isinstance(my_ref_dict, dict)` returning `False` or calling mutable dict methods like `pop()`
`RefDict` no longer inherits directly from `dict` but from `collections.abc.Mapping` since version 0.6.0, making it an immutable collection.
fixFor type checks, use `isinstance(obj, collections.abc.Mapping)`. To get a mutable dictionary or apply modifications, first call `my_ref_dict.materialize()` to convert it to a regular `dict`.
AttributeError: 'RefDict' object has no attribute '__json_ref__'
The internal attribute for accessing the original JSON reference object was renamed from `__json_ref__` to `__reference__` in `json-ref-dict` version 0.6.0 to align with `jsonref` library conventions.
fixUpdate any direct access to `obj.__json_ref__` to `obj.__reference__`.
jsonschema.exceptions.RefResolutionError: Unresolvable JSON pointer
This error, often encountered in the JSON Schema ecosystem, means a JSON reference (`$ref`) within the schema cannot be resolved because the path is incorrect, the referenced document (file/URL) is inaccessible, or its content is malformed.
fixEnsure all `$ref` pointers are valid, accessible, and point to properly formatted JSON or YAML documents relative to the base URI of the `RefDict`.
TypeError: Object of type RefDict is not JSON serializable
A `RefDict` object is a specialized, lazily resolving dictionary and is not directly serializable by Python's standard `json.dumps()` function, which expects plain Python primitive types or standard collections.
fixBefore serializing, convert the `RefDict` into a standard Python dictionary using its `materialize()` method: `json.dumps(my_ref_dict.materialize())`. If the materialized dict contains other non-serializable types (e.g., `datetime` objects), provide a custom JSONEncoder to `json.dumps()`.
Upgrade
Version history
0.7.2latest on PyPI · released Aug 6, 2023
Audit
Dependencies
PyYAMLoptionalOptional dependency to enable loading of YAML documents; without it, only JSON documents are supported.