jschon 0.7.2

A pythonic, extensible JSON Schema implementation.

jschon

jschon is a pythonic and extensible implementation of the JSON Schema specification.

Features

• JSON Schema 2019-09 and 2020-12 vocabulary implementations
• Support for custom metaschemas, vocabularies and format validators
• JSON class implementing the JSON data model
• JSON pointer implementation (RFC 6901)

Installation

pip install jschon

Usage

A simple example illustrates several key aspects of jschon usage:

• Catalog setup
• Construction of a compiled, reusable JSONSchema object
• Validation of the schema by a metaschema
• Construction of a JSON instance
• Evaluation of the instance
• Output generation

import pprint

from jschon import create_catalog, JSON, JSONSchema

# initialize the catalog, with JSON Schema 2020-12 vocabulary support
create_catalog('2020-12', default=True)

# create a schema to validate a JSON greeting object
schema = JSONSchema({
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://example.com/greeting",
    "type": "object",
    "properties": {
        "greeting": {"$ref": "#/$defs/greetingDefinition"}
    },
    "$defs": {
        "greetingDefinition": {
            "type": "string",
            "pattern": "^Hello, .+!$"
        }
    }
})

# validate the schema against its metaschema
schema_validity = schema.validate()
print(f'Schema validity check: {schema_validity.valid}')

# declare a valid JSON instance
valid_json = JSON({
    "greeting": "Hello, World!"
})

# declare an invalid JSON instance
invalid_json = JSON({
    "greeting": "Hi, World."
})

# evaluate the valid instance
valid_result = schema.evaluate(valid_json)

# evaluate the invalid instance
invalid_result = schema.evaluate(invalid_json)

# print output for the valid case
print(f'Valid JSON result: {valid_result.valid}')
print('Valid JSON basic output:')
pprint.pp(valid_result.output('basic'))

# print output for the invalid case
print(f'Invalid JSON result: {invalid_result.valid}')
print('Invalid JSON detailed output:')
pprint.pp(invalid_result.output('detailed'))

The script produces the following output:

Schema validity check: True
Valid JSON result: True
Valid JSON basic output:
{'valid': True,
 'annotations': [{'instanceLocation': '',
                  'keywordLocation': '/properties',
                  'absoluteKeywordLocation': 'https://example.com/greeting#/properties',
                  'annotation': ['greeting']}]}
Invalid JSON result: False
Invalid JSON detailed output:
{'valid': False,
 'instanceLocation': '',
 'keywordLocation': '',
 'absoluteKeywordLocation': 'https://example.com/greeting#',
 'errors': [{'instanceLocation': '/greeting',
             'keywordLocation': '/properties/greeting/$ref/pattern',
             'absoluteKeywordLocation': 'https://example.com/greeting#/$defs/greetingDefinition/pattern',
             'error': 'The text must match the regular expression "^Hello, .+!$"'}]}

Documentation

Further examples of usage, and an API reference, are available at Read the Docs.

Additional resources

• jschon.dev - an online validator powered by jschon
• JSON Schema 2020-12 core and validation specifications
• Understanding JSON Schema

Running the tests

jschon is tested using the JSON Schema Test Suite (excluding optional and format tests), along with custom unit tests that make use of the Hypothesis testing library.

To run the tests, install jschon in editable mode, including testing dependencies:

pip install -e git+https://github.com/marksparkza/jschon.git#egg=jschon[test]

Then, cd to the jschon source directory (pip show jschon will give you the location), and type tox.

Note that a complete test run requires all of the supported Python versions (3.8, 3.9, 3.10) to be installed on your system.

Contributing

Please see the guidelines for contributing.