JSON Schema generation

[Fatal1ty]

Is your feature request related to a problem? Please describe.

Many users, including me, want to generate JSON Schema for their dataclasses. This can be useful for further integration into web frameworks. Thanks to the rich and tested data type support in mashumaro, it is pretty straightforward to add such functionality. The main difficulty will be to support various specifications, some of which are as follows:

• JSON Schema 2020-12
• OpenAPI Specification

Examples of who needs this feature:

• generate schema from models? #55
• [CT-1944] [SPIKE] Remove dependency on hologram dbt-labs/dbt-core#6776

Describe the solution you'd like

Linked PR:

• JSON Schema generation #99

I see it this way:

from enum import Enum
from uuid import UUID
from dataclasses import dataclass
from typing import Annotated
from mashumaro.jsonschema import JSONSchemaBuilder
from mashumaro.jsonschema.annotations import Minimum


class ModelType(Enum):
    ANDROID = "android"
    IPHONE = "iphone"


@dataclass
class Device:
    id: UUID
    type: ModelType = ModelType.IPHONE


@dataclass
class User:
    name: str
    age: Annotated[int, Minimum(1)]
    devices: list[Device]


builder = JSONSchemaBuilder()
print(builder.build(User).to_json())
print(builder.get_definitions().to_json())

Here builder.build(User) will generate the following schema:

{"$ref":"#/defs/User"}

A separated get_definitions method can be used to get all subschema definitions that can be referenced to:

• JSON Schema 2020-12: 8.2.4. Schema Re-Use With "$defs"
• OpenAPI Specification 3.1.0: 4.8.7 Components Object

Here builder.get_definitions() will produce the following schema:

{
    "Device": {
        "type": "object",
        "title": "Device",
        "properties": {
            "id": {
                "type": "string",
                "format": "uuid"
            },
            "type": {
                "enum": [
                    "android",
                    "iphone"
                ],
                "default": "iphone"
            }
        },
        "additionalProperties": false,
        "required": [
            "id"
        ]
    },
    "User": {
        "type": "object",
        "title": "User",
        "properties": {
            "name": {
                "type": "string"
            },
            "age": {
                "type": "integer",
                "minimum": 1
            },
            "devices": {
                "type": "array",
                "items": {
                    "$ref": "#/defs/Device"
                }
            }
        },
        "additionalProperties": false,
        "required": [
            "name",
            "age",
            "devices"
        ]
    }
}

Open questions to discuss

The following questions come to mind

• What keywords must be added to the final scheme?
• What dialects should be supported out of the box?
  • Which versions of JSON Schema Drafts?
  • Which versions of OpenAPI Specification?
• How to add custom keywords to the final scheme?

[Fatal1ty]

From now on, mashumaro can build JSON Schema 🎉