JSON to TypeScript

The Kordu JSON to TypeScript converter generates TypeScript type definitions from any JSON sample you paste in. Instead of hand-writing interface User declarations from a Swagger response or a dumped fetch payload, paste the JSON and get a ready-to-use interface or type alias in under a second — with nested objects promoted to named types and array elements unified into a single, accurate element type.

Why typing your JSON matters

TypeScript types are the contract between the data your application receives and the code that consumes it. When an API returns JSON without a typed definition, every consumer either casts to any (giving up type safety entirely) or duplicates an ad-hoc shape inline. Both paths break during refactors: a field renamed server-side slips past the compiler, autocomplete stops suggesting real properties, and every field access becomes a runtime gamble. A generated interface gives you compile-time detection of shape drift, IDE autocomplete for every nested field, safer refactors across large codebases, and readable documentation of the payload in a single file.

How the generator infers types

The tool walks the parsed JSON tree depth-first. Each object node becomes a named interface — the root uses the name you provide (default MyType), and nested objects derive their names from the parent key (user.address → Address). Primitive leaves map to string, number, boolean, or null. Arrays are scanned; if every element has the same inferred shape, the array becomes T[], and if elements differ (for example a mix of string and number, or two different object shapes), the generator emits a union element type such as (string | number)[]. Keys that are not valid JavaScript identifiers (hyphens, dots, numeric prefixes, spaces, reserved words) are auto-quoted so the output compiles without manual fix-ups.

Interface vs type alias

Both declare object shapes, but they have different superpowers. Interfaces support declaration merging (two interface User blocks in the same scope fuse into one), use extends to compose hierarchies, and are the TypeScript handbook's preferred default for public API surfaces because their error messages read more cleanly. Type aliases (type User = { … }) can express things interfaces cannot: unions (Status = 'idle' | 'loading'), intersections (Admin & Paging), mapped types, tuple types, and aliases for primitives. Rule of thumb: use interface for object shapes and public contracts; reach for type when you need unions, mapped types, or conditional types. The tool lets you pick either and switch later — the emitted structure is identical.

Naming conventions that age well

Generated types read better when you apply a consistent naming scheme across the project. Use PascalCase for every type (Order, not order or IOrder — the I prefix is a C#-ism TypeScript style guides have moved away from). Name item shapes in the singular (OrderLine, not OrderLines) so OrderLine[] reads naturally. For API payloads, a common pattern is ApiResponse<T> as an envelope and User, Order, or InvoiceLine for domain entities inside it — keep domain types separate from transport types so you can swap REST for GraphQL without renaming.

Handling real-world API responses

Production APIs rarely return bare objects. REST endpoints usually wrap the payload ({ data, pagination, meta }), pagination cursors add envelope noise, and error branches return a different shape entirely. Generate the type from a real successful response — include the envelope — and then extract only the inner types your UI actually consumes (User from ApiResponse<User>). Re-exporting every generated type from a public barrel is a common anti-pattern: it leaks transport shapes into business code and forces every downstream rename into a breaking API change.

Nullable vs optional

TypeScript has three related concepts that JSON flattens into one. An optional property (age?: number) means the key may be missing. A nullable property (age: number | null) means the key is present but may be null. A property typed number | undefined is again optional but noisier. Since JSON samples don't distinguish "missing" from "explicitly null," the generator defaults to field?: T | null when it sees null in the sample — the most permissive interpretation. If you enable exactOptionalPropertyTypes (TS 4.4+), tighten the generated type by removing ? when you know the field is always present, and remove | null when the API guarantees it.

What inference can and cannot do

A single JSON sample is a snapshot, not a schema. The generator infers exactly what it sees: a field that happens to be null in your sample will come through as nullable, even if the API also returns strings. A numeric field will be typed number — TypeScript has no integer type, and JSON doesn't either. String fields will be typed string even when the values are clearly an enum ("pending" | "shipped" | "delivered"). Inference cannot detect semantic formats (email, URL, UUID, ISO date) or discriminated unions without multiple samples. Treat the output as a strong starting draft — tighten the literal unions, narrow string to template literal types where it adds value, and add readonly to arrays you never mutate.

Limitations and when to reach for a schema tool

If you have multiple samples of the same endpoint, quicktype (the de-facto multi-sample inference tool) unifies them into a single type more accurately than any single-sample tool can. If you need runtime validation — parsing an unknown API response and rejecting malformed payloads at the boundary — pair the generated interface with a Zod or Valibot schema, or use Ajv with a JSON Schema. For OpenAPI specs, openapi-typescript generates the full client from the spec. The Kordu generator is the fastest path from "I have a JSON example" to "I have a working TypeScript type," not a substitute for those stronger approaches when you need them.

Compared to writing types by hand

Hand-writing types from a JSON example is mechanical, error-prone, and scales badly: a 40-field User object takes 10 minutes to type, and every typo sits latent until it causes a bug. The generator is deterministic, handles nested structures correctly on the first pass, and enforces consistent naming. Paste, review, copy — ten seconds instead of ten minutes.

Privacy and data processing

All parsing, inference, and code generation happens entirely in your browser. Kordu does not upload, log, or store your JSON. There is no backend — the generator is pure client-side JavaScript, which means it works offline once the page has loaded, handles sensitive payloads safely, and has no rate limits or signup walls.