Safely Convert Nested JSON Objects to TypeScript Types

Blind Faith vs. Informed Conversion: How I Stopped Trusting JSON Converters With My TypeScript

Last March, I was building a client-side dashboard for a logistics company. The API we were consuming came from a third-party route-optimization service, and the JSON responses were, to put it diplomatically, organic. I'm talking 47 top-level fields, six levels of nesting in some branches, and optional fields scattered throughout like landmines.

My first instinct was to paste the whole JSON blob into the first JSON to TypeScript converter I found online. It spat out interfaces. I pasted them into my types.ts file. TypeScript was happy. I was happy.

Then production happened.

A shipment object came back without its estimatedArrival field. My interface said that field was required. The runtime said otherwise. The dashboard crashed on a Tuesday afternoon, and I spent three hours explaining to a very calm but very disappointed engineering manager why our "type-safe" application couldn't handle a missing field.

That was the day I learned there's a massive difference between converting JSON to TypeScript interfaces and converting them safely. Let me walk you through what changed in my approach, contrasted section by section with what I used to do wrong.

Flat Assumptions vs. Nested Reality

The Wrong Way: Treating Nested Objects as Afterthoughts

Here's what the naive conversion looked like for a route segment from that API:

interface RouteSegment {
  id: string;
  origin: any;
  destination: any;
  waypoints: any[];
  metadata: any;
}

The online TypeScript interface generator I used had encountered nested objects it couldn't cleanly resolve and just defaulted to any. This is shockingly common. Many client-side converters choke on deeply nested JSON because they either flatten everything into dot-notation type names or give up and assign any.

The problem? any isn't a type. It's a surrender. Once you introduce any into your interface, TypeScript stops protecting you in that entire subtree. You might as well be writing JavaScript at that point.

The Right Way: Extracting Nested Interfaces Deliberately

What I do now is manually trace the nesting before I even open a converter. I sketch the tree structure on paper or in a comment block. Then I generate or write each level as its own named interface:

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

interface Waypoint {
  position: Coordinates;
  label: string;
  sequence: number;
}

interface RouteSegment {
  id: string;
  origin: Coordinates;
  destination: Coordinates;
  waypoints: Waypoint[];
  metadata: Record<string, unknown>;
}

Notice the difference. Each nested object becomes its own interface with a meaningful name. The metadata field, which was genuinely a grab-bag of keys I couldn't predict, gets Record<string, unknown> instead of any. That tiny change means TypeScript still warns me when I try to access metadata.someField without narrowing it first.

The contrast here is philosophical: naive converters flatten complexity; safe converters name it. When you name a nested structure, you make it legible to the next developer who reads your code. You also make it reusable, because that Coordinates interface almost certainly shows up in other API responses too.

Required by Default vs. Optional by Evidence

The Wrong Way: Assuming Every Field in the Sample JSON Is Always Present

This was the exact mistake that crashed the dashboard. The JSON sample I pasted into the converter had estimatedArrival populated, so the converter marked it as a required string. But the API documentation, which I didn't read carefully enough, clearly stated that this field is only returned once a route has been confirmed by the driver.

Here's the thing about optional fields in TypeScript interfaces: a single API response sample is not evidence of a field's guaranteed presence. It's evidence that the field can exist. Those are very different claims.

Most online JSON-to-TypeScript tools operate on a single sample. They see a key in the JSON, they mark it required. They don't see a key, they either omit it or mark it optional. Neither behavior tells you what the API contract actually promises.

The Right Way: Cross-Referencing Multiple Samples and API Docs

My current workflow for determining optionality looks like this:

First, I capture at least three different API responses, ideally from different scenarios (empty result, partial result, full result). I compare the key sets across all three. Any key that appears in some responses but not others gets the ? modifier:

interface Shipment {
  id: string;
  status: 'pending' | 'confirmed' | 'in_transit' | 'delivered';
  route: RouteSegment;
  estimatedArrival?: string;
  actualArrival?: string;
  driverNotes?: string;
  incidentReports?: IncidentReport[];
}

Second, I check the API documentation for explicit statements about conditional fields. The docs for our logistics API, for instance, specified that incidentReports is only included when the status is in_transit or delivered. That's an optional field, full stop.

Third, for fields where I genuinely can't determine optionality, I default to optional. This is the safer assumption. A required field marked optional produces a TypeScript warning that's easy to catch. An optional field marked required produces a runtime crash that's easy to miss until production.

