JSONSchema Spec with object-oriented paths

0.4.5 verified Tue May 12 auth: no python install: verified quickstart: verified

jsonschema-path is a Python library that provides an object-oriented way to traverse and access JSONSchema definitions. It enhances JSON Schema handling by offering path-like navigation and on-demand dereferencing with a separate accessor layer. It is currently at version 0.4.5 and actively maintained with a regular release cadence, focusing on bug fixes and feature enhancements.

pip install jsonschema-path

Common errors

error ModuleNotFoundError: No module named 'jsonschema.compat' ↓

cause This error occurs when the `jsonschema-path` library (or a library that depends on `jsonschema`) attempts to import `jsonschema.compat`, but the installed `jsonschema` version is 4.0 or higher, where the `compat` module was removed due to API changes.

fix

Downgrade the jsonschema package to a version less than 4.0. For example: pip install 'jsonschema<4.0'

error AttributeError: 'list' object has no attribute 'get' ↓

cause This typically happens when you try to access data using dictionary-like `.get()` method on a Python list object. In the context of JSON Schema, this means your schema path traversal or data access resulted in a JSON array (Python list), but you expected a JSON object (Python dictionary).

fix

Inspect the structure of your JSON schema or instance data at the point of the error. If it's an array, use list indexing (e.g., [0]) instead of .get() to access elements, or iterate over the list. Ensure your code correctly handles both array and object types where they might appear.

error jsonschema.exceptions.RefResolutionError: Unresolvable JSON pointer: ↓

cause This error indicates that `jsonschema-path` (or its underlying `jsonschema` dependency during dereferencing) failed to locate or resolve a `$ref` within your JSON Schema. This could be due to an incorrect path in the `$ref` itself, a missing schema file, or an improperly configured base URI for resolution.

fix

Verify that the $ref value correctly points to an existing and accessible location. For local file references, ensure the base URI (if manually configured or if the schema relies on external files) includes a trailing slash for directories, and that all referenced files exist relative to the base.

error ModuleNotFoundError: No module named 'jsonschema' ↓

cause The core `jsonschema` library, which `jsonschema-path` depends on, is not installed in your current Python environment or is not available in the Python path.

fix

Install the jsonschema package using pip: pip install jsonschema. If you are using a virtual environment, make sure it is activated before running the installation command.

Warnings

breaking Python 3.8 and 3.9 support has been dropped. The library now requires Python >=3.10. ↓

fix Upgrade your Python environment to 3.10 or newer, or pin jsonschema-path to a version before 0.4.0.

gotcha The resolved-path LRU cache is disabled by default (`resolved_cache_maxsize=0`). For applications with repeated path lookups, enabling this cache can significantly improve performance, especially for `read_value` and membership checks. ↓

fix Initialize `SchemaPath` or `SchemaAccessor` with `resolved_cache_maxsize` set to a positive integer, e.g., `SchemaPath.from_dict(schema_dict, resolved_cache_maxsize=64)`.

breaking Version 0.4.5 introduced a fix for `SchemaAccessor.resolver` backward compatibility (issue #246). If you have custom resolver configurations, earlier 0.4.x versions might have exhibited unexpected behavior related to how resolvers were handled during schema traversal and dereferencing. ↓

fix Upgrade to `jsonschema-path` 0.4.5 or later to ensure correct `SchemaAccessor.resolver` behavior and backward compatibility. Review custom resolver logic if issues persist.

gotcha The library relies on the `referencing` library for JSON Schema reference resolution. While `jsonschema-path` manages its dependency, ensure compatibility if you manually manage `referencing` or rely on specific resolution behaviors across different `jsonschema-path` versions. ↓

fix Refer to the `jsonschema-path` release notes for the supported `referencing` versions. As of 0.4.1, `referencing 0.37` is supported. Pin `referencing` to a compatible version if necessary.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.48s 22.8M

3.10 slim (glibc) - - 0.30s 24M

3.11 alpine (musl) - - 0.73s 25.1M

3.11 slim (glibc) - - 0.69s 26M

3.12 alpine (musl) - - 0.66s 17.0M

3.12 slim (glibc) - - 0.55s 18M

3.13 alpine (musl) - - 0.47s 16.3M

3.13 slim (glibc) - - 0.56s 17M

3.9 alpine (musl) - - 1.36s 25.4M

3.9 slim (glibc) - - 0.93s 26M

Imports

SchemaPath
```
from jsonschema_path import SchemaPath
```

Quickstart verified last tested: 2026-04-23

Demonstrates creating a SchemaPath from a dictionary, traversing properties, dereferencing `$ref`s, and accessing schema content. It also shows how to enable the optional resolved-path cache for performance improvements.

from jsonschema_path import SchemaPath

d = {
    "properties": {
        "info": {
            "$ref": "#/definitions/Info"
        }
    },
    "definitions": {
        "Info": {
            "properties": {
                "title": {
                    "type": "string"
                },
                "version": {
                    "type": "string",
                    "default": "1.0"
                }
            }
        }
    }
}

path = SchemaPath.from_dict(d)

# Traverse schema like paths
assert "properties" in path

# Concatenate paths with /
info_path = path / "properties" / "info"
assert "properties" in info_path # Implicit dereferencing

version_path = info_path / "properties" / "version"

# Open content with implicit dereferencing
with version_path.open() as contents:
    print(contents)
# Expected output: {'type': 'string', 'default': '1.0'}

# Enable resolved-path LRU cache for performance
path_with_cache = SchemaPath.from_dict(d, resolved_cache_maxsize=64)