Dataclasses JSON Schema
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
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
Metadata
Release files for dataclasses-jsonschema 2.16.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| dataclasses-jsonschema-2.16.0.tar.gz | 29.6 kB | Without provenance | Details for dataclasses-jsonschema-2.16.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| dataclasses_jsonschema-2.16.0-py3-none-any.whl | Python 3 | none | any | Details for dataclasses_jsonschema-2.16.0-py3-none-any.whl |
Total release size: 48.5 kB
Release files / dataclasses-jsonschema-2.16.0.tar.gz
| Download URL | dataclasses-jsonschema-2.16.0.tar.gz |
|---|---|
| Size | 29.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
effb0c73db30a537a962da75c4f35b94a5b1b7c1b17806b1ef74aed8e0aa2768
|
|
BLAKE2b-256 checksum How to use checksums |
423285aa01902972b8f6bf933b69f3887e5840ec3afa6cbbeafb7bfca9276b51
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is 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
|
Release files / dataclasses_jsonschema-2.16.0-py3-none-any.whl
| Download URL | dataclasses_jsonschema-2.16.0-py3-none-any.whl |
|---|---|
| Size | 18.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d203d6a16c990f7d09eae58c97ffaaea1e45ecb7a033d312e61e4c7836a741bf
|
|
BLAKE2b-256 checksum How to use checksums |
a2fcf8e6a8d753810e9b3b1799f9ac2e4bb33b0659e315236fba8da15317af81
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is 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
|
Security for dataclasses-jsonschema 2.16.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.