Convert Nested JSON Objects to TypeScript Interfaces

Handling Nested Structures

Real-world JSON is rarely flat. APIs typically return objects inside objects, and each level of nesting maps to a separate TypeScript interface.

Example JSON

{
  "id": 1,
  "name": "Acme Corp",
  "address": {
    "street": "123 Main St",
    "city": "Springfield",
    "geo": {
      "lat": 39.7817,
      "lng": -89.6501
    }
  }
}

Generated TypeScript

interface Geo {
  lat: number;
  lng: number;
}

interface Address {
  street: string;
  city: string;
  geo: Geo;
}

interface Company {
  id: number;
  name: string;
  address: Address;
}

Why Separate Interfaces?

Extracting each nested object into its own interface provides several benefits:

1. Reusability — Geo can be reused anywhere coordinates appear (e.g., store locations, event venues).
2. Readability — A deeply nested inline type like { street: string; city: string; geo: { lat: number; lng: number } } quickly becomes hard to read.
3. Testability — You can write tests and mock data for Address independently of Company.

Naming Conventions

The converter derives interface names from the property key in PascalCase. If two properties at different paths share the same name but different shapes, the converter appends a numeric suffix or nests the name (e.g., UserAddress vs OrderAddress). You should review generated names and rename them to match your domain language.

Depth Limits

Extremely deep nesting (5+ levels) is a code smell. Consider whether the JSON can be redesigned, or flatten intermediate layers into a single interface with dotted-path comments for documentation.