Python Dataclasses and JSON: Serialization Guide

Written and reviewed by the Jsonic editorial team — every guide is verified against the official spec or runtime before publication.

Last updated: May 19, 2026

Python dataclasses (introduced in Python 3.7) give you structured, typed data classes with minimal boilerplate. But they don't come with built-in JSON support — you need to know the right tools to serialize them to JSON and deserialize JSON back into typed dataclass instances. This guide covers every approach: from the standard library's asdict(), to dacite, marshmallow-dataclass, and Pydantic.

1. Dataclass to JSON: asdict() + json.dumps()

The standard library approach: dataclasses.asdict() converts the dataclass to a dict, then json.dumps() serializes it.

import json
import dataclasses
from dataclasses import dataclass, field
from typing import List

@dataclass
class Product:
    name: str
    price: float
    tags: List[str] = field(default_factory=list)

# Serialize to JSON
product = Product(name="Widget", price=9.99, tags=["sale", "new"])
d = dataclasses.asdict(product)
# {'name': 'Widget', 'price': 9.99, 'tags': ['sale', 'new']}

json_str = json.dumps(d, indent=2)
print(json_str)
# {
#   "name": "Widget",
#   "price": 9.99,
#   "tags": ["sale", "new"]
# }

# One-liner
json_str = json.dumps(dataclasses.asdict(product))

To deserialize a simple flat dataclass (no nested types), unpack the parsed dict directly:

data = json.loads(json_str)
product = Product(**data)
print(product.name)   # Widget
print(product.price)  # 9.99

# WARNING: This only works if all keys in data match field names exactly
# and all types are already correct (json.loads returns str, float, list, dict)

2. JSON to Dataclass: dacite

For deserializing JSON into dataclasses — especially with nested types — install dacite:

pip install dacite

import json
from dataclasses import dataclass
from typing import Optional
import dacite

@dataclass
class Address:
    street: str
    city: str
    country: str = "US"

@dataclass
class User:
    name: str
    email: str
    age: Optional[int] = None
    address: Optional[Address] = None

json_str = '''
{
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "age": 36,
  "address": {
    "street": "123 Main St",
    "city": "London",
    "country": "GB"
  }
}
'''

data = json.loads(json_str)
user = dacite.from_dict(User, data)

print(user.name)             # Ada Lovelace
print(user.address.city)     # London
print(type(user.address))    # <class 'Address'>  -- properly typed!

dacite raises dacite.exceptions.WrongTypeError if a field has the wrong type, and dacite.exceptions.MissingValueError if a required field is absent.

3. Nested Dataclasses

dataclasses.asdict() handles nested dataclasses recursively — no extra code needed for serialization:

import json
import dataclasses
from dataclasses import dataclass
from typing import List

@dataclass
class Tag:
    name: str
    color: str

@dataclass
class Article:
    title: str
    body: str
    tags: List[Tag]

article = Article(
    title="Python Tips",
    body="Use dataclasses for structured data.",
    tags=[Tag("python", "blue"), Tag("tips", "green")]
)

print(json.dumps(dataclasses.asdict(article), indent=2))
# {
#   "title": "Python Tips",
#   "body": "Use dataclasses for structured data.",
#   "tags": [
#     {"name": "python", "color": "blue"},
#     {"name": "tips", "color": "green"}
#   ]
# }

For deserialization, dacite handles lists of nested dataclasses via the List[Tag] type annotation automatically:

import dacite

data = json.loads(json_str)
article = dacite.from_dict(Article, data)
print(article.tags[0].color)  # blue
print(type(article.tags[0]))  # <class 'Tag'>

4. Handling datetime and Enums

datetime and Enum are not JSON-serializable by default. Here are the patterns for each.

datetime Fields

import json
import dataclasses
from dataclasses import dataclass
from datetime import datetime

@dataclass
class Event:
    title: str
    created_at: datetime

event = Event(title="Launch", created_at=datetime(2026, 5, 19, 12, 0, 0))

# Option 1: default=str (simplest — calls str() on non-serializable objects)
json_str = json.dumps(dataclasses.asdict(event), default=str)
# {"title": "Launch", "created_at": "2026-05-19 12:00:00"}

# Option 2: default=str with isoformat (explicit)
def json_serial(obj):
    if isinstance(obj, datetime):
        return obj.isoformat()
    raise TypeError(f"Type {type(obj)} not serializable")

json_str = json.dumps(dataclasses.asdict(event), default=json_serial)
# {"title": "Launch", "created_at": "2026-05-19T12:00:00"}

# Deserialization: parse the string back to datetime
data = json.loads(json_str)
data["created_at"] = datetime.fromisoformat(data["created_at"])
event = Event(**data)

Enum Fields

import json
import dataclasses
from dataclasses import dataclass
from enum import Enum

class Status(str, Enum):
    ACTIVE = "active"
    INACTIVE = "inactive"
    PENDING = "pending"

@dataclass
class Account:
    name: str
    status: Status

account = Account(name="Ada", status=Status.ACTIVE)

