How to Convert JSON to TypeScript Interfaces (and Why Types Aren't Enough)

When you retrieve data from an API using TypeScript, manually creating types from the JSON response can be time-consuming and prone to mistakes. However, a generator can swiftly convert a sample response into interfaces, providing a useful starting point—provided you understand its limitations.

Here's an example of JSON to TypeScript conversion:

- JSON: `{ "id": 7, "name": "Ada", "email": null, "tags": ["a", "b"], "address": { "city": "Pune" } }`

- TypeScript Interfaces:

```typescript

interface Address {

city: string;

}

interface User {

id: number;

name: string;

email: null;

tags: string[];

address: Address;

}

```

Notice the `email` field is marked as `null`. The generator only observed a null value, so it cannot infer it's typically a string.

To refine the generated types:

1. Convert null to the appropriate type when the field can hold other values.

2. Use a question mark to mark optional fields that might be missing.

3. Employ unions for fields that can store different data types.

4. Explicitly convert dates to strings in JSON, as TypeScript has no native date type.

5. Utilize integers or strings for fields with a fixed set of possible values.

When deciding between `interface` and `type`, either can be used for object shapes. Use `type` for unions and `interface` for extending or merging declarations.

It's crucial to remember that TypeScript types are erased at runtime. While TypeScript won't check the data, it's essential to validate untrusted data at the boundary of your application using schema libraries like Zod or JSON Schema.

After generating an initial interface from a sample response, refine nullable fields, optional fields, and unions based on the API documentation. Regularly update or regenerate types when the API changes. Be cautious about the data you paste into third-party sites, especially when working with real API responses that may contain sensitive information.