Dataclasses JSON

Warnings

• gotcha The `@dataclass_json` decorator must be placed *above* the built-in `@dataclass` decorator. Incorrect ordering can lead to unexpected behavior or errors.
  Fix: Ensure `@dataclass_json` is the outermost decorator on your dataclass definition (e.g., `@dataclass_json\n@dataclass`).
• gotcha Deserialization of `Union` types can be complex. If not explicitly tagged (e.g., with a `__type` field) or if multiple types in the Union can match the input JSON, `dataclasses-json` might deserialize to a generic `dict` instead of the intended dataclass, or fail to correctly infer the type. This is especially true for 'naive' unions without explicit discriminators.
  Fix: For complex `Union` types, consider providing explicit type discriminators within your JSON payload or implementing custom decoding logic using `config(decoder=...)` to guide `dataclasses-json` to the correct target type.
• gotcha Using `from __future__ import annotations` can interfere with `dataclasses-json`'s ability to access type annotations, potentially causing serialization or deserialization issues.
  Fix: Avoid using `from __future__ import annotations` when working with `dataclasses-json` if you encounter unexpected type resolution problems.
• gotcha Naive `datetime` objects are encoded as `float` (UNIX timestamps) and decoded into timezone-aware `datetime` objects (using the system's local timezone). This can lead to non-inverse transformations for naive datetimes.
  Fix: For consistent datetime handling, always use timezone-aware `datetime` objects, or define custom encoders/decoders (e.g., for ISO 8601 string format) using `field(metadata=config(...))` to ensure predictable serialization and deserialization.
• gotcha When deserializing JSON with fields not present in the dataclass (undefined parameters), the default behavior may vary or result in `KeyError` or `ValidationError`. The `undefined` parameter (e.g., `Undefined.RAISE`, `Undefined.EXCLUDE`, `Undefined.INCLUDE`) on `dataclass_json` or per-field `config` dictates this behavior.
  Fix: Explicitly set the `undefined` parameter on the `@dataclass_json` decorator or within `field(metadata=config(...))` to control how extraneous fields are handled. `Undefined.EXCLUDE` is often a safe choice to ignore unknown fields.
• deprecated Python 3.7 support is still present but may be removed in future minor releases after 0.6.0. Python 3.7 is end-of-life and no longer receives official support.
  Fix: Users on Python 3.7 should plan to migrate to a newer Python version (e.g., 3.8, 3.9, 3.10+) to ensure continued compatibility and support.

Install

• pip install dataclasses-json Install stable version

Imports

• dataclass_json

  from dataclasses_json import dataclass_json

  The decorator is directly available under the `dataclasses_json` top-level package.
• DataClassJsonMixin

  from dataclasses_json import DataClassJsonMixin

  The mixin is directly available under the `dataclasses_json` top-level package.

Quickstart

This quickstart demonstrates how to define a dataclass, apply the `@dataclass_json` decorator, and then use the generated `to_json()` and `from_json()` methods for serialization and deserialization.

from dataclasses import dataclass
from dataclasses_json import dataclass_json
import json

@dataclass_json
@dataclass
class Person:
    name: str
    age: int
    city: str

# Encoding to JSON
person_instance = Person(name='Alice', age=30, city='New York')
json_string = person_instance.to_json(indent=2)
print(f"Serialized JSON:\n{json_string}")

# Decoding from JSON
raw_json = '{"name": "Bob", "age": 25, "city": "London"}'
decoded_person = Person.from_json(raw_json)
print(f"Deserialized Person: {decoded_person}")