dataclasses-jsonschema

Please Note: This project is in maintenance mode. I’m currently only making urgent bugfixes.

A library to generate JSON Schema from python 3.7 dataclasses. Python 3.6 is supported through the dataclasses backport. Aims to be a more lightweight alternative to similar projects such as marshmallow & pydantic.

Feature Overview

Support for draft-04, draft-06, Swagger 2.0 & OpenAPI 3 schema types
Serialisation and deserialisation
Data validation against the generated schema
APISpec support. Example below:

Installation

~$ pip install dataclasses-jsonschema

For improved validation performance using fastjsonschema, install with:

~$ pip install dataclasses-jsonschema[fast-validation]

For improved uuid performance using fastuuid, install with:

~$ pip install dataclasses-jsonschema[fast-uuid]

For improved date and datetime parsing performance using ciso8601, install with:

~$ pip install dataclasses-jsonschema[fast-dateparsing]

Beware ciso8601 doesn’t support the entirety of the ISO 8601 spec, only a popular subset.

Examples

from dataclasses import dataclass

from dataclasses_jsonschema import JsonSchemaMixin


@dataclass
class Point(JsonSchemaMixin):
    "A 2D point"
    x: float
    y: float

Schema Generation

>>> pprint(Point.json_schema())
{
    'description': 'A 2D point',
    'type': 'object',
    'properties': {
        'x': {'format': 'float', 'type': 'number'},
        'y': {'format': 'float', 'type': 'number'}
    },
    'required': ['x', 'y']
}

Data Serialisation

>>> Point(x=3.5, y=10.1).to_dict()
{'x': 3.5, 'y': 10.1}

Deserialisation

>>> Point.from_dict({'x': 3.14, 'y': 1.5})
Point(x=3.14, y=1.5)
>>> Point.from_dict({'x': 3.14, y: 'wrong'})
dataclasses_jsonschema.ValidationError: 'wrong' is not of type 'number'

Generating multiple schemas

from dataclasses_jsonschema import JsonSchemaMixin, SchemaType

@dataclass
class Address(JsonSchemaMixin):
    """Postal Address"""
    building: str
    street: str
    city: str

@dataclass
class Company(JsonSchemaMixin):
    """Company Details"""
    name: str
    address: Address

>>> pprint(JsonSchemaMixin.all_json_schemas(schema_type=SchemaType.SWAGGER_V3))
{'Address': {'description': 'Postal Address',
             'properties': {'building': {'type': 'string'},
                            'city': {'type': 'string'},
                            'street': {'type': 'string'}},
             'required': ['building', 'street', 'city'],
             'type': 'object'},
 'Company': {'description': 'Company Details',
             'properties': {'address': {'$ref': '#/components/schemas/Address'},
                            'name': {'type': 'string'}},
             'required': ['name', 'address'],
             'type': 'object'}}

Custom validation using NewType

from dataclasses_jsonschema import JsonSchemaMixin, FieldEncoder

PhoneNumber = NewType('PhoneNumber', str)

class PhoneNumberField(FieldEncoder):

    @property
    def json_schema(self):
        return {'type': 'string', 'pattern': r'^(\([0-9]{3}\))?[0-9]{3}-[0-9]{4}$'}

JsonSchemaMixin.register_field_encoders({PhoneNumber: PhoneNumberField()})

@dataclass
class Person(JsonSchemaMixin):
    name: str
    phone_number: PhoneNumber

For more examples see the tests

APISpec Plugin

New in v2.5.0

OpenAPI & Swagger specs can be generated using the apispec plugin:

from typing import Optional, List
from dataclasses import dataclass

from apispec import APISpec
from apispec_webframeworks.flask import FlaskPlugin
from flask import Flask, jsonify
import pytest

from dataclasses_jsonschema.apispec import DataclassesPlugin
from dataclasses_jsonschema import JsonSchemaMixin


# Create an APISpec
spec = APISpec(
    title="Swagger Petstore",
    version="1.0.0",
    openapi_version="3.0.2",
    plugins=[FlaskPlugin(), DataclassesPlugin()],
)


@dataclass
class Category(JsonSchemaMixin):
    """Pet category"""
    name: str
    id: Optional[int]

@dataclass
class Pet(JsonSchemaMixin):
    """A pet"""
    categories: List[Category]
    name: str


app = Flask(__name__)


@app.route("/random")
def random_pet():
    """A cute furry animal endpoint.
    ---
    get:
      description: Get a random pet
      responses:
        200:
          content:
            application/json:
              schema: Pet
    """
    pet = get_random_pet()
    return jsonify(pet.to_dict())

# Dependant schemas (e.g. 'Category') are added automatically
spec.components.schema("Pet", schema=Pet)
with app.test_request_context():
    spec.path(view=random_pet)

TODO

Add benchmarks against alternatives such as pydantic and marshmallow

Download files

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

Source Distribution

dataclasses-jsonschema-2.16.0.tar.gz (29.6 kB view details)

Uploaded Oct 27, 2022 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

dataclasses_jsonschema-2.16.0-py3-none-any.whl (18.9 kB view details)

Uploaded Oct 27, 2022 Python 3

File details

Details for the file dataclasses-jsonschema-2.16.0.tar.gz.

File metadata

Download URL: dataclasses-jsonschema-2.16.0.tar.gz
Upload date: Oct 27, 2022
Size: 29.6 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/3.3.0 pkginfo/1.6.1 requests/2.22.0 setuptools/65.3.0 requests-toolbelt/0.9.1 tqdm/4.57.0 CPython/3.8.10

File hashes

Hashes for dataclasses-jsonschema-2.16.0.tar.gz
Algorithm	Hash digest
SHA256	`effb0c73db30a537a962da75c4f35b94a5b1b7c1b17806b1ef74aed8e0aa2768`
MD5	`2b532cd611c030ba722cba182a644b3a`
BLAKE2b-256	`423285aa01902972b8f6bf933b69f3887e5840ec3afa6cbbeafb7bfca9276b51`

See more details on using hashes here.

File details

Details for the file dataclasses_jsonschema-2.16.0-py3-none-any.whl.

File metadata

Download URL: dataclasses_jsonschema-2.16.0-py3-none-any.whl
Upload date: Oct 27, 2022
Size: 18.9 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/3.3.0 pkginfo/1.6.1 requests/2.22.0 setuptools/65.3.0 requests-toolbelt/0.9.1 tqdm/4.57.0 CPython/3.8.10

File hashes

Hashes for dataclasses_jsonschema-2.16.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`d203d6a16c990f7d09eae58c97ffaaea1e45ecb7a033d312e61e4c7836a741bf`
MD5	`d3093fcf42290b4d1e569112f31f5368`
BLAKE2b-256	`a2fcf8e6a8d753810e9b3b1799f9ac2e4bb33b0659e315236fba8da15317af81`