JSON schema generation from dataclasses
Project description
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]
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:
$ref: 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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Close
Hashes for dataclasses-jsonschema-rereleased-2.12.2.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | a75791f3f1caf1acbc0699ab2988d0613f27a1661fb721fa6aaecc44e6c714c8 |
|
MD5 | 71bdd36e293ef6fc95d232abdf87b286 |
|
BLAKE2b-256 | 2e46f517db7364b8250996e95e26e04f889de0275844d0b6c56b0938dce24101 |
Close
Hashes for dataclasses_jsonschema_rereleased-2.12.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 73a8ca281dea719d1282187f6f718ebad31aa8923ec7bbe173d65b2d335b2585 |
|
MD5 | de23a4b75ebe278fd81a7d28317c5a39 |
|
BLAKE2b-256 | 9aa0517477ac4f0972484e05161f5ec4de4e8209ce606b249f25b246f334648f |