JSON to TypeScript Guide: Create Safer API Types From Real Payloads

The generated type may infer:

But the real API may return a string for company when present:

Review generated types carefully.

Optional vs Nullable

Optional and nullable are different.

Optional:

Nullable:

An optional field may be missing. A nullable field exists but can be null. APIs use both patterns.

Check multiple examples before deciding.

Arrays Need Multiple Samples

An array with one item may not reveal every possible shape.

If possible, collect examples with:

• Empty arrays.
• Multiple items.
• Optional fields.
• Different item types.
• Null values.

One sample is rarely the whole contract.

Runtime Validation Still Matters

TypeScript types disappear at runtime. They help your code, but they do not validate external data by themselves.

For critical API boundaries, use runtime validation with a schema library or validation layer.

Types answer:

Validation answers:

You often need both.

Naming Types

Generated names may be generic. Rename them for clarity:

• Root becomes UserResponse.
• Item becomes InvoiceLineItem.
• Data becomes SearchResult.

Good names make types easier to use and review.

Common Mistakes

Trusting one payload. APIs have edge cases.

Forgetting null. Null values are common.

Treating generated types as contracts. The API contract is the real source.

Skipping runtime checks. External data can be wrong.

Using vague names. Clear names improve maintainability.

Practical Workflow

1. Capture real JSON.
2. Format and inspect it.
3. Generate TypeScript types.
4. Rename types.
5. Review optional and nullable fields.
6. Test with multiple payloads.
7. Add runtime validation where needed.
8. Keep types close to API client code.

The Bottom Line

JSON to TypeScript conversion is a fast way to bootstrap types from real data. Use it as a draft, not a final truth.

The best API types are generated quickly, reviewed carefully, and protected with runtime validation where it matters.