Registry / serialization / jsonschema-path

jsonschema-path

library0.5.0pypypi✓ verified 25d 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

IMPORT

SIG · JSONSCHEMA-PATH

jsonschema-path

serializationpythonv0.5.0

Install

2.9s avg

Import

432ms

Disk

22MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

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.95 runs

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

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.9s · import 0.422s · 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 · released May 19, 2026

Audit

Dependencies

pythonrequiredExplicitly requires Python 3.10 or newer.

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

Agent activity

11 hits · last 30 days

node

Anthropic

Resources

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

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