JSON to TypeScript Interface — Union Detection, Optional Inference, Zero Upload

Real-world use cases

• Type a GitHub / Stripe API response without writing types by hand

  You're integrating with the GitHub API for the first time and the docs list 40 fields on the user object. Curl the endpoint once, paste the JSON here, set root name to `GitHubUser`, copy the output into `src/types/github.ts`. The nested `plan` object becomes a `GitHubUserPlan` interface automatically. Now your `fetch('/user').then(r => r.json() as Promise<GitHubUser>)` has real autocomplete — and when GitHub adds a field next year, you re-paste the new response and diff the file.

• Generate types for a Postgres `row_to_json` query

  You have a SQL query that returns one row per record with nested `row_to_json(addr)` joins. Run it once, copy the JSON column, paste here, set root to `OrderRow`. The address sub-object lifts out as `OrderRowAddress`. Now your `db.query<OrderRow[]>(sql)` returns a typed array with the exact shape your SQL emits — no manual interface that drifts from the query.

• Build types for a webhook payload you haven't shaped yet

  A vendor (Slack, Linear, Vercel) is sending you an event. Their docs are out of date. Log the first 3 payloads, paste them as a JSON array, the optional-field detection flags everything that isn't always present. The resulting interface tells you not just the shape but which fields you can rely on vs which are situational — way more useful than a doc page that says "this field is sometimes there".

• Migrate from `any` to `unknown` in a legacy codebase

  Your old code does `const data: any = await res.json()`. Pick a representative response, paste it, generate types, replace the `any` with the new interface. Repeat for every endpoint. You haven't refactored the runtime — you just gave the next dev a map of what the response actually looks like.

• Document an internal JSON-RPC contract for new hires

  Your team's internal RPC has a `methods.json` spec but the response shapes were never typed. Paste each example, generate `RpcGetUserResponse`, `RpcListOrdersResponse`, etc., commit them to `packages/rpc-types/`. New hires can now Cmd-click any RPC method and see the exact shape — institutional knowledge moved from Slack threads into the type system.

• Type a GraphQL response without setting up codegen

  You have a one-off GraphQL query you're not running through codegen (small project, prototype, side script). Run it once in the playground, copy the `data` field, paste here, root name `ViewerData`. You get the same `data.viewer.repositories.nodes[0].name` autocomplete that real codegen would give, in 5 seconds, without `.graphqlconfig`.

Common pitfalls

• Pasting a single object and expecting optional fields. A single object root has no ambiguity — every key is required. Optional inference only kicks in across an array of multiple objects (where some have a key and others don't). If you want everything optional from one object, write the JSON as `[{...}]` instead.

• Forgetting that JSON numbers all become `number` — there is no `int` vs `float` distinction. A field that is always `42`, `43`, `44` still types as `number`, not as a literal `42 | 43 | 44`. Use a runtime validator (zod, valibot) if you need narrower types.

• Treating the output as a JSON Schema. It's a TypeScript type only — there is no validator generated. The output tells the compiler what shape to expect; at runtime an API can return any garbage and TS won't notice. Pair with a runtime validator at the network boundary.

• Pasting a giant JSON (10 MB+) and expecting instant results. The inferer is O(n) but the React re-render isn't free. For huge payloads, sample down to ~100 KB first — the inferred shape is the same.

• Pasting a JSON5 / JSON-with-comments blob and getting a parse error. We use the strict `JSON.parse` — trailing commas, comments, unquoted keys all fail. Strip those first or use the YAML→JSON converter as a pre-step (YAML is a JSON superset that tolerates comments).

• Setting root name to something that isn't PascalCase like `user_data`. The tool converts it (`UserData`) but if you wanted to keep snake_case for an exported binding you can't — TS interface names follow PascalCase by community convention, and we enforce it to avoid lint errors downstream.

Privacy