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]

클래스는 사용되기 전에 정의되도록 정렬됩니다. 두 번째 댓글에는 text가 없어서 Optional[str] = None이 됩니다.

dataclass, Pydantic, TypedDict 차이

세 모드는 같은 구조를 나타내지만 실행 시 동작이 다릅니다(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가 첫 항목에서는 null, 둘째 항목에서는 없고, discount는 둘째 항목에만 있는 상품 데이터(루트 클래스 이름 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 값이 있는 대표 객체를 포함하세요.