JSON → Python Dataclass

型マッピング

• null → Optional[Any] = None
• 文字列 → str
• 整数 → int
• 浮動小数点数 → float
• 真偽値 → bool
• 配列 → List[T]
• 混合配列 → List[Union[T1, T2]]
• ネストオブジェクト → 別クラス

例

このJSONが与えられた場合：

{"user": {"first_name": "Alice", "age": 30}, "tags": ["admin"], "note": null}

@dataclassモードで生成されるコード：

from dataclasses import dataclass
from typing import Any, List, Optional

@dataclass
class User:
    first_name: str
    age: int

@dataclass
class Root:
    user: User
    tags: List[str]
    note: Optional[Any] = None

例：ネストしたオブジェクトと欠けているキー

入力：

{"id": 7, "title": "Release notes", "author": {"name": "Alice", "email": null}, "tags": ["python", "json"], "score": 4.5, "comments": [{"user": "bob", "text": "nice"}, {"user": "carol"}]}

@dataclass モードの出力：

from dataclasses import dataclass
from typing import Any, List, Optional

@dataclass
class Author:
  name: str
  email: Optional[Any] = None

@dataclass
class CommentsItem:
  user: str
  text: Optional[str] = None

@dataclass
class Root:
  id: int
  title: str
  author: Author
  tags: List[str]
  score: float
  comments: List[CommentsItem]

クラスは使われる前に定義される順に並びます。2 件目のコメントには text がないので Optional[str] = None になります。

dataclass・Pydantic・TypedDict の違い

3 つのモードは同じ構造を表しますが、実行時の動きが違います（Python 3.12、Pydantic 2.13 で確認）：

root = Root(**json.loads(raw))
type(root.author)          # <class 'dict'>, not Author

root = Root.model_validate(json.loads(raw))   # Pydantic mode
root.comments[1]           # CommentsItem(user='carol', text=None)

• @dataclass は検証も変換もしません。Root(**data) ではネストしたオブジェクトはただの dict のままで、型が違っても受け付けます。信頼できるデータに使うか、ネストしたフィールドを自分で変換します。
• Pydantic は型を検証し、ネストしたモデルを組み立てます。自分で管理していない API のレスポンスに向いています。model_validate_json(raw) でパースと検証を一度に行えます。
• TypedDict は型チェッカー向けに dict の型を書くだけで、実行時には何も確認しません。キーは既定ですべて必須なので、ツールは一部の要素にしかないキーを NotRequired[...] にします（PEP 655。Python 3.11 以降は typing、それ以前は typing_extensions）。Optional[...] は値が None になりうることを表すだけで、キーは必須のままです。

例：キーが欠ける TypedDict

note が 1 件目では null、2 件目では欠けていて、discount は 2 件目にしかない商品データ（ルートクラス名 Product、TypedDict モード）：

[{"id": 1, "sku": "PEN-01", "price": 2, "note": null}, {"id": 2, "sku": "INK-07", "price": 1.5, "discount": 0.1}]

from typing import Any, NotRequired, Optional, TypedDict

class Product(TypedDict):
  id: int
  sku: str
  price: float
  note: NotRequired[Optional[Any]]
  discount: NotRequired[float]

price は 2 と 1.5 です。PEP 484 では int を float として扱えるので、型は float になります。実行時の Product.required_keys は {'id', 'sku', 'price'}、optional_keys は {'note', 'discount'} です（Python 3.12 で確認）。

制限

• null は Optional[Any] になります。Any を実際の型に置き換えてください。
• Python の識別子として使えないキー（user-id や class のような予約語）は名前を変え、Pydantic では Field(alias="user-id") を付けます。
• 日付は str のままです。型を datetime に変えれば Pydantic が ISO 8601 文字列を変換します。
• ルートがプリミティブの配列のときはクラスを生成しません。

空の配列とサンプルの範囲

空の配列からは要素の型を判断できないため、{"tags": []} は tags: List[Any] になります。同じ入力配列に {"tags": ["admin"]} を持つ別のオブジェクトを加えると、統合したフィールドは List[str] になります。生成器は入力したサンプルに基づいて型を推測し、どのサンプルにもないフィールドは推測できません。クラスをコピーする前に、キーの欠落や null 値を含む代表的なオブジェクトを加えてください。