Generating TypeScript Interfaces From JSON Objects

How Do You Generate TypeScript Interfaces From JSON With Nested Objects Without Losing Your Mind?

You've just received a 200-line JSON response from an API. It has objects inside arrays inside objects. Your deadline is tomorrow. Manually typing out every interface feels like punishment. So—how do you turn that messy nested JSON into clean, accurate TypeScript interfaces without spending hours hunting for missing brackets?

The good news: there are several paths to do this, ranging from quick online converters to fully automated CLI pipelines. The bad news: most tutorials only show flat JSON examples, leaving you stranded when real-world nesting kicks in. Let's fix that.

Why Does Nested JSON Break Most TypeScript Generators?

Flat JSON is easy. A object with name, age, and email maps directly to three fields. But when your JSON looks like this—

{
  "user": {
    "profile": {
      "name": "Alice",
      "addresses": [
        { "street": "123 Main St", "city": "Portland" }
      ]
    }
  }
}

—most naive generators either flatten everything into one giant interface or produce names like RootObjectUserProfileAddressesItem that nobody wants to read.

Nesting introduces three real problems: naming (what do you call the inner interface?), arrays (is it an array of objects or primitives?), and optionality (what if some objects in an array have different keys?). A quality TypeScript JSON converter handles all three.

What's the Manual Approach to Converting Nested JSON?

Sometimes you just need to do it by hand. For small payloads—say, under 50 lines—manual conversion gives you full control over naming and structure.

Step-by-step: Manual Nested Interface Writing

Take this JSON:

{
  "id": 42,
  "metadata": {
    "created": "2024-01-15",
    "tags": ["typescript", "json"]
  }
}

You'd write:

interface Metadata {
  created: string;
  tags: string[];
}

interface RootObject {
  id: number;
  metadata: Metadata;
}

The trick is to work inside-out. Start with the deepest nested object, name it, then reference it in the parent. This prevents you from rewriting outer interfaces when you realize an inner structure needs its own type.

For a 200-line JSON payload with 4 levels of nesting, manual conversion typically takes 25–40 minutes. That's real time you could save.

Which Online Tools Auto-Generate Interfaces From Nested JSON?

Several web-based TypeScript converters handle nested objects well. Here are the ones worth knowing:

json2ts

Paste your JSON, and it generates interfaces with sensible names. It detects nested objects and creates separate interfaces, though naming can sometimes be generic (like Result or Item).

QuickType

Probably the most powerful option. QuickType supports multiple output languages, infers types from multiple JSON samples, and handles deeply nested structures with reasonable naming conventions. You can even customize the root interface name before generating.

Transform Tools

A solid TypeScript JSON converter that lets you toggle between interface and type output, control optional field detection, and even generate JSDoc comments from your JSON values.

For most developers, the workflow is: paste JSON → review generated interfaces → rename inner types to match your domain language → copy into your project.

How Do You Handle Arrays of Nested Objects in TypeScript?

Arrays are where things get interesting. Consider:

{
  "orders": [
    { "id": 1, "items": [{ "sku": "A1", "qty": 2 }] },
    { "id": 2, "items": [{ "sku": "B2", "qty": 1 }] }
  ]
}

The correct TypeScript output should be:

interface Item {
  sku: string;
  qty: number;
}

interface Order {
  id: number;
  items: Item[];
}

interface RootObject {
  orders: Order[];
}

Notice that items becomes Item[], not Array<Item> or any[]. Good converters detect the array element shape and extract it into its own interface. Poor ones just emit any[] or object[], which defeats the purpose of TypeScript.

If array elements have inconsistent shapes—some objects have a discount field, others don't—you need union types or optional fields. QuickType handles this by merging all observed keys and marking absent ones as optional. Manual conversion requires you to inspect every array element, which is tedious but more precise.

What About Optional Fields and Null Values in Nested JSON?

Real APIs return inconsistent data. One response includes "middleName": null, another omits the key entirely. How should your interfaces reflect that?

TypeScript distinguishes between three states:

• field: string — always present, always a string
• field?: string — may be absent
• field: string | null — present but can be null

Most online converters add ? when a key appears in some array elements but not others. Fewer handle null correctly—they often type the field as any or just null instead of string | null.

If your JSON has null values, check the generated output carefully. You may need to manually adjust middleName: any to middleName: string | null.

Can You Automate This in Your Build Pipeline?

Absolutely. If you're consuming a stable API, generating interfaces once and pasting them into your codebase is fine. But if the API schema changes frequently, you want automation.

Using QuickType CLI

Install it globally:

npm install -g quicktype

Then generate interfaces from a JSON file:

quicktype --src-lang json --lang typescript --top-level Root --src ./api-response.json -o ./types.ts

This reads your JSON, detects nested structures, and writes a types.ts file. You can wire this into a pre-build script so interfaces regenerate whenever your sample JSON updates.

From OpenAPI / Swagger Specs

If the API publishes an OpenAPI spec, skip JSON entirely. Tools like openapi-typescript generate interfaces directly from the spec, which is more reliable than inferring types from a single response sample. One spec can produce 500+ lines of accurate, nested TypeScript interfaces in under 2 seconds.

What Naming Conventions Should Generated Interfaces Follow?

This is the underrated part. Auto-generated names like RootObject or InlineResponse200 make your codebase unreadable. After generation, always rename:

• RootObject → something meaningful like ApiResponse or UserDto
• Item → the singular form of its parent array (e.g., OrderItem)
• Generic names like Result → domain-specific names

Some converters let you set a custom root name before generating. Others require post-generation renaming. Either way, budget 5–10 minutes for cleanup. Your future self will thank you.

Final Thoughts: Pick the Right Tool for Your Nesting Depth

For shallow JSON (1–2 levels of nesting), any online converter works fine. For deep nesting (3+ levels) with arrays, optional fields, and null values, QuickType is your best bet. For ongoing projects with evolving APIs, automate with the CLI or switch to OpenAPI-based generation.

The goal isn't just to generate TypeScript interfaces—it's to generate ones that actually help you catch bugs at compile time. Nested objects are where TypeScript's type system shines, but only if your interfaces accurately reflect the JSON structure. Take the extra minute to verify array types, optionality, and naming. It pays off the first time the compiler catches a mismatched field name before runtime.