JSONSchema Path

.. image:: https://img.shields.io/pypi/v/jsonschema-path.svg :target: https://pypi.python.org/pypi/jsonschema-path .. image:: https://travis-ci.org/p1c2u/jsonschema-path.svg?branch=master :target: https://travis-ci.org/p1c2u/jsonschema-path .. image:: https://img.shields.io/codecov/c/github/p1c2u/jsonschema-path/master.svg?style=flat :target: https://codecov.io/github/p1c2u/jsonschema-path?branch=master .. image:: https://img.shields.io/pypi/pyversions/jsonschema-path.svg :target: https://pypi.python.org/pypi/jsonschema-path .. image:: https://img.shields.io/pypi/format/jsonschema-path.svg :target: https://pypi.python.org/pypi/jsonschema-path .. image:: https://img.shields.io/pypi/status/jsonschema-path.svg :target: https://pypi.python.org/pypi/jsonschema-path

About

Object-oriented JSONSchema

Key features ############

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

Installation ############

.. code-block:: console

pip install jsonschema-path

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

.. code-block:: console

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

Usage

.. code-block:: python

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

Identity and equality #####################

Two SchemaPath instances are equal if they have the same parts and point to the same SchemaAccessor. SchemaAccessor identity is per-resource-handle: same wrapped dict (by reference), same base_uri, and same internal resolver instance. In practice:

• Paths derived from the same accessor compare equal as expected:

  .. code-block:: python

  accessor = SchemaAccessor.from_schema(d) SchemaPath(accessor) / "properties" == SchemaPath(accessor) / "properties" True

• Paths from separate from_dict or from_schema calls do not compare equal even with identical arguments, because each call builds its own accessor:

  .. code-block:: python

  SchemaPath.from_dict(d) == SchemaPath.from_dict(d) False

• SchemaAccessor is hashable, so accessors and paths can be used as set members and dict keys.

This is also why the "build one accessor, reuse it" pattern below matters: it is both a caching optimisation and the contract you need for path equality to behave the way you expect.

Resolved cache ##############

The resolved-path cache is intended for repeated path lookups and may significantly improve read_value/membership hot paths. When the underlying referencing registry grows (e.g. an external $ref pulls in a new document), cached entries are rebound to the new registry on read instead of being discarded. This relies on registries growing monotonically — resources are added, never replaced. Handlers that return drifting content for the same URI violate that assumption; disable caching with resolved_cache_maxsize=0 if you need to defend against it.

This cache is enabled by default (resolved_cache_maxsize=128). You can disable it when creating paths or accessors, for example:

.. code-block:: python

path = SchemaPath.from_dict(d, resolved_cache_maxsize=0)

Build one :code:SchemaAccessor per schema document and reuse it for every :code:SchemaPath you derive from that document. Treat the accessor as the long-lived handle to the resource; treat paths as cheap views over it.

.. code-block:: python

from jsonschema_path import SchemaAccessor, SchemaPath

Construct the accessor once, with caching enabled.

accessor = SchemaAccessor.from_schema(d, resolved_cache_maxsize=128)

Derive as many paths as you like from the same accessor.

root = SchemaPath(accessor) info = root / "properties" / "info" version = info / "properties" / "version"

Every path over accessor shares the same resolved-ref cache.

with version.open() as contents: ... ...

Benchmarks ##########

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

Run locally with Poetry:

.. code-block:: console

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:

.. code-block:: console

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:

.. code-block:: console

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

Compare two results:

.. code-block:: console

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 <https://github.com/p1c2u/openapi-core>__ Python library that adds client-side and server-side support for the OpenAPI.
• openapi-spec-validator <https://github.com/p1c2u/openapi-spec-validator>__ Python library that validates OpenAPI Specs against the OpenAPI 2.0 (aka Swagger) and OpenAPI 3.0 specification
• openapi-schema-validator <https://github.com/p1c2u/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