Skip to main content
ponderloop

JSON to TypeScript Interface Generator

Paste JSON and get TypeScript interfaces straight away: nested objects become named interfaces, arrays of objects are merged into one interface with ? on the keys that are missing from some elements, and null, mixed arrays and empty arrays get the types you would write by hand. The example JSON becomes 4 interfaces with 20 properties, 2 of them optional: the orders are merged into one Order interface, gift and note get ? because only some orders and items have them, coupon is string | null, billing and shipping share one interface, and the mixed scores array is typed as a union. Choose interface or type, readonly, export and the root name, and copy or download the result. Errors show the exact line and column. Everything runs in your browser, so the JSON never leaves it.

Updated Runs in your browser: nothing you enter is uploadedHow this tool works

Stays in your browser

Replace the example: paste or type any JSON value. The result updates as you type. Up to 2,000,000 characters.

Your data is converted on this device and never uploaded. It is not saved either: reload the page and it is gone.

Options

Result

Generated 4 interfaces with 20 properties (2 optional).

  • “shipping” has the same shape as Billing, so it reuses that type.

Counts

Object types
4
Properties
20
Optional
2
Lines
31

How JSON values become TypeScript types

Each value is the value of one key; the type is what the generator writes for that property.
JSON valueTypeScript typeRule
"Ada"stringAny string.
42numberEvery JSON number is a number, whole or not.
-2.5e3numberExponents and signs do not change it.
truebooleantrue and false are both boolean.
nullnullA key that is only ever null is typed null.
[]unknown[]An empty array tells nothing about its elements.
[1, 2, 3]number[]All elements share one type.
[1, "a", true](string | number | boolean)[]Mixed elements become a union, always written in the order string, number, boolean.
[1, null](number | null)[]null joins the union last.
[[1], [2, 3]]number[][]Arrays of arrays nest.
[[], ["a"]]string[][]An empty array adds nothing when another array has elements.
{}Record<string, unknown>An object with no keys has nothing to name.

How arrays of objects are merged

The input is the root of the JSON; the result is shown with the defaults and without export.
CaseInputTypeScriptRule
A key missing from some elements[{"id":1,"name":"a"},{"id":2}]type Root = RootItem[]; ⏎ interface RootItem { ⏎ id: number; ⏎ name?: string; ⏎ }The key becomes optional.
A key that is sometimes null[{"id":1,"email":null},{"id":2,"email":"a@example.com"}]type Root = RootItem[]; ⏎ interface RootItem { ⏎ id: number; ⏎ email: string | null; ⏎ }Its type gets | null; it stays required because it is always present.
A key with different types[{"v":1},{"v":"x"},{"v":[true]}]type Root = RootItem[]; ⏎ interface RootItem { ⏎ v: string | number | boolean[]; ⏎ }The types are joined in a union.
Objects inside the objects[{"geo":{"lat":1}},{"geo":{"lat":2,"lng":3}}]type Root = RootItem[]; ⏎ interface RootItem { ⏎ geo: Geo; ⏎ } ⏎ interface Geo { ⏎ lat: number; ⏎ lng?: number; ⏎ }Nested objects are merged the same way, so geo has an optional lng.
Objects mixed with plain values[1,{"a":1}]type Root = (number | RootItem)[]; ⏎ interface RootItem { ⏎ a: number; ⏎ }The objects merge into one interface and the union keeps the number.

How keys become names

