JSON to Python Dataclass & Pydantic — Type Hints, Optional, Zero Upload

Real-world use cases

• Type a third-party API response without hand-writing classes

  You're integrating a REST API and the user object has 30+ fields. Curl the endpoint once, paste the JSON, set the root name to `GitHubUser`, pick Pydantic v2, copy the output into `app/clients/github.py`. The nested `plan` object lifts out as `GitHubUserPlan` automatically, `html_url` becomes `html_url` with its alias, and now `GitHubUser.model_validate(resp.json())` gives you a typed object with editor autocomplete instead of a raw `dict` you index by string and pray.

• Generate request/response models for a FastAPI endpoint

  A teammate sends a sample JSON body for the `/orders` POST they're building. Paste it, name the root `CreateOrderRequest`, choose Pydantic v2 so FastAPI validates the body automatically. Paste the response sample too as `CreateOrderResponse`. Drop both into `schemas.py`, wire them into the route signature, and FastAPI's OpenAPI docs + 422 validation come for free — before either of you writes the handler.

• Decide Optional vs required for a nullable webhook payload

  A vendor's webhook sometimes includes `cancelled_at` and sometimes omits it. Log the first few payloads, paste them as a JSON array, and the Optional detection flags `cancelled_at` as `Optional[str] = None`. In your handler `if event.cancelled_at is not None:` cleanly distinguishes "cancelled" from "still active" — and Pydantic raises if a genuinely required field is missing, instead of a `KeyError` three calls deep.

• Replace a dict[str, Any] blob with a real model

  Old code does `data: dict = resp.json()` and reaches in with `data["user"]["profile"]["id"]`, exploding at runtime on a renamed key. Capture one representative response, paste it, generate the dataclass or model, replace the dict. The string indexing that bit you turns into attribute access (`data.user.profile.id`) with mypy / Pyright catching typos at edit time instead of in production.

• Build typed config and fixtures for a Python service

  Your service reads a `config.json`. Paste it, name the root `Config`, keep `@dataclass` for a zero-dependency loader. You get `Config`, `ConfigServer`, `ConfigServerTLS` nested classes with `int` ports and `bool` flags, and `list` fields already using `field(default_factory=list)`. Load it with `Config(**json.load(f))`, and a typo'd key fails at construction with a clear `TypeError` rather than silently passing through a dict.

Common pitfalls

• Pasting a single object and expecting some fields to be Optional. A single object has no missing-key signal, so every field is required (no `= None`). Optional inference only kicks in across an array of objects where some elements carry a key and others don't, or when a value is literally `null`. To explore optionality from one sample, wrap it as `[{...}]`.

• Forgetting that dataclass doesn't validate types at runtime. `@dataclass` only annotates; `User(id="not-an-int")` constructs happily and the wrong type slips through. If the JSON crosses a trust boundary (external API, user input), pick Pydantic v2 so `model_validate` actually coerces and rejects bad data. dataclass is for data you already trust.

• Assuming the generated aliases work without populate_by_name. For Pydantic, `Field(alias="userId")` means `model_validate({"userId": 7})` works, but constructing by the Python name — `Account(user_id=7)` — raises unless you set `model_config = ConfigDict(populate_by_name=True)`. If you build instances in code (not just parse JSON), add that config or construct with the alias.

• Editing a number's type to int when the JSON sometimes has decimals. If one sample is `1` and another is `1.5`, the field correctly widens to `float`. Manually narrowing it back to `int` will make Pydantic reject the `1.5` row (or dataclass store a float under an int annotation, fooling type checkers). Trust the widening — JSON `1` is a valid `float` in Python anyway.

• Pasting JSON5 / JSON-with-comments / trailing commas. We use strict `JSON.parse`, so comments, unquoted keys, and trailing commas all error out with a line/column. Strip them first, or run the payload through a JSON formatter as a pre-step.

Privacy