jsonref: JSON Reference Dereferencing

Warnings

• breaking The `jsonloader` utility (for loading URIs) changed from being an instance of a class to a plain function. If you were subclassing `JsonLoader` prior to version 0.4, your code will break.
  Fix: Rewrite code that subclassed `JsonLoader` to adapt to `jsonloader` being a standalone function. Review the `loader` parameter in `replace_refs` and `loads`.
• deprecated The class method `JsonRef.replace_refs()` is deprecated. You should use the top-level function `jsonref.replace_refs()` instead.
  Fix: Change calls from `JsonRef.replace_refs(obj)` to `jsonref.replace_refs(obj)`.
• gotcha When working with `JsonRef` proxy objects, direct access to the dereferenced subject is via the `__subject__` attribute (which forces loading if lazy). The original reference object can be accessed via `__reference__`.
  Fix: Be aware that simply accessing a `JsonRef` instance will trigger lazy loading. If you need the raw reference or the underlying data without proxy behavior, use `.__reference__` or `.__subject__` respectively.
• gotcha The `jsonschema=True` parameter in `loads` and `replace_refs` changes how object identifiers are handled, defaulting to `$id` instead of `id` (like JSON Schema draft v06+). This also means `$id` does *not* establish the base URI for references within the document, differing from canonical JSON Schema.
  Fix: If working with JSON Schema, set `jsonschema=True`. Be mindful that base URIs must be provided explicitly or derived from the resource's load location, as `$id` will not automatically change it within `jsonref`.
• gotcha Unlike the standard `json.dumps()` or `json.dump()`, `jsonref.dumps()` and `jsonref.dump()` will serialize `JsonRef` instances back into their *original JSON Reference objects*, not their dereferenced values. This is by design to preserve the reference structure.
  Fix: If you need to serialize the fully dereferenced content, ensure all `JsonRef` objects have been accessed (thus loaded) and then use standard `json.dumps()` on the resulting Python object. Alternatively, convert `JsonRef` objects to their `__subject__` if necessary before dumping.

Install

• pip install jsonref Install with pip

Imports

• loads

  import jsonref
  data = jsonref.loads(json_string)

  Used for parsing JSON strings with references directly.
• replace_refs

  from jsonref import replace_refs
  dereferenced_obj = replace_refs(python_object)

  The class method `JsonRef.replace_refs` is deprecated since version 0.4; use the top-level function `jsonref.replace_refs` instead.
• JsonRef

  from jsonref import JsonRef

  Represents a lazy-loading proxy to dereferenced data. Instances proxy almost all operators and attributes to the referent data.
• JsonRefError

  from jsonref import JsonRefError

  Exception raised when a JSON reference resolution fails.

Quickstart

Demonstrates loading JSON with references using `jsonref.loads`, dereferencing an existing Python object with `jsonref.replace_refs`, and a conceptual example of handling external references using a custom loader. It highlights how `JsonRef` objects act as lazy proxies to the underlying data.

import jsonref
import json

# Example 1: Loading from a JSON string with internal references
json_str = '''
{
    "data": [1, 2, 3, 4],
    "ref_to_data": {"$ref": "#/data"},
    "ref_to_item": {"$ref": "#/data/1"}
}
'''
data_from_str = jsonref.loads(json_str)

print("--- From jsonref.loads ---")
print(f"Original data: {data_from_str['data']}")
print(f"Reference to data: {data_from_str['ref_to_data']}") # Lazy loaded when accessed
print(f"Reference to item: {data_from_str['ref_to_item']}") # Lazy loaded when accessed
print(f"Is ref_to_data a JsonRef instance? {isinstance(data_from_str['ref_to_data'], jsonref.JsonRef)}")
print(f"Direct access to referent: {data_from_str['ref_to_data'].__subject__}")
print(f"Original reference object: {data_from_str['ref_to_data'].__reference__}")

# Example 2: Replacing references in an existing Python object
from jsonref import replace_refs

python_obj = {
    "items": ["apple", "banana", "cherry"],
    "first_item_ref": {"$ref": "#/items/0"}
}

dereferenced_obj = replace_refs(python_obj)

print("\n--- From jsonref.replace_refs ---")
print(f"Original Python object: {json.dumps(python_obj)}")
print(f"Dereferenced object: {json.dumps(dereferenced_obj)}")
print(f"Accessing dereferenced value: {dereferenced_obj['first_item_ref']}")

# Example 3: Handling external references (requires 'requests' or will use urllib)
# For external references, a loader can be specified. jsonloader is the default.
# This example is conceptual as 'example.com/schema.json' is not guaranteed to exist.
# If you have a local 'schema.json' with {"version": "1.0"}, use 'file:///path/to/schema.json'
external_ref_schema = {
    "my_schema": {"$ref": "http://example.com/schema.json#/version"}
}
# Assuming http://example.com/schema.json contains {"version": "1.0"}
# This would attempt to fetch the external URI:
try:
    # Use a mock loader for demonstration, as live external URIs might be flaky
    def mock_loader(uri):
        if uri == "http://example.com/schema.json":
            return {"version": "1.0", "description": "A simple schema"}
        raise JsonRefError(f"Unknown URI: {uri}", reference={'$ref': uri})

    external_data = replace_refs(external_ref_schema, loader=mock_loader)
    print("\n--- External Reference Example (Conceptual) ---")
    print(f"External data reference: {external_data['my_schema']}")
except JsonRefError as e:
    print(f"\nCould not resolve external reference (expected if example.com is not valid): {e.message}")