Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Build Status Documentation Status


statham is a Python Model Parsing Library for JSON Schema. Read the documentation.

This project includes tools for writing and generating extensible Python classes based on JSON Schema documents.

Example Model Definition

statham can be used to write JSON Schema documents and their corresponding application-level models in one go:

from typing import List

from statham.schema.elements import Array, Integer, Object, String
from import Property

class Choice(Object):
    choice_text: str = Property(String(maxLength=200), required=True)
    votes: int = Property(Integer(default=0))

class Poll(Object):
    question: str = Property(String(), required=True)
    choices: List[Choice] = Property(Array(Choice), required=True)

Generating python classes

Alternatively, Python models may be generated automatically from an existing schema:

statham --input

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 JSON Schema `$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.


This project requires Python 3.6+ and may be installed using pip:

pip install statham-schema


See Compatibility for information regarding the currently supported JSON Schema draft and exceptions.


  1. Clone the repository: git clone && cd statham-schema
  2. Initialise git submodules: git submodule update --init --recursive
  3. Install the requirements: pip install -r requirements.txt -r requirements-test.txt
  4. Run pre-commit install
  5. 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.
  • Black - for uniform code formatting.

Documentation is written using Sphinx.


This project is distributed under the MIT license.