JSON a TypeScript

Cómo funciona

Para usar con tipos los datos de una API en TypeScript necesita una interfaz para la respuesta; escribirla a mano lleva tiempo y es fácil olvidar un campo. Pegue una respuesta de ejemplo a la izquierda y escriba un nombre de tipo raíz (por ejemplo Cliente); las declaraciones aparecen a la derecha. Cada objeto anidado recibe su propia interfaz: el campo direccion pasa al tipo Direccion, y un array de objetos toma el singular de su nombre ("pedidos" → Pedido[]). Si el JSON empieza con un array, el tipo raíz describe un elemento y se agrega una línea RootList = Root[]. Todas las entradas de un array se combinan en un tipo: un campo que falta en alguna entrada lleva ? (correo?: string) y un campo que fue null en alguna lleva | null (ultimo_pedido: string | null). Un campo con tipos distintos se vuelve una unión (string | number). Los nombres de propiedad son exactamente las claves del JSON, porque un tipo de TypeScript no puede renombrar los datos: nombre_completo sigue siendo nombre_completo y un nombre que no es identificador válido, como "nombre-completo", va entre comillas. Un array vacío no tiene tipo de elemento conocido y se escribe unknown[].

Esta herramienta también se busca como json a typescript, json to typescript, generar interfaz typescript desde json, json to ts interface, convertir json a typescript.

¿Qué es Interfaz de TypeScript?

En TypeScript, una interfaz describe qué campos tiene un objeto y de qué tipo son: interface Direccion { ciudad: string; codigo_postal: string; }. El compilador la usa para detectar, antes de ejecutar el código, nombres de campo mal escritos, campos que faltan y errores de tipo. La declaración se borra al compilar y no existe en el JavaScript resultante; por eso nunca valida datos en tiempo de ejecución, solo avisa a quien programa.

¿Qué es Campo opcional y campo nullable?

Un campo opcional (correo?: string) puede no estar en el objeto; al leerlo da undefined. Un campo nullable (ultimo_pedido: string | null) siempre está, pero su valor puede ser null. En el JSON se ven distintos: en un caso falta la clave, en el otro aparece "ultimo_pedido": null. La herramienta los marca por separado porque el código debe tratarlos con comprobaciones diferentes.

¿Cuál es la diferencia entre interface y type en TypeScript?

Para describir la forma de un objeto, interface y type suelen dar el mismo resultado. Una interface se amplía con extends, y una segunda declaración con el mismo nombre se combina con la primera, algo útil para agregar campos a los tipos de una biblioteca. Un type puede expresar uniones (string | number), intersecciones y alias, pero no se puede declarar dos veces con el mismo nombre. Ambos sirven para respuestas de API; elija el que ya use el estilo de código de su equipo.

Campos faltantes, null y uniones: cómo se deduce el tipo

La herramienta deduce a partir de un solo ejemplo; cuantas más variantes muestre, más exacto será el tipo. Las entradas de un array se combinan y para cada campo se hacen dos preguntas distintas: ¿está en todas las entradas?, ¿fue null alguna vez? Si la primera respuesta es no, el campo es opcional (?); si la segunda es sí, se agrega | null. No es lo mismo: correo?: string dice que el campo puede no llegar, y ultimo_pedido: string | null dice que siempre llega pero puede venir vacío.

Si un campo muestra tipos distintos, se escribe una unión: un campo que vale 5 en una entrada y "5" en otra pasa a string | number. Suele ser señal de una incoherencia de la API; revise su documentación antes de restringir el tipo. Un campo que solo fue null no tiene tipo conocido y se escribe null.

• [{"a":1},{"b":2}] → a?: number; b?: number;
• {"x": null} y {"x": "y"} → x: string | null
• {"n": 5} y {"n": "5"} → n: string | number
• {"nombre-completo": "x"} → "nombre-completo": string

interface o type, y límites honestos

Para describir la forma de un objeto, los dos hacen el mismo trabajo. Una interface se amplía con extends y se combina con una segunda declaración del mismo nombre, lo que ayuda a agregar campos a los tipos de una biblioteca. Un type comparte su escritura con las uniones (A | B), las intersecciones y los alias; si su equipo escribe todo con type, elíjalo. En ambos casos la salida empieza con export y se puede importar desde otro archivo.

Límites honestos: las fechas en texto ("2026-09-20") no pasan a Date y los conjuntos de valores fijos ("activo" | "inactivo") no pasan a uniones literales; quedan como string y hay que restringirlos a mano. Dos objetos anidados con la misma forma pueden escribirse dos veces con nombres distintos. Un tipo de TypeScript no valida datos en tiempo de ejecución; para asegurarse de que una API devuelve esa forma se necesita una biblioteca de validación como zod.

Preguntas frecuentes

¿Cómo creo una interfaz TypeScript a partir de un JSON?

Pegue un JSON de ejemplo en el panel izquierdo de esta página y escriba el nombre del tipo raíz. A la derecha aparecen declaraciones TypeScript que empiezan con export, con una interfaz para cada objeto anidado. Copie el código a un archivo .ts de su proyecto y úselo para tipar los datos.

¿Qué significan los campos con signo de interrogación (?)?

Ese campo falta en algunas entradas del array. En TypeScript, ? indica que el campo puede no estar, así que hay que comprobarlo antes de usarlo. Si está seguro de que el campo siempre existe, ponga Campos faltantes en Obligatorio y no se agregará ?.

¿Por qué no se convierten los nombres de propiedad a camelCase?

Un tipo de TypeScript no cambia los datos, solo describe su forma. Si la clave del JSON es nombre_completo, la propiedad del tipo también debe llamarse nombre_completo; si no, el compilador esperaría un campo que los datos reales no tienen. Si quiere otros nombres, cámbielos en el código que lee los datos.

¿El JSON que pego se envía a un servidor?

No. La deducción de tipos y la escritura del código TypeScript ocurren por completo en su navegador; ni siquiera una respuesta de ejemplo con datos de clientes sale de esta página. Una vez cargada, la página funciona sin conexión.