Hand-Written vs Generated TypeScript Interfaces

Two Developers, One Monster API Response

Picture this. Two frontend developers sit at adjacent desks. Both receive the same 47-level-deep JSON payload from a legacy e-commerce API that nobody on the backend team wants to touch. Developer A cracks their knuckles and starts hand-typing TypeScript interfaces. Three hours later, they're on field 212, they've misspelled cattegory twice, and their eyes have glazed over like a donut left in the rain. Developer B pastes the same JSON into a secure client-side TypeScript converter, clicks once, and gets fully typed interfaces with optional fields correctly flagged in under 800 milliseconds. Developer B then goes to get a coffee. Developer A does not get a coffee.

That gap — between 3 hours and 0.8 seconds — is what this article is about. Specifically, it's about how to generate TypeScript interfaces for deeply nested JSON with optional fields without sending your data to some random server across the internet. We're going to walk through this from the ground up, because understanding *why* a good converter behaves the way it does matters just as much as knowing which button to click.

Hand-Written Interfaces vs Generated Types: Where Humans Break

Let's be honest. Hand-writing TypeScript interfaces for shallow JSON is fine. A user object with name, email, and id? You can knock that out in 20 seconds. But the moment you're staring at a payload where a product contains an inventory that contains a warehouse that contains a metadata object with 14 keys, half of which might not exist — your human brain starts making mistakes.

The Manual Approach: What Goes Wrong

Here's what typically happens when you hand-write interfaces for nested JSON with optional fields:

You forget a question mark. You mark discount as required when the API only returns it 30% of the time. You nest an interface inside an interface inside an interface until your indentation is so deep you need a periscope to read it. You lose track of which type belongs to which parent. And when the backend team quietly adds a new field to the fourth nesting level? You don't find out until production breaks.

The Converter Approach: What Goes Right

A well-built TypeScript converter scans the entire JSON structure recursively. It identifies every object, every array, every primitive. It detects which fields appear consistently across multiple samples and which ones are sporadic — marking the sporadic ones as optional with the ? modifier. It names nested interfaces sensibly, based on parent key names, so you get ProductInventory instead of InlineType47. And it does all of this without you having to think about it.

The difference isn't just speed. It's reliability. A converter doesn't get tired at field 200. It doesn't misspell things. It doesn't forget question marks.

Shallow JSON vs Deeply Nested JSON: Why Nesting Changes Everything

Let's talk about depth, because this is where most generic TypeScript converter articles wave their hands and say "it handles nesting" without explaining what that actually means.

Shallow JSON: The Easy Case

Shallow JSON — say, 2 or 3 levels deep — is straightforward. You have a root object, maybe a couple of nested objects, and that's it. Most online TypeScript generators handle this fine. Even the bad ones. Even the one your coworker built in 2019 and never maintained.

Deeply Nested JSON: Where Cheap Converters Collapse

Real-world APIs don't stay shallow. A typical enterprise response from a CMS, e-commerce platform, or legacy REST API can easily nest 10, 15, even 20 levels deep. At that depth, you encounter several problems that separate good converters from toy tools:

Name collisions. If three different objects in your JSON have a metadata field, a naive converter will generate three interfaces all named Metadata. A good converter prefixes them by parent: ProductMetadata, UserMetadata, OrderMetadata.

