From JSON to TypeScript, Go and Zod: Typing API Responses Without Lying to the Compiler
Generating types from a JSON sample is fast, but one sample hides optional fields, nulls and number traps. Learn how to turn JSON into TypeScript, Go structs and Zod schemas you can actually trust.
You call a new API, get a JSON response back, and want types for it. Writing them by hand is slow and error-prone, so most developers paste the JSON into a generator and copy the result. That is a good start. The problem is what happens next: the generated types describe one example, while your code has to handle every response the API can send. This article shows where generated types go wrong, and how to fix them before they turn into runtime errors.
Why types from JSON matter
In TypeScript, response.json() returns Promise<any>. From that point on the compiler checks nothing, so a typo like user.emial compiles without complaint. Most codebases then write this:
const user = (await res.json()) as User;
That as User is a promise you make to the compiler, not something it verifies. Types are erased at runtime, so if the API returns something different, the code fails later, often far away from the actual cause. Good types reduce that risk. Wrong types make it worse, because they give you false confidence.
What a generator sees, and what it misses
Here is a typical response, and the TypeScript that the JSON to TypeScript converter produces from it:
{
"id": 1024,
"name": "Lan",
"email": null,
"created_at": "2026-10-01T08:30:00Z",
"score": 4.5,
"tags": ["admin"],
"orders": [
{ "order_id": 1, "total": 199000, "coupon": "FALL10" },
{ "order_id": 2, "total": 85000.5 }
]
}
export interface User {
id: number;
name: string;
email: null;
created_at: string;
score: number;
tags: string[];
orders: Order[];
}
export interface Order {
order_id: number;
total: number;
coupon?: string;
}
Some of this is already smart. The two orders were merged, so coupon became optional because it is missing from the second order, and total became a general number because one value is a decimal. But look closely and you will find the usual problems.
1. null in the sample becomes the type null
email: null means "this field is always null", which is almost certainly wrong. In this sample the user simply had no email. The real type is string | null. Any field that is null in your sample needs a human decision.
2. Missing keys are invisible
If a field is absent from every object in your sample, the generator cannot know it exists. Optional fields such as phone or deleted_at often appear only on some records. The fix is to paste several real responses at once, as an array. The generator merges them, and keys missing from some objects become optional (?).
3. Empty arrays tell you nothing
"tags": [] gives the generator no element type. You will get something like unknown[], which you must replace with the real type.
4. Strings that are really something else
created_at is typed as string because JSON has no date type. That is correct for the wire format, but your code may want a Date. Status fields like "status": "paid" are typed as string, while the API probably only allows a few values, which is better expressed as a union: "pending" | "paid" | "refunded".
5. Numbers too large for JavaScript
JavaScript numbers are 64-bit floats. Integers above Number.MAX_SAFE_INTEGER (9,007,199,254,740,991) lose precision silently when parsed. IDs from systems such as Snowflake-style generators often exceed this. That is why some APIs, Twitter's being the famous example, also send IDs as strings (id_str). If an ID might be that large, type it as string and ask the API to send it that
Written by
Nguyễn Thành Nam
Full-Stack Engineer · Backend & Platform
Full-stack engineer with 9+ years of experience building high-traffic APIs and platforms with Go, NestJS, PHP (Laravel, Phalcon) and Node.js. Specializes in GraphQL API design, real-time systems and performance optimization, and builds NICETOOL.dev for the developer community.