JSON a TypeScript
Genera interfaces de TypeScript a partir de un ejemplo JSON.
Acerca de esta herramienta
Pega una respuesta JSON y obtén sus interfaces de TypeScript. Los objetos anidados se convierten en interfaces con nombre propio, los arrays de objetos se combinan para marcar con ? los campos opcionales y los valores mixtos se convierten en tipos unión.
Cómo se usa
- Pega un ejemplo de respuesta JSON de tu API.
- Indica el nombre del tipo raíz, por ejemplo User u OrderResponse.
- Elige declaraciones interface o type, y si quieres exportarlas.
- Copia el TypeScript generado en tu proyecto y ajusta lo que el ejemplo no pudiera mostrar.
Preguntas
- ¿Cómo se detectan los campos opcionales?
- Cuando un array contiene varios objetos, un campo que falta en alguno de ellos se marca como opcional con ?. Un solo objeto no puede revelar campos opcionales, así que, si puedes, usa un ejemplo con varios elementos.
- ¿Por qué un campo tiene el tipo null?
- Porque era null en el ejemplo, así que su tipo real es desconocido. Sustitúyelo por algo como string | null cuando sepas qué devuelve la API.
- ¿Debo usar interface o type?
- Ambos sirven para describir JSON. Las interfaces se pueden extender y fusionar, y dan mensajes de error algo más claros; los alias de tipo son necesarios para las uniones. Elige lo que ya use tu código.
- ¿Valida los datos en tiempo de ejecución?
- No. Los tipos de TypeScript desaparecen al compilar. Para comprobar los datos en tiempo de ejecución, usa una biblioteca de esquemas como Zod junto con estos tipos.
- ¿Qué pasa si la raíz del JSON es un array?
- La raíz se convierte en un alias de tipo para un array. Con el nombre raíz User y un ejemplo como [{"id": 1}], obtienes type User = UserItem[] más una interfaz UserItem para los elementos. Pon el nombre raíz en plural, como Users, para obtener type Users = User[].
- ¿Puedo pegar un objeto de JavaScript en lugar de JSON estricto?
- Sí. Las comillas simples, las claves sin comillas, las comas finales y True, False y None de Python se convierten a JSON antes de generar los tipos, así que funciona la salida copiada de console.log en Node o de una shell de Python. Los valores que JSON no puede expresar, como funciones o instancias de clases, siguen provocando un error.
- ¿Por qué el tipo de los elementos de un array se llama DataItem?
- Los tipos de los elementos se nombran poniendo en singular la clave del array: users da User y entries da Entry. Cuando una clave no tiene terminación de plural, como data o children, se añade Item, lo que da DataItem y ChildrenItem. Si prefieres otros nombres, cámbialos en tu editor después de pegarlos.
Cómo generar interfaces de TypeScript a partir de JSON
Pega una respuesta real de una API y cada objeto JSON se convierte en una interfaz de TypeScript con nombre. Se conservan los nombres de los campos, los valores se asignan a string, number y boolean, y un objeto anidado recibe su propia declaración con el nombre de su clave, así que un campo address genera una interfaz Address. Los arrays de objetos se nombran en singular: orders da Order[] y categories da Category[]. Pon en Nombre raíz el tipo que usará tu código, como User.
El TypeScript generado compila tal cual, así que puedes pegarlo en un archivo types.ts o descargarlo. Las claves que no son identificadores válidos, como "first-name" o "2fa", se escriben entre comillas. Cuando dos objetos anidados recibirían el mismo nombre, el segundo lleva un número, como Address2. Un array vacío se convierte en unknown[] y un objeto vacío en Record<string, unknown>, porque el ejemplo no muestra nada sobre su contenido.
Cómo se infieren los tipos unión a partir de JSON
Cuando un mismo campo contiene distintos tipos de valores, su tipo pasa a ser una unión. Un array como [1, "two", null] se tipa como (string | number | null)[], y un campo que es una cadena en un elemento y un número en otro se convierte en string | number. Los objetos dentro de un mismo array se fusionan en una sola interfaz en lugar de formar una unión de estructuras, y los campos que solo aparecen en algunos se marcan como opcionales.
Fusionar va bien para listas de registros, pero oculta las uniones etiquetadas. Si un array events mezcla {"type": "click", "x": 3} y {"type": "key", "code": "Enter"}, obtienes una sola interfaz Event con type como string y con x y code opcionales. Reescríbela a mano como una unión discriminada de dos interfaces, una con type: "click" y otra con type: "key", para que TypeScript pueda acotar el tipo según el campo type.
JSON a TypeScript a partir de un ejemplo o de un esquema
Un ejemplo de JSON muestra una respuesta, no el contrato. Las cadenas que en realidad son fechas, los enums como "active" | "banned", los ID numéricos que pueden superar 2^53 y los campos que solo aparecen a veces no se ven en un único ejemplo. Trata las interfaces generadas como un primer borrador: pega una respuesta con varios elementos en el array y luego ajusta los tipos donde sepas más, por ejemplo sustituyendo status: string por una unión de los valores permitidos.
Si una API publica un documento OpenAPI o un JSON Schema, genera los tipos a partir de él, porque describe todos los campos que puede devolver el servidor. Generar tipos a partir de JSON es el camino rápido para API de terceros sin especificación, payloads de webhooks y endpoints internos antiguos. Para datos que no controlas, añade una comprobación en tiempo de ejecución con la misma estructura, como un esquema de Zod, para que una respuesta modificada falle de forma visible en lugar de colarse sin que nadie lo note.
¿Algo no funciona o un resultado parece incorrecto? Informar de un problema con esta herramienta