Array inference. When a converter hits an array, it needs to peek inside and infer the element type. If the array is empty (which happens — APIs return [] when there's no data), a poor converter gives up and types it as any[]. A robust one looks at the array's key name and makes a reasonable guess, or at least types it as unknown[] so you're forced to handle it explicitly.

Circular references. Some JSON payloads contain circular structures, especially when they've been serialized from ORM-backed objects. A converter that doesn't detect cycles will either crash or generate infinitely recursive interfaces. The good ones detect cycles and break them with a type reference.

These are not edge cases. If you work with real APIs long enough, you hit all three.

Required Fields vs Optional Fields: The Question Mark Problem

This is the part where most developers get tripped up, and it's the part where a thoughtful TypeScript converter earns its keep.

The Wrong Way: Everything Required

Most basic converters look at a single JSON sample and assume every field they see is required. This is catastrophically wrong. If your JSON sample happens to include a middleName field, the converter marks it as required — even though 85% of your users don't have a middle name on file. Now your TypeScript code thinks middleName always exists, and when it doesn't, you get a runtime error that your type system promised wouldn't happen.

The entire point of TypeScript is to catch errors at compile time. If your generated types lie about which fields exist, your type system is working against you.

The Right Way: Statistical Optionality Detection

A sophisticated converter doesn't just look at one sample. It lets you paste multiple JSON samples — or it remembers samples across sessions — and compares them. If a field appears in 3 out of 5 samples, it's marked optional. If it appears in 5 out of 5, it's required. If it appears in 1 out of 5, it's still marked optional, but the converter might flag it with a comment like // Present in 20% of samples so you know to investigate.

Even with a single sample, a good converter applies heuristics. Fields with names like error, fallback, optionalData, or deprecatedField get the question mark by default. Fields that are clearly part of the core object identity — id, type, name — stay required. It's not perfect, but it's dramatically better than marking everything required and hoping for the best.

Server-Side Conversion vs Client-Side Security

Now we need to talk about where the conversion happens, because this matters more than most developers realize.

Server-Side Converters: The Privacy Problem

Many popular JSON-to-TypeScript tools operate server-side. You paste your JSON into a text box, it gets sent to a server, the server processes it, and sends back the generated interfaces. This is fast. This is convenient. This is also a potential disaster if your JSON contains real user data, API keys, internal system names, or proprietary business logic.

That 47-level JSON payload from your e-commerce API? It probably contains customer email addresses, order totals, internal warehouse codes, and product margins. Do you want to send that to a server you don't control? Do you want to be the person who explains to your compliance team why customer data was pasted into a random online tool?

Client-Side Converters: The Secure Alternative

A secure client-side TypeScript converter runs entirely in your browser. The JSON you paste never leaves your machine. No server processes it. No network request transmits it. The conversion happens in JavaScript, in your local browser tab, and the result is generated right there on your screen.

This is not a minor feature. For anyone working with real production data — which is, frankly, anyone who actually needs a TypeScript converter for deeply nested JSON — client-side processing is non-negotiable. The 0.8 seconds it takes to convert a complex payload is 0.8 seconds of local CPU time, not 0.8 seconds of data traveling across the internet to a server you can't audit.

How to Verify a Converter Is Truly Client-Side

Don't just take a tool's word for it. Open your browser's DevTools, go to the Network tab, paste a JSON payload, and watch. If you see a POST request fire off to an external server, it's not client-side. If the only network activity is the initial page load, you're safe. This takes 10 seconds to check and saves you from potential data exposure.

Quick Hacks vs Production-Ready Types

Finally, let's contrast what a quick-and-dirty conversion looks like versus what you actually need for a production codebase.

The Quick Hack: any Everywhere

The fastest way to "convert" JSON to TypeScript is to slap any on every field and call it a day. This technically gives you a TypeScript file. It also gives you zero type safety, zero autocomplete, and zero reason to be using TypeScript in the first place. It's the equivalent of buying a gym membership and using it exclusively to buy protein bars from the vending machine.

The Production Approach: Precise, Named, Optional-Aware

A production-ready converter gives you:

- Named interfaces for every nested object, with names derived from parent keys - Proper array typing with inferred element types - Optional fields marked with ? based on actual data analysis - Union types for fields that accept multiple value types (like a price that's sometimes a number and sometimes a string) - null vs undefined distinction where it matters - Exported types you can import directly into your codebase

When you paste a deeply nested JSON payload into a quality converter and get back types that look like they were written by a senior developer who actually cares — that's when you know you're using the right tool.

The Bottom Line

The gap between hand-writing TypeScript interfaces for nested JSON and using a proper converter isn't just about saving time. It's about correctness, security, and maintainability. Hand-written types have human errors. Server-side converters have privacy risks. Cheap converters produce types that lie about optionality.

A secure client-side converter that handles deep nesting, detects optional fields intelligently, and names types clearly is the difference between Developer A (no coffee, misspelled fields, broken production) and Developer B (coffee, correct types, afternoon free). Be Developer B. Your future self, your codebase, and your compliance team will all thank you.