JSONSchema Spec with object-oriented paths

0.4.5 · active · verified Sat Mar 28

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.

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

pip install jsonschema-path Install stable version

Imports

SchemaPath
```
from jsonschema_path import SchemaPath
```

Quickstart

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)

view raw JSON →