{"id":3512,"library":"hologram","title":"Hologram Library","description":"Hologram is a Python library that generates JSON schemas from standard Python dataclasses. It provides a `JsonSchemaMixin` that, when added to a dataclass, enables automatic schema generation and object parsing from JSON data. The current version is 0.0.16, with releases being infrequent.","status":"active","version":"0.0.16","language":"en","source_language":"en","source_url":"https://github.com/dbt-labs/hologram","tags":["JSON schema","dataclasses","schema generation","validation","type hints"],"install":[{"cmd":"pip install hologram","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for JSON schema generation and validation.","package":"jsonschema","optional":false},{"reason":"Required for certain type features on Python versions prior to 3.8.","package":"typing-extensions","optional":false},{"reason":"Provides alternative serialization/deserialization capabilities, integrated in v0.13.0.","package":"mashumaro","optional":true}],"imports":[{"note":"The primary mixin for schema generation is directly available from the top-level 'hologram' package.","wrong":"from hologram.json_schema_mixin import JsonSchemaMixin","symbol":"JsonSchemaMixin","correct":"from hologram import JsonSchemaMixin"},{"symbol":"FieldSpec","correct":"from hologram import FieldSpec"},{"symbol":"ValidationError","correct":"from hologram import ValidationError"}],"quickstart":{"code":"from dataclasses import dataclass, field\nfrom typing import List, Optional, Union\nfrom hologram import FieldSpec, JsonSchemaMixin\n\n@dataclass\nclass SubModel(JsonSchemaMixin):\n    id: int\n    name: str\n\n@dataclass\nclass MyModel(JsonSchemaMixin):\n    id: int\n    name: str\n    optional_field: Optional[str] = None\n    list_of_strings: List[str] = field(default_factory=list)\n    union_field: Union[str, int] = FieldSpec(\n        title='Union Field',\n        description='This is a union field.'\n    )\n    nested_model: SubModel = field(default_factory=lambda: SubModel(id=1, name=\"default\"))\n\n# Generate JSON schema\nschema = MyModel.json_schema()\nprint(\"Generated Schema:\", schema)\n\n# Parse object from dictionary\ndata = {'id': 1, 'name': 'test model', 'list_of_strings': ['a', 'b'], 'nested_model': {'id': 2, 'name': 'nested test'}} \ntry:\n    instance = MyModel.parse_object(data)\n    print(\"Parsed Instance:\", instance)\nexcept Exception as e:\n    print(f\"Error parsing object: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to define dataclasses with `JsonSchemaMixin`, including optional fields, lists, unions with `FieldSpec`, and nested models. It then shows how to generate a JSON schema from the dataclass and parse a Python dictionary into a dataclass instance, leveraging Hologram's validation capabilities."},"warnings":[{"fix":"Review the GitHub repository's issues and PRs for current activity and known compatibility problems with newer Python versions or type hints before relying on it for critical projects. Consider contributing or forking if you require active maintenance.","message":"Hologram is in a `0.0.x` versioning stage and has infrequent releases (last release May 2022). This may mean slower adoption of new Python features, types, or addressing breaking changes in dependent libraries (like `jsonschema`).","severity":"gotcha","affected_versions":"<0.1.0"},{"fix":"Always use `FieldSpec` for `Union`, `Optional` with default values where custom metadata is desired, and any other complex type requiring specific JSON schema attributes. Refer to the official documentation for advanced `FieldSpec` usage.","message":"For complex type hints or custom schema modifications (e.g., adding descriptions, examples, titles), understanding and correctly using `hologram.FieldSpec` is crucial. Omitting it for complex types might lead to generic or incorrect schema generation.","severity":"gotcha","affected_versions":"All"},{"fix":"If `mashumaro` is desired, consult `hologram`'s GitHub README or source code for examples on how to integrate `mashumaro`'s `DataClassDictMixin` with `JsonSchemaMixin` for your dataclasses.","message":"Hologram introduced optional `mashumaro` integration in v0.0.13, which is not the default serialization/deserialization path. If you intend to use `mashumaro` for its performance or specific features, you'll need to explicitly configure it, which might diverge from the basic `JsonSchemaMixin` usage.","severity":"gotcha","affected_versions":">=0.0.13"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}