JSON to TypeScript Interface Generator

How Types Are Inferred From a Sample

Generating TypeScript from JSON is structural inference. The generator walks the value, and at every node it asks what shape this is: an object becomes an interface with one member per key, an array becomes an element type followed by square brackets, and a primitive becomes string, number, or boolean.

For an array of objects, the generator does not stop at the first element. It merges every element to build one type that describes all of them, which is what makes optional properties and unions possible. Nested objects become their own named interfaces rather than inline literals, because named types produce far more readable errors and can be imported individually.

Side by Side Example

A paginated API response and the interfaces it produces.

Two keys picked up a question mark because they were present in one result and absent in the other. And next_cursor was typed as null, which is almost certainly wrong: see the caveat section.

Interface or Type Alias

The practical difference is smaller than the debate around it suggests. Object shapes as interfaces and everything else as type aliases is a rule that never causes friction.

Optional Properties, Unions, and Null

The interesting inference happens when records disagree with each other.

• A key present in some records and missing from others is marked optional with a question mark, which types it as its inferred type or undefined.
• A key that holds different types across records produces a union, so a field seen as both a number and a string becomes string | number.
• A key that is sometimes null and sometimes a value becomes a nullable union such as string | null. This is different from optional, and the difference is real: optional means the key may be absent, nullable means the key is present and empty.
• An array with mixed element types produces an array of a union, written as (string | number)[]. An empty array in the sample gives the generator nothing to work with and produces unknown[] or any[].
• An object with no keys at all becomes Record<string, unknown>, since there is nothing to describe.

Under strictNullChecks, which every project should have on, null and undefined are not assignable to other types. That is what makes the optional versus nullable distinction enforceable instead of decorative. A field typed string | null forces you to handle the empty case at the point of use, which is the entire value of the exercise.

The Caveat That Matters Most

Types generated from a sample describe that sample. They do not describe the API contract, and the difference between those two things is where the bugs live.

Treat the generated file as a first draft that saves you the typing, then read the API documentation and correct it. Pay particular attention to fields that were null or empty in your sample, enumerable status fields that deserve a literal union, and every error shape, because error responses are almost never in the happy path sample you copied.

Types Vanish at Runtime

TypeScript types are erased during compilation. Nothing checks that the JSON arriving over the network actually matches the interface you wrote, and a response that has changed shape will flow straight into code that assumes otherwise.

Runtime validation libraries such as Zod, Valibot, io-ts, and ArkType let you declare the shape once and get both a runtime check and a static type from it. For anything crossing a trust boundary, which means network responses, form input, webhook payloads, and files on disk, that is worth the small amount of extra code.