JSONからPythonへ：Dataclass、Pydantic、JSONパースの完全ガイド

Why Model JSON with Python Classes?

JSON is the universal data-exchange format for REST APIs, webhooks, and configuration files. When you receive JSON in Python, you have several options: work with raw dicts, use the lightweight standard library dataclasses, or adopt Pydantic'sBaseModel for full validation. The right choice depends on your use case.

Dicts vs Dataclasses vs Pydantic

For production APIs consuming external JSON, Pydantic is the clear winner: it validates types, raises structured errors, handles nested models, and integrates natively with FastAPI. Dataclasses shine for internal domain objects where you control all inputs.

Generate Python dataclasses and Pydantic models from JSON instantly →

Standard json Module: json.loads and json.dumps

Python's built-in json module is your starting point. It converts between JSON strings and Python native types (dict, list, str, int, float, bool, None).

import json

# Deserialize JSON string → Python dict
raw = '{"user_id": 42, "name": "Alice", "active": true}'
data = json.loads(raw)
print(data["name"])   # Alice
print(type(data))     # <class 'dict'>

# Serialize Python dict → JSON string
output = json.dumps(data, indent=2)
print(output)
# {
#   "user_id": 42,
#   "name": "Alice",
#   "active": true
# }

# Reading JSON from a file
with open("config.json") as f:
    config = json.load(f)   # json.load() for file objects

# Writing JSON to a file
with open("output.json", "w") as f:
    json.dump(data, f, indent=2)  # json.dump() for file objects

The json module has no validation — it simply maps JSON types to Python types. All values remain generic: numbers become int orfloat, objects become dict, arrays become list. For structured access with type safety, move to dataclasses or Pydantic.

Type Mapping Reference

Python Dataclasses: @dataclass + from_dict

The @dataclass decorator (Python 3.7+) automatically generates__init__, __repr__, and__eq__ from class field annotations. It's stdlib — no extra dependencies needed.

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

@dataclass
class Address:
    street: str
    city: str
    zip_code: str

@dataclass
class User:
    user_id: int
    name: str
    email: str
    address: Address
    tags: List[str] = field(default_factory=list)
    phone: Optional[str] = None

# Manual deserialization from dict
def user_from_dict(data: dict) -> User:
    return User(
        user_id=data["user_id"],
        name=data["name"],
        email=data["email"],
        address=Address(**data["address"]),
        tags=data.get("tags", []),
        phone=data.get("phone"),
    )

raw_json = """
{
  "user_id": 42,
  "name": "Alice",
  "email": "alice@example.com",
  "address": {"street": "123 Main St", "city": "NYC", "zip_code": "10001"},
  "tags": ["admin", "verified"]
}
"""
data = json.loads(raw_json)
user = user_from_dict(data)
print(user.name)           # Alice
print(user.address.city)   # NYC
print(user.phone)          # None

# Serialize back to dict / JSON
user_dict = asdict(user)
user_json = json.dumps(user_dict, indent=2)
print(user_json)

Dataclasses do not validate types. If the JSON contains "user_id": "42" (a string), the dataclass will store it as a string without complaint. For type enforcement, use Pydantic.

Pydantic v2: BaseModel — The Industry Standard

Pydantic v2 (released June 2023) is written in Rust and is 5-50x faster than v1. It validates, coerces, and serializes Python data with a minimal, expressive API. Install with:pip install pydantic

from pydantic import BaseModel, Field
from typing import Optional, List
import json

class Address(BaseModel):
    street: str
    city: str
    zip_code: str

class User(BaseModel):
    user_id: int
    name: str
    email: str
    address: Address
    tags: List[str] = Field(default_factory=list)
    phone: Optional[str] = None

raw_json = """
{
  "user_id": "42",
  "name": "Alice",
  "email": "alice@example.com",
  "address": {"street": "123 Main St", "city": "NYC", "zip_code": "10001"},
  "tags": ["admin", "verified"]
}
"""
# Pydantic coerces "42" → 42 automatically
user = User.model_validate_json(raw_json)
print(user.user_id)        # 42  (int, not "42")
print(user.address.city)   # NYC
print(user.phone)          # None

