How to Convert JSON to TypeScript Interfaces

To convert JSON into TypeScript, infer a type for every value: strings become string, numbers number, booleans boolean, arrays T[], and each nested object becomes its own named interface. Paste a JSON object into a JSON-to-TypeScript generator and it walks the structure and writes the interfaces for you — including optional keys and unions where an array’s objects differ. It’s the fastest way to get typed models for an API response.

Why hand-typing API responses is a losing game

Writing interfaces by hand for a real API response is slow and error-prone. A single endpoint can return dozens of fields, several levels of nesting, and arrays whose elements do not all share the same keys. Miss one optional field and TypeScript will happily let an undefined slip through until it crashes at runtime. Inference from a concrete sample removes the guesswork: the shape you paste is the contract, so the generated types match the data exactly rather than matching what you remembered the data to be.

JSON has only six value kinds — string, number, boolean, null, array, and object — and TypeScript has a natural home for each. That small, fixed mapping is what makes reliable automatic conversion possible.

How the conversion works

A generator parses your JSON and walks it recursively, choosing a TypeScript type for each value. The core rules are a direct one-to-one mapping:

JSON value	Example	TypeScript type
String	"Ada"	string
Number (int or float)	42, 3.14	number
Boolean	true	boolean
Null	null	null
Array of one type	["x", "y"]	string[]
Array of objects	[{…}, {…}]	Thing[] + a Thing interface
Object	{ "kind": "cat" }	a new named interface, referenced by field

Note that JSON has no integer/float distinction and no date type: 42 and 3.14 both become number, and an ISO date string like "2026-08-23" becomes plain string — TypeScript cannot tell a date from any other string at the type level, so you narrow those by hand if it matters.

So this JSON:

{ "id": 1, "name": "Ada", "active": true, "tags": ["x"], "pet": { "kind": "cat" } }

becomes:

interface Root {
  id: number;
  name: string;
  active: boolean;
  tags: string[];
  pet: Pet;
}

interface Pet {
  kind: string;
}

Optional keys and unions

When your JSON is an array of objects, the generator merges their shapes:

• A key present in only some elements becomes optional (gift?: boolean).
• A key that appears with different types becomes a union (id: string | number).

[{ "sku": "X1", "qty": 2 }, { "sku": "X2", "qty": 3, "gift": true }]

interface Order {
  sku: string;
  qty: number;
  gift?: boolean;
}

This is exactly what you want for real API data, where optional fields are common.

A fuller worked example

Real responses nest arrays inside objects inside arrays. Take a small order payload:

{
  "orderId": "A-1001",
  "customer": { "name": "Ada", "vip": true },
  "items": [
    { "sku": "X1", "qty": 2 },
    { "sku": "X2", "qty": 1, "giftWrap": true }
  ]
}

A generator produces a named interface for every distinct object shape and wires them together:

interface Root {
  orderId: string;
  customer: Customer;
  items: Item[];
}

interface Customer {
  name: string;
  vip: boolean;
}

interface Item {
  sku: string;
  qty: number;
  giftWrap?: boolean;
}

Notice three things at once: customer became its own Customer interface, items became Item[] from a single merged Item shape, and giftWrap is optional because it appears in only one of the two items. That is the whole value of inference in one example — you would have had to spot the missing key yourself.

interface vs type alias

Most generators let you emit either an interface or a type alias, and for a plain object shape the two are interchangeable. The differences only matter at the edges:

Aspect	interface	type alias
Object shapes	Yes	Yes
Declaration merging	Supported	Not supported
Unions / intersections at top level	No	Yes (type Id = string | number)
Extending	extends	& intersection

A common convention is to prefer interface for object models and reach for type when you need a union, a tuple, or a mapped type. Pick whichever matches your codebase’s existing style — consistency matters more than the choice itself.

The limits of inference

Types are only as good as the sample you paste:

• A field whose only value is null is typed null — widen it by hand if it can hold other values.
• Empty arrays become any[], since there’s no element to infer from.
• The generator can’t know about fields that never appear in your sample.

Treat the output as a strong starting point, then adjust nullable and union types to match the real API contract.

A practical habit: paste the largest, most complete sample you have — ideally one that exercises optional fields and every variant. The more the sample resembles the full range of real responses, the fewer manual fixes you make afterward. If your API documents nullable fields, reconcile the generated null types against that documentation rather than trusting a single lucky response.

Do it privately

API responses can contain sensitive data — tokens, personal details, internal IDs. A browser-based JSON-to-TypeScript tool does the inference locally in your browser, so the JSON you paste is never uploaded to a server. You can also switch the output between interface and type aliases to match your codebase’s style.

FAQ

How do I convert JSON to a TypeScript interface? Paste your JSON into a generator and it infers an interface for it, breaking nested objects into their own named interfaces. Copy the result into your .ts file.

Does it detect optional and union types? Yes. In an array of objects, a key missing from some elements is marked optional (?), and a key that appears with different value types becomes a union like string | number.

Can I get type aliases instead of interface? Yes — most generators (including this one) let you switch the output to type X = { … } instead of interface X { … }. Both describe the same shape.

Why is a field typed null or any? A field whose only sample value is null is typed null — widen it manually if it can hold other values. Empty arrays become any[] because there’s nothing to infer the element type from.

Is it safe to paste a real API response? With a browser-based tool, yes — the JSON is parsed locally and never uploaded, so even responses containing tokens or personal data stay on your device.

Does it handle deeply nested JSON? Yes. The generator recurses through nested objects and arrays, creating a named interface for each object shape and referencing them, so even complex structures produce clean, reusable types.