[](https://pypi.python.org/pypi/jsonschema-gen/)
[](https://jsonschema-gen.readthedocs.io)
[](https://codecov.io/gh/violet-black/jsonschema-gen)
[](https://github.com/psf/black)
[](https://github.com/violet-black/jsonschema-gen/actions/workflows/py38.yaml)
[](https://github.com/violet-black/jsonschema-gen/actions/workflows/py39.yaml)
[](https://github.com/violet-black/jsonschema-gen/actions/workflows/py310.yaml)
[](https://github.com/violet-black/jsonschema-gen/actions/workflows/py311.yaml)
[](https://github.com/violet-black/jsonschema-gen/actions/workflows/py312.yaml)
**jsonschema-gen** is Python type hints parser which can convert function and method annotations
into [JSONSchema](https://json-schema.org) objects.
- Pythonic [classes](https://jsonschema-gen.readthedocs.io/reference.html) for JSONSchema types
- Extensive type coverage: TypedDict, Generic, NewType, etc.
- No external dependencies
# Installation
With pip and python 3.8+:
```bash
pip3 install jsonschema-gen
```
# How to use
See the [user guide](https://jsonschema-gen.readthedocs.io/guide.html) for more info.
Create a parser:
```python
from jsonschema_gen import Parser
parser = Parser(strict=True)
```
Generate schema for your function or method from Python type hints
(see the list of [supported types](https://jsonschema-gen.readthedocs.io/type_map.html)):
```python
from typing import NewType
UserName = NewType('UserName', str)
class UserData:
def get_user(self, name: UserName, active: bool = True) -> dict:
"""Get user by username."""
annotation = parser.parse_function(UserData.get_user, UserData)
```
The result is an annotation object with input `.kwargs` and output `.returns`. You can get a JSONSchema compatible dict
using `json_repr()` on `.kwargs`:
```python
schema = annotation.kwargs.json_repr()
```
The result would look like this (if converted to JSON with `dumps`):
```json
{
"type": "object",
"title": "Get user by username.",
"properties": {
"name": {
"title": "Username",
"type": "string"
},
"active": {
"type": "boolean",
"default": true
}
},
"required": [
"name"
],
"additionalProperties": false
}
```
Use [fastjsonschema](https://github.com/horejsek/python-fastjsonschema) or other JSONSchema validation library to
create a validator for the schema:
```python
from fastjsonschema import compile
validator = compile(schema)
valiator({'name': 'John', 'email': 'john@dowe'})
```
Alternatively you can pass the whole class to the parser to get the annotation mapping:
```python
annotations = parser.parse_class(UserData)
annotations['get_user'].kwargs.json_repr()
```
# Compatibility
The Python type hints are vast and yet not well organized, so there could always be some data type I forgot to add
here. Read the customization guide to extend the standard list of type parsers.
Some annotations cannot be converted to JSONSchema objects, for example: positional-only arguments, variable
positionals, etc. There are [different strategies](https://jsonschema-gen.readthedocs.io/guide.html#variable-args)
considering these types of parameters.
Python 3.8 compatibility is so-so due to lots of features and changes made in 3.9. However, it still should support
most of the functionality.
Also read about the [strict mode](https://jsonschema-gen.readthedocs.io/guide.html#strict-mode).
Raw data
{
"_id": null,
"home_page": "https://github.com/violet-black/jsonschema-gen",
"name": "jsonschema-gen",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "jsonschema, validation, typing",
"author": "violetblackdev@gmail.com",
"author_email": null,
"download_url": null,
"platform": null,
"description": "[](https://pypi.python.org/pypi/jsonschema-gen/)\n[](https://jsonschema-gen.readthedocs.io)\n[](https://codecov.io/gh/violet-black/jsonschema-gen)\n[](https://github.com/psf/black)\n\n[](https://github.com/violet-black/jsonschema-gen/actions/workflows/py38.yaml)\n[](https://github.com/violet-black/jsonschema-gen/actions/workflows/py39.yaml)\n[](https://github.com/violet-black/jsonschema-gen/actions/workflows/py310.yaml)\n[](https://github.com/violet-black/jsonschema-gen/actions/workflows/py311.yaml)\n[](https://github.com/violet-black/jsonschema-gen/actions/workflows/py312.yaml)\n\n**jsonschema-gen** is Python type hints parser which can convert function and method annotations\ninto [JSONSchema](https://json-schema.org) objects.\n\n- Pythonic [classes](https://jsonschema-gen.readthedocs.io/reference.html) for JSONSchema types\n- Extensive type coverage: TypedDict, Generic, NewType, etc.\n- No external dependencies\n\n# Installation\n\nWith pip and python 3.8+:\n\n```bash\npip3 install jsonschema-gen\n```\n\n# How to use\n\nSee the [user guide](https://jsonschema-gen.readthedocs.io/guide.html) for more info.\n\nCreate a parser:\n\n```python\nfrom jsonschema_gen import Parser\n\nparser = Parser(strict=True)\n```\n\nGenerate schema for your function or method from Python type hints\n(see the list of [supported types](https://jsonschema-gen.readthedocs.io/type_map.html)):\n\n```python\nfrom typing import NewType\n\nUserName = NewType('UserName', str)\n\nclass UserData:\n def get_user(self, name: UserName, active: bool = True) -> dict:\n \"\"\"Get user by username.\"\"\"\n\nannotation = parser.parse_function(UserData.get_user, UserData)\n```\n\nThe result is an annotation object with input `.kwargs` and output `.returns`. You can get a JSONSchema compatible dict\nusing `json_repr()` on `.kwargs`:\n\n```python\nschema = annotation.kwargs.json_repr()\n```\n\nThe result would look like this (if converted to JSON with `dumps`):\n\n```json\n{\n \"type\": \"object\",\n \"title\": \"Get user by username.\",\n \"properties\": {\n \"name\": {\n \"title\": \"Username\",\n \"type\": \"string\"\n },\n \"active\": {\n \"type\": \"boolean\",\n \"default\": true\n }\n },\n \"required\": [\n \"name\"\n ],\n \"additionalProperties\": false\n}\n```\n\nUse [fastjsonschema](https://github.com/horejsek/python-fastjsonschema) or other JSONSchema validation library to\ncreate a validator for the schema:\n\n```python\nfrom fastjsonschema import compile\n\nvalidator = compile(schema)\nvaliator({'name': 'John', 'email': 'john@dowe'})\n```\n\nAlternatively you can pass the whole class to the parser to get the annotation mapping:\n\n```python\nannotations = parser.parse_class(UserData)\nannotations['get_user'].kwargs.json_repr()\n```\n\n# Compatibility\n\nThe Python type hints are vast and yet not well organized, so there could always be some data type I forgot to add\nhere. Read the customization guide to extend the standard list of type parsers.\n\nSome annotations cannot be converted to JSONSchema objects, for example: positional-only arguments, variable\npositionals, etc. There are [different strategies](https://jsonschema-gen.readthedocs.io/guide.html#variable-args)\nconsidering these types of parameters.\n\nPython 3.8 compatibility is so-so due to lots of features and changes made in 3.9. However, it still should support\nmost of the functionality.\n\nAlso read about the [strict mode](https://jsonschema-gen.readthedocs.io/guide.html#strict-mode).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "JSONSchema generation from Python type hints",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/violet-black/jsonschema-gen"
},
"split_keywords": [
"jsonschema",
" validation",
" typing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c66e7c0049f841179e0bf001a5a64536c23d4a51383f240569139d13875eb575",
"md5": "8abddfe2478bd064949708d6fbfa2bb6",
"sha256": "26835a130d781b5cf311ba1ef5d37532943a57bd21c7667e099410a988d34f50"
},
"downloads": -1,
"filename": "jsonschema_gen-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8abddfe2478bd064949708d6fbfa2bb6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11057,
"upload_time": "2024-04-07T18:10:24",
"upload_time_iso_8601": "2024-04-07T18:10:24.422617Z",
"url": "https://files.pythonhosted.org/packages/c6/6e/7c0049f841179e0bf001a5a64536c23d4a51383f240569139d13875eb575/jsonschema_gen-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-07 18:10:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "violet-black",
"github_project": "jsonschema-gen",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "jsonschema-gen"
}
JSON