# Serialize to dict
user_dict = user.model_dump()

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

# Validate from dict
data = json.loads(raw_json)
user2 = User.model_validate(data)
print(user2.name)          # Alice

Key Pydantic v2 methods: Model.model_validate(dict),Model.model_validate_json(str),model.model_dump(), andmodel.model_dump_json(). Invalid data raises pydantic.ValidationError with detailed field-level messages.

TypedDict for Lightweight Typing

TypedDict (Python 3.8+) adds type annotations to dicts without any runtime overhead. It is essentially a dict — type checkers enforce the shape, but Python itself does not validate at runtime.

from typing import TypedDict, Optional, List
import json

class AddressDict(TypedDict):
    street: str
    city: str
    zip_code: str

class UserDict(TypedDict, total=False):
    user_id: int
    name: str
    email: str
    address: AddressDict
    tags: List[str]
    phone: Optional[str]

raw_json = '{"user_id": 42, "name": "Alice", "email": "a@b.com"}'
# json.loads returns a plain dict; we "cast" it with type: ignore or cast()
from typing import cast
user: UserDict = cast(UserDict, json.loads(raw_json))
print(user["name"])   # Alice

# mypy / pyright will flag wrong key access at analysis time
# No runtime validation — this is purely for the type checker

Use total=False to make all fields optional, or useRequired / NotRequired (Python 3.11+) to control individual field optionality.

Attrs Library: A Powerful Dataclass Alternative

The attrs library predates Python dataclasses and offers more features: validators, converters, slots, and frozen (immutable) instances. Install with: pip install attrs

import attr
from typing import Optional, List
import json

@attr.s(auto_attribs=True)
class User:
    user_id: int
    name: str
    email: str
    tags: List[str] = attr.Factory(list)
    phone: Optional[str] = None

    # Built-in validator example
    @name.validator
    def _check_name(self, attribute, value):
        if len(value) < 1:
            raise ValueError("Name cannot be empty")

raw = {"user_id": 42, "name": "Alice", "email": "alice@example.com"}
user = User(**raw)
print(user.name)    # Alice

# attrs also works with cattrs for structured deserialization
# pip install cattrs
import cattrs
user2 = cattrs.structure(raw, User)
print(user2.user_id)  # 42

attrs with cattrs provides deserialization similar to Pydantic but with a more explicit API. It's particularly popular in high-performance contexts where slot classes are needed.

Nested Models with Pydantic BaseModel

Pydantic handles arbitrarily nested JSON structures. Each nested object maps to its ownBaseModel subclass, and validation cascades through all levels.

from pydantic import BaseModel
from typing import List

class Tag(BaseModel):
    id: int
    name: str
    color: str = "#000000"

class Company(BaseModel):
    name: str
    domain: str

class User(BaseModel):
    id: int
    username: str
    company: Company
    tags: List[Tag] = []

raw = {
    "id": 1,
    "username": "alice",
    "company": {"name": "Acme Corp", "domain": "acme.com"},
    "tags": [
        {"id": 10, "name": "admin", "color": "#ff0000"},
        {"id": 11, "name": "verified"},  # color uses default
    ]
}

user = User.model_validate(raw)
print(user.company.name)       # Acme Corp
print(user.tags[0].color)      # #ff0000
print(user.tags[1].color)      # #000000

# Serialize nested structure
print(user.model_dump())
# {'id': 1, 'username': 'alice', 'company': {'name': 'Acme Corp', ...}, ...}

# Serialize with JSON indentation
print(user.model_dump_json(indent=2))

When a nested field fails validation, Pydantic includes the full path in the error:ValidationError: 1 validation error for User — tags.0.id — Input should be a valid integer. This makes debugging API responses significantly easier.

Optional and Nullable Fields

