JSONSchema Path

About

Object-oriented JSONSchema

Key features

• Traverse schema like paths
• Access schema on demand with separate dereferencing accessor layer

Installation

pip install jsonschema-path

Alternatively you can download the code and install from the repository:

pip install -e git+https://github.com/p1c2u/jsonschema-path.git#egg=jsonschema_path

Usage

>>> from jsonschema_path import SchemaPath

>>> d = {
...     "properties": {
...        "info": {
...            "$ref": "#/$defs/Info",
...        },
...     },
...     "$defs": {
...         "Info": {
...             "properties": {
...                 "title": {
...                     "$ref": "http://example.com",
...                 },
...                 "version": {
...                     "type": "string",
...                     "default": "1.0",
...                 },
...             },
...         },
...     },
... }

>>> path = SchemaPath.from_dict(d)

>>> # Stat keys
>>> "properties" in path
True

>>> # Concatenate paths with /
>>> info_path = path / "properties" / "info"

>>> # Stat keys with implicit dereferencing
>>> "properties" in info_path
True

>>> # Concatenate paths with implicit dereferencing
>>> version_path = info_path / "properties" / "version"

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

Resolved cache

The resolved-path cache is intended for repeated path lookups and may significantly improve read_value/membership hot paths. Cache entries are invalidated when the resolver registry evolves during reference resolution.

This cache is optional and disabled by default (resolved_cache_maxsize=0). You can enable it when creating paths or accessors, for example:

>>> path = SchemaPath.from_dict(d, resolved_cache_maxsize=64)

Benchmarks

Benchmarks mirror the lightweight (dependency-free) JSON output format used in pathable.

Run locally with Poetry:

poetry run python -m tests.benchmarks.bench_parse --output reports/bench-parse.json
poetry run python -m tests.benchmarks.bench_lookup --output reports/bench-lookup.json

For a quick smoke run:

poetry run python -m tests.benchmarks.bench_parse --output reports/bench-parse.quick.json --quick
poetry run python -m tests.benchmarks.bench_lookup --output reports/bench-lookup.quick.json --quick

You can also control repeats/warmup and resolved cache maxsize via env vars:

export JSONSCHEMA_PATH_BENCH_REPEATS=5
export JSONSCHEMA_PATH_BENCH_WARMUP=1
export JSONSCHEMA_PATH_BENCH_RESOLVED_CACHE_MAXSIZE=64

Compare two results:

poetry run python -m tests.benchmarks.compare_results \
   --baseline reports/bench-lookup-master.json \
   --candidate reports/bench-lookup.json \
   --tolerance 0.20

Related projects

• openapi-core

  Python library that adds client-side and server-side support for the OpenAPI.

• openapi-spec-validator

  Python library that validates OpenAPI Specs against the OpenAPI 2.0 (aka Swagger) and OpenAPI 3.0 specification

• openapi-schema-validator

  Python library that validates schema against the OpenAPI Schema Specification v3.0.

License

Copyright (c) 2017-2025, Artur Maciag, All rights reserved. Apache-2.0