A sample response pasted into a type generator produces an interface in seconds. The danger is that the interface describes one sample, not the API contract. Fields that happened to be present are marked required; fields that happened to be absent disappear; a null becomes any. The generated type compiles and quietly lies.
Generated types are a starting point. Treat them as a draft to review, not as the contract itself.
What a good generator should infer
Given this payload:
{
"id": 42,
"name": "Ada",
"email": null,
"roles": ["admin", "editor"],
"profile": { "avatar": "https://example.com/a.png", "bio": "Engineer" },
"createdAt": "2026-11-01T10:00:00Z"
}
a reasonable output is:
export interface Profile {
avatar: string;
bio: string;
}
export interface Root {
id: number;
name: string;
email: null;
roles: string[];
profile: Profile;
createdAt: string;
}
That is structurally correct for this sample. It is also misleading in three ways:
emailis nullable but typed asnull, which is narrower than reality.createdAtis a date string, not an arbitrary string.- Every field is required because every field appeared once.
Improve the inference before trusting it
- Use several samples. Merge objects from multiple responses so fields that are sometimes missing become optional.
- Separate null from the value type.
email?: string | nullis usually right;email: nullis rarely the intent. - Name the root.
Rootis a symptom of not knowing what the payload represents. - Replace primitive strings for dates and IDs with branded types or plain comments if you do not use a validation library.
- Check arrays of mixed shapes. A generator may emit
(A | B)[]or merge them into one interface; both can be wrong. - Handle empty arrays.
unknown[]is the honest type when no element sample exists.
Optional versus nullable
These are different:
interface A { email?: string } // may be absent
interface B { email: string | null } // present, may be null
Many APIs use both. A field may be absent when it was never set and null when it was explicitly cleared. The generated type from one sample cannot tell you which convention the API follows; the documentation or the serializer can.
Dates are strings on the wire
JSON has no date type. An ISO 8601 string is still a string to TypeScript. You can model it as a branded type:
type IsoDate = string & { readonly __brand: "IsoDate" };
and validate at the boundary. Otherwise a function that expects a date will happily accept "not a date" until runtime.
Large integers lose precision
If the payload contains 9007199254740993, JavaScript parses it as 9007199254740992. The generated type says number, which is technically true and practically wrong. APIs that return 64-bit IDs should return them as strings. If they do not, your client needs a parser that preserves big integers.
Types are erased at runtime
TypeScript does not validate the payload. A cast is a promise, not a check. For anything crossing a trust boundary, pair generated types with a runtime validator such as Zod, Valibot or a JSON Schema validator. A common pattern is to generate a schema first, then derive the type from it, so there is one source of truth.
Code generation versus hand-written types
Generated types are cheap and catch structural drift. Hand-written types can encode domain meaning: which fields are required, which strings are enums, which numbers are cents. The pragmatic workflow is:
- Generate a draft from a representative response.
- Rename types and fields to match the domain.
- Tighten nullability and replace
stringwhere a union is known. - Add a runtime check at the boundary.
- Keep the generator output in a separate file so regeneration is easy to diff.
A warning about enums
A single sample may show "status": "active". The generator emits string. The API may actually return "active" | "paused" | "closed". Without a schema or documentation, no sample-based tool can infer the full union. If the value controls behavior, define the union by hand and validate it.
Generated types are useful when they are treated as evidence, not authority. Use the JSON to TypeScript converter for the draft, then spend five minutes making it honest.