How to convert JSON to TypeScript types

Step 1 — Start with a representative JSON sample

Use a real API response, webhook payload, or fixture. Include nested objects and at least one item in each array so the generated type has enough information to work with.

{
  "id": 42,
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "isAdmin": false,
  "profile": {
    "company": "Analytical Engine Labs",
    "timezone": "Europe/London"
  },
  "tags": ["math", "engine"]
}

Step 2 — Generate TypeScript interfaces

Paste the sample into the JSON → TypeScript converter. The first pass gives you clean structural types:

export interface Root {
  id: number;
  name: string;
  email?: string;
  isAdmin: boolean;
  profile: Profile;
  tags: string[];
}

export interface Profile {
  company: string;
  timezone: string;
}

Step 3 — Rename and tighten the output

Generated names are a starting point. Rename the root type, review nested types, and check optional fields against your real API contract.

export interface User {
  id: number;
  name: string;
  email?: string;
  isAdmin: boolean;
  profile: UserProfile;
  tags: string[];
}

export interface UserProfile {
  company: string;
  timezone: string;
}

Step 4 — Use the type at your API boundary

TypeScript helps your editor and compiler, but it does not validate JSON at runtime. This pattern is fine when you trust the upstream response:

export async function fetchUser(): Promise<User> {
  const res = await fetch("/api/me");
  return (await res.json()) as User;
}

Step 5 — Upgrade to Zod when runtime validation matters

If the JSON comes from a third-party API, user form, webhook, env var, or localStorage, TypeScript alone cannot protect you. Generate a Zod schema instead and derive the type from that schema:

import { z } from "zod";

export const User = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email().optional(),
  isAdmin: z.boolean(),
  profile: z.object({
    company: z.string(),
    timezone: z.string(),
  }),
  tags: z.array(z.string()),
});

export type User = z.infer<typeof User>;

Common pitfalls

• • One sample is not the whole API. A field missing from this sample might still exist later; a field present here might be optional in production.
• • Empty arrays become weak types. Use a sample with at least one array item to infer the element shape.
• • Dates are strings over the wire. JSON has no Date type. Keep timestamps as string unless your code explicitly parses them.
• • Types are not validators. If bad JSON can crash a flow, use the JSON to Zod guide after generating the first type.

Troubleshooting generated TypeScript types

TypeScript types generated from JSON are only as complete as the sample. Before using them as an API contract, check the cases that a single payload cannot prove.

// If this field may be omitted:
email?: string;

// If the API sends null explicitly:
email: string | null;

// If both can happen:
email?: string | null;

// Empty sample arrays cannot reveal the element type
const sample = { tags: [] };

// Weak first pass
interface User {
  tags: unknown[];
}

// Tighten it after checking real data
interface User {
  tags: string[];
}

interface Invoice {
  id: string;

  // JSON sends this as a string, even when it represents a date
  issuedAt: string;
}

const issuedAt = new Date(invoice.issuedAt);

// This only tells TypeScript to trust you.
// It does not validate the response at runtime.
const user = (await res.json()) as User;

FAQ