Welcome to Statham’s documentation!

statham is a tool for generating Python models from JSON Schema 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.

  2. Internal validation: Ensure your application logic is consistent with the schema. Static type checking (see mypy) can do this job for you.

  3. Extensibility: Extend the generated models with properties and methods useful to you.

  4. Visibility: Update the model layer against schema changes automatically, and let static tools identify any issues.

The models generated by this tool are declared using a JSON Schema DSL. This DSL can easily be used to write schemas by hand.

Example DSL Definition

from typing import List

from statham.dsl.elements import Array, Integer, Object, String
from statham.dsl.property 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)

Development currently targets compatibility with JSONSchema Draft 6.

Requirements

This package is currently tested for Python 3.6.

Installation

This project may be installed using pip:

$ pip install statham-schema

Generating python classes

Class definitions may be generated with the following command:

$ 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
                   stdout.

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

Indices and tables