JSON to TypeScript

Hand-writing an interface for an API response is tedious and easy to get subtly wrong, particularly around fields that are only sometimes present. Pasting a real response gives you the interface it implies.

Nested objects are hoisted into their own named interfaces rather than inlined, so you can refer to Address directly instead of repeating its shape, and structurally identical objects are emitted once and reused.

TypeScript's mapping is the coarsest of the nine targets, which is worth knowing rather than a flaw: number covers every JSON number with no integer/float distinction and no 64-bit type, so an id past Number.MAX_SAFE_INTEGER needs string or bigint and a serialiser that agrees. A field with no observable type becomes unknown rather than any, which keeps the compiler asking about it instead of letting it spread silently through the call sites.

What is the difference between field?: string and field: string | null?

The first means the key may be absent; the second means the key is there but its value may be null. They are different failure modes and this generator distinguishes them, because the JSON does.

Why an interface and not a Zod schema?

An interface is erased at build time, so it costs nothing at runtime and tells you nothing about whether the response actually matched. If you need the check to happen against real traffic, take the interface as the shape and write the validator separately — a generated schema would imply the payload had been verified when it had only been observed once.

Why interface rather than type?

For an object shape the two are near-interchangeable; interfaces are used here because declaration merging lets you extend one from your own code without editing the generated file, and their error messages name the interface rather than expanding the whole structure inline. Switch to type if you need a union or a mapped type, which a sample cannot tell you about.

Will this catch a response that changes shape?

No — and that is the trap. The interface describes what you observed once; nothing checks the next response against it. The compiler will be entirely confident about a field the API stopped sending. Use it for the shape and validate at the boundary if the payload is not yours.

How are optional fields decided?

Every record in an array is inspected, not just the first. A field that appears in some records and not others is typed as optional, and a value that is sometimes null widens accordingly. Generators that read only the first element get this wrong on exactly the payloads where it matters.

What happens to a key that is a reserved word?

It is renamed to something legal in the target language, and where the language supports it, an annotation records the original JSON key so serialisation still round-trips.