# str Enum: inheriting from str makes Enum values JSON-serializable directly
json_str = json.dumps(dataclasses.asdict(account))
# {"name": "Ada", "status": "active"}  -- works because Status inherits from str

# For plain Enum (not str Enum), use default=lambda o: o.value
class Priority(Enum):
    LOW = 1
    HIGH = 2

@dataclass
class Task:
    name: str
    priority: Priority

task = Task("Fix bug", Priority.HIGH)
json_str = json.dumps(dataclasses.asdict(task), default=lambda o: o.value)
# {"name": "Fix bug", "priority": 2}

# Deserialization with dacite and Enum
import dacite
data = json.loads(json_str)
# dacite can cast int/str to Enum with strict=False or cast config
task = dacite.from_dict(Task, data, config=dacite.Config(cast=[Enum]))

5. marshmallow-dataclass for Validation

marshmallow-dataclass generates a full marshmallow Schema from a dataclass, adding validation and field-level error reporting on top of serialization.

pip install marshmallow marshmallow-dataclass

from marshmallow_dataclass import dataclass
from marshmallow import ValidationError
from typing import Optional
from datetime import datetime

@dataclass
class User:
    name: str
    email: str
    age: Optional[int] = None
    created_at: Optional[datetime] = None

# Schema is auto-generated
schema = User.Schema()

# Serialize: dump() -> dict, dumps() -> JSON string
user = User(name="Ada", email="ada@example.com", age=30,
            created_at=datetime(2026, 5, 19))
json_str = schema.dumps(user)
# '{"name": "Ada", "email": "ada@example.com", "age": 30, "created_at": "2026-05-19T00:00:00"}'

# Deserialize + validate: load() raises ValidationError on bad data
try:
    user = schema.load({"name": "Ada", "email": "ada@example.com", "age": "not-a-number"})
except ValidationError as e:
    print(e.messages)
    # {'age': ['Not a valid integer.']}

# Successful deserialization
user = schema.load({"name": "Ada", "email": "ada@example.com", "age": 30})
print(type(user))   # <class 'User'>
print(user.age)     # 30

marshmallow-dataclass handles datetime, UUID, and custom field types automatically — without any default= workarounds.

6. Pydantic vs dataclasses

Pydantic v2 BaseModel is the most capable option for JSON-heavy applications. Here is a direct comparison:

pip install pydantic

from pydantic import BaseModel, EmailStr
from typing import Optional, List
from datetime import datetime

class Address(BaseModel):
    street: str
    city: str
    country: str = "US"

class User(BaseModel):
    name: str
    email: str
    age: Optional[int] = None
    created_at: datetime = None
    address: Optional[Address] = None

# Deserialize from JSON string — validates types automatically
json_str = '''
{
  "name": "Ada",
  "email": "ada@example.com",
  "age": 30,
  "created_at": "2026-05-19T12:00:00",
  "address": {"street": "123 Main", "city": "London", "country": "GB"}
}
'''
user = User.model_validate_json(json_str)
print(user.address.city)       # London
print(type(user.created_at))   # <class 'datetime.datetime'>  -- auto-parsed!

# Serialize back to JSON
print(user.model_dump_json(indent=2))

# Generate JSON Schema for OpenAPI docs
import json
print(json.dumps(User.model_json_schema(), indent=2))

7. Custom JSON Encoder for Dataclasses

For maximum control, write a custom json.JSONEncoder subclass that handles your specific non-serializable types:

import json
import dataclasses
from dataclasses import dataclass
from datetime import datetime, date
from enum import Enum
from uuid import UUID
from typing import Any

class DataclassEncoder(json.JSONEncoder):
    """
    JSON encoder that handles:
    - dataclass instances (via asdict)
    - datetime / date (via isoformat)
    - Enum (via .value)
    - UUID (via str)
    """
    def default(self, obj: Any) -> Any:
        if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
            return dataclasses.asdict(obj)
        if isinstance(obj, (datetime, date)):
            return obj.isoformat()
        if isinstance(obj, Enum):
            return obj.value
        if isinstance(obj, UUID):
            return str(obj)
        return super().default(obj)

# Usage
@dataclass
class OrderLine:
    product_id: UUID
    quantity: int
    unit_price: float

@dataclass
class Order:
    order_id: UUID
    created_at: datetime
    lines: list[OrderLine]

from uuid import uuid4

order = Order(
    order_id=uuid4(),
    created_at=datetime.now(),
    lines=[
        OrderLine(uuid4(), 2, 9.99),
        OrderLine(uuid4(), 1, 29.99),
    ]
)

# Serialize directly — no need to call asdict() first
json_str = json.dumps(order, cls=DataclassEncoder, indent=2)
print(json_str)
# {
#   "order_id": "f47ac10b-...",
#   "created_at": "2026-05-19T12:00:00",
#   "lines": [
#     {"product_id": "...", "quantity": 2, "unit_price": 9.99},
#     ...
#   ]
# }

Note that DataclassEncoder.default() is called for objects that the standard encoder cannot handle. Dataclass instances are not dicts, so they hit default() — where we call asdict() to convert them. This approach works even for deeply nested structures.

FAQ