JSON fields can be absent (missing key) or explicitly null. Python handles both scenarios withOptional and default values.

from pydantic import BaseModel, Field
from typing import Optional
import json

class UserProfile(BaseModel):
    user_id: int
    username: str
    # Optional field: may be absent or null in JSON
    bio: Optional[str] = None
    # Python 3.10+ shorthand: bio: str | None = None

    # Field with metadata and default
    avatar_url: Optional[str] = Field(
        default=None,
        description="URL to profile image",
        examples=["https://cdn.example.com/avatar.png"]
    )
    follower_count: int = Field(default=0, ge=0)  # ge=0 means >= 0

# All these are valid:
p1 = UserProfile(user_id=1, username="alice")
p2 = UserProfile(user_id=2, username="bob", bio=None)
p3 = UserProfile(user_id=3, username="carol", bio="Developer")
print(p1.bio)           # None
print(p3.bio)           # Developer

# JSON with missing optional field
raw = '{"user_id": 4, "username": "dave"}'
p4 = UserProfile.model_validate_json(raw)
print(p4.bio)           # None
print(p4.avatar_url)    # None
print(p4.follower_count) # 0

Enum Handling in JSON Parsing

Use Python's enum.Enum to represent JSON string or integer constants. Pydantic automatically validates and coerces enum values.

from pydantic import BaseModel
from enum import Enum
from typing import Optional

class UserRole(str, Enum):
    ADMIN = "admin"
    EDITOR = "editor"
    VIEWER = "viewer"

class Priority(int, Enum):
    LOW = 1
    MEDIUM = 2
    HIGH = 3

class Task(BaseModel):
    title: str
    role: UserRole = UserRole.VIEWER
    priority: Priority = Priority.MEDIUM
    assigned_to: Optional[str] = None

# Pydantic coerces string "admin" → UserRole.ADMIN
task = Task.model_validate({
    "title": "Fix bug",
    "role": "admin",
    "priority": 3,
    "assigned_to": "alice"
})
print(task.role)              # UserRole.ADMIN
print(task.role.value)        # admin
print(task.priority)          # Priority.HIGH
print(task.priority.value)    # 3

# Serialization includes enum values by default
print(task.model_dump())
# {'title': 'Fix bug', 'role': <UserRole.ADMIN: 'admin'>, ...}

# To serialize as plain values:
print(task.model_dump(mode='json'))
# {'title': 'Fix bug', 'role': 'admin', 'priority': 3, ...}

Date and Time Handling with datetime

JSON has no native date type. Dates are typically serialized as ISO 8601 strings (e.g., "2026-02-27T14:30:00Z"). Pydantic automatically parses ISO 8601 strings into Python datetime objects.

from pydantic import BaseModel
from datetime import datetime, date, timedelta
from typing import Optional
import json

class Event(BaseModel):
    title: str
    start_at: datetime          # ISO 8601 string → datetime
    end_at: Optional[datetime] = None
    event_date: date            # "2026-02-27" → date
    duration_minutes: int = 60

raw = {
    "title": "Team Standup",
    "start_at": "2026-02-27T09:00:00Z",
    "end_at": "2026-02-27T09:30:00Z",
    "event_date": "2026-02-27",
}
event = Event.model_validate(raw)
print(event.start_at)              # 2026-02-27 09:00:00+00:00
print(type(event.start_at))       # <class 'datetime.datetime'>
print(event.event_date)            # 2026-02-27

# Serialize datetime back to JSON (ISO 8601 string)
serialized = event.model_dump_json()
print(serialized)
# {"title":"Team Standup","start_at":"2026-02-27T09:00:00Z",...}

# For plain dataclasses, convert manually:
import dataclasses
@dataclasses.dataclass
class Event2:
    title: str
    start_at: datetime

