dataclasses-jsonschema

Common errors

• TypeError: 'type' object is not subscriptable

  cause Using PEP 585 type hints (e.g., `list[str]`, `dict[str, int]`) without `from __future__ import annotations` on Python 3.8 or earlier.
  fix Add `from __future__ import annotations` at the top of your file, or use `typing.List[str]` and `typing.Dict[str, int]` instead.

• AttributeError: type object 'MyDataclass' has no attribute 'json_schema'

  cause The dataclass was not correctly inherited from `dataclasses_jsonschema.JsonSchemaMixin`.
  fix Ensure your dataclass definition includes `(JsonSchemaMixin)`: `@dataclass class MyDataclass(JsonSchemaMixin):`

• jsonschema.exceptions.ValidationError: 'None' is not of type 'string'

  cause Schema generated for an `Optional[str]` field (or similar nullable type) might not correctly mark it as nullable, especially on older `dataclasses-jsonschema` versions or with complex `Union` types.
  fix Upgrade `dataclasses-jsonschema` to the latest version (2.15.3+) to improve `Union` and `Optional` handling. Ensure your dataclass field is correctly typed as `str | None` (Python 3.10+) or `Optional[str]` (Python < 3.10).

Warnings

• gotcha When using built-in generic types (e.g., `list[str]`, `dict[str, int]`) in Python versions older than 3.9, you must include `from __future__ import annotations` at the top of your module.
  Fix: Add `from __future__ import annotations` or use `typing.List[str]` for older Python versions.
• breaking Support for PEP 585 (built-in generics like `list[str]`) and PEP 604 (union operator `|`) was introduced in version 2.14.0. If you upgrade to 2.14.0+ and start using these new syntaxes without `from __future__ import annotations` on Python < 3.9, your code might break.
  Fix: Ensure `from __future__ import annotations` is present, or stick to `typing.List`/`typing.Union` for compatibility.
• gotcha `dataclasses-jsonschema` is specifically designed for JSON schema generation from dataclasses. It does not provide runtime data validation, parsing, or serialization/deserialization like libraries such as Pydantic do. Trying to use it as a full-fledged data validation library will lead to unexpected behavior.
  Fix: Understand its scope: schema generation. For validation, use a dedicated library like `jsonschema` or `Pydantic`.
• gotcha Prior to version 2.15.0, handling of complex `Union` types, especially with `Optional` (e.g., `Optional[Union[A, B]]`), could lead to incorrect or incomplete schema generation. This was further refined in 2.15.2 and 2.15.3.
  Fix: Upgrade to version 2.15.3 or newer for robust handling of complex `Union` and `Optional` types.
• breaking Discriminator support, crucial for OpenAPI 3.0 polymorphic schemas, was added in version 2.15.0. Any attempts to use discriminator functionality with versions older than 2.15.0 will not work as expected.
  Fix: Upgrade to version 2.15.0 or newer to use discriminators for OpenAPI 3.0 polymorphism.

Install

• pip install dataclasses-jsonschema Install stable version

Imports

• JsonSchemaMixin

  from dataclasses_jsonschema import JsonSchemaMixin

• dataclass

  from dataclasses import dataclass

  Remember to import `dataclass` from the standard `dataclasses` module.

Quickstart

Define a dataclass that inherits from `JsonSchemaMixin`. Then, call the static method `.json_schema()` on the dataclass to retrieve the generated JSON schema. This example demonstrates basic field types and metadata usage.

from dataclasses import dataclass, field
from datetime import datetime
from dataclasses_jsonschema import JsonSchemaMixin

@dataclass
class Person(JsonSchemaMixin):
    name: str
    age: int = field(metadata=dict(description="Age in years"))
    birth_date: datetime
    # Example with an optional field
    email: str | None = None # Use typing.Optional for Python < 3.10

# Generate the JSON schema
schema = Person.json_schema()

# Print the generated schema
import json
print(json.dumps(schema, indent=2))