JSON to TypeScript Interfaces That Tell Optional Apart From Nullable

How to Use This Tool

Paste a response, get interfaces. Read the decisions panel underneath — it lists the places where one sample could not tell the whole truth.

Optional and nullable are not the same thing

This is the distinction that most generated types get wrong, and it matters because TypeScript enforces them differently:

• nickname?: string — the key may be absent. Reading it gives undefined.
• nickname: string | null — the key is always there and may hold null.
• nickname?: string | null — both are possible.

Across an array, a key that appears in some elements and not others is optional. A key that always appears but is sometimes null is nullable. Those are different observations about your API and only merging every element can tell them apart. A generator reading element zero sees neither.

What null in a sample really means

A field whose only observed value is null carries almost no information. Its type is null, which is technically correct and useless — you know it will hold something else sometimes, you just have not seen it. Emitting any here, as many tools do, is worse: it switches off type checking for that field silently.

This tool types it null and tells you, in the decisions panel, that it needs a human. That is the honest answer: the sample does not contain the information, so the generator should say so rather than invent a type.

The empty array problem

An empty array in your sample gives no information about its element type. There are three ways to handle it and only one is honest:

• any[] — silently disables checking for everything read out of it.
• never[] — technically what an empty literal is, and it will reject every push.
• unknown[] — forces you to narrow before use, which is the correct response to not knowing.

This tool emits unknown[] and flags it. If you know what belongs in there, you are the only one who does.

Date strings stay strings

With the flag on, fields that look like ISO 8601 timestamps are noted in the decisions panel but still typed string. That is deliberate. JSON.parse returns a string; nothing turns it into a Date on its own. Typing it as Date would be a lie about what is in the variable at runtime, and it is a lie the compiler cannot catch. Convert explicitly at the boundary, and let the type describe reality.

What a sample cannot tell you

Everything here is inferred from one example, so treat the output as a strong first draft, not a contract. A sample cannot show you a field that was absent that day, an enum value that had not occurred yet, or a number that is sometimes a string because an upstream service stringifies large integers. If the API publishes an OpenAPI or JSON Schema document, generate from that instead — it states what is possible rather than what happened once.