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.10:
- Add ability to define
patternProperties
for dataclasses. See ./tests/test_dc_schema.py for details (test_object_pattern_properties
).
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.10.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | e34119cfbb7a69a830f57f538c2a441b27a5b0c1f113e98d7e564da45df75392 |
|
MD5 | bd4bb13b886d6b47fd968b7f14121d58 |
|
BLAKE2b-256 | af5902a4314b5f67b6f3a8cf21e623ae6fa1853e0e03a21bcac3ef9a454961fe |
Hashes for warchant_dc_schema-0.0.10-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a671976e307a64ec6b3f50b8460adc59c2d89ef738261c285d7c730a833baff7 |
|
MD5 | 27f4e10c91a69b46929d33bee0d6b214 |
|
BLAKE2b-256 | 825bf88f87ce8f945b6bd1f41570447a67190c172dbaa591521f7490a89a72f6 |