dataclasses-json

dataclasses-json is a lightweight Python library that adds JSON serialization to standard library dataclasses through a simple @dataclass_json decorator or a DataClassJsonMixin base class. With one line, your dataclasses gain to_json, from_json, to_dict, and from_dict methods that recursively handle nested dataclasses, collections, and common standard-library types.

Beyond the basics, it integrates with marshmallow to offer optional schema-based validation, and supports camelCase/kebab-case letter-case mapping, per-field name overrides, configurable handling of missing and undefined fields, and custom encoders/decoders. It is fully typed and ships a py.typed marker for static analysis.

What You Get

• to_json/from_json and to_dict/from_dict methods on any dataclass via a decorator or mixin
• Recursive encoding and decoding of nested dataclasses, collections, datetimes, UUIDs, and Decimals
• Optional marshmallow schema generation via .schema() for validation and many=True batch loading
• Letter-case mapping (camelCase, kebab-case) and per-field name overrides
• Configurable handling of missing, optional, and undefined fields (RAISE / EXCLUDE / CatchAll)

Common Use Cases

• Serializing dataclass models to JSON for HTTP API requests and responses
• Parsing external JSON payloads into strongly typed dataclass instances
• Mapping between snake_case Python fields and camelCase JSON from third-party APIs
• Validating incoming JSON against a schema before constructing objects

Under The Hood

Architecture The public surface lives in dataclasses_json/api.py, where DataClassJsonMixin and the dataclass_json decorator attach to_json, from_json, to_dict, from_dict, and schema to a target dataclass. Encoding and decoding logic is centralized in core.py: _asdict and the _ExtendedEncoder recursively serialize nested dataclasses, collections, and special types, while _decode_dataclass reconstructs typed instances by reading get_type_hints and mapping collection ABCs to concrete implementations. mm.py builds marshmallow schemas on demand for the validation path, cfg.py holds LetterCase/global_config, and undefined.py implements the RAISE/EXCLUDE/CatchAll strategies for unknown fields.

Tech Stack Pure Python targeting 3.7+, with just two runtime dependencies: marshmallow (>=3.18,<4) for schema validation and typing-inspect for introspecting generic and union types. The project is built with Poetry using poetry-dynamic-versioning, and dev tooling includes pytest, hypothesis, mypy, flake8, and black.

Code Quality The repository carries a substantial test suite (27 test modules) that combines example-based tests with hypothesis property-based tests over generated dataclasses. The codebase is type-annotated and ships a py.typed marker, so downstream users get static-analysis support. Internals are organized into small focused modules (core, mm, cfg, undefined, utils).

API Design The developer experience is deliberately minimal: a single decorator stacked above @dataclass, or a mixin, is enough to get full JSON support with zero configuration. Method names mirror the standard json module (to_json/from_json) so they feel familiar, and advanced behavior (letter case, field overrides, undefined-field handling) is opt-in through keyword arguments and config() metadata rather than required setup.