Registry / serialization / jsonschema-spec

jsonschema-spec

library0.2.4pypypi✓ verified 23d ago

jsonschema-spec is a Python library (current version 0.4.5) that provides object-oriented paths for traversing and accessing JSON Schemas. It allows developers to interact with schema elements and their references in a programmatic way, abstracting away raw dictionary manipulation. The library sees active development, with frequent patch releases and minor updates to enhance features and ensure compatibility with related tools.

serialization

pip install jsonschema-spec

github ↗package ↗

INSTALL

IMPORT

SIG · JSONSCHEMA-SPEC

jsonschema-spec

serializationpythonv0.2.4

Install

2.9s avg

Import

620ms

Disk

24MB

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.2.4 · 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.642s · 25.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.9s · import 0.598s · 27MB

24MB installed

● package 24MB

Code

Verified usage

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

SchemaPath

✓ from jsonschema_spec import SchemaPath

SchemaAccessor

✓ from jsonschema_spec import SchemaAccessor

This quickstart demonstrates how to create a `SchemaPath` from a dictionary representing a JSON Schema and then traverse it using path-like syntax. It shows accessing properties, definitions, and performing implicit dereferencing.

from jsonschema_spec import SchemaPath # Define a simple JSON Schema schema_dict = { "type": "object", "properties": { "name": {"type": "string"}, "age": {"type": "integer", "minimum": 0} }, "$defs": { "Person": { "type": "object", "properties": { "firstName": {"type": "string"}, "lastName": {"type": "string"} } } }, "$ref": "#/$defs/Person" } # Create a SchemaPath object from the dictionary path = SchemaPath.from_dict(schema_dict) # Traverse the schema using path-like access name_prop_path = path / "properties" / "name" print(f"Name property schema: {name_prop_path.get_value()}") # Expected: {'type': 'string'} # Access a definition using implicit dereferencing person_def_path = path / '$defs' / 'Person' print(f"Person definition schema: {person_def_path.get_value()}") # Expected: {'type': 'object', 'properties': {'firstName': {'type': 'string'}, 'lastName': {'type': 'string'}}} # Directly dereference the root '$ref' dereferenced_root = path.dereference() print(f"Dereferenced root schema type: {dereferenced_root.get_value()['type']}") # Expected: object # Check for keys print(f"'properties' in root path: {'properties' in path}") # Expected: True

Debug

Known issues

breakingThe `SchemaAccessor.resolver` interface underwent changes that affected backward compatibility. If you were directly interacting with or extending `SchemaAccessor.resolver` in versions prior to `0.4.5`, your code might break.

fix

Upgrade to `jsonschema-spec>=0.4.5`. Review the change log for `0.4.5` and `referencing` library updates, as this fix was introduced to restore compatibility. Adjust custom resolver implementations as per the latest `referencing` API.

affects: <0.4.5

gotchaThe resolved-path cache, which can significantly improve performance for repeated schema lookups, is disabled by default. For performance-critical applications with frequent schema path traversals, enabling this cache is highly recommended.

fix

Enable the cache by setting `resolved_cache_maxsize` when creating `SchemaPath` or `SchemaAccessor` instances. For example: `SchemaPath.from_dict(schema_dict, resolved_cache_maxsize=64)`.

affects: All versions

gotchaWhile `jsonschema-spec` provides robust schema traversal, the underlying JSON Schema specification itself has introduced breaking changes between its different drafts (e.g., Draft 2019-09 to Draft 2020-12). These changes can alter the interpretation and validation behavior of schemas, even if `jsonschema-spec` correctly parses the structure.

fix

Always specify the `$schema` keyword in your JSON Schemas to indicate the intended draft version (e.g., `"$schema": "https://json-schema.org/draft/2020-12/schema"`). Be aware of the specific changes between drafts (e.g., `$recursiveRef` to `$dynamicRef`, `items` array form) when working with schemas from different specifications.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'jsonschema_spec'

The 'jsonschema-spec' library is not installed in your Python environment, or there is a typo in the import statement.

fix

Ensure the library is correctly installed using pip: `pip install jsonschema-spec`

AttributeError: 'Spec' object has no attribute 'non_existent_property'

You are attempting to access a non-existent key in the loaded JSON Schema using attribute-style access (e.g., `schema.non_existent_property`). The 'Spec' object only provides attribute access for defined schema keywords.

fix

Verify the exact property name in your JSON Schema. If the property may not exist, use dictionary-style access with a `.get()` method or check for its presence first: `schema.get('non_existent_property')` or `if 'non_existent_property' in schema: ...`

KeyError: 'non_existent_key'

You are attempting to access a non-existent key in the loaded JSON Schema using dictionary-style access (e.g., `schema['non_existent_key']`).

fix

Verify the exact key name in your JSON Schema. To safely access potentially missing keys, use the `.get()` method: `schema.get('non_existent_key', default_value)`

referencing.exceptions.Unresolvable: Could not resolve reference

The JSON Schema contains a `$ref` that cannot be resolved, either because the target URI is incorrect, the referenced schema does not exist, or the reference path within the schema is invalid.

fix

Check the `$ref` URL or JSON Pointer path for correctness. Ensure all referenced schemas are accessible and correctly formatted. If referencing local files, verify the file paths and ensure they are loaded into the resolver if necessary.

ImportError: cannot import name 'SchemaAccessor' from 'jsonschema_spec'

The SchemaAccessor class is located within the 'accessors' submodule of 'jsonschema_spec', not directly under the top-level package.

fix

from jsonschema_spec.accessors import SchemaAccessor

Upgrade

Version history

0.2.4latest on PyPI · released Aug 16, 2023

Audit

Dependencies

referencingrequiredUsed for JSON Reference (RFC3986) and JSON Pointer (RFC6901) resolution within schemas, enabling dereferencing capabilities. Required version >=0.28.0,<1.0.0.

pathablerequiredProvides the underlying pathing and traversal primitives for object-oriented schema access. Required version >=0.5.0,<1.0.0.

Agent activity

9 hits · last 30 days

node

Resources

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

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