Developer tools
How to convert JSON to TypeScript safely
Learn how to turn JSON payloads into TypeScript types without losing safety: interfaces, unions, nullability, and keeping types in sync.
Document summary
A guide to generating TypeScript types from JSON: interfaces, unions, nullability, and keeping types in sync with APIs.
Key takeaways
- Generate from a realistic sample, then refine
- Model nullability explicitly so runtime data fits the types
- Regenerate when the API response changes
Why hand-typing fails
Hand-written types drift from the real API: fields get renamed, types change, and optional fields are guessed. Generating from an actual response gives you a starting point that matches reality.
Generation is not the end. The output is a scaffold to refine with domain names and constraints.
Generate and refine
- 1
Open the JSON to TypeScript tool and paste a realistic response.
- 2
Generate the interfaces and review the shape.
- 3
Add nullability: mark fields that can be null in real responses.
- 4
Move the types into a shared types file and use them in your client.
Patterns that keep types safe
- Use unions for fields with a small set of values
- Prefer optional properties for genuinely optional fields
- Keep response types separate from domain types
- Add a runtime validator for untrusted API data
Keep types in sync with the API
Re-run generation whenever the API contract changes, and diff the new output against the old with the JSON diff tool to see exactly what moved.
For configuration-style JSON, validate the source with the JSON formatter before generating types.
Frequently asked questions
Are generated types production-ready?
They are a strong scaffold. Refine naming, nullability, and unions before shipping.
How are arrays handled?
Arrays become typed arrays such as string[] or User[], using the item type from the sample.
What if my JSON has inconsistent shapes?
Generate from several responses and union the variants, or normalize the API before typing.
Is my JSON uploaded?
No. Conversion runs locally in your browser.
