Registry / serialization / jsonschema-path

jsonschema-path

library0.4.5pypypi✓ verified 52d ago

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.

serialization

pip install jsonschema-path

github ↗package ↗

Install & Compatibility

Where this runs

tested against v0.5.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.925 runs

installs and imports cleanly · install 0.0s · import 0.592s · 22.9MB

glibc

py 3.10–3.925 runs

installs and imports cleanly · install 2.5s · import 0.516s · 24MB

22MB installed

● package 22MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SchemaPath

✓ from jsonschema_path import SchemaPath

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)

Debug

Known issues

breakingPython 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.

affects: <0.4.0

gotchaThe 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)`.

affects: 0.4.0+

breakingVersion 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.

affects: 0.4.0 - 0.4.4

gotchaThe 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.

affects: 0.4.1+

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'jsonschema.compat'

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'`

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

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.

jsonschema.exceptions.RefResolutionError: Unresolvable JSON pointer:

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.

ModuleNotFoundError: No module named 'jsonschema'

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.

Upgrade

Version history

0.5.0latest on PyPI

Audit

Dependencies

pythonrequiredExplicitly requires Python 3.10 or newer.

referencingrequiredUsed for JSON Schema reference resolution; version 0.37+ is supported.

Agent activity

17 hits · last 30 days

node

seranking-bot

ahrefsbot

Amazon

mj12bot

Resources

githubhttps://github.com/p1c2u/jsonschema-path ↗

packagehttps://pypi.org/project/jsonschema-path/ ↗