JSON a TypeScript: cuándo aparecen ? y | en las interfaces

PublicadoHerramientaJSON → tipos de TypeScript

Contenido
  1. Problemas que surgen al escribir a mano el JSON de un array
  2. Cómo crear los tipos tú mismo a partir de un JSON de ejemplo
  3. Las marcas que más confunden en el código de resultado
  4. Resumen
  5. Preguntas frecuentes

Cuando escribes a mano una interface de TypeScript mientras revisas un JSON de ejemplo recibido como respuesta de una API, llega un momento en el que no tienes claro a qué clave hay que añadirle un signo de interrogación (?).

Ese signo de interrogación y la barra vertical (|) de la unión no son cuestión de intuición: son valores que se calculan con reglas definidas, y si las conoces puedes revisar a simple vista el código generado automáticamente.

Este artículo explica esas reglas y, con un JSON real, por qué los objetos anidados se dividen en varias interfaces en lugar de quedar todos dentro de una única interface grande.

Resumen ① Las claves que solo aparecen en algunos elementos del array llevan optional (?); si están en todos los elementos, no lo llevan. ② Aunque se trate de la misma clave, si el tipo de valor varía de un elemento a otro, los tipos se combinan con una unión (|). ③ Los objetos anidados y los objetos dentro de arrays reciben un nombre basado en el nombre de la clave y se separan en su propia interface.

Problemas que surgen al escribir a mano el JSON de un array

Es habitual tener que crear los tipos a partir de un único JSON de respuesta real en lugar de la documentación de la API. Si se trata de la respuesta de una API de lista de pedidos, puede que dentro del array items haya elementos distintos para cada producto.

Por ejemplo, algunos productos tienen una tasa de descuento (discountRate) y otros no.

Errores de criterio habituales al escribirlo a mano

En ese caso, si escribes la interface a mano, es frecuente cometer dos errores.

Puedes marcar todos los campos como optional (?) y perder la seguridad de tipos o, al contrario, declarar como obligatorio un campo que en realidad solo aparece en algunos elementos, lo que provocará un error de compilación al usar otra muestra de respuesta.

También resulta ambiguo decidir a mano hasta dónde incluir la información anidada del cliente (customer) o los elementos del array (items) dentro de una misma interface y a partir de qué punto separarlos.

Estas tres cuestiones —si es optional, si lleva unión y si se separa— en realidad son valores que se determinan de forma mecánica con solo mirar la estructura del JSON.

Cómo crear los tipos tú mismo a partir de un JSON de ejemplo

Aunque no uses una herramienta, puedes llegar al mismo resultado a mano siguiendo este orden:

  1. Anota la lista de claves del objeto de nivel superior.
  2. Indica si el valor de cada clave es un valor primitivo (cadena, número, booleano, null), un objeto o un array.
  3. Para las claves con valores primitivos, escribe su tipo tal cual.
  4. Para los valores de tipo objeto, crea una interface aparte con un nombre formado al convertir el nombre de la clave a PascalCase.
  5. Para los valores de tipo array, toma todos sus elementos como un único conjunto de comparación (conjunto de muestras) y comprueba, elemento por elemento, si existe cada clave y de qué tipo es su valor.
  6. Las claves que solo aparecen en algunas muestras llevan un signo de interrogación (?); si, cuando existen, sus valores pueden ser de varios tipos, escribe esos tipos separados por |.

Vamos a hacerlo con un JSON real.

{
  "orderId": 1024,
  "customer": { "name": "김민준", "email": "minjun@example.com" },
  "couponCode": "WELCOME10",
  "items": [
    { "productId": "A1", "price": 12000, "discountRate": 0.1 },
    { "productId": "A2", "price": 8000, "discountRate": null },
    { "productId": "A3", "price": 15000 }
  ]
}

orderId solo contiene un número, por lo que es number; couponCode solo contiene una cadena, por lo que es string. customer es un objeto, así que lo extraemos con un nombre.

Si convertimos el nombre de la clave customer a PascalCase, obtenemos Customer, y como name y email del interior son cadenas, el tipo es { name: string; email: string }.

Comparar los elementos del array items como muestras

items es un array, así que tomamos sus tres elementos como muestras y los comparamos. productId y price están en los tres elementos y, además, sus valores son siempre de un único tipo —cadena y número, respectivamente—, por lo que se quedan como string y number.

discountRate es un número en el primer elemento, null en el segundo y en el tercero la clave ni siquiera existe.

Como la existencia varía, se añade el signo de interrogación; y como, cuando existe, el valor puede ser un número o null, se combinan ambos tipos con una unión: discountRate?: number | null.

Los objetos dentro de un array también necesitan un nombre. Si pasamos items al singular, item, y lo usamos como nombre, obtenemos Item. Reuniendo todo, este es el resultado hecho a mano.

interface Customer {
  name: string;
  email: string;
}

interface Item {
  productId: string;
  price: number;
  discountRate?: number | null;
}

interface Root {
  orderId: number;
  customer: Customer;
  couponCode: string;
  items: Item[];
}

Como el ejemplo tiene solo tres elementos en el array, era posible compararlos a mano; sin embargo, las respuestas reales de una API tienen decenas o cientos de elementos y muchas más claves. Por eso aumenta el número de claves que se pasan por alto al compararlas una a una a simple vista.

