JSON to TypeScript: Handling Nulls, Arrays and Optional Properties
Reviewed September 3, 2026 · Maintained by William
Generating TypeScript from a JSON sample is useful because it turns an observed runtime shape into a starting interface. The trap is treating one sample as if it proves the complete API contract.
Null is evidence, but incomplete evidence
{ "id": 7, "nickname": null }From that sample alone, nickname could be always null, string | null, or a field with a wider schema. A generator should be conservative, and a developer should compare the output with API documentation or multiple representative samples.
Empty arrays cannot reveal an element type
{ "items": [] }There is no runtime evidence showing whether items contains strings, objects or a union. A tool may choose unknown[], any[] or another fallback; each choice has tradeoffs.
Optional properties are a contract question
If one object in an array contains email and another does not, a merged interface can reasonably infer email?. But a single object cannot tell you whether a present field is mandatory across all valid responses.
Mixed arrays need review
{ "values": [1, "two", null] }A faithful inferred type may be (number | string | null)[]. If the API actually promises one type and the sample is dirty, preserving the mixed shape could hide a data-quality bug rather than document the contract.
Generated type is not runtime validation
TypeScript interfaces disappear at runtime. If you receive untrusted external JSON, use schema/runtime validation where correctness matters. A generated interface improves editor tooling; it does not make an HTTP response conform to it.
The JSON to TypeScript Interface tool is therefore positioned as an inference helper. Review nullability, optionality and empty arrays before pasting the result into production code.
Reference
TypeScript Handbook — Everyday Types
One JSON sample is evidence, not a contract
Type inference from JSON can produce a useful starting interface, but it only knows the values present in the sample. If middleName is absent from one response, the generator cannot know whether the property is optional, forbidden, or simply missing from that particular record. If it is present as null, that still does not prove the API will never return a string.
Null versus optional
// sample A
{ "id": 7, "nickname": null }
// sample B
{ "id": 8 }These can imply different TypeScript models:
interface User {
id: number;
nickname: string | null; // value may be null
}
interface UserSummary {
id: number;
nickname?: string; // property may be absent
}Real APIs can require both possibilities: nickname?: string | null. Only the API contract or multiple representative samples can establish that.
Empty arrays provide no element evidence
From {"tags":[]}, a generator cannot infer whether tags is string[], Tag[] or something else. Prefer an API schema (OpenAPI/JSON Schema) when available. Otherwise review empty-array inferences manually before committing generated types.
Mixed arrays need a policy
{ "values": [1, "two", null] }A literal inference could become (number | string | null)[], but mixed primitive arrays may also indicate inconsistent upstream data. Generated TypeScript should not hide that data-quality question.
Runtime validation is separate
TypeScript types disappear at runtime. A response that violates the interface can still arrive over the network. For untrusted or external data, pair static types with runtime validation, schema validation or explicit checks at the boundary.
Review workflow
- Generate a starting interface from a representative sample.
- Compare it with API/OpenAPI/JSON Schema documentation.
- Mark truly optional fields based on the contract, not a single omission.
- Review nullable fields and empty arrays.
- Name reusable nested interfaces meaningfully.
- Add runtime validation where malformed external data would be costly.
The JSON to TypeScript tool intentionally describes its output as an inference. Use it to reduce repetitive typing, then apply domain knowledge before the generated interface becomes part of your public API model.