Professional JSON-to-TypeScript Engineering: The Definitive Guide to Type-Safe APIs

JSON to TypeScript: Generating Type-Safe Interfaces from Real-World Data

TypeScript's value comes from its types — but writing interfaces by hand for every API response, config file, or database row is tedious and error-prone. Generating TypeScript interfaces from JSON lets you establish a compile-time contract instantly. When your backend returns a new field or renames a property, TypeScript surfaces the mismatch before it reaches production.

Live Example: Nested API Response

// Input JSON
{
  "id": "usr_9921",
  "profile": {
    "username": "dev_guru",
    "tags": ["typescript", "rust"],
    "settings": {
      "theme": "dark",
      "notifications": true
    }
  },
  "last_login": "2023-10-27T10:00:00Z",
  "subscription": null
}

// Generated TypeScript Interfaces
export interface Settings {
  theme: string;
  notifications: boolean;
}

export interface Profile {
  username: string;
  tags: string[];
  settings: Settings;
}

export interface User {
  id: string;
  profile: Profile;
  last_login: string;
  subscription: null;
}

Handling null, undefined, and Optional Fields

One of the trickiest aspects of JSON-to-TypeScript conversion is handling absence correctly. JSON has null, but TypeScript also has undefined and optional properties (?). The distinction matters:

// A field present but null → use union with null
subscription: string | null;

// A field that may not appear at all → use optional modifier
nickname?: string;

// A field that can be absent OR null → both
middleName?: string | null;

High-quality converters infer these from your sample data. If a field is null in your JSON, it becomes T | null. If it's completely missing in some array items, it gets marked optional. Always test with the most complete sample you have — a sparse sample produces sparse interfaces.

Working with Date Fields

JSON has no native date type — dates travel as ISO 8601 strings. TypeScript interfaces typically represent them as string, which is accurate at the boundary. But once inside your application, you usually want a Date object. The standard pattern:

// Interface at the API boundary (raw JSON)
interface ApiUser {
  id: string;
  created_at: string;  // ISO 8601 string from JSON
}

// Domain model inside your app
interface User {
  id: string;
  createdAt: Date;     // parsed Date object
}

// Mapping function
function toUser(raw: ApiUser): User {
  return {
    id: raw.id,
    createdAt: new Date(raw.created_at),
  };
}

Keep the raw boundary type separate from your domain model. This makes the transformation explicit and testable.

Discriminated Unions from Polymorphic JSON

APIs often return polymorphic responses — events, notifications, or payment types that share some fields but differ by a type discriminator. TypeScript handles this cleanly:

// JSON array with mixed event types
[
  { "type": "click", "x": 120, "y": 340 },
  { "type": "keypress", "key": "Enter", "ctrlKey": false }
]

// Generated discriminated union
export interface ClickEvent {
  type: 'click';
  x: number;
  y: number;
}

export interface KeypressEvent {
  type: 'keypress';
  key: string;
  ctrlKey: boolean;
}

export type DomEvent = ClickEvent | KeypressEvent;

// Narrowing in application code
function handleEvent(event: DomEvent) {
  if (event.type === 'click') {
    console.log(event.x, event.y); // TypeScript knows these exist
  }
}

Utility Types: Going Further with Generated Interfaces

Once you have a base interface, TypeScript's built-in utility types let you derive related types without duplication:

// Base generated interface
export interface User {
  id: string;
  name: string;
  email: string;
  role: 'admin' | 'user' | 'guest';
  createdAt: string;
}

// Derived types using utility types
type CreateUserDto = Omit<User, 'id' | 'createdAt'>;
type UpdateUserDto = Partial<Pick<User, 'name' | 'email' | 'role'>>;
type UserSummary = Pick<User, 'id' | 'name' | 'role'>;
type ReadonlyUser = Readonly<User>;

This pattern — generate once, derive many — is far more maintainable than maintaining separate interfaces for each use case.

Common Pitfalls to Avoid

• Trusting a single API sample: If a field is missing from your sample, you'll get an incomplete interface. Use the most complete response available, or manually add optional markers after generation.
• Using any as an escape hatch: It defeats the purpose of TypeScript. Use unknown with type guards instead when the shape is genuinely unpredictable.
• Ignoring array item variance: If an array contains objects with different shapes, a naive converter merges them into one interface. Check the output and add discriminated unions if needed.
• Forgetting to update types after API changes: Generated interfaces are a snapshot. Wire them to your CI pipeline or use runtime validators like Zod to catch drift automatically.

Integration with Next.js and React

In a Next.js app, generated interfaces flow naturally through the data layer:

// lib/types.ts — generated from your API response
export interface Post {
  id: string;
  title: string;
  body: string;
  author: { id: string; name: string };
  publishedAt: string;
}

// app/posts/[id]/page.tsx
async function getPost(id: string): Promise<Post> {
  const res = await fetch(`/api/posts/${id}`);
  if (!res.ok) throw new Error('Post not found');
  return res.json() as Promise<Post>;
}

export default async function PostPage({ params }: { params: { id: string } }) {
  const post = await getPost(params.id);
  // post.title, post.author.name — fully typed
  return <article><h1>{post.title}</h1></article>;
}

For extra safety, pair the interface with a Zod schema that validates the fetch response at runtime. TypeScript catches structural errors at compile time; Zod catches them when the actual API response differs from what you expected.

Comparison with Alternatives

quicktype is the most full-featured option and supports many target languages. TypeMorph focuses specifically on TypeScript/Zod and goes deeper on validation inference. json-to-ts is a lightweight npm package suitable for one-off scripts. For projects using GraphQL, codegen from the schema replaces manual interface writing entirely. For OpenAPI/Swagger APIs, tools like openapi-typescript generate types directly from the spec, which is more reliable than inferring from a sample response.

FAQ

Q: How do I handle dynamic or unknown keys?
A: Use an index signature: interface Config { [key: string]: string | number | boolean; }. For more safety, use a Record<string, unknown> and validate the values at runtime.

Q: Should I use interface or type?
A: Both work. Interfaces are open (can be augmented with declaration merging) and slightly better for object shapes. Type aliases are more flexible for unions, intersections, and utility type compositions. The practical difference is small — pick one and be consistent.

Q: How do I handle union types (e.g., a field can be a string or number)?
A: TypeScript handles this directly: id: string | number. A smart converter can infer this if you provide a sample where the field varies across array items.

Q: My JSON has 50+ fields. Should I split it into multiple interfaces?
A: Yes. Flat, monolithic interfaces are hard to reuse. Identify logical sub-objects (e.g., Address, ContactInfo) and extract them. The converter will do this automatically for nested objects.

Q: Can I generate types from a URL directly?
A: TypeMorph works locally in the browser — paste the JSON response from your API, or fetch it with curl and paste the output. The tool also accepts curl commands directly as input.

Q: How do I keep generated types in sync with the API?
A: The most robust approach is to generate from the OpenAPI spec if your API has one. If not, write a Zod schema alongside the TypeScript interface and validate API responses at runtime — mismatches throw errors in development, catching drift early.