Generate JSON schema from python dataclasses
Project description
dc_schema
Tiny library to generate JSON schema (2020-12) from python dataclasses. No other dependencies, standard library only.
pip install dc-schema
Fork changelog:
0.0.9:
- Add handling of typing.Any type
- Add ability to define
additionalProperties
for dataclasses. See ./tests/test_dc_schema.py for details (test_schema_additiona_properties_are_not_allowed
). - Replace flake8, isort, black with ruff+ruff format.
- Add .pre-commit-config.yaml with pre-commit hooks: ruff, ruff-format, mypy...
- If a dataclass has
SchemaConfig
attribute and doesn't haveannotation
attribute, raise aValueError
.
Assumptions
- python 3.9+
Motivation
Create a lightweight, focused solution to generate JSON schema from plain dataclasses. pydantic is a much more mature option, however it also does a lot of other things I didn't want to include here. Deepen my understanding of python dataclasses, typing and JSON schema.
Usage
Basics
Create a regular python dataclass and pass it to get_schema
.
import dataclasses
import datetime
import json
from dc_schema import get_schema
@dataclasses.dataclass
class Book:
title: str
published: bool = False
@dataclasses.dataclass
class Author:
name: str
age: int
dob: datetime.date
books: list[Book]
print(json.dumps(get_schema(Author), indent=2))
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"title": "Author",
"properties": {
"name": {
"type": "string"
},
"age": {
"type": "integer"
},
"dob": {
"type": "string",
"format": "date"
},
"books": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/$defs/Book"
}
]
}
}
},
"required": [
"name",
"age",
"dob",
"books"
],
"$defs": {
"Book": {
"type": "object",
"title": "Book",
"properties": {
"title": {
"type": "string"
},
"published": {
"type": "boolean",
"default": false
}
},
"required": [
"title"
]
}
}
}
Annotations
You can use typing.Annotated + SchemaAnnotation
to attach
metadata to the schema, such as field descriptions, examples, validation (min/max length, regex pattern, ...), etc.
Consult the code for full details.
import dataclasses
import datetime
import json
import typing as t
from dc_schema import get_schema, SchemaAnnotation
@dataclasses.dataclass
class Author:
name: t.Annotated[str, SchemaAnnotation(title="Full name", description="The authors full name")]
age: t.Annotated[int, SchemaAnnotation(minimum=0)]
dob: t.Annotated[t.Optional[datetime.date], SchemaAnnotation(examples=["1990-01-17"])] = None
print(json.dumps(get_schema(Author), indent=2))
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"title": "Author",
"properties": {
"name": {
"type": "string",
"title": "Full name",
"description": "The authors full name"
},
"age": {
"type": "integer",
"minimum": 0
},
"dob": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
],
"default": null,
"examples": [
"1990-01-17"
]
}
},
"required": [
"name",
"age"
]
}
To customize the metadata of a dataclass itself, use a SchemaConfig
.
import dataclasses
import json
from dc_schema import get_schema, SchemaAnnotation
@dataclasses.dataclass
class User:
name: str
class SchemaConfig:
annotation = SchemaAnnotation(title="System user", description="A user of the system")
print(json.dumps(get_schema(User), indent=2))
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"title": "System user",
"description": "A user of the system",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
}
Further examples
See the tests for full example usage.
CLI
dc_schema <file_path> <dataclass>
e.g.
dc_schema ./schema.py Author
Other tools
For working with dataclasses or JSON schema:
- https://github.com/konradhalas/dacite - create data classes from dictionaries.
- https://python-jsonschema.readthedocs.io/en/stable/ - validate an object against a JSON schema.
- https://json-schema.org/understanding-json-schema/index.html - nice reference for understanding JSON schema.
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
Hashes for warchant_dc_schema-0.0.9-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | da51d4d9e60d7706eff9ab2855953449dc01903e741eedae917e5e623b476906 |
|
MD5 | 69ad9ae8f4231679339a837559de2a3f |
|
BLAKE2b-256 | 41849b2993f9b0c586ec1d66ba3f97e9be0de2c12a7d6a0b1f31af686385c288 |