Python クラスを JSON に変換しよう!

Python の Pydantic·dataclass コードを入力すると例の JSON を作ります!Pydantic BaseModel, Field(alias), dataclass, TypedDict 対応。API ドキュメントやテスト用のリクエストボディ(sample JSON)に。
Python
結果
 

Python クラスを JSON に変換しよう!

Pydantic の BaseModel、@dataclass、TypedDict で書いた Python のモデルを貼り付けると、その構造に沿った例の JSON ドキュメントが返ってきます。Field(alias=...) や alias_generator=to_camel の設定も読み取るので、snake_case のフィールドが実際にどのキーでシリアライズされるかがわかります。

FastAPI のエンドポイントのリクエスト例を作るとき、Webhook やキューのペイロードのスキーマを他チームと共有するとき、pytest 用の JSON フィクスチャを用意するときに向いています。

使い方

  1. モデルのある .py ファイルの内容を貼り付けます。import の行、メソッド、@field_validator のようなデコレーターは読み飛ばされます。
  2. 参照しているサブモデルや Enum クラスも含めると、その部分が埋まります。文字列の前方参照("Order")も理解します。
  3. ルート型 が 自動 のときは、他のモデルからフィールドの型として使われていないクラスが選ばれます。リストから選ぶこともできます。
  4. JSON をコピーして、json_schema_extra の examples、テストデータのファイル、API ドキュメントに使います。

例

入力 (Python · Pydantic)
class Payer(BaseModel):
    model_config = ConfigDict(alias_generator=to_camel)
    customer_id: str
    email_address: str

class PaymentEvent(BaseModel):
    model_config = ConfigDict(alias_generator=to_camel)
    event_type: Literal["payment.succeeded", "payment.failed"]
    amount: Decimal
    currency: str = "KRW"
    payer: Payer
    receipt_url: Optional[str] = None
    retry_count: int = Field(default=0, alias="retries")
    raw_payload: dict = Field(exclude=True)
出力 (JSON)
{
  "eventType": "payment.succeeded",
  "amount": "0",
  "currency": "KRW",
  "payer": {
    "customerId": "",
    "emailAddress": ""
  },
  "receiptUrl": "",
  "retries": 0
}

model_config の to_camel により、event_type、receipt_url、customer_id は camelCase のキーになりますが、retry_count は明示的な alias="retries" が優先されます。raw_payload には Field(exclude=True) があるので省かれます。Literal は最初の値 payment.succeeded を取り、リテラルのデフォルト値 "KRW" はそのまま残ります。

対応機能

  • Pydantic の BaseModel(v1 と v2)、@dataclass、TypedDict、auto() を含む Enum/StrEnum/IntEnum を読み取ります。
  • キー名は Field(alias=...)、serialization_alias、そして model_config = ConfigDict(...) や内側の class Config: で設定した alias_generator(to_camel、to_pascal)から決めます。
  • 除外されるもの: _ で始まる名前、ClassVar、model_config、Field(exclude=True) のフィールド。
  • 型の扱い: Optional[X] / X | None → X のサンプル、Literal[...] → 最初の値、Annotated/Required/NotRequired → 内側の型、list/set/tuple → 要素1つの配列、dict[str, V] → {"key": V}。
  • Pydantic の型: EmailStr、HttpUrl、SecretStr、constr → 文字列、conint、PositiveInt → 0、Decimal と condecimal → Pydantic v2 の JSON と同じく文字列の "0"。
  • 日付と時刻: datetime → 1970-01-01T00:00:00、date → 1970-01-01、time → 00:00:00、timedelta → PT0S。UUID には正しい形式の値が入ります。
  • 文字列、数値、True/False のリテラルのデフォルト値はサンプルとして使い、Status.PAID のような enum のデフォルトはそのメンバーの値になります。

利用シーン

FastAPI のリクエスト例

リクエストモデルから JSON を生成して model_config = {"json_schema_extra": {"examples": [...]}} に入れれば、/docs の例もエンドポイントが期待するのと同じエイリアスのキーになります。

Webhook やイベントのペイロードを共有する

Celery のタスクや Kafka のメッセージのペイロードを Pydantic で定義しているなら、Node や Go を使う利用側のチームには Python のコードではなく生成した JSON を渡して、構造をすり合わせられます。

pytest のフィクスチャを用意する

model_validate_json() や API クライアントのテストに使う JSON ファイルの骨組みを作り、個々の値を変えてエッジケースを追加できます。

注意点と制限

  • Optional のフィールドや、デフォルトが None のフィールドにも、null ではなく型に応じたサンプルが入ります。
  • Decimal は Pydantic v2 の JSON シリアライズ(model_dump_json)に合わせて文字列の "0" で埋めます。プロジェクトが数値で出力している場合(Pydantic v1 や json.dumps(default=float))は数値に変えてください。
  • @computed_field、@field_serializer、@model_serializer のように出力を作り変えるコードは実行しません。
  • Union[A, B] は None 以外の最初のメンバーを使います。discriminator フィールドで選ぶ判別共用体はモデル化しません。
  • default_factory や関数呼び出しで作るデフォルト値は実行せず、値は型から作ります。

よくある質問

出力はエイリアスのキーなのに、model_dump_json() ではフィールド名で出てきます。

Pydantic は by_alias=True を渡さない限りフィールド名でシリアライズします。FastAPI の response_model は既定で by_alias=True を使うので、このツールの出力と一致します。自分でダンプする場合は model_dump_json(by_alias=True) を呼んでください。

dataclass にはエイリアスがありません。それでもキーがフィールド名と異なることはありますか?

標準の dataclass には名前を変える仕組みがないので、フィールド名がそのままキーになります。このサイトの JSON → Python のページが生成する dataclass のように、フィールドの末尾に # JSON: "orderId" というコメントがあれば、その名前を使います。

TypedDict の NotRequired のキーも含まれますか?

含まれます。サンプルはありうるキーをすべて見せるためのものなので、NotRequired や total=False のフィールドも含めます。省略されうるものはドキュメントで明記してください。

SQLAlchemy のモデルも扱えますか?

このページは型ヒントベースのモデル向けです。Column(...) や Mapped[...] で宣言した SQLAlchemy のモデルには、SQLAlchemy → JSON のページを使ってください。