{"id":5979,"library":"json-ref-dict","title":"JSON Ref Dict","description":"json-ref-dict is a Python dict-like object that abstracts the resolution of JSONSchema references. It allows lazy loading of referenced documents, supporting both local filesystem and remote HTTP/HTTPS references. The library is currently at version 0.7.2 and maintains an active release cadence with frequent updates.","status":"active","version":"0.7.2","language":"python","source_language":"en","source_url":"https://github.com/jacksmith15/json-ref-dict","tags":["json","schema","reference","lazy-loading","dict","jsonschema"],"install":[{"cmd":"pip install json-ref-dict","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Optional dependency to enable loading of YAML documents; without it, only JSON documents are supported.","package":"PyYAML","optional":true}],"imports":[{"symbol":"RefDict","correct":"from json_ref_dict import RefDict"},{"note":"The `JsonRefDict` alias for `RefDict` was removed in version 0.6.0. Use `RefDict` directly.","wrong":"from json_ref_dict import JsonRefDict","symbol":"JsonRefDict","correct":"from json_ref_dict import RefDict"}],"quickstart":{"code":"import os\nfrom json_ref_dict import RefDict\n\n# Create dummy YAML files for the example\nmaster_yaml_content = \"\"\"\ndefinitions:\n  foo:\n    type: string\n  local_ref:\n    $ref: '#/definitions/foo'\n  remote_ref:\n    $ref: 'other.yaml#/definitions/bar'\n  backref:\n    $ref: 'other.yaml#/definitions/baz'\n\"\"\"\n\nother_yaml_content = \"\"\"\ndefinitions:\n  bar:\n    type: integer\n  baz:\n    $ref: 'master.yaml#/definitions/foo'\n\"\"\"\n\nwith open(\"master.yaml\", \"w\") as f:\n    f.write(master_yaml_content)\nwith open(\"other.yaml\", \"w\") as f:\n    f.write(other_yaml_content)\n\ntry:\n    # Initialize RefDict with a reference to a local YAML file and JSON pointer\n    schema = RefDict(\"master.yaml#/definitions\")\n\n    # Accessing elements triggers lazy resolution\n    print(\"Type of local_ref:\", schema[\"local_ref\"][\"type\"])\n    print(\"Type of remote_ref:\", schema[\"remote_ref\"][\"type\"])\n    print(\"Type of backref:\", schema[\"backref\"][\"type\"])\n\n    # Materialize the document to a regular dict (optional)\n    # from json_ref_dict import materialize\n    # materialized_schema = materialize(schema)\n    # print(\"Materialized schema type:\", type(materialized_schema))\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Clean up dummy files\n    os.remove(\"master.yaml\")\n    os.remove(\"other.yaml\")","lang":"python","description":"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."},"warnings":[{"fix":"Update any direct access to `obj.__json_ref__` to `obj.__reference__`.","message":"The internal attribute for accessing the original JSON reference object was renamed from `__json_ref__` to `__reference__` to align with the `jsonref` library conventions.","severity":"breaking","affected_versions":">=0.7.0"},{"fix":"If you relied on `RefDict` being a mutable `dict`, reassess your logic. For type checks, use `isinstance(obj, collections.abc.Mapping)` instead of `isinstance(obj, dict)`.","message":"`RefDict` no longer inherits directly from `dict`, but now from `collections.abc.Mapping`. This changes its behavior regarding mutability and can affect `isinstance` checks. `RefDict` instances are now immutable collections.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Always use `RefDict` directly for imports and class instantiation.","message":"The `JsonRefDict` alias for `RefDict` has been removed.","severity":"deprecated","affected_versions":">=0.6.0"}],"env_vars":null,"search_vec":"'0.7.2':43 'abstract':16 'activ':47 'allow':23 'cadenc':49 'current':40 'dict':3,7,12,59 'dict-lik':11 'document':28 'filesystem':32 'frequent':51 'http/https':35 'json':1,5,53 'json-ref-dict':4 'jsonschema':20,60 'lazi':24,57 'lazy-load':56 'librari':38 'like':13 'load':25,58 'local':31 'maintain':45 'object':14 'python':10 'ref':2,6 'refer':21,36,55 'referenc':27 'releas':48 'remot':34 'resolut':18 'schema':54 'support':29 'updat':52 'version':42","created_at":"2026-04-14T18:36:43.433022+00:00","updated_at":"2026-04-16T15:55:01.725195+00:00","problems":[{"fix":"Always use `RefDict` directly for imports and class instantiation: `from json_ref_dict import RefDict`.","cause":"The alias `JsonRefDict` for the main `RefDict` class was removed in `json-ref-dict` version 0.6.0.","error":"from json_ref_dict import JsonRefDict"},{"fix":"For 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`.","cause":"`RefDict` no longer inherits directly from `dict` but from `collections.abc.Mapping` since version 0.6.0, making it an immutable collection.","error":"isinstance(my_ref_dict, dict)` returning `False` or calling mutable dict methods like `pop()`"},{"fix":"Update any direct access to `obj.__json_ref__` to `obj.__reference__`.","cause":"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.","error":"AttributeError: 'RefDict' object has no attribute '__json_ref__'"},{"fix":"Ensure all `$ref` pointers are valid, accessible, and point to properly formatted JSON or YAML documents relative to the base URI of the `RefDict`.","cause":"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.","error":"jsonschema.exceptions.RefResolutionError: Unresolvable JSON pointer"},{"fix":"Before 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()`.","cause":"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.","error":"TypeError: Object of type RefDict is not JSON serializable"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.7.2","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/jacksmith15/json-ref-dict","docs":null,"changelog":null,"pypi":"https://pypi.org/project/json-ref-dict/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}