JSON to TypeScript converter

The converter walks the whole document, not just the first array item. Each spot in the data collects every value it saw, and the type is built from all of them. That is why a sample with 20 users gives a better type than a sample with one.

Two objects with exactly the same fields share one type, so home and work addresses both become Home instead of two copies. When two different shapes want the same name, the second gets a number (Item2); rename it in your editor. You can also paste JSON Lines (one object per line, as in logs and .ndjson exports) and every line is merged as one sample.

For JSON data the two produce the same checks. The TypeScript handbook lists the real differences: an interface can be reopened to add fields (declaration merging) and extended with extends; a type alias cannot be reopened, but it can name unions, tuples and primitives.

// interface: can be extended and merged
interface User { id: number; name: string }
interface Admin extends User { permissions: string[] }

// type alias: can name a union, cannot be reopened
type Id = number | string;
type User = { id: Id; name: string };

A root that is an array or a primitive is always a type alias (type Root = RootItem[]), because an interface can only describe an object.

TypeScript types are removed when the code is compiled, so JSON.parse(body) as User checks nothing. If the API changes or returns an error object, the bug shows up later and far away. A schema library checks the data when it arrives. Pick Zod schema above to get the schemas and the types in one go:

import { z } from 'zod';

export const RepoSchema = z.object({
  name: z.string(),
  stars: z.int(),
  license: z.string().optional(),
});
export type Repo = z.infer<typeof RepoSchema>;

const repo = RepoSchema.parse(await res.json()); // throws if the shape is wrong

Zod 4 has top-level format checks such as z.email(), z.url() and z.iso.datetime(); the Zod 3 output uses the older z.string().email() forms, which Zod 4 still accepts but marks as deprecated. Format checks are only added when every sampled value matches, and z.uuid() is only used when the samples follow the RFC version and variant bits (Zod 4 checks them); otherwise you get z.guid().

Import the file. With "resolveJsonModule": true in tsconfig.json, import data from './data.json' gets a type inferred from the file. Good for config and fixtures you keep in the repo.

quicktype CLI. Generates types and runtime converters in many languages from JSON samples, JSON Schema or GraphQL:

npx quicktype users.json -o User.ts
npx quicktype users.json --lang go -o user.go

From a JSON Schema. If the API publishes a schema, generate types from it instead of from a sample, since the schema knows about fields your sample happens to lack. You can also build a schema from samples with the JSON Schema generator.

• Your sample is all the tool knows. A field that is never null in the sample will not be typed as nullable. Paste several responses, including error and empty ones, to get honest types.
• Dates are strings. JSON has no date type, so "2024-03-01T09:30:00Z" is a string. Convert it with new Date() after parsing, or use z.coerce.date() in Zod.
• Big integers lose precision. JSON.parse turns numbers into doubles, which are exact only up to Number.MAX_SAFE_INTEGER (2^53 - 1). IDs like Twitter's are sent as strings for this reason; keep them as string.
• Integers and decimals are both number. TypeScript has one number type. The Zod output uses z.int() (Zod 4) or .int() (Zod 3) when every sample is a whole number.

Need to tidy the JSON first? Use the JSON formatter. To pull one part out of a big response, try the JSONPath tester. For more developer APIs and SDKs, browse API tools on DevHunt.