Each input is an object holding that key; the result is what the generator writes.
KeyInputTypeScriptRule
user_profile{"user_profile":{"id":1}}interface Root { ⏎ user_profile: UserProfile; ⏎ } ⏎ interface UserProfile { ⏎ id: number; ⏎ }Snake case, kebab case and camel case all give PascalCase.
userProfile{"userProfile":{"id":1}}interface Root { ⏎ userProfile: UserProfile; ⏎ } ⏎ interface UserProfile { ⏎ id: number; ⏎ }The property keeps your spelling; only the type name changes.
users (array){"users":[{"id":1}]}interface Root { ⏎ users: User[]; ⏎ } ⏎ interface User { ⏎ id: number; ⏎ }The elements of an array are named from the singular of the key (a simple English rule that can be turned off).
categories (array){"categories":[{"id":1}]}interface Root { ⏎ categories: Category[]; ⏎ } ⏎ interface Category { ⏎ id: number; ⏎ }ies becomes y.
first-name{"first-name":"Ada"}interface Root { ⏎ "first-name": string; ⏎ }A key that is not a valid identifier is written in double quotes.
2fa{"2fa":{"on":true}}interface Root { ⏎ "2fa": _2fa; ⏎ } ⏎ interface _2fa { ⏎ on: boolean; ⏎ }A type name cannot start with a digit, so an underscore is added.
date{"date":{"day":1}}interface Root { ⏎ date: DateData; ⏎ } ⏎ interface DateData { ⏎ day: number; ⏎ }A name that clashes with a built-in type gets Data added.
item (twice){"a":{"item":{"x":1}},"b":{"item":{"y":1}}}interface Root { ⏎ a: A; ⏎ b: B; ⏎ } ⏎ interface A { ⏎ item: Item; ⏎ } ⏎ interface Item { ⏎ x: number; ⏎ } ⏎ interface B { ⏎ item: BItem; ⏎ } ⏎ interface BItem { ⏎ y: number; ⏎ }Two different shapes with one name: the second gets its parent in front.

Objects with the same shape share one interface

Key order does not matter, but every key, its type and whether it is optional must match.
InputTypeScript
{"billing":{"street":"a","city":"b"},"shipping":{"city":"c","street":"d"}}interface Root { ⏎ billing: Billing; ⏎ shipping: Billing; ⏎ } ⏎ interface Billing { ⏎ street: string; ⏎ city: string; ⏎ }

What each option changes

The same input every time: {"id":1,"tags":["a"],"owner":{"name":"x"}}
OptionTypeScriptEffect
Defaults (interface)interface Root { ⏎ id: number; ⏎ tags: string[]; ⏎ owner: Owner; ⏎ } ⏎ interface Owner { ⏎ name: string; ⏎ }One interface per object, properties separated by semicolons.
type instead of interfacetype Root = { ⏎ id: number; ⏎ tags: string[]; ⏎ owner: Owner; ⏎ }; ⏎ type Owner = { ⏎ name: string; ⏎ };The same shapes as type aliases of object types.
readonlyinterface Root { ⏎ readonly id: number; ⏎ readonly tags: readonly string[]; ⏎ readonly owner: Owner; ⏎ } ⏎ interface Owner { ⏎ readonly name: string; ⏎ }Every property and array is readonly, for data you do not mean to change.
Root name “Person”interface Person { ⏎ id: number; ⏎ tags: string[]; ⏎ owner: Owner; ⏎ } ⏎ interface Owner { ⏎ name: string; ⏎ }Renames the top-level type; the others keep their key names.
exportexport interface Root { ⏎ id: number; ⏎ tags: string[]; ⏎ owner: Owner; ⏎ } ⏎ export interface Owner { ⏎ name: string; ⏎ }Puts export in front of every declaration, so the file can be imported.

How errors are reported

The line and column count characters from 1, as in a text editor, and are the same as on the JSON formatter.
InputPositionMessage
{"a": 1,}line 1, column 8Trailing comma before “}”. JSON does not allow a comma after the last property.
{"a" 1}line 1, column 6Unexpected “1”. Expected “:” after the property name.
[1, 2 ⏎ 3]line 2, column 2Unexpected “3”. Expected “,” or “]”.

How to generate TypeScript interfaces from JSON

  1. Paste your JSON. Replace the example with an API response, a config file or any JSON value. A sample with the same keys is enough; the types depend on the shape, not the size.
  2. Name the root type. Type the name you want for the top-level type, for example ApiResponse. The others are named after their keys.
  3. Choose the style. Pick interface or type, and tick readonly or export if you need them. The result updates as you change an option.
  4. Check the result. Look for ? on keys that may be missing and for unions on keys with several types. If your sample did not include a case (a key that is sometimes absent, a value that can be null), add it to the JSON first.
  5. Copy or download. Copy the types into your project or download them as types.ts. Nothing is uploaded.

Frequently asked questions

