How to Convert JSON to TypeScript Interfaces

The problem with manual interface writing

When you get a new API response, the typical workflow is: look at the JSON, mentally map each field to a TypeScript type, write the interface, realize you missed a nested object, go back and fix it. For a response with 30 fields and 5 levels of nesting, that's 20 minutes of mechanical work before you can write a single line of actual logic.

Manual interfaces also drift from reality. The API adds a field in a new version, you forget to update the interface, and TypeScript silently passes while your runtime code breaks. Generating from an actual payload keeps the types grounded in what the API actually returns.

Basic JSON to TypeScript example

Start with a simple API response:

{
  "id": 42,
  "username": "alice",
  "email": "alice@example.com",
  "createdAt": "2024-01-15T10:30:00Z",
  "active": true
}

A generator produces:

interface Root {
  id: number;
  username: string;
  email: string;
  createdAt: string;
  active: boolean;
}

Straightforward. The interesting cases are where the naive approach fails.

Nested objects

Most real API responses have nested objects. A good generator creates separate interfaces for each nested level rather than inlining everything as any.

{
  "user": {
    "id": 1,
    "name": "Alice"
  },
  "address": {
    "street": "123 Main St",
    "city": "Springfield",
    "zip": "62701"
  }
}

Correct output:

interface Root {
  user: User;
  address: Address;
}

interface User {
  id: number;
  name: string;
}

interface Address {
  street: string;
  city: string;
  zip: string;
}

Arrays and union types

Arrays of a single type are straightforward: string[], number[]. The tricky case is mixed-type arrays.

{
  "tags": ["active", "premium"],
  "scores": [98, 87, 92],
  "mixed": [1, "two", true]
}

Expected output:

interface Root {
  tags: string[];
  scores: number[];
  mixed: (number | string | boolean)[];
}

A naive generator might just produce any[] for mixed arrays. A better one inspects all elements and constructs a union type.

Null handling

This is where most hand-written interfaces go wrong. When a field is nullin the sample JSON, what type should it be?

{
  "userId": 1,
  "deletedAt": null,
  "bio": null
}

A generator that outputs null as the type is technically correct but useless:

// Bad — doesn't tell you what the field actually holds
interface Root {
  userId: number;
  deletedAt: null;
  bio: null;
}

A better approach marks nullable fields with a union:

// Better — acknowledges the field could have a real value
interface Root {
  userId: number;
  deletedAt: string | null;
  bio: string | null;
}

Since the generator can't know the intended type from a null value alone, string | nullis the reasonable default. You'll refine it based on the API docs.

Optional fields

Some generators produce optional fields (field?: Type) when a key is absent in some samples but present in others. This requires comparing multiple samples — something single-payload generators can't do. For a single input, all fields present in the payload should be required; you add ? manually where the API docs say the field is optional.

Arrays of objects

A common pattern: paginated list responses.

{
  "total": 150,
  "page": 1,
  "items": [
    { "id": 1, "name": "Widget A", "price": 9.99 },
    { "id": 2, "name": "Widget B", "price": 14.99 }
  ]
}

Expected output:

interface Root {
  total: number;
  page: number;
  items: Item[];
}

interface Item {
  id: number;
  name: string;
  price: number;
}

The generator should inspect all objects in the array to build a unified interface. If one item has a field that another doesn't, the field should be marked optional.

What to look for in a JSON to TypeScript generator

• Creates named interfaces for nested objects (not inline types)
• Handles mixed-type arrays with proper union types
• Uses string | null (not null) for null values
• Merges fields across array items to produce complete interfaces
• Runs in the browser — no server upload for sensitive API responses
• Handles deeply nested structures without hitting recursion limits