JSON to TypeScript

How the interfaces are generated

Choose Example to load an order from a shop’s API. Each object becomes an interface named after its key, so customer becomes Customer. Objects inside an array get the singular form: the ones in items become Item.

All the objects in an array share one interface. A field that every object has is required, and a field that some of them leave out is optional. In the example, only the T-shirt has a discount:

export interface Item {
  sku: string;
  name: string;
  qty: number;
  price: number;
  discount?: number;
}

This is why a sample with one item isn’t enough. With a single item, every field looks required. Paste a response with several items, ideally including ones with empty or missing fields.

A field with different kinds of values gets a union type. If phone were null for one customer and "555-0142" for another, its type would be string | null.

Objects with exactly the same fields share an interface too. billingAddress and shippingAddress both hold a city and a zip, so both use Address. Keys that aren’t valid TypeScript names, such as content-type, stay in quotes.

Check these before you use the types

The converter can only describe the values in your sample. These are the gaps to look for:

• Fields that are always null. phone is null in the example, so its type is just null. Replace it with the real type, such as string | null.
• Empty arrays. tags is empty, so there’s nothing to go on and it becomes unknown[].
• Strings with a fixed set of values. status comes out as string. If the API only ever sends a few values, list them so TypeScript catches a typo like "shiped".
• Dates. JSON has no date type, so createdAt is a string. That matches what response.json() returns. Call new Date(order.createdAt) where you need a date.
• Long IDs. An ID like 12345678901234567890 is typed as number, but JSON.parse rounds numbers past 15 or 16 digits. If the API offers the ID as a string, use that field instead.
• Objects that come in different kinds. If a payment is either a card with a last4 or PayPal with an email, both end up in one interface with every field optional. A union describes it better, and TypeScript can then tell which fields exist from type:

  type Payment =
    | { type: "card"; last4: string }
    | { type: "paypal"; email: string };

• Repeated names. If two arrays would both produce Item, the second becomes Item2. Rename it to something that says what it holds, like CartItem.

With the first four fixes, the example’s types look like this:

export interface Order {
  status: "pending" | "shipped" | "delivered";
  tags: string[];
  createdAt: string; // ISO 8601, like "2026-11-04T09:30:00Z"
  // other fields unchanged
}

export interface Customer {
  phone: string | null;
  // other fields unchanged
}

Interface or type?

The converter writes interfaces, but a type alias works just as well for JSON data. If your project uses type aliases, change export interface Order { to export type Order = {. The main difference is that two interfaces with the same name merge into one, while a second type alias with the same name is an error.

Using the types with fetch

response.json() returns any, so you can assign the result to your interface:

const response = await fetch("/api/orders/1042");
const order: Order = await response.json();

This tells the compiler what to expect, but nothing checks the response when the code runs, because TypeScript types are removed when the code is compiled. If the API renames a field, order.customer.name quietly becomes undefined instead of raising an error where the response arrives.

To catch that, validate the response before you use it. The JSON Schema validator can generate a schema from the same sample. Libraries such as Zod let you describe the shape once in code and get both the runtime check and the TypeScript type from it.

Generating TypeScript types from the command line

If you regenerate types often, use a command-line tool. When the API publishes an OpenAPI description, generate from that instead of a sample. It lists every field and every allowed value, including the ones your sample happened not to contain.

# From a sample file, with quicktype
npx quicktype order.json -o order.ts

# From an OpenAPI description, with openapi-typescript
npx openapi-typescript openapi.yaml -o api.d.ts