Skip to main content

Tools for generating Python models from JSONSchema definitions.

Project description

Build Status

Statham Schema

A tool for generating Python classes/models from JSONSchema documents.

This project aims to simplify the experience of integrating with external sources, by providing:

  1. External validation: Ensure that incoming data matches what you expect early.
  2. Internal validation: Ensure your application's use of external data sources is consistent with the schema. Declared models and static type checking (see mypy) can do this job for you.
  3. Visibility: Update the model layer against schema changes automatically, and let static tools identify any issues.

The tool will generate attrs dataclasses which can then be used and extended as a model layer for the external data source.


This package is currently tested for Python 3.6.


This project may be installed using pip:

pip install statham-schema

Generating python classes

From the directory of the cloned repository, run

statham --input /path/to/schema.json

This will write generated python classes to stdout. Optionally specify an --output path to write to file.

Command-line arguments

Required arguments:
  --input INPUT    Specify the path to the JSON Schema to be generated.

                   If the target schema is not at the root of a document, specify the
                   JSON Pointer in the same format as a JSONSchema `$ref`, e.g.
                   `--input path/to/document.json#/definitions/schema`

Optional arguments:
  --output OUTPUT  Output directory or file in which to write the output.

                   If the provided path is a directory, the command will derive the name
                   from the input argument. If not passed, the command will write to

  -h, --help       Display this help message and exit.

See this example output.

Using custom format keywords

JSONSchema allows use of custom string formats as specified here. Custom validation logic for string format may be added like so:

from statham.validators import format_checker

def _check_my_format(value: str) -> bool:

Supported JSONSchema features

  • [x] Basic types (primitves, array, object)
  • [x] Composite primitive types
  • [x] Type validation on generated classes
  • [x] Validation of required
  • [x] Local references
  • [x] Type-specific validation (pattern, format, minimum, maximum etc)
  • [x] Custom string format validation
  • [x] Remote references
  • [ ] Tuple validation of arrays
  • [ ] Built-in string format validation #6
  • [ ] Generic keywords: enum #8, const #9
  • [ ] Array keywords: uniqueItems #10, contains
  • [ ] Composition keywords (allOf #12, anyOf #13, oneOf #11, not #14)
  • [ ] minProperties, maxProperties #15
  • [ ] Property dependencies
  • [ ] Schema dependencies
  • [ ] propertyNames, patternProperties, additionalProperties (This is tricky with attrs)
  • [ ] additionalItems keyword
  • [ ] if, then, else keywords


  1. Clone the repository: git clone && cd statham-schema
  2. Install the requirements: pip install -r requirements.txt -r requirements-test.txt
  3. Run pre-commit install
  4. Run the tests: bash -c -a

This project uses the following QA tools:

  • PyTest - for running unit tests.
  • PyLint - for enforcing code style.
  • MyPy - for static type checking.
  • Travis CI - for continuous integration.


This project is distributed under the MIT license.


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for statham-schema, version 0.1.1
Filename, size File type Python version Upload date Hashes
Filename, size statham_schema-0.1.1-py3-none-any.whl (19.4 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size statham-schema-0.1.1.tar.gz (16.5 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page