TypeScript Converters: Tame Nested JSON Without Server

You have a proprietary API payload sitting in a terminal buffer. It contains customer names, an email field, a nested profile object and an array of addresses. You want TypeScript interfaces for it, and the fastest route looks like pasting it into an online converter. That paste is the entire risk, and it is the reason the order of operations matters more than the tool you pick.

This is the security-first version of that workflow: how a genuinely client-side converter behaves, how it decides which fields deserve a question mark, and what you still have to fix by hand before the generated types are safe to commit.

The Security Question Comes First, Not Last

Most guides treat privacy as a footnote under "is this tool safe". That is backwards. A JSON-to-TypeScript conversion is a pure transformation with no server-side value: the input is text, the output is text, and nothing about the task requires a network round trip. Any converter that uploads your payload is doing so because it is convenient for the operator, not because the conversion needs it.

That matters because of what is typically inside those payloads. API responses carry personal data, internal identifiers, feature flags that reveal unreleased product plans, and error objects that leak stack traces and service names. A pasted payload is a snapshot of your production database in miniature. Once it reaches a server you do not control, it is in a log you cannot audit, under a retention policy you cannot read.

So the first decision is not which converter to use. It is whether the conversion can happen entirely inside the tab.

What Client-Side Has to Actually Mean

"Client-side" is a claim, not a guarantee. Three things have to be true at the same time before the claim holds.

First, the transforming code must execute in your browser's JavaScript engine. If the page posts your JSON to a URL and renders the response, the work happened on a server, whatever the marketing copy says.

Second, the page must not transmit the payload elsewhere as a side effect. A converter can be fully local and still phone home with analytics payloads that include the input. Check the network activity, not the description.

Third, the result must be reproducible offline. Load the page, disconnect the network, and convert again. If it still works, the logic is local. If it fails, it was never local.

The practical test takes about thirty seconds: open the browser's developer tools, switch to the network panel, paste a payload, and convert. If a request goes out carrying anything resembling your input, close the tab.

The Step-by-Step Secure Conversion Workflow

1. Open the converter and load the page fully before pasting anything, so the conversion logic is already in memory.
2. Paste only the smallest payload that still contains the nesting you care about. Strip unrelated top-level keys first.
3. Redact anything you would not want in a screenshot: real names, real emails, real tokens. Replace them with same-typed placeholders, because the converter infers types from values, not from meaning.
4. Run the conversion and watch the network panel for outbound requests carrying the payload.
5. Copy the generated interfaces out into your editor, not into a shared document.
6. Reload the page before pasting a different payload, so no in-memory state carries over between schemas.

Step three is the one people skip. If you replace a real email with an empty string, the converter infers a string. If you delete the key entirely, it infers nothing and you lose the field. A same-typed placeholder keeps the inference honest and the payload clean.

How the Converter Decides Which Fields Are Optional

The optional-field logic is the most useful thing these tools do, and it is also the most misunderstood. A converter cannot know from a single object whether a field is optional, because a single object either has the key or does not. Optionality only becomes visible when the payload contains an array of objects that disagree.

When the parser walks an array, it collects the union of all keys across the elements. Any key that is present in at least one element but missing from at least one other is marked optional with a question mark. Keys present in every element are required.

That has a direct consequence for what you paste. If your payload contains only one object in the array, optional fields will be invisible and the generated interface will mark everything required. To get useful optional markers, paste a response that includes several real elements from the array, exactly as your API returns them.

The same union logic applies to types, not just presence. If a key holds a string in one element and a number in another, the generated type is a union rather than whichever value happened to come first.

A Worked Example: One Nested Payload, Four Interfaces

Here is the kind of payload that shows every behavior at once. It is a single user record with a null email, a nested profile, and an address array whose second element is missing a field.

{
  "id": 1,
  "name": "Ada Lovelace",
  "email": null,
  "roles": ["admin", "editor"],
  "profile": {
    "theme": "dark",
    "notifications": { "email": true, "sms": false }
  },
  "addresses": [
    { "street": "12 Analytical Way", "city": "London", "zip": "N1" },
    { "street": "9 Engine St", "city": "Paris" }
  ],
  "scores": [98, 85.5, 76],
  "active": true
}

A correct converter produces four interfaces, because two of the nested objects have their own shape.

interface Root {
  id: number;
  name: string;
  email: string | null;
  roles: string[];
  profile: Profile;
  addresses: Address[];
  scores: number[];
  active: boolean;
}

interface Profile {
  theme: string;
  notifications: Notifications;
}

interface Notifications {
  email: boolean;
  sms: boolean;
}

interface Address {
  street: string;
  city: string;
  zip?: string;
}

Read the output carefully and you can see all three inference rules at work. The null email became a union with null instead of a plain string. The two arrays became element-typed arrays rather than untyped ones. And the second address, which has no zip key, is what produced the question mark on zip in the Address interface. Delete that second address and the question mark disappears.

The Three Output Problems You Will Have to Fix by Hand

Generated interfaces are a starting point, not a finished contract. Three problems show up repeatedly.

Fields that should be optional but are not. This is the inverse of the case above. If every element in your pasted array happens to include a key that is optional in production, the converter marks it required and your build breaks on the first real response. Widen the sample, or add the question marks manually.

any and unknown leaking into the output. A value that is an empty array, an empty object, or a key whose value is missing entirely may be typed loosely. Find every any in the generated file and replace it with a concrete type or an explicit unknown that forces a narrowing check at the call site.

Duplicate interface names when two branches collide. If two different nested objects share a property name, the generator may emit two interfaces with the same name, or reuse one where it should have created another. Give each one a distinctive name before you commit.

Hardening the Generated Types Before You Commit Them

Regex-checked environment strings are almost never what you want. Neither is a theme field typed as a bare string when the API only ever returns two values. Tighten the unions the generator could not know about.

type Theme = 'dark' | 'light';

interface Profile {
  theme: Theme;
  notifications: Notifications;
}

After that, run the three checks that catch the real mistakes. Does the file compile with strict mode on? Does it produce an error if you assign an object missing a required key? Does removing an optional key from a test fixture still compile? If all three pass, the interfaces reflect your data rather than the one sample you happened to paste.

When a Browser Converter Is the Wrong Tool

A client-side converter is the right default, but there are cases where it is not enough. If your schema lives in OpenAPI, JSON Schema or a protobuf definition, generate from the schema rather than from a sample payload, because the schema is the contract and the sample is an accident. If the payload is enormous, a browser tab may struggle where a local script in Node would not. And if your organization requires every artifact to pass through a reviewed pipeline, keep the conversion in that pipeline rather than in a tab, even when the tab is safer than the alternative.

The common thread is that the browser converter is the best tool for a sample payload you want to understand quickly. It is not a substitute for a schema you already own.

The Rule to Remember

The conversion itself is a pure text transformation, so there is no reason for your JSON to leave the machine. Paste a sample that actually contains the disagreements your data has, because optional fields and union types only appear when the payload disagrees with itself, then tighten the unions the generator could not infer. Do that and the interfaces you commit will describe your API instead of describing one lucky response.