---
id: jsonschema-spec
version: "0.2.4"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# jsonschema-spec — JSONSchema Spec with object-oriented paths

License: permissive · Maintenance: active · Downloads: 924.8K/mo

## What it is and what it does

jsonschema-spec wraps JSONSchema documents in an object-oriented path interface, letting you navigate nested schema structures using forward-slash syntax while automatically resolving $ref pointers to local or remote definitions. Instead of manually parsing dictionaries and tracking reference paths, you construct a SchemaPath from a schema dict and then traverse it like a filesystem—checking key membership, concatenating paths, and opening dereferenced content on demand. The package handles both internal references (like #/$defs/Info) and external URLs, delegating actual HTTP fetches to requests and reference resolution to the referencing library.

This is most useful when you need to inspect or validate schema structure programmatically—for example, walking a schema to extract all property definitions, following $ref chains to understand the full shape of a nested object, or building tools that reason about schema metadata. It sits between raw dict manipulation and full schema validation, offering a cleaner API for schema introspection without enforcing validation rules.

Use it for:

- Extract all properties from a JSONSchema by traversing the schema tree and following $ref pointers automatically
- Build API documentation tools that need to walk OpenAPI or JSONSchema specs and resolve references
- Validate that a schema structure is well-formed by checking key existence and dereferencing paths
- Generate code or type definitions from a schema by navigating its structure and collecting metadata

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides an object-oriented interface to traverse and dereference JSONSchema documents, treating them as navigable paths with automatic resolution of $ref pointers.

Yes, if you need to programmatically inspect or traverse JSONSchema documents with automatic reference resolution. The low install friction, active maintenance, permissive license, and zero known vulnerabilities make it a safe choice. Not necessary if you only validate data against schemas or parse schemas as raw dicts.

## Install

pip install jsonschema-spec
uv add jsonschema-spec
poetry add jsonschema-spec

## Installing jsonschema-spec

Before you install: Low friction installation with four straightforward runtime dependencies (pathable, PyYAML, requests, referencing). Actively maintained with recent commits; last release was over a year ago but the repository remains active.

License in practice: Apache-2.0 permissive license allows commercial and private use with minimal restrictions; you must retain copyright and license notices in distributions.

Quickstart:

from jsonschema_spec import SchemaPath

schema = {
    "properties": {"info": {"$ref": "#/$defs/Info"}},
    "$defs": {"Info": {"properties": {"title": {"type": "string"}}}}
}

path = SchemaPath.from_dict(schema)
info_path = path / "properties" / "info"
with info_path.open() as contents:
    print(contents)

Verify before relying:

- Whether the package handles circular $ref chains or other edge cases in schema dereferencing
- Performance characteristics when working with very large or deeply nested schemas
- Whether remote schema fetching via requests is cached or requires manual optimization

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 924.8K/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

jsonschema path traversal, schema reference dereferencing, object-oriented json schema, navigate json schema documents, resolve schema references, schema-navigation, openapi-tooling

[View on SkillFed](https://skillfed.io/packages/jsonschema-spec) · [View on PyPI](https://pypi.org/project/jsonschema-spec/)