raw2 = json.loads('{"title": "Meeting", "start_at": "2026-02-27T10:00:00Z"}')
e2 = Event2(
    title=raw2["title"],
    start_at=datetime.fromisoformat(raw2["start_at"].replace("Z", "+00:00"))
)
print(e2.start_at)  # 2026-02-27 10:00:00+00:00

Custom Validators with Pydantic @field_validator

Pydantic v2 provides @field_validator for field-level validation and @model_validator for cross-field validation. These replace v1's @validator decorator.

from pydantic import BaseModel, field_validator, model_validator, Field
from typing import Optional
import re

class UserRegistration(BaseModel):
    username: str
    email: str
    password: str
    confirm_password: str
    age: int = Field(ge=0, le=150)

    @field_validator("username")
    @classmethod
    def username_alphanumeric(cls, v: str) -> str:
        if not re.match(r"^[a-zA-Z0-9_]{3,20}$", v):
            raise ValueError(
                "Username must be 3-20 chars, alphanumeric and underscores only"
            )
        return v.lower()

    @field_validator("email")
    @classmethod
    def email_valid(cls, v: str) -> str:
        if "@" not in v or "." not in v.split("@")[-1]:
            raise ValueError("Invalid email address")
        return v.lower()

    @model_validator(mode="after")
    def passwords_match(self) -> "UserRegistration":
        if self.password != self.confirm_password:
            raise ValueError("Passwords do not match")
        return self

# Valid data
user = UserRegistration(
    username="Alice_99",
    email="Alice@Example.COM",
    password="secret123",
    confirm_password="secret123",
    age=30
)
print(user.username)   # alice_99 (lowercased by validator)
print(user.email)      # alice@example.com

# Invalid data raises ValidationError
from pydantic import ValidationError
try:
    UserRegistration(
        username="a",  # too short
        email="not-an-email",
        password="abc",
        confirm_password="xyz",  # mismatch
        age=200  # out of range
    )
except ValidationError as e:
    print(e.error_count(), "errors")  # 4 errors

FastAPI Integration: Automatic JSON Deserialization

FastAPI is built on Pydantic. Declare a Pydantic model as a request body parameter and FastAPI automatically deserializes the incoming JSON, validates it, and provides IDE-complete typed access — no manual parsing needed.

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field
from typing import Optional, List
from datetime import datetime

app = FastAPI()

class CreateUserRequest(BaseModel):
    username: str = Field(min_length=3, max_length=50)
    email: str
    role: str = "viewer"
    tags: List[str] = []

class UserResponse(BaseModel):
    id: int
    username: str
    email: str
    role: str
    created_at: datetime
    tags: List[str]

@app.post("/users", response_model=UserResponse, status_code=201)
async def create_user(body: CreateUserRequest):
    # FastAPI has already validated body against CreateUserRequest
    # body.username, body.email etc. are fully typed
    new_user = {
        "id": 100,
        "username": body.username,
        "email": body.email,
        "role": body.role,
        "created_at": datetime.utcnow(),
        "tags": body.tags,
    }
    return UserResponse(**new_user)

@app.get("/users/{user_id}", response_model=UserResponse)
async def get_user(user_id: int):
    # Path params are also validated by FastAPI
    if user_id <= 0:
        raise HTTPException(status_code=404, detail="User not found")
    return UserResponse(
        id=user_id,
        username="alice",
        email="alice@example.com",
        role="admin",
        created_at=datetime.utcnow(),
        tags=["verified"]
    )

# FastAPI auto-generates OpenAPI docs at /docs
# Invalid JSON bodies return 422 Unprocessable Entity with field-level errors

FastAPI uses the response_model parameter to automatically filter and serialize the response using the specified Pydantic model, ensuring the output matches the declared shape and excluding any extra fields.

Generate Python Classes Instantly with DevToolBox

Writing Pydantic models or dataclasses by hand from complex JSON is tedious and error-prone. The DevToolBox JSON to Python converter at viadreams.cc/en/tools/json-to-python generates production-ready Pydantic v2 models and dataclasses from any JSON payload:

