How to Generate a Python Dataclass From JSON

You’ve got a sample JSON response from an API — maybe a dozen fields, some nested — and you want a proper typed Python @dataclass to represent it, rather than working with a loosely-typed dictionary throughout your codebase. Writing that dataclass by hand means going through the JSON field by field, figuring out the right Python type for each value, and typing out the boilerplate class definition, which is exactly the kind of mechanical translation task that’s easy to get slightly wrong or just tedious to do for anything beyond a few fields.

Type inference from example JSON isn’t perfect — a null value doesn’t reveal an unambiguous type, and a JSON number doesn’t distinguish between Python’s int and float if it happens to be a whole number — but for a large share of real-world JSON, a good generator gets you most of the way to a usable dataclass, saving the mechanical typing even where you need to make small manual adjustments.

What generating a dataclass from JSON actually involves

Each JSON field maps to a dataclass attribute, with its type inferred from the JSON value: strings become str, numbers become int or float depending on whether they contain a decimal point, booleans become bool, arrays become List[...] with an inferred element type, and nested objects become their own separate dataclasses. Python’s @dataclass decorator handles the boilerplate __init__ generation automatically once the field definitions are correct, which is most of the value of using dataclasses over a plain dictionary in the first place.

The genuinely tricky cases are ones the sample JSON alone can’t fully resolve — an empty array gives no element type to infer, a null value gives no type at all, and a numeric field with only whole-number examples might actually need to accept float values in other cases you haven’t seen yet.

Why people get stuck here

• Manually mapping JSON types to Python types. Going field by field to translate JSON’s data types into the correct Python type annotations is mechanical, repetitive work for anything beyond a small object.
• Nested objects needing their own dataclasses. A JSON object with nested objects doesn’t map to a single flat dataclass — each nested structure typically needs its own separate class definition.
• Ambiguous types from limited sample data. A single example JSON payload might not reveal the full range of types a field can actually take across different API responses.
• Keeping the dataclass in sync as the API evolves. An API’s response shape can change over time, and manually updating a hand-written dataclass to match isn’t something that happens automatically.

What a good JSON to dataclass generator looks like

Infers reasonable types from the JSON values

Correctly mapping strings, numbers, booleans, arrays, and nested objects to their Python equivalents removes the manual translation step.

Generates separate dataclasses for nested structures

Rather than flattening everything into one class, properly representing nested JSON objects as their own linked dataclasses keeps the generated code structurally sound.

Produces genuinely usable, idiomatic code

The output should look like code a Python developer would actually write by hand — proper type hints, sensible naming, and correct use of the @dataclass decorator.

Common mistakes to avoid

• Trusting inferred types from a single sample without considering whether the field might take other types in different API responses (a nullable field, for instance).
• Not reviewing generated field names for cases where JSON keys don’t map cleanly to valid Python identifiers.
• Forgetting to regenerate or update the dataclass when the underlying API response shape changes.
• Treating a generated dataclass as complete without adding any validation logic your actual use case might need beyond basic typing.
• Assuming an empty array or null value in the sample JSON gives enough information to infer a meaningful type — these cases often need manual correction.

How to do it with JSON to Python Dataclass

Online Tool Store’s JSON to Python Dataclass generates the dataclass entirely in your browser.

1. Open the JSON to Python Dataclass tool.
2. Paste your sample JSON object or array.
3. Review the generated Python dataclass with inferred field types.
4. Copy the code into your project, adjusting any ambiguous types as needed.

Because it runs locally, you can paste real API response data without sending it to an external server.

Frequently asked questions

What happens when a JSON field is null in the sample data?

A null value alone doesn’t reveal what type the field should actually be, so a generator typically needs to fall back to a generic or optional type — worth reviewing and correcting manually if you know what type the field actually represents from other context.

Does this handle nested JSON objects correctly?

Yes, a good generator should create separate, properly linked dataclasses for nested objects rather than flattening everything into a single class, which keeps the generated code structurally accurate to the original JSON’s shape.

Should I always trust the inferred types without review?

It’s worth a quick review, especially for fields where the sample JSON might not represent the full range of values the field can actually take — a number that happens to be a whole number in your sample might need to be float if the API can return decimal values in other cases.

Final thought

Generating a dataclass from real JSON gets you most of the way to solid, typed Python code fast — worth a quick manual review of the ambiguous fields, but far faster than writing the whole thing by hand.

Try the free JSON to Python Dataclass tool