Compruébalo con nuestra herramienta gratuita.

JSON → tipos de TypeScript

La conversión es inmediata dentro del navegador: el JSON que pegas no se envía a ningún servidor ni se guarda.

Las marcas que más confunden en el código de resultado

SituaciónMarca en el resultadoMotivo
Una clave solo aparece en algunos elementos del arraykey?: TSolo existe en algunas muestras → optional
La misma clave tiene valores de distinto tipokey: A | BEl tipo del valor varía entre muestras → unión
Solo aparece en algunas muestras y además los tipos varíankey?: A | BVarían tanto la existencia como el tipo de valor
Las claves y los tipos de dos objetos distintos tienen exactamente la misma estructuraSe reutiliza la misma interfaceLas estructuras idénticas se unifican bajo un mismo nombre
Objeto anidado / objeto dentro de un arraySe separa en una interface con nombre propioRecibe un nombre basado en el nombre de la clave (PascalCase)

Hay un punto que conviene tener en cuenta: el signo de interrogación y la unión solo se calculan cuando hay varias muestras que comparar. Si pegas únicamente un objeto suelto y el JSON no contiene ningún array, solo hay un elemento de comparación, así que no aparecerán ni el signo de interrogación ni la unión.

Si quieres comprobar varios casos de respuesta a la vez, basta con envolver el propio JSON de nivel superior en un array y pegar varios registros juntos.

El nombre del tipo raíz se puede cambiar en el campo de entrada (el valor predeterminado es Root), y también puedes elegir si declararlo como interface o como type, y si añadir la palabra clave export (activada por defecto).

Sea cual sea el modo de declaración que elijas, las reglas de optional, unión y separación explicadas arriba se aplican igual.

Resumen

  • El optional (?) se determina según si la clave aparece solo en algunas de las muestras.
  • La unión (|) se determina según si el tipo de valor de esa clave varía de una muestra a otra.
  • Cuando se cumplen las dos condiciones, ambas se muestran juntas, como en key?: A | B.
  • Los objetos anidados y los objetos dentro de arrays se convierten en interfaces propias con un nombre basado en el nombre de la clave, y si la estructura es la misma se reutilizan.
  • Si solo introduces un objeto suelto sin arrays, únicamente hay un elemento de comparación, por lo que no aparecen el signo de interrogación ni la unión.
JSON → tipos de TypeScript

La conversión es inmediata dentro del navegador: el JSON que pegas no se envía a ningún servidor ni se guarda.

Preguntas frecuentes

¿Cuál es exactamente el criterio para que se añada un ? (optional)?

Se añade cuando esa clave existe solo en algunos de los elementos del array (las muestras). Si la clave está en todos los elementos, no se añade optional aunque su valor sea null; en ese caso, el hecho de que haya null entre los tipos de valor se indica con una unión.

¿Cuándo aparece una unión (|)?

Aparece cuando, para una misma clave, el tipo de valor (cadena, número, booleano, null, objeto, etc.) varía entre las muestras; en ese caso, los tipos se muestran separados por |. Si solo hay un tipo, se muestra un único tipo sin unión.

¿Por qué los objetos anidados no se incluyen todos en una sola interface, sino que se separan?

Los valores de tipo objeto y los objetos dentro de arrays reciben un nombre formado al convertir el nombre de la clave a PascalCase y se separan en una interface (o un type) propia.

Si dos objetos en posiciones distintas tienen exactamente la misma estructura de claves y tipos, no se crea uno nuevo, sino que se reutiliza la misma interface.

¿El JSON que introduzco se guarda en el servidor?

No. El análisis del JSON y la inferencia de tipos se ejecutan al instante en el navegador cada vez que escribes, y el contenido introducido no se envía ni se guarda en el servidor.

Este artículo está adaptado de nuestro original en coreano. Leer el original en coreano

Artículos relacionados

  1. Convertir JSON a YAML: reglas de listas e indentaciónDescubre cómo los arrays de JSON pasan a listas con guion y los objetos anidados a niveles de indentación, y evita errores de comillas en Kubernetes.
  2. Sintaxis JSONPath: qué selecciona cada símbolo con ejemplosRepasa qué selecciona cada símbolo de JSONPath ($, ., [n], [*], ..) con un JSON de ejemplo y por qué los filtros y slices no están soportados.
  3. Cómo decodificar un JWT: estructura y fecha de expUn JWT no está cifrado, solo codificado: aprende a leer el header y el payload, y a convertir exp e iat en fechas legibles.
  4. Verificar un JWT: cómo comprobar si la firma fue alteradaDescubre cómo se calcula y compara la firma HMAC-SHA256 de un JWT y por qué falla la verificación: clave distinta o token manipulado.
  5. line-clamp CSS: cómo usarlo y por qué no funcionaEntiende por qué line-clamp no funciona sin display: -webkit-box y qué propiedades necesita el truncado de una línea y de varias líneas.
  6. Cómo convertir listas y viñetas a Markdown, HTML o símbolosAprende a cambiar viñetas y números por listas Markdown, etiquetas HTML ul/li o símbolos personalizados, con los errores más comunes al copiar y pegar.

Herramientas relacionadas