• Paste any JSON object or array — get instant Python classes
• Supports Pydantic v2 BaseModel, @dataclass, and TypedDict output
• Handles nested objects, arrays, optional fields, and mixed types
• Generates Optional[T] for nullable fields automatically
• Free to use, no sign-up required, works in-browser

Open the JSON to Python tool now →

Related tools also available on DevToolBox: JSON Formatter, JSON Validator, JSON to TypeScript.

Common Pitfalls and How to Avoid Them

1. JSON Numbers: int vs float Ambiguity

JSON does not distinguish integers from floats — 42 and42.0 are both valid numbers. Python'sjson.loads() maps integers to intand decimals to float, but 42.0becomes a float, not an int. Pydantic coerces 42.0 to42 when the field is typed as int.

import json
from pydantic import BaseModel

data = json.loads('{"count": 42.0}')
print(type(data["count"]))  # <class 'float'>

class MyModel(BaseModel):
    count: int

m = MyModel.model_validate(data)
print(m.count)              # 42 (int) — Pydantic coerced it
print(type(m.count))        # <class 'int'>

# But precision loss is possible for large floats:
data2 = json.loads('{"value": 9007199254740993.0}')
print(data2["value"])       # May lose precision!
# Use Decimal for financial data:
from decimal import Decimal
from pydantic import BaseModel
class Financial(BaseModel):
    amount: Decimal

2. datetime Serialization Pitfalls

datetime objects are not JSON-serializable by default. Usingjson.dumps({"ts": datetime.utcnow()}) raises aTypeError: Object of type datetime is not JSON serializable. Use Pydantic's model_dump_json() which handles datetime automatically, or use json.dumps(data, default=str) as a quick workaround.

from datetime import datetime
import json

now = datetime.utcnow()

# This FAILS:
# json.dumps({"ts": now})  # TypeError!

# Quick fix (loses timezone info):
print(json.dumps({"ts": now}, default=str))
# {"ts": "2026-02-27 14:30:00.123456"}

# Better: use isoformat()
print(json.dumps({"ts": now.isoformat() + "Z"}))
# {"ts": "2026-02-27T14:30:00.123456Z"}

# Best: use Pydantic (handles tz, precision, ISO 8601)
from pydantic import BaseModel
class Event(BaseModel):
    ts: datetime

e = Event(ts=now)
print(e.model_dump_json())
# {"ts":"2026-02-27T14:30:00.123456"}

3. snake_case vs camelCase Mapping

JSON APIs often use camelCase keys (e.g., userId), but Python convention is snake_case (user_id). Pydantic handles this with alias_generator:

from pydantic import BaseModel, ConfigDict
from pydantic.alias_generators import to_camel

class UserResponse(BaseModel):
    model_config = ConfigDict(
        alias_generator=to_camel,
        populate_by_name=True  # allow both alias and field name
    )
    user_id: int
    first_name: str
    last_name: str
    is_active: bool = True

# Accepts camelCase JSON
user = UserResponse.model_validate({
    "userId": 42,
    "firstName": "Alice",
    "lastName": "Smith"
})
print(user.user_id)      # 42
print(user.first_name)   # Alice

# Serializes with camelCase aliases
print(user.model_dump(by_alias=True))
# {'userId': 42, 'firstName': 'Alice', 'lastName': 'Smith', 'isActive': True}

4. Mutable Default Arguments in Dataclasses

Never use mutable defaults like tags: list = [] in a dataclass — this is a common Python footgun where all instances share the same list object. Usefield(default_factory=list) instead:

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

@dataclass
class User:
    name: str
    # WRONG — all User instances share same list!
    # tags: List[str] = []

    # CORRECT — new list per instance
    tags: List[str] = field(default_factory=list)
    metadata: Dict[str, str] = field(default_factory=dict)

u1 = User(name="Alice")
u2 = User(name="Bob")
u1.tags.append("admin")
print(u2.tags)   # [] — separate list, not affected

Frequently Asked Questions