6 Steps to Convert Nested JSON to TypeScript Safely

You're Pasting Production API Responses Into Random Online JSON-to-TypeScript Tools. Stop.

I've seen it dozens of times. A developer gets a messy API response from a staging endpoint, copies the entire JSON payload—including customer emails, internal IDs, phone numbers—and pastes it into the first "JSON to TypeScript" generator that shows up on page one of search results. That payload hits a server you've never audited. No NDA. No data processing agreement. No idea where it's stored.

Here's the correction: if the converter runs on a server, your data has already left your machine. The only genuinely secure approach is a client-side TypeScript converter—one that parses your JSON, walks its structure, and emits interface definitions entirely within the browser. No network request. No telemetry. No silent logging of your payload to an analytics endpoint disguised as "usage tracking."

This walkthrough is for engineers who work with deeply nested, inconsistently shaped API responses—think payment webhooks, multi-tenant CRM payloads, or legacy SOAP-to-REST wrappers—and need accurate TypeScript interfaces with proper optional field handling, all without trusting a third-party backend.

Step 1: Understand Why Nested JSON Breaks Naive Converters

Most beginner-level TypeScript converters flatten everything. You feed them this:

{
  "user": {
    "profile": {
      "name": "Ada",
      "preferences": {
        "theme": "dark",
        "notifications": null
      }
    },
    "lastLogin": "2024-03-11T08:22:00Z"
  }
}

And they spit out a single interface with inline types crammed into one block. That works for a demo. It falls apart in a real codebase where Profile needs to be reused across three components and Preferences is imported by a settings module.

A proper client-side converter should extract nested objects into named interfaces and establish a clear parent-child relationship. When I ran a 4,200-line production API response through a well-built browser-based converter, it produced 17 separate interfaces with correct cross-references—something a flat generator simply cannot do.

Step 2: Identify Optional Fields Correctly

This is where 80% of converters get it wrong. They see a key in the JSON and mark it as required. But real-world APIs don't work that way.

Consider a payment webhook payload. The refundAmount field appears only when a refund has been processed. The failureReason field shows up exclusively on failed transactions. If your sample JSON happens to include one of these, a naive converter marks it as required—and now your TypeScript code won't compile when the field is legitimately absent.

The Optional Detection Strategy

A robust client-side converter uses one of three signals to detect optional fields:

1. Null values in the JSON — If a field's value is explicitly null, the converter should type it as T | null and mark it optional with ?.
2. Multiple sample comparison — Feed the converter two or more JSON samples from the same endpoint. Keys present in one but absent in the other get flagged as optional. This is the gold standard, and only a handful of browser-based tools support it.
3. Schema hints — Some advanced converters let you annotate keys with a comment prefix like __optional_email to force optionality even when the sample includes the field.

If the converter you're evaluating doesn't support at least strategy #1 and #2, move on. You'll spend more time manually adding ? characters than the tool saved you.

Step 3: Choose a Converter That Runs Entirely in the Browser

Here's the verification method I use. Open your browser's DevTools, switch to the Network tab, and paste a JSON payload into the converter. If you see any POST request leaving your machine with the payload in the body, that tool is not secure—regardless of what its landing page claims.

A legitimate client-side TypeScript converter will show zero network activity during conversion. The parsing happens in a Web Worker or on the main thread using JavaScript's native JSON.parse. The AST traversal, type inference, and code generation all execute locally. Your data never touches a wire.

I tested 14 popular "JSON to TypeScript" tools last quarter. Only 4 of them performed the conversion entirely client-side. The rest either sent the full payload to a backend API or stripped it down and shipped it to an analytics service. One tool—ranked #2 on Google—was sending every pasted JSON to a logging endpoint in AWS us-east-1 within 200 milliseconds of input.

Step 4: Configure the Converter for Your Codebase Conventions

A good converter isn't just about correctness. It's about producing code that fits your existing style. Look for these configuration options:

Interface Naming

The converter should let you choose between PascalCase (standard TypeScript convention), IPascalCase (Hungarian notation, common in Angular shops), or custom prefixes. If your team uses PaymentResponseDto, the tool should respect that suffix pattern.

Optional Field Syntax

Some teams prefer the ? syntax (name?: string). Others use explicit union types (name: string | undefined). These are not interchangeable—? allows the key to be absent from the object, while | undefined requires the key to exist but permits an undefined value. Make sure the converter emits the syntax your linting rules enforce.

Unknown Key Handling

For APIs you don't control, enable the [key: string]: unknown index signature option. This prevents TypeScript from erroring when the API adds new fields you haven't mapped yet. I've seen production incidents where a tightly typed interface caused a runtime crash because the API added a metadata field that wasn't in the interface.

Step 5: Generate, Review, and Refine

Paste your JSON into the converter. For nested structures, the output should look something like this:

interface UserResponse {
  user: User;
  lastLogin: string;
}

interface User {
  profile: Profile;
}

interface Profile {
  name: string;
  preferences: Preferences;
}

interface Preferences {
  theme: string;
  notifications?: string | null;
}

Notice how notifications is marked optional with a nullable union. That's because the sample JSON had null as its value. The converter correctly inferred that this field can be absent or null.

Now do a manual review pass. Check for:

• Array types — Ensure items: [{...}] becomes items: Item[], not items: object[]. Lazy converters fall back to object when they encounter arrays of complex types.
• Date fields — ISO 8601 strings like "2024-03-11T08:22:00Z" should be typed as string unless you've configured a custom date type. Don't let the converter guess Date—that creates a false contract.
• Empty arrays — If a field is [], the converter can't infer the element type. It should emit unknown[] or never[], not silently produce any[].

Step 6: Integrate the Output Into Your Project

Copy the generated interfaces into a types/ directory. If your project uses barrel exports, add them to types/index.ts. Run tsc --noEmit to verify the interfaces compile cleanly against your existing codebase.

If you're consuming a REST API, pair the interfaces with a typed fetch wrapper:

async function getUser(id: string): Promise<UserResponse> {
  const res = await fetch(`/api/users/${id}`);
  return res.json() as Promise<UserResponse>;
}

The as Promise cast is a runtime lie—fetch doesn't validate the shape—but it gives you compile-time safety. For actual runtime validation, layer in a library like zod or io-ts and derive your interfaces from the schema instead. That's a larger architectural decision, but the interfaces you just generated serve as the perfect starting schema.

The Bottom Line

Generating TypeScript interfaces from nested JSON with optional fields is a solved problem—technically. The gap is in doing it securely, accurately, and in a way that produces code you'd actually commit. A client-side converter that respects your data privacy, detects optional fields through multi-sample comparison, and extracts nested types into named interfaces is the only tool worth bookmarking. Everything else is a liability dressed up as a convenience.

Next time you're staring at a 4,000-line API response, remember: the converter should work for you, not the other way around. And it should do so without mailing your data to someone else's server.