The math here is simple. I tracked it after the dashboard incident: across 47 top-level fields and roughly 120 nested fields in that API's response shape, 34 fields were genuinely optional. The converter I originally used marked exactly zero of them as optional. That's a 34-field surface area for runtime crashes, and I only needed one to take down the dashboard.

Trusting the Converter Blindly vs. Validating the Shape at Runtime

The Wrong Way: Assuming TypeScript Types Are Enforced at Runtime

Here's a hard truth that took me too long to internalize: TypeScript interfaces do not exist at runtime. They're compile-time constructs. When your application receives JSON from an API, TypeScript isn't standing at the door checking IDs. Whatever the API sends, your code receives, and your code will happily try to use it according to the interface you declared, even if the actual data looks nothing like it.

This means that even a perfectly crafted interface with correctly marked optional fields and properly typed nested objects can't protect you if the API changes its response shape. And APIs change. Frequently. Often without warning.

The Right Way: Layering Runtime Validation on Top of Static Types

The approach I use now combines static TypeScript interfaces with lightweight runtime validation. On the client side, I run the incoming JSON through a validation step before trusting it. I don't use a heavy library for this, a simple function is often enough:

function isShipment(value: unknown): value is Shipment {
  if (typeof value !== 'object' || value === null) return false;
  const obj = value as Record<string, unknown>;
  return typeof obj.id === 'string' &&
         typeof obj.status === 'string' &&
         ['pending', 'confirmed', 'in_transit', 'delivered']
           .includes(obj.status as string) &&
         typeof obj.route === 'object';
}

This type guard acts as a bridge between the untyped JSON world and your carefully constructed TypeScript interfaces. If the validation passes, TypeScript narrows the type and you get full IDE support. If it fails, you can handle the error gracefully instead of letting a missing field propagate through your render pipeline until something explodes.

The contrast is stark: static types alone are a suggestion; static types plus runtime validation are a guarantee. The validation function takes maybe ten minutes to write per major response type. The dashboard crash took three hours to debug, plus the reputational cost of explaining it in a postmortem meeting.

One-Shot Conversion vs. Iterative Refinement

The Wrong Way: Generating Interfaces Once and Never Touching Them

When I used a JSON to TypeScript converter as a one-shot tool, I treated the output as finished code. I pasted it, imported it, and moved on. The interfaces fossilized. Three months later, when the API added a new field to its response, nobody updated the interface. Six months later, when the API changed a field from string to string | null, the interface still said string. The types drifted from reality, and the drift was invisible until something broke.

The Right Way: Treating Interfaces as Living Documents

Now I treat interface files as living documents that evolve alongside the API. My team has a simple rule: any time we encounter a field in the API response that isn't in our interface, we update the interface within the same PR. We also periodically run a diff check, capturing a fresh API response and comparing its keys against our declared interfaces.

This iterative approach means our TypeScript types stay honest. They reflect what the API actually returns today, not what it returned six months ago when someone first ran the converter.

The practical setup looks like this: we have a types/ directory with one file per API resource. Each file has a comment at the top noting the last verified date and the API version. When someone touches a resource, they check the date. If it's older than our API release cycle, they re-verify. It's not automated, and it's not fancy, but it catches drift before it catches us.

The Lesson That Actually Stuck

If I had to distill the whole experience into one contrast, it's this: converting JSON to TypeScript interfaces is not a mechanical task, it's an act of interpretation.

The mechanical approach, paste JSON into a converter, paste output into your codebase, treats the converter as an authority. It assumes the sample JSON perfectly represents the API contract. It assumes all fields are always present. It assumes nested objects don't need names. It assumes static types are enforced at runtime. Every one of those assumptions is wrong, and each one is a potential production incident.

The interpretive approach treats the converter as a starting point. You generate a first draft, then you refine it by cross-referencing multiple API responses, reading the documentation, naming nested structures, marking optional fields conservatively, and layering runtime validation on top. The converter saves you typing time. Your judgment saves you debugging time.

That dashboard I mentioned? It's been running for over a year now. We've had API changes, new fields added, fields deprecated, response shapes restructured. Zero crashes from type mismatches. The interfaces aren't perfect, and they never will be, but they're honest. They reflect what we know, they mark what we don't, and they fail loudly when reality doesn't match expectation.

That's what safe client-side JSON to TypeScript conversion actually looks like. Not a single tool, but a workflow. Not a one-time paste, but an ongoing conversation between your types, your runtime, and the API you're trying to understand.