How do I convert JSON to TypeScript interfaces?
Paste the JSON into the box above and copy the result. Each object becomes an interface named after its key, each array becomes a list type such as Order[], and strings, numbers and booleans become string, number and boolean. Choose interface or type and the root name in Options.
How does it decide which properties are optional?
When an array holds several objects, they are merged into one interface, and a key that is missing from at least one of them gets a question mark. A key that is present everywhere stays required, even when its value is null in some of them: that adds | null instead. A single object has no missing keys, so everything in it is required.
How is null handled?
A value that is null in some places and something else in others becomes a union with null, for example string | null. A key that is null in every place you gave it is typed null, because nothing else is known about it: add a sample with a real value to get the full type.
What happens with arrays of different types, and with empty arrays?
An array of mixed values becomes a union, written in a fixed order (string, number, boolean, objects, arrays, null): (string | number | null)[]. All objects in it are merged into one interface. An empty array gives unknown[], since there is nothing to infer from; if another array at the same place has elements, their type is used.
Why do two keys use the same interface?
Objects with exactly the same keys, types and optional keys are described by one interface, so billing and shipping in the example both use Billing. The name comes from the first key that was seen, and a note under the result says when a later key reuses it. If you would rather keep them apart, give one of them a different key in your sample.
How are keys that are not valid identifiers written?
A key such as first-name, 123 or an empty string cannot be written bare, so the property name is put in double quotes: "first-name": string. Keys that are valid identifiers, including reserved words like class and non-English letters, are written as they are. Type names are made from keys in PascalCase, with an underscore in front when a name would start with a digit.
Should I use interface or type?
For plain data shapes they behave the same. Interfaces can be extended and merged with another declaration of the same name, and they show up under their own name in error messages; type aliases can also name unions and tuples. The generated types only use features both support, so pick the style your project uses.
Does the type check the JSON when my program runs?
No. TypeScript types are erased when the code is compiled, so an interface cannot reject bad data at run time. It lets the compiler check the code that uses the data. To check data that comes from outside your program, validate it with a schema library or write a type guard, and use the generated types as the starting point.
Is one JSON sample enough?
It shows what the sample contains and nothing else. A key that is present in every element of the sample is typed as required even if the real API sometimes leaves it out, and a field that was always a number is typed number even if it can also be a string. Paste several records, or add the unusual ones, so that the union and optional keys appear.
What about dates and large numbers?
JSON has no date type, so a date is a string and is typed string; convert it to a Date in your own code. JSON numbers are all typed number. A whole number too large for a JavaScript number (beyond 9,007,199,254,740,991) loses digits when your program reads it with JSON.parse, so such values are better sent as strings.
How large a JSON can I paste?
Up to 2,000,000 characters, about 2 MB. Above that the page tells you so instead of generating. The types depend on the shape of the data, not its size, so a sample with a few records that show every variation gives the same result as the whole file.
Is my JSON uploaded anywhere?
No. The types are generated in your browser and the JSON you paste and the TypeScript it becomes are never uploaded, stored or logged; it is gone when you close or reload the page. The download is built in memory from a Blob. The only thing the site records, if you allow analytics, is that a button was used, never any of the data.

How it works

The text is first checked by the same strict RFC 8259 parser as the JSON formatter, so an error has the same message, line and column, and is then read into a value tree that keeps object keys in the order written. Every value is turned into a shape: the set of primitive kinds it can be (string, number, boolean, null), at most one object shape and at most one array shape. Shapes at the same place are merged: the objects of an array, and the values of one key across those objects, become a single object shape that counts how many objects it was built from and how many of them had each key; a key seen fewer times than that is optional. Arrays are merged by their elements. The shapes are then named from the leaves up. A type name is the key in PascalCase (the singular of the key for array elements when that option is on); if the name is taken by a different shape, the parent type name is put in front, and then a number is added. An object shape whose keys, types and optional flags equal those of one already named reuses its name. Names of built-in types such as Date and Error get Data added so they cannot clash with the global ones. Unions are written in a fixed order, so the same data always gives the same text: string, number, boolean, an object type, an array type, then null. An object with no keys is written as Record<string, unknown> and an array with no elements as unknown[]. The declarations are written root first, then each declaration followed by the types it uses, in key order. Property names that are not valid identifiers are written as JSON strings. Input above 2,000,000 characters is refused with a notice. The output is checked by compiling it with the TypeScript compiler in strict mode, together with an assignment of the original JSON to the root type, for a large set of samples and random documents.

Sources

More: Formatters and data convertersAll developer toolsAll toolsHome & DIY calculators