How to use the JSON to TypeScript
- Paste a representative JSON sample – ideally a real response with several array items.
- Choose the root type name; nested names are derived from their keys.
- Review the generated interfaces and rename anything the generator could not name well.
- Copy the code into a .ts file, or download it.
Worked example
An API list response where one user has no email
Input
{"users":[{"id":1,"name":"Ada","email":"ada@example.com"},{"id":2,"name":"Linus"}],"total":2}TypeScript
interface Root {
users: User[];
total: number;
}
interface User {
id: number;
name: string;
email?: string;
}email exists on the first user only, so it becomes optional. Exact type names can differ slightly from this listing depending on settings.
How JSON values map to TypeScript
| JSON value | TypeScript type | Note |
|---|---|---|
| "text" | string | Dates stay string; JSON has no date type |
| 42 or 4.2 | number | Integers above 2^53 lose precision when parsed by JSON.parse |
| true / false | boolean | |
| null | null | Combined with other samples, e.g. string | null |
| [1, 2] | number[] | Mixed arrays become a union, e.g. (string | number)[] |
| [] | unknown[] | An empty array gives no element type to infer |
| { ... } | named interface | One per distinct nested object |
Optional vs. nullable fields
A field missing from some array elements is optional (email?: string). A field that is present but sometimes null is nullable (email: string | null). These mean different things to the compiler and to your API consumers, so feed the generator samples that show both cases if your API has them.
Interfaces are not runtime checks
TypeScript types disappear at compile time. Writing const data = (await res.json()) as Root tells the compiler to trust the response; it does not check it. If the data comes from outside your code, validate it at runtime with a schema library such as Zod, then infer the type from the schema.
Keys that are not valid identifiers, such as "first-name", are emitted in quotes: "first-name": string. That is valid TypeScript, but you must access the field with bracket notation.
JSON to TypeScript FAQ
Should I use interface or type for JSON data?
Either works for plain object shapes. Interfaces can be extended and merged and give slightly clearer error messages; type aliases are needed for unions. Pick one style per codebase.
How do I make the generated types match every API response?
Paste a sample with several array elements covering the variations you know about: missing fields, null values, different item kinds. One item only tells the generator about one shape.
Can TypeScript validate JSON at runtime?
No. Types are erased when compiling to JavaScript. For runtime validation use a schema (Zod, JSON Schema with Ajv) and derive the TypeScript type from it.
What type should an empty array get?
Nothing in the sample says what it holds, so unknown[] is the safe answer. Replace it with the real element type once you know it.
Why is my ISO date typed as string?
JSON only has strings, numbers, booleans, null, arrays and objects. A date is just a string until your code converts it, so string is the accurate type for the parsed JSON.