jschon: A JSON Toolkit for Python Developers

0.11.1 · active · verified Fri Apr 17

jschon is a comprehensive Python library for working with JSON data, JSON Schema validation (supporting Draft 2020-12), JSON Pointer, JSON Patch, and JSONPath. It provides robust tools for schema definition, data validation, and JSON document manipulation. The current version is 0.11.1, and the library maintains a relatively active release cadence with frequent minor and patch updates.

Common errors

```
TypeError: object of type 'str' has no len()
```
cause Attempting to pass a plain Python string where a `jschon.URI` object is expected, typically in methods dealing with schema URIs or JSONPointers.

fix Wrap the string with `jschon.URI()` before passing it. E.g., `schema = JSONSchema(schema_data, uri=URI('https://example.com/schema'))`.
```
AttributeError: 'JSON' object has no attribute 'schema'
```
cause Attempting to access the `schema` attribute on a `jschon.JSON` instance, which was deprecated in `v0.9.0`.

fix Retrieve schemas directly from the `Catalog` using `Catalog.get_schema()` which now returns a `JSONSchema` object directly.
```
TypeError: get_schema() missing 2 required positional arguments: 'recursive', and 'session'
```
cause Calling `Catalog.get_schema()` without the newly required `recursive` and `session` arguments introduced in `v0.10.0`.

fix Update your call to `Catalog.get_schema()` to include these arguments, e.g., `catalog.get_schema(URI('https://example.com/schema'), recursive=False, session=None)`.

Warnings

breaking The `Catalog.get_schema()` method signature changed. It now requires `recursive` and `session` arguments, which were previously implicit or handled differently.
Fix: Update calls to `Catalog.get_schema()` to explicitly pass `recursive=False` (or `True`) and `session=None` (or a valid `SchemaSession` object).
breaking The `JSONPointer` constructor now strictly requires a `jschon.URI` object as its base argument, rather than a `jschon.JSON` instance or a string. If a `JSON` instance is provided, its `JSON.uri` attribute is extracted internally.
Fix: Ensure `JSONPointer` is initialized with a `jschon.URI` object. Convert strings to `URI(your_string)` first if necessary.
breaking The `Catalog.get_schema()` method now returns a `JSONSchema` instance instead of a raw `JSON` instance. The `JSON.schema` attribute was deprecated and now returns `None`.
Fix: Directly use the `JSONSchema` object returned by `Catalog.get_schema()`. Do not rely on `JSON.schema` for schema access.
gotcha jschon extensively uses `jschon.URI` objects instead of plain Python strings for all URI-related parameters (e.g., `$id`, `$ref`, base URIs). Passing strings where `URI` objects are expected will lead to `TypeError`.
Fix: Always wrap URI strings with `jschon.URI()` before passing them to methods or constructors that expect a URI object.

Install

pip install jschon Install base library
pip install jschon[uri] Install with URI reference support
pip install jschon[graphql] Install with GraphQL support

Imports

JSON
```
from jschon import JSON
```
JSONSchema
```
from jschon import JSONSchema
```
URI
```
from jschon import URI
```
JSONPointer
```
from jschon import JSONPointer
```
Catalog
```
from jschon import Catalog
```

Quickstart

This quickstart demonstrates how to define a JSON Schema, create a JSON data instance, and validate the instance against the schema using `jschon`'s `JSONSchema` and `JSON` classes.

from jschon import JSON, JSONSchema

# Define a JSON Schema
schema_data = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer", "minimum": 0}
    },
    "required": ["name", "age"]
}
schema = JSONSchema(schema_data)

# Define a JSON instance
instance_data = {"name": "Alice", "age": 30}
instance = JSON(instance_data)

# Validate the instance against the schema
result = schema.evaluate(instance)

if result.valid:
    print("JSON instance is valid!")
else:
    print("JSON instance is invalid:")
    print(result.output('basic'))

# Example of invalid data
invalid_instance_data = {"name": "Bob", "age": -5}
invalid_instance = JSON(invalid_instance_data)
invalid_result = schema.evaluate(invalid_instance)

if not invalid_result.valid:
    print("\nInvalid instance output:")
    print(invalid_result.output('basic'))

view raw JSON →