jsonref: JSON Reference Dereferencing

Common errors

• ImportError: cannot import name 'URIDict' from 'jsonref'

  cause This error often occurs when an older version of `jsonref` is installed, or when a dependent library expects a newer API that includes `URIDict`, which was removed or refactored in `jsonref` versions 1.0.0 and above.
  fix Upgrade `jsonref` to the latest version using `pip install --upgrade jsonref` to ensure compatibility with recent API changes. If using a dependency manager like `pipenv` or `conda`, ensure `jsonref` is updated to a compatible version.

• RecursionError: maximum recursion depth exceeded

  cause This error typically arises when processing JSON documents with deeply nested or circular `$ref` references, causing `jsonref`'s dereferencing logic to enter an infinite loop or exceed Python's default recursion limit.
  fix Inspect your JSON schema for circular references or excessively deep nesting. If the recursion is legitimate, you can temporarily increase Python's recursion limit for complex documents using `import sys; sys.setrecursionlimit(YOUR_NEW_LIMIT)`. However, it's often better to resolve circular dependencies in the schema itself if possible.

• json.decoder.JSONDecodeError: Expecting value: line X column Y (char Z)

  cause This error indicates that the input JSON document provided to `jsonref.loads()` or `jsonref.load()` is syntactically incorrect, preventing the underlying `json` module from parsing it before `jsonref` can process references.
  fix Validate your JSON input using a JSON linter or validator. Common issues include missing commas, unquoted keys or string values, incorrect use of single vs. double quotes, or unclosed brackets. Ensure the input is valid JSON before passing it to `jsonref`.

• JsonRefError: Unable to resolve reference: '#/some/path'

  cause This is a general error raised by `jsonref` when it encounters a JSON Reference (`$ref`) that it cannot successfully resolve, often due to a malformed URI, a non-existent path within the document, or an inaccessible external file.
  fix Verify that the URI in your `$ref` points to a valid location, both for internal document references (JSON Pointers) and external URIs. Ensure that any external files are accessible and contain valid JSON. Check for typos in the reference path or filename.

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
  wrong:

  from jsonref import JsonRef
  dereferenced_obj = JsonRef.replace_refs(python_object)

  correct:

  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}")