{"id":9639,"library":"dataclasses-jsonschema","title":"dataclasses-jsonschema","description":"The `dataclasses-jsonschema` library (current version 2.16.0) provides a straightforward way to generate JSON schemas from Python dataclasses. It augments dataclasses with a `JsonSchemaMixin` to expose schema generation capabilities and includes utilities for type conversion. The library maintains an active release cadence, frequently addressing bug fixes, improving type handling, and adding support for newer Python features.","status":"active","version":"2.16.0","language":"en","source_language":"en","source_url":"https://github.com/s-knibbs/dataclasses-jsonschema","tags":["dataclass","json-schema","schema-generation","openapi","python-types"],"install":[{"cmd":"pip install dataclasses-jsonschema","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Provides faster UUID and datetime parsing for schema generation.","package":"fastuuid","optional":true}],"imports":[{"symbol":"JsonSchemaMixin","correct":"from dataclasses_jsonschema import JsonSchemaMixin"},{"note":"Remember to import `dataclass` from the standard `dataclasses` module.","symbol":"dataclass","correct":"from dataclasses import dataclass"}],"quickstart":{"code":"from dataclasses import dataclass, field\nfrom datetime import datetime\nfrom dataclasses_jsonschema import JsonSchemaMixin\n\n@dataclass\nclass Person(JsonSchemaMixin):\n    name: str\n    age: int = field(metadata=dict(description=\"Age in years\"))\n    birth_date: datetime\n    # Example with an optional field\n    email: str | None = None # Use typing.Optional for Python < 3.10\n\n# Generate the JSON schema\nschema = Person.json_schema()\n\n# Print the generated schema\nimport json\nprint(json.dumps(schema, indent=2))","lang":"python","description":"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."},"warnings":[{"fix":"Add `from __future__ import annotations` or use `typing.List[str]` for older Python versions.","message":"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.","severity":"gotcha","affected_versions":"< 2.14.0 (Python < 3.9)"},{"fix":"Ensure `from __future__ import annotations` is present, or stick to `typing.List`/`typing.Union` for compatibility.","message":"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.","severity":"breaking","affected_versions":">= 2.14.0 (on Python < 3.9)"},{"fix":"Understand its scope: schema generation. For validation, use a dedicated library like `jsonschema` or `Pydantic`.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to version 2.15.3 or newer for robust handling of complex `Union` and `Optional` types.","message":"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.","severity":"gotcha","affected_versions":"< 2.15.3"},{"fix":"Upgrade to version 2.15.0 or newer to use discriminators for OpenAPI 3.0 polymorphism.","message":"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.","severity":"breaking","affected_versions":"< 2.15.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Add `from __future__ import annotations` at the top of your file, or use `typing.List[str]` and `typing.Dict[str, int]` instead.","cause":"Using PEP 585 type hints (e.g., `list[str]`, `dict[str, int]`) without `from __future__ import annotations` on Python 3.8 or earlier.","error":"TypeError: 'type' object is not subscriptable"},{"fix":"Ensure your dataclass definition includes `(JsonSchemaMixin)`: `@dataclass\nclass MyDataclass(JsonSchemaMixin):`","cause":"The dataclass was not correctly inherited from `dataclasses_jsonschema.JsonSchemaMixin`.","error":"AttributeError: type object 'MyDataclass' has no attribute 'json_schema'"},{"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).","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.","error":"jsonschema.exceptions.ValidationError: 'None' is not of type 'string'"}]}