JSON to TypeScript

How the types are inferred

The generator reads every element of an array and merges their shapes. Whole numbers and decimals both become number, mixed value types become union types such as string | null, and objects with the same structure share one interface instead of producing duplicates.

Tips for accurate types

Use a sample that includes the optional and nullable cases, ideally several records rather than one. A single example cannot reveal that a field is sometimes missing. Treat the output as a starting point and tighten it, for example by replacing string with a literal union.

From a JSON sample to useful types

Generated types are a starting point, not a specification. The generator reads the sample you give it and describes exactly that: it cannot know which strings are really dates, which numbers are really enums, or which fields might be missing in a response you have not seen. The more varied your sample, the better the result. If you paste an array of records, every record is merged into one interface, so a key that is absent from some of them becomes optional.

// Input
{ "id": 7, "name": "Ada", "email": null, "roles": ["admin"], "address": { "city": "London" } }

// Output
export interface Root {
  id: number;
  name: string;
  email: null;
  roles: string[];
  address: Address;
}

export interface Address {
  city: string;
}

Optional, nullable and missing are three different things

In TypeScript, name?: string means the key may be absent. name: string | null means the key is always present but may hold null. A value that can be absent or null is written name?: string | null. APIs differ in which one they use, and the difference matters for code that checks `in`, `=== undefined` or `=== null`.

When your sample has a field that is null in every record, the generator can only say null, because it has no way to know what the real type would be. Replace it by hand with the type you expect, for example string | null, or give the generator a record where that field is filled in.

Dates, enums and other things JSON cannot say

JSON has no date type. A timestamp arrives as a string, so the generated type is string. If your code converts it to a Date, keep the wire type as string and convert in one place. The same applies to enums: a field that only ever holds one of a few strings is typed as string until you narrow it, for example to "active" | "disabled".

Large integers are another trap. JavaScript numbers are 64-bit floats, so ids above 9,007,199,254,740,991 lose precision when parsed. If an API sends such ids, ask for them as strings or parse them with a library that supports big integers.

Types disappear at runtime: validate the data

A TypeScript interface is erased when your code is compiled, so it cannot check what an API actually returns. If the server changes a field, the compiler will not notice and the error will show up later as a confusing crash. For data that crosses a trust boundary, validate it at runtime. The Zod output of this tool generates a schema that both validates the data and gives you the static type with z.infer, so one definition covers both.

The Schema tab can also validate your JSON against a JSON Schema, which is useful for checking sample responses against a contract before you write any code.

Naming and structure

Nested objects become their own interfaces, named after the key that holds them, with the singular form for arrays (a users array of objects gives User). When two different shapes would get the same name, a number is added so that nothing is overwritten, and identical shapes are reused. Change the root name in the field above the output, then rename the rest in your editor.