{"id":648,"library":"jsonref","title":"jsonref: JSON Reference Dereferencing","description":"jsonref is a Python library (supporting Python 3.7+) for automatic dereferencing of JSON Reference objects within JSON documents. It allows you to work with data structures containing JSON references as if they were already replaced with their referent data, supporting lazy and recursive dereferencing. The current version is 1.1.0, with its last release in January 2023, indicating active maintenance.","status":"active","version":"1.1.0","language":"python","source_language":"en","source_url":"https://github.com/gazpachoking/jsonref","tags":["JSON","reference","dereferencing","schema","lazy loading"],"install":[{"cmd":"pip install jsonref","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Used for fetching HTTP/HTTPS URIs if available; falls back to urllib otherwise.","package":"requests","optional":true}],"imports":[{"wrong":"import jsonref","symbol":"JsonRef","correct":"from jsonref import JsonRef"},{"wrong":"import jsonref","symbol":"loads","correct":"from jsonref import loads"},{"wrong":"import jsonref","symbol":"load","correct":"from jsonref import load"}],"quickstart":{"code":"import jsonref\nimport json\n\n# Example 1: Loading from a JSON string with internal references\njson_str = '''\n{\n    \"data\": [1, 2, 3, 4],\n    \"ref_to_data\": {\"$ref\": \"#/data\"},\n    \"ref_to_item\": {\"$ref\": \"#/data/1\"}\n}\n'''\ndata_from_str = jsonref.loads(json_str)\n\nprint(\"--- From jsonref.loads ---\")\nprint(f\"Original data: {data_from_str['data']}\")\nprint(f\"Reference to data: {data_from_str['ref_to_data']}\") # Lazy loaded when accessed\nprint(f\"Reference to item: {data_from_str['ref_to_item']}\") # Lazy loaded when accessed\nprint(f\"Is ref_to_data a JsonRef instance? {isinstance(data_from_str['ref_to_data'], jsonref.JsonRef)}\")\nprint(f\"Direct access to referent: {data_from_str['ref_to_data'].__subject__}\")\nprint(f\"Original reference object: {data_from_str['ref_to_data'].__reference__}\")\n\n# Example 2: Replacing references in an existing Python object\nfrom jsonref import replace_refs\n\npython_obj = {\n    \"items\": [\"apple\", \"banana\", \"cherry\"],\n    \"first_item_ref\": {\"$ref\": \"#/items/0\"}\n}\n\ndereferenced_obj = replace_refs(python_obj)\n\nprint(\"\\n--- From jsonref.replace_refs ---\")\nprint(f\"Original Python object: {json.dumps(python_obj)}\")\nprint(f\"Dereferenced object: {json.dumps(dereferenced_obj)}\")\nprint(f\"Accessing dereferenced value: {dereferenced_obj['first_item_ref']}\")\n\n# Example 3: Handling external references (requires 'requests' or will use urllib)\n# For external references, a loader can be specified. jsonloader is the default.\n# This example is conceptual as 'example.com/schema.json' is not guaranteed to exist.\n# If you have a local 'schema.json' with {\"version\": \"1.0\"}, use 'file:///path/to/schema.json'\nexternal_ref_schema = {\n    \"my_schema\": {\"$ref\": \"http://example.com/schema.json#/version\"}\n}\n# Assuming http://example.com/schema.json contains {\"version\": \"1.0\"}\n# This would attempt to fetch the external URI:\ntry:\n    # Use a mock loader for demonstration, as live external URIs might be flaky\n    def mock_loader(uri):\n        if uri == \"http://example.com/schema.json\":\n            return {\"version\": \"1.0\", \"description\": \"A simple schema\"}\n        raise JsonRefError(f\"Unknown URI: {uri}\", reference={'$ref': uri})\n\n    external_data = replace_refs(external_ref_schema, loader=mock_loader)\n    print(\"\\n--- External Reference Example (Conceptual) ---\")\n    print(f\"External data reference: {external_data['my_schema']}\")\nexcept JsonRefError as e:\n    print(f\"\\nCould not resolve external reference (expected if example.com is not valid): {e.message}\")","lang":"python","description":"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."},"warnings":[{"fix":"Rewrite code that subclassed `JsonLoader` to adapt to `jsonloader` being a standalone function. Review the `loader` parameter in `replace_refs` and `loads`.","message":"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.","severity":"breaking","affected_versions":">=0.4"},{"fix":"Change calls from `JsonRef.replace_refs(obj)` to `jsonref.replace_refs(obj)`.","message":"The class method `JsonRef.replace_refs()` is deprecated. You should use the top-level function `jsonref.replace_refs()` instead.","severity":"deprecated","affected_versions":">=0.4"},{"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.","message":"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__`.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'1.1.0':53 '2023':60 '3.7':12 'activ':62 'allow':24 'alreadi':38 'automat':14 'contain':31 'current':50 'data':29,43 'dereferenc':4,15,48,66 'document':22 'indic':61 'januari':59 'json':2,17,21,32,64 'jsonref':1,5 'last':56 'lazi':45,68 'librari':9 'load':69 'mainten':63 'object':19 'python':8,11 'recurs':47 'refer':3,18,33,42,65 'releas':57 'replac':39 'schema':67 'structur':30 'support':10,44 'version':51 'within':20 'work':27","created_at":"2026-03-28T17:08:47.094936+00:00","updated_at":"2026-04-16T15:57:12.399262+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"1.1.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/gazpachoking/jsonref","docs":"https://jsonref.readthedocs.io/en/latest/","changelog":null,"pypi":"https://pypi.org/project/jsonref/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-07-03","last_verified":"2026-07-03","next_check":"2026-08-02","install_tag":"verified"}}