Dataclasses JSON Schema
=======================
.. image:: https://github.com/s-knibbs/dataclasses-jsonschema/workflows/Tox%20tests/badge.svg?branch=master
:target: https://github.com/s-knibbs/dataclasses-jsonschema/actions
.. image:: https://badge.fury.io/py/dataclasses-jsonschema.svg
:target: https://badge.fury.io/py/dataclasses-jsonschema
.. image:: https://img.shields.io/lgtm/grade/python/g/s-knibbs/dataclasses-jsonschema.svg?logo=lgtm&logoWidth=18
:target: https://lgtm.com/projects/g/s-knibbs/dataclasses-jsonschema/context:python
:alt: Language grade: Python
**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 <https://github.com/ericvsmith/dataclasses>`_. Aims to be a more lightweight alternative to similar projects such as `marshmallow <https://github.com/marshmallow-code/marshmallow>`_ & `pydantic <https://github.com/samuelcolvin/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 <https://github.com/marshmallow-code/apispec>`_ support. Example below_:
Installation
------------
.. code:: bash
~$ pip install dataclasses-jsonschema
For improved validation performance using `fastjsonschema <https://github.com/horejsek/python-fastjsonschema>`_, install with:
.. code:: bash
~$ pip install dataclasses-jsonschema[fast-validation]
For improved uuid performance using `fastuuid <https://pypi.org/project/fastuuid/>`_, install with:
.. code:: bash
~$ pip install dataclasses-jsonschema[fast-uuid]
For improved date and datetime parsing performance using `ciso8601 <https://pypi.org/project/ciso8601/>`_, install with:
.. code:: bash
~$ pip install dataclasses-jsonschema[fast-dateparsing]
Beware `ciso8601` doesn’t support the entirety of the ISO 8601 spec, only a popular subset.
Examples
--------
.. code:: python
from dataclasses import dataclass
from dataclasses_jsonschema import JsonSchemaMixin
@dataclass
class Point(JsonSchemaMixin):
"A 2D point"
x: float
y: float
Schema Generation
^^^^^^^^^^^^^^^^^
.. code:: python
>>> 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
^^^^^^^^^^^^^^^^^^
.. code:: python
>>> Point(x=3.5, y=10.1).to_dict()
{'x': 3.5, 'y': 10.1}
Deserialisation
^^^^^^^^^^^^^^^
.. code:: python
>>> 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
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code:: python
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 <https://docs.python.org/3/library/typing.html#newtype>`_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code:: python
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 <https://github.com/s-knibbs/dataclasses-jsonschema/blob/master/tests/conftest.py>`_
.. _below:
APISpec Plugin
--------------
**New in v2.5.0**
OpenAPI & Swagger specs can be generated using the apispec plugin:
.. code:: python
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 <https://github.com/samuelcolvin/pydantic>`_ and `marshmallow <https://github.com/marshmallow-code/marshmallow>`_
Raw data
{
"_id": null,
"home_page": "https://github.com/s-knibbs/dataclasses-jsonschema",
"name": "dataclasses-jsonschema",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Simon Knibbs",
"author_email": "simon.knibbs@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/42/32/85aa01902972b8f6bf933b69f3887e5840ec3afa6cbbeafb7bfca9276b51/dataclasses-jsonschema-2.16.0.tar.gz",
"platform": null,
"description": "Dataclasses JSON Schema\n=======================\n\n.. image:: https://github.com/s-knibbs/dataclasses-jsonschema/workflows/Tox%20tests/badge.svg?branch=master\n :target: https://github.com/s-knibbs/dataclasses-jsonschema/actions\n\n.. image:: https://badge.fury.io/py/dataclasses-jsonschema.svg\n :target: https://badge.fury.io/py/dataclasses-jsonschema\n\n.. image:: https://img.shields.io/lgtm/grade/python/g/s-knibbs/dataclasses-jsonschema.svg?logo=lgtm&logoWidth=18\n :target: https://lgtm.com/projects/g/s-knibbs/dataclasses-jsonschema/context:python\n :alt: Language grade: Python\n\n**Please Note:** This project is in maintenance mode. I'm currently only making urgent bugfixes.\n\nA library to generate JSON Schema from python 3.7 dataclasses. Python 3.6 is supported through the `dataclasses backport <https://github.com/ericvsmith/dataclasses>`_. Aims to be a more lightweight alternative to similar projects such as `marshmallow <https://github.com/marshmallow-code/marshmallow>`_ & `pydantic <https://github.com/samuelcolvin/pydantic>`_.\n\nFeature Overview\n----------------\n\n* Support for draft-04, draft-06, Swagger 2.0 & OpenAPI 3 schema types\n* Serialisation and deserialisation\n* Data validation against the generated schema\n* `APISpec <https://github.com/marshmallow-code/apispec>`_ support. Example below_:\n\nInstallation\n------------\n\n.. code:: bash\n\n ~$ pip install dataclasses-jsonschema\n\nFor improved validation performance using `fastjsonschema <https://github.com/horejsek/python-fastjsonschema>`_, install with:\n\n.. code:: bash\n\n ~$ pip install dataclasses-jsonschema[fast-validation]\n\nFor improved uuid performance using `fastuuid <https://pypi.org/project/fastuuid/>`_, install with:\n\n.. code:: bash\n\n ~$ pip install dataclasses-jsonschema[fast-uuid]\n\nFor improved date and datetime parsing performance using `ciso8601 <https://pypi.org/project/ciso8601/>`_, install with:\n\n.. code:: bash\n\n ~$ pip install dataclasses-jsonschema[fast-dateparsing]\n\nBeware `ciso8601` doesn\u2019t support the entirety of the ISO 8601 spec, only a popular subset.\n\n\nExamples\n--------\n\n.. code:: python\n\n from dataclasses import dataclass\n\n from dataclasses_jsonschema import JsonSchemaMixin\n\n\n @dataclass\n class Point(JsonSchemaMixin):\n \"A 2D point\"\n x: float\n y: float\n\n\nSchema Generation\n^^^^^^^^^^^^^^^^^\n\n.. code:: python\n\n >>> pprint(Point.json_schema())\n {\n 'description': 'A 2D point',\n 'type': 'object',\n 'properties': {\n 'x': {'format': 'float', 'type': 'number'},\n 'y': {'format': 'float', 'type': 'number'}\n },\n 'required': ['x', 'y']\n }\n\nData Serialisation\n^^^^^^^^^^^^^^^^^^\n.. code:: python\n\n >>> Point(x=3.5, y=10.1).to_dict()\n {'x': 3.5, 'y': 10.1}\n\nDeserialisation\n^^^^^^^^^^^^^^^\n\n.. code:: python\n\n >>> Point.from_dict({'x': 3.14, 'y': 1.5})\n Point(x=3.14, y=1.5)\n >>> Point.from_dict({'x': 3.14, y: 'wrong'})\n dataclasses_jsonschema.ValidationError: 'wrong' is not of type 'number'\n\nGenerating multiple schemas\n^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n.. code:: python\n\n from dataclasses_jsonschema import JsonSchemaMixin, SchemaType\n \n @dataclass\n class Address(JsonSchemaMixin):\n \"\"\"Postal Address\"\"\"\n building: str\n street: str\n city: str\n \n @dataclass\n class Company(JsonSchemaMixin):\n \"\"\"Company Details\"\"\"\n name: str\n address: Address\n \n >>> pprint(JsonSchemaMixin.all_json_schemas(schema_type=SchemaType.SWAGGER_V3))\n {'Address': {'description': 'Postal Address',\n 'properties': {'building': {'type': 'string'},\n 'city': {'type': 'string'},\n 'street': {'type': 'string'}},\n 'required': ['building', 'street', 'city'],\n 'type': 'object'},\n 'Company': {'description': 'Company Details',\n 'properties': {'address': {'$ref': '#/components/schemas/Address'},\n 'name': {'type': 'string'}},\n 'required': ['name', 'address'],\n 'type': 'object'}}\n \n\nCustom validation using `NewType <https://docs.python.org/3/library/typing.html#newtype>`_\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n.. code:: python\n\n from dataclasses_jsonschema import JsonSchemaMixin, FieldEncoder\n\n PhoneNumber = NewType('PhoneNumber', str)\n \n class PhoneNumberField(FieldEncoder):\n \n @property\n def json_schema(self):\n return {'type': 'string', 'pattern': r'^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$'}\n \n JsonSchemaMixin.register_field_encoders({PhoneNumber: PhoneNumberField()})\n \n @dataclass\n class Person(JsonSchemaMixin):\n name: str\n phone_number: PhoneNumber\n\nFor more examples `see the tests <https://github.com/s-knibbs/dataclasses-jsonschema/blob/master/tests/conftest.py>`_\n\n.. _below:\n\nAPISpec Plugin\n--------------\n**New in v2.5.0**\n\nOpenAPI & Swagger specs can be generated using the apispec plugin:\n\n.. code:: python\n\n from typing import Optional, List\n from dataclasses import dataclass\n\n from apispec import APISpec\n from apispec_webframeworks.flask import FlaskPlugin\n from flask import Flask, jsonify\n import pytest\n\n from dataclasses_jsonschema.apispec import DataclassesPlugin\n from dataclasses_jsonschema import JsonSchemaMixin\n\n\n # Create an APISpec\n spec = APISpec(\n title=\"Swagger Petstore\",\n version=\"1.0.0\",\n openapi_version=\"3.0.2\",\n plugins=[FlaskPlugin(), DataclassesPlugin()],\n )\n \n \n @dataclass\n class Category(JsonSchemaMixin):\n \"\"\"Pet category\"\"\"\n name: str\n id: Optional[int]\n\n @dataclass\n class Pet(JsonSchemaMixin):\n \"\"\"A pet\"\"\"\n categories: List[Category]\n name: str\n\n\n app = Flask(__name__)\n\n\n @app.route(\"/random\")\n def random_pet():\n \"\"\"A cute furry animal endpoint.\n ---\n get:\n description: Get a random pet\n responses:\n 200:\n content:\n application/json:\n schema: Pet\n \"\"\"\n pet = get_random_pet()\n return jsonify(pet.to_dict())\n \n # Dependant schemas (e.g. 'Category') are added automatically\n spec.components.schema(\"Pet\", schema=Pet)\n with app.test_request_context():\n spec.path(view=random_pet)\n\nTODO\n----\n\n* Add benchmarks against alternatives such as `pydantic <https://github.com/samuelcolvin/pydantic>`_ and `marshmallow <https://github.com/marshmallow-code/marshmallow>`_\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "JSON schema generation from dataclasses",
"version": "2.16.0",
"project_urls": {
"Homepage": "https://github.com/s-knibbs/dataclasses-jsonschema"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a2fcf8e6a8d753810e9b3b1799f9ac2e4bb33b0659e315236fba8da15317af81",
"md5": "d3093fcf42290b4d1e569112f31f5368",
"sha256": "d203d6a16c990f7d09eae58c97ffaaea1e45ecb7a033d312e61e4c7836a741bf"
},
"downloads": -1,
"filename": "dataclasses_jsonschema-2.16.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d3093fcf42290b4d1e569112f31f5368",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 18901,
"upload_time": "2022-10-27T09:48:11",
"upload_time_iso_8601": "2022-10-27T09:48:11.596560Z",
"url": "https://files.pythonhosted.org/packages/a2/fc/f8e6a8d753810e9b3b1799f9ac2e4bb33b0659e315236fba8da15317af81/dataclasses_jsonschema-2.16.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "423285aa01902972b8f6bf933b69f3887e5840ec3afa6cbbeafb7bfca9276b51",
"md5": "2b532cd611c030ba722cba182a644b3a",
"sha256": "effb0c73db30a537a962da75c4f35b94a5b1b7c1b17806b1ef74aed8e0aa2768"
},
"downloads": -1,
"filename": "dataclasses-jsonschema-2.16.0.tar.gz",
"has_sig": false,
"md5_digest": "2b532cd611c030ba722cba182a644b3a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 29639,
"upload_time": "2022-10-27T09:48:13",
"upload_time_iso_8601": "2022-10-27T09:48:13.098071Z",
"url": "https://files.pythonhosted.org/packages/42/32/85aa01902972b8f6bf933b69f3887e5840ec3afa6cbbeafb7bfca9276b51/dataclasses-jsonschema-2.16.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-10-27 09:48:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "s-knibbs",
"github_project": "dataclasses-jsonschema",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "dataclasses-jsonschema"
}
JSON
