Generar tipos TypeScript a partir de JSON: una guía práctica

Cómo funciona la inferencia de JSON a TypeScript

Un generador recorre el árbol de valores JSON y mapea cada tipo de JavaScript a su equivalente de TypeScript: string sigue siendo string, number sigue siendo number, boolean sigue siendo boolean, null se convierte en null (o se fusiona en una unión), los arrays se convierten en T[] donde T se infiere de los elementos, y los objetos se convierten en interfaces anidadas.

{
  "id": 42,
  "email": "ada@example.com",
  "isActive": true,
  "roles": ["admin", "editor"],
  "profile": {
    "displayName": "Ada",
    "avatarUrl": null
  }
}

interface Root {
  id: number;
  email: string;
  isActive: boolean;
  roles: string[];
  profile: {
    displayName: string;
    avatarUrl: string | null;
  };
}

Dónde la inferencia tiene que adivinar

Campos opcionales frente a siempre presentes: una sola muestra JSON no puede decirle a un generador si avatarUrl a veces falta por completo (lo que debería ser avatarUrl?: string | null) o siempre está presente pero a veces es null. Dale al generador unas cuantas muestras representativas, o marca manualmente un campo como opcional tras la generación si sabes que la API lo omite bajo ciertas condiciones.

Números que guardan IDs frente a cantidades: JSON tiene un único tipo number, y TypeScript no puede distinguir un ID entero de un precio de coma flotante sin contexto extra. Algunos generadores ofrecen tipos con marca o unions literales para esto; la mayoría emite number y te deja la distinción a ti.

Arrays vacíos: un array sin elementos ("tags": []) no le da al generador nada para inferir el tipo de elemento, así que recurre a unknown[] o any[]. Apunta el generador a una muestra donde el array tenga elementos, o anótalo a mano después.

Uniones de literales de cadena: el generador inferirá como string simple un campo status que contiene uno de "pending" | "active" | "closed", salvo que vea todos los valores posibles en la muestra. Incluso entonces, la mayoría de generadores usa por defecto el tipo string más amplio salvo que actives la inferencia de unions literales.

Fechas: JSON no tiene tipo de fecha, así que los timestamps llegan como cadenas (ISO 8601) o números (epoch de Unix). Un generador tipa un campo de fecha como string o number, no como Date, y tú lo sigues analizando tras el fetch.

La misma idea en otros lenguajes

La lógica de inferencia (recorrer el árbol, mapear tipos, nombrar objetos anidados) es la misma para cualquier lenguaje destino; solo cambia la sintaxis de salida. Un struct de Go recibe el mismo mapeo de campos con etiquetas de struct para los nombres de clave JSON; un dataclass de Python recibe type hints y un envoltorio Optional[...] donde haga falta; una clase de Java o C# recibe campos tipados y getters/setters o records. Si tu equipo trabaja en varios lenguajes contra la misma API, genera los tipos de cada uno desde la misma muestra JSON para que sigan siendo coherentes.

type Root struct {
	ID       int     `json:"id"`
	Email    string  `json:"email"`
	IsActive bool    `json:"isActive"`
	Roles    []string `json:"roles"`
	Profile  struct {
		DisplayName string  `json:"displayName"`
		AvatarURL   *string `json:"avatarUrl"`
	} `json:"profile"`
}

Antes de confiar en los tipos generados

Trata los tipos generados como punto de partida y termina tú el contrato. Antes de hacer commit, confirma los campos opcionales con la documentación de la API (una muestra no basta), sustituye por unions literales los campos string sueltos que guardan enums, comprueba que los campos de array vacío recibieron un tipo de elemento real a partir de una muestra mejor, y regenera cada vez que la API aguas arriba añada o renombre un campo en lugar de parchear la interfaz a mano.