How to Generate TypeScript Types from JSON
Writing TypeScript interfaces for an API by hand is slow and easy to get wrong, especially for large responses. A faster way is to generate them from a real sample of the JSON, then review the result. This guide shows how, and explains the decisions a good generator makes for you.
From sample to types
Start with a real response, ideally one that includes all the optional fields:
{
"id": 42,
"title": "Hello",
"author": { "name": "Sara", "verified": true },
"comments": [
{ "id": 1, "text": "Nice", "likes": 3 },
{ "id": 2, "text": "Thanks", "replyTo": 1 }
],
"tags": ["news"],
"deletedAt": null
}Paste it into JSON to TypeScript, and you get:
export interface Root {
id: number;
title: string;
author: Author;
comments: Comment[];
tags: string[];
deletedAt: null;
}
export interface Author {
name: string;
verified: boolean;
}
export interface Comment {
id: number;
text: string;
likes?: number;
replyTo?: number;
}What the generator decides for you
Nested objects become their own interfaces
author becomes an Author interface instead of an inline type, which keeps types readable and reusable. Names come from the key, and plural keys become singular: comments โ Comment.
Objects in an array are merged
The two comments have different keys. A naive generator would create two types or use only the first item. A good one merges them into one Comment interface and marks keys that are missing in some items as optional (likes?, replyTo?).
Different value types become unions
If one item has "price": 5 and another "price": "5.00", the result is price: number | string. That is usually a sign the API is inconsistent, which is worth knowing.
Review these three things
nullvalues. The sample only showsdeletedAt: null, so the generator can only saynull. You know it is really a date string when set, so change it todeletedAt: string | null.- Empty arrays become
unknown[]because there is nothing to learn from. Fill in the real item type. - Fields that are optional in the API but present in your sample look required. Use a sample that includes the variations, or mark them optional yourself based on the API docs.
interface or type?
For object shapes both work. interface is a common default for API models and gives clearer error messages. type is needed for unions and other type operations. The generator can output either form.
Types don't check data at runtime
TypeScript types disappear when your code runs. If the API sends something unexpected, response as Root will not catch it. For data from outside your app, combine the types with runtime validation, for example with the Zod library:
import { z } from 'zod'
const Comment = z.object({
id: z.number(),
text: z.string(),
likes: z.number().optional(),
replyTo: z.number().optional(),
})
const Post = z.object({
id: z.number(),
title: z.string(),
comments: z.array(Comment),
deletedAt: z.string().nullable(),
})
type Post = z.infer<typeof Post> // the TypeScript type, for free
const post = Post.parse(await res.json()) // throws if the data is wrongTypical workflow
- Copy a real response from your browser's Network tab, or explore a big one first in the JSON Viewer.
- Generate the interfaces and paste them into your project.
- Fix
null-only fields and empty arrays, and rename the root type (for exampleRootโPost). - For untrusted input, add runtime validation.