Imagen del ecosistema JSON

En el desarrollo moderno, JSON es más que un formato de datos: es el “contrato” que conecta el frontend y el backend. A partir de una sola muestra JSON puedes derivar definiciones de tipos, validación en tiempo de ejecución y documentación de API. Esa es la fortaleza del ecosistema JSON.

Usando una respuesta de API como ejemplo, este artículo conecta el flujo de formatear → generar tipos → validar → definir la API con código real.

El punto de partida: una respuesta JSON

Usaremos esta respuesta de información de usuario como ejemplo.

{
  "id": 42,
  "name": "Alice",
  "email": "[email protected]",
  "roles": ["admin"],
  "createdAt": "2026-06-19T10:00:00Z"
}

Esta única muestra es el punto de partida de todo lo que sigue.

Paso 1: Formatear para entender la estructura

El JSON del mundo real a menudo llega en una sola línea, lo que hace ilegible la estructura. Primero, usa el formateador JSON para formatearlo y revisar la profundidad de anidamiento, si los valores son arreglos y el tipo de cada valor. Solo tras formatear se hace clara una estructura como “¿es roles un arreglo o un valor único?”.

Paso 2: Generar los tipos de TypeScript

Una vez entendida la estructura, crea el tipo de TypeScript correspondiente.

interface User {
  id: number;
  name: string;
  email: string;
  roles: string[];
  createdAt: string;
}

Con el generador de JSON → TypeScript, obtienes este tipo con solo pegar. Ahora la comprobación de tipos en tiempo de compilación está activa.

Paso 3: Garantizar la seguridad en tiempo de ejecución con Zod

Un tipo de TypeScript es solo una comprobación en tiempo de compilación. No hay garantía de que una API externa devuelva realmente datos que coincidan con tus tipos: un cambio de especificación o un error pueden romper la forma. Para la validación en tiempo de ejecución, prepara un esquema de Zod.

import { z } from "zod";

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  roles: z.array(z.string()),
  createdAt: z.string().datetime(),
});

// Deriva el tipo a partir del esquema
type User = z.infer<typeof UserSchema>;

// Valida en el punto de entrada
const user = UserSchema.parse(await res.json());

Con z.infer, derivas el tipo de TypeScript a partir del esquema, de modo que gestionas tipos y validación en un solo lugar. Los datos no válidos se rechazan con una excepción justo en parse.

Paso 4: Convertirlo en un lenguaje común con OpenAPI

Por último, convertir el mismo JSON en un esquema de especificación de API (OpenAPI / Swagger) te da un “lenguaje común” para frontend, backend, QA y socios externos.

components:
  schemas:
    User:
      type: object
      properties:
        id:       { type: integer }
        name:     { type: string }
        email:    { type: string, format: email }
        roles:    { type: array, items: { type: string } }
        createdAt: { type: string, format: date-time }

El generador de JSON → OpenAPI te da un primer borrador rápido de este esquema, reduciendo el esfuerzo de documentación para que dediques tiempo a las discusiones de diseño.

El panorama: un JSON, muchas salidas

        Respuesta JSON real
               │
   ┌───────────┼────────────────┬────────────────┐
 Formato    Tipos TS       Esquema Zod        OpenAPI
(entender) (estática)   (en tiempo de ejec.) (espec. común)

El punto clave: no son tareas separadas, sino un flujo único derivado de una sola muestra. Partir de datos reales evita el desfase entre la documentación y la implementación, y entre los tipos y la validación.

Preguntas frecuentes

Si tengo tipos de TypeScript, ¿aún necesito Zod?

Los tipos solo funcionan en tiempo de compilación y no validan los datos que realmente llegan en tiempo de ejecución. Para “entradas no confiables” —API externas, formularios, LocalStorage— combínalos con validación en tiempo de ejecución como Zod. Para datos internos de confianza, los tipos solos pueden bastar.

¿Debo gestionar los datos en YAML o JSON?

El tráfico de API máquina a máquina encaja con JSON; los archivos de configuración editados por humanos (CI/CD, Kubernetes, etc.) encajan con YAML, que permite comentarios. Ambos son interconvertibles con el conversor JSON ⇔ YAML, así que usa cada uno donde corresponda.

¿Basta con una sola muestra para generar tipos?

Una sola muestra se pierde campos opcionales y valores que pueden ser null. Usa una respuesta representativa con tantos campos como sea posible y luego añade ? o | null a mano para que coincida con la especificación.