How to use the JSON to Python
- Paste a JSON object (or an array of objects) into the input.
- Use the Python style option to choose dataclasses or Pydantic v2 models.
- Check the field types: int vs float is inferred from the sample numbers.
- Copy the classes into a .py file. Hints use typing's List and Optional, so they work on Python 3.7+.
Worked example
An order with nested line items
Input
{"order_id":"A-1001","total":59.9,"paid":true,"items":[{"sku":"X1","qty":2}]}Python
from dataclasses import dataclass
from typing import List
@dataclass
class Item:
sku: str
qty: int
@dataclass
class Root:
order_id: str
total: float
paid: bool
items: List[Item]Item comes first because Root refers to it. The class name comes from the key: items is singularized to Item.
Dataclass or Pydantic?
| Need | dataclass | Pydantic model |
|---|---|---|
| Dependencies | Standard library | pip install pydantic |
| Builds nested objects from dicts | No – Root(**data) leaves items as dicts | Yes – Root.model_validate(data) |
| Type checking at runtime | No | Yes, with clear errors |
| Coerces "2" to 2 | No | Yes in lax mode (default) |
| Best for | Internal data you already trust | API input, config, anything external |
Loading JSON into dataclasses
json.loads returns plain dicts and lists. Root(**data) fills the top-level fields, but items will still be a list of dicts, not Item objects, because dataclasses do not convert nested values. Either build them explicitly (Root(**{**data, "items": [Item(**i) for i in data["items"]]})) or switch to Pydantic, which does this for you.
Keys that are not valid Python names
JSON keys like "class", "from" or "first-name" cannot be attribute names. The generator renames them (first-name becomes first_name, class becomes class_). In dataclass output a comment records the original key and you map it yourself when loading; in Pydantic output the field gets Field(alias="first-name") automatically.
A value that is null in every sample becomes Optional[Any], since nothing tells the generator its real type.
JSON to Python FAQ
How do I convert a JSON string to a Python dataclass?
Parse it with json.loads, then pass the dict to the class: Root(**json.loads(text)). Nested objects need converting separately, or use Pydantic's Root.model_validate_json(text), which handles nesting in one call.
Why is my number field typed as float instead of int?
The sample contained a decimal point, e.g. 59.9 or 2.0. JSON 2.0 parses to a Python float. If the field is always whole, change the hint to int.
Can I generate Pydantic v2 models instead?
Yes. Set Python style to Pydantic v2 models on this same page. Models subclass BaseModel and load with model_validate / model_validate_json, the v2 API.
Which Python version do I need for the generated code?
Dataclasses need Python 3.7+. The generated hints use List, Optional and Union from typing, which work on every version since; on 3.9+ you can switch to list[Item] and on 3.10+ to X | None if you prefer.
How do I turn a dataclass back into JSON?
Use dataclasses.asdict(obj), which recurses into nested dataclasses, then json.dumps the result. Pydantic models have model_dump_json().