Saltar al contenido

Cómo hacer que la IA devuelva JSON válido, siempre

En la práctica/ 15 min de lectura

Pedirle «solo JSON» a la IA no basta. Con structured outputs, un esquema de zod y un reintento que le devuelve el error, recibes un objeto válido o un error claro.

  • IA
  • JavaScript
En este artículo (8)
  1. Por qué «responde solo en JSON» no basta
  2. Structured outputs: darle un esquema a la IA
  3. Validar con zod
  4. Reintentar con el error y un límite de intentos
  5. Ejemplo completo en TypeScript
  6. Errores comunes
  7. Preguntas frecuentes
  8. Checklist

Para que la IA devuelva JSON válido siempre, no basta con pedirlo en el prompt: activa structured outputs con un esquema JSON en output_config.format, valida la respuesta con zod y, si falla, reintenta mandándole al modelo el error exacto, con un límite de intentos. Una negativa o un corte por max_tokens se tratan aparte.

Aquí vas a ver qué garantiza structured outputs según la documentación de Anthropic y qué no, cómo validar con zod lo que el esquema no exige y una función en TypeScript que reintenta con el error. La forma del pedido sigue la documentación tal como estaba el 2 de noviembre de 2026, y las pruebas usan un cliente falso: no hicimos ninguna llamada real a la API. Si lo que falla son las instrucciones, empieza por cómo escribir un prompt para crear una landing con IA.

Por qué «responde solo en JSON» no basta

Una instrucción en el prompt es una petición, no un contrato. El modelo casi siempre la cumple, y ese «casi» rompe una integración que corre miles de veces al día, como importar fichas de proveedores. La documentación de structured outputs de Anthropic enumera lo que pasa sin un esquema, aun con un buen prompt: errores de sintaxis al parsear, campos obligatorios que faltan, tipos inconsistentes y violaciones del esquema que te obligan a manejar errores y reintentar.

En la práctica se ve así:

  • Texto alrededor. «Claro, aquí está el producto:» y luego el objeto. JSON.parse falla en el primer carácter.
  • Bloque de markdown. El JSON llega dentro de ```json. Se ve bien en un chat y rompe tu código.
  • Corte por max_tokens. La respuesta se queda a la mitad de un campo.
  • Tipos equivocados. "price": "899" en lugar de 899. Es el peor, porque JSON.parse lo acepta y el error aparece más adelante: en JavaScript, "899" + 99 da "89999".
  • Campos que faltan o sobran. No viene inStock, o viene un color que nadie pidió.
cómo falla el JSON de la IA y quién lo atrapafallocómo se vecon esquemaqué hace el códigotexto antes del JSONClaro, aquí está: {…}no pasaSyntaxError, reintentobloque de markdown```json {…} ```no pasaSyntaxError, reintentocortado en max_tokens{"price":899,"currpuede pasarduplica max_tokenstipo equivocado"price":"899"no pasazod, reintentofalta un camposin "inStock"no pasazod, reintentocampo de más"color":"negro"no pasaz.object lo descartamayúsculas del enum"mxn" en vez de "MXN"puede pasarzod, reintentostructured outputs evita cinco; el corte y el enum, noy lo que la API no exige, como .positive(), solo lo revisa zod

Desliza la figura para verla completa

La solución tiene tres capas: un esquema que el modelo no puede saltarse, una validación en tu código para lo que el esquema no cubre y un reintento con el error para cuando algo falla. Ninguna basta sola.

Structured outputs: darle un esquema a la IA

Structured outputs restringe lo que genera el modelo a un esquema JSON mediante decodificación restringida (constrained decoding). La documentación lo resume en tres promesas: siempre válido, sin errores de JSON.parse(); tipos y campos obligatorios garantizados; y sin reintentos por violaciones del esquema. Se activa en el pedido, con el esquema dentro de output_config.format:

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "messages": [{ "role": "user", "content": "Extract the product from this supplier sheet: …" }],
  "output_config": {
    "format": {
      "type": "json_schema",
      "schema": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "price": { "type": "number" },
          "currency": { "type": "string", "enum": ["MXN", "USD"] },
          "sizes": { "type": "array", "items": { "type": "string" } },
          "inStock": { "type": "boolean" }
        },
        "required": ["title", "price", "currency", "sizes", "inStock"],
        "additionalProperties": false
      }
    }
  }
}
  1. model y max_tokens son los de siempre. Según la documentación, structured outputs está disponible en todos los modelos; su lista incluye claude-opus-5-5, claude-sonnet-5-5 y claude-haiku-5-5.
  2. messages lleva la petición en lenguaje natural. El esquema no sustituye al prompt: dile qué extraer y de dónde.
  3. output_config.format con type: "json_schema" activa la función, y ya no hace falta encabezado beta. El parámetro anterior, output_format, está obsoleto: solo funciona con el encabezado structured-outputs-2025-11-13 y, sin él, la API responde 400.
  4. schema es un JSON Schema normal: required con todos los campos y additionalProperties: false en cada objeto, que la API exige.
  5. enum limita currency a dos valores. Ojo con las mayúsculas, que vemos abajo.

Claude devuelve el JSON en el bloque de texto de la respuesta. Lo que el esquema no admite, según la sección de limitaciones: esquemas recursivos, restricciones numéricas (minimum, maximum, multipleOf), restricciones de cadenas (minLength, maxLength), restricciones de arreglos más allá de minItems 0 o 1, tipos complejos dentro de un enum, $ref externos y additionalProperties distinto de false. Si usas algo de eso, recibes un 400. También hay límites por pedido: 20 herramientas estrictas, 24 parámetros opcionales y 16 con tipos unión.

Y esto es lo que no garantiza, que es lo que tu código tiene que resolver:

CasoQué dice la documentaciónQué hace tu código
JSON que no parseaNo ocurre con el esquema activoLo atrapa igual: cuesta una línea
Campos y tiposGarantizados para los campos de requiredValida con zod y tipa el resultado
Negativastop_reason: "refusal", estado 200, se cobra y la salida puede no cumplir el esquemaSe detiene sin reintentar
Límite de tokensstop_reason: "max_tokens", salida incompleta; reintentar con más max_tokensRepite con el doble
Mayúsculas de un enumNo garantizadas: puede llegar "Conversation Topic 3" cuando el valor es "Conversation topic 3", sin errorZod lo rechaza y reintenta
Orden de las propiedadesPrimero las obligatorias, luego las opcionalesNo depende del orden

Además, es incompatible con las citas (devuelve 400) y con el prefill de la respuesta. Para las entradas de una herramienta existe su pariente, strict tool use: strict: true en la herramienta garantiza que su input cumpla el input_schema. Usan la misma gramática y se pueden combinar.

Validar con zod

Si el esquema ya está garantizado, ¿para qué validar? Por tres razones. La tabla de arriba deja tres huecos: la negativa, el corte y las mayúsculas. Las restricciones que la API no admite no se cumplen solas. Y quieres un objeto tipado en TypeScript, no un unknown.

El SDK de TypeScript, @anthropic-ai/sdk (probamos la 1.4.0), trae zodOutputFormat(), que convierte un esquema de zod en el output_config.format. La documentación explica que los SDK quitan del esquema las restricciones no admitidas y las agregan a la descripción del campo. Esto es lo que generó para price: z.number().positive() y currency: z.enum(["MXN", "USD"]):

{
  "price": {
    "type": "number",
    "description": "{exclusiveMinimum: 0}"
  },
  "currency": {
    "type": "string",
    "description": "{enum: [\"MXN\",\"USD\"]}"
  }
}
  1. price sale como un number sin restricción: .positive() se volvió exclusiveMinimum: 0 y pasó a la descripción, como pista para el modelo. La API no impide un precio negativo.
  2. currency también sale como texto con una descripción. En la 1.4.0 del SDK, el helper movió el enum a la descripción en lugar de dejarlo en el esquema, aunque la API sí admite enum. La gramática no lo exige; solo zod.

Por eso la validación en tu código no es opcional. Product.safeParse(...) devuelve { success, data } o { success, error } sin lanzar excepciones, y z.prettifyError(result.error) convierte el error en texto legible, una línea por problema con su ruta (→ at price): justo lo que el modelo necesita para corregirse. Probado con zod 4.6.7: z.object() descarta en silencio las claves no declaradas (z.strictObject() las rechaza con Unrecognized key: "color"), y un campo que falta da expected boolean, received undefined.

Sobre versiones: el SDK acepta zod ^3.25.0 || ^4.0.0. Con zod 4, import * as z from "zod". En zod 3.25.x, importa desde "zod/v4", un subpath que según la página de versiones de zod se queda para siempre. Con zod 3.25.76 y "zod/v4" pasan las mismas cuatro pruebas; con "zod", zodOutputFormat() falla con Cannot read properties of undefined (reading 'def'). Más en la guía de formato de errores y en la de JSON Schema, que explica z.toJSONSchema(), la función que el helper usa por dentro.

Reintentar con el error y un límite de intentos

Un reintento que solo dice «inténtalo de nuevo» repite el mismo error. Uno que le manda al modelo su respuesta y el error exacto le da algo concreto que corregir. Estas son las reglas que seguimos:

del pedido a la IA a un objeto validadoclient.messages.create()modelo + output_config.formatres.stop_reasonrefusal: para · max_tokens: el dobleJSON.parse(text)si falla: reintento con su mensajeProduct.safeParse(json)si falla: reintento con z.prettifyErrorreturn result.dataobjeto tipado, listo para usarel error vuelve al modelo como mensaje de usuariolínea punteada: reintento, 3 intentos como máximo; una negativa no se reintenta

Desliza la figura para verla completa

  • Negativa (refusal): para. Repetir el mismo pedido no cambia la decisión, y cada intento se cobra. Lanza un error para que lo revise una persona.
  • Corte (max_tokens): repite con el doble. Es lo que recomienda la documentación. La respuesta cortada no se reenvía: no tiene nada que corregir, solo le faltó espacio.
  • Falla JSON.parse o zod: devuelve el error. Agrega la respuesta como turno assistant y un turno user con el error y la instrucción de responder solo con el objeto corregido. El último mensaje es del usuario, así que no es un prefill.
  • Límite de intentos. Tres por defecto. Al llegar, un error con el último motivo, para registrarlo y revisarlo, en lugar de un bucle que gasta tokens sin fin.

Este es el mensaje que armó nuestra función cuando el cliente falso devolvió tipos equivocados:

Your reply does not match the JSON schema:
✖ Invalid input: expected number, received string
  → at price
✖ Invalid option: expected one of "MXN"|"USD"
  → at currency
✖ Invalid input: expected boolean, received string
  → at inStock
Reply again with only the corrected JSON object.
  1. La primera línea es fija y dice qué pasó.
  2. Cada ✖ es un problema de z.prettifyError, con su campo en la línea → at: price llegó como texto, currency como "mxn" e inStock como "yes".
  3. La última línea pide solo el objeto, sin explicaciones alrededor.
el error de JSON que vuelve al modelo1 · respuesta del modelo (assistant)```json{"title":"Sudadera Volcán","price":899,…}```no empieza con {2 · el reintento (user)Your reply does not match the JSON schema:encabezado fijoUnexpected token '`', "```jsonerr.message de JSON.parse,{""... is not valid JSONcopiado tal cualReply again with only the corrected JSON object.pide solo el objeto3 · si falla zod, en su lugar va✖ Invalid input: expected number, received string→ at pricez.prettifyError(result.error)una línea por problemavuelve el error exacto, no un «inténtalo de nuevo»una respuesta cortada por max_tokens no se reenvía: se repite con el doble

Desliza la figura para verla completa

Ejemplo completo en TypeScript

Todo junto es una función, extractJson, en extract.ts. Recibe el cliente como argumento: en producción le pasas el del SDK y en las pruebas uno falso.

import type Anthropic from "@anthropic-ai/sdk";
import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";
import * as z from "zod";

export const Product = z.object({
  title: z.string(),
  price: z.number().positive(),
  currency: z.enum(["MXN", "USD"]),
  sizes: z.array(z.string()),
  inStock: z.boolean(),
});

type Client = {
  messages: { create(body: Anthropic.MessageCreateParamsNonStreaming): Promise<Anthropic.Message> };
};

export async function extractJson<S extends z.ZodType>(
  client: Client,
  schema: S,
  prompt: string,
  { model = "claude-sonnet-5-5", maxTokens = 1024, maxAttempts = 3 } = {},
): Promise<z.infer<S>> {
  const messages: Anthropic.MessageParam[] = [{ role: "user", content: prompt }];
  let lastError = "";

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const res = await client.messages.create({
      model,
      max_tokens: maxTokens,
      messages,
      output_config: { format: zodOutputFormat(schema) },
    });

    if (res.stop_reason === "refusal") {
      throw new Error("The model refused the request; retrying will not change that.");
    }
    if (res.stop_reason === "max_tokens") {
      lastError = `output cut off at max_tokens=${maxTokens}`;
      maxTokens *= 2;
      continue;
    }

    const text = res.content.flatMap((block) => (block.type === "text" ? [block.text] : [])).join("");
    try {
      const result = schema.safeParse(JSON.parse(text));
      if (result.success) return result.data;
      lastError = z.prettifyError(result.error);
    } catch (err) {
      lastError = (err as Error).message;
    }

    messages.push(
      { role: "assistant", content: text || "(empty)" },
      {
        role: "user",
        content: `Your reply does not match the JSON schema:\n${lastError}\nReply again with only the corrected JSON object.`,
      },
    );
  }

  throw new Error(`No valid JSON after ${maxAttempts} attempts. Last error: ${lastError}`);
}
  1. Product es el esquema de zod: título, precio positivo, moneda MXN o USD, tallas y disponibilidad. Los datos del ejemplo son ilustrativos.
  2. Client describe solo lo que la función usa, messages.create. El cliente real del SDK cumple ese tipo, y uno falso también.
  3. extractJson recibe el cliente, el esquema, el prompt y opciones: modelo, maxTokens (1024) y maxAttempts (3). Devuelve z.infer<S>, el tipo que sale del esquema.
  4. Cada intento manda el historial y output_config: { format: zodOutputFormat(schema) }. El helper incluye una función parse que no viaja: al serializar el pedido, JSON.stringify la descarta.
  5. refusal lanza un error de inmediato. max_tokens guarda el motivo, duplica maxTokens y vuelve a pedir sin tocar el historial.
  6. Junta el texto de los bloques text, lo parsea y lo valida. Si pasa, devuelve result.data, ya tipado; si no, el motivo es el texto de z.prettifyError o el mensaje del SyntaxError.
  7. Agrega la respuesta y el mensaje de corrección al historial. text || "(empty)" evita mandar un turno vacío.
  8. Tras maxAttempts intentos, lanza un error con el último motivo.

Con el SDK se usa así. Este archivo pasa el chequeo de tipos de TypeScript 5.7.3 en modo estricto, pero no lo ejecutamos: necesita una clave de API y no le mandamos datos a la API de Anthropic.

import Anthropic from "@anthropic-ai/sdk";
import { extractJson, Product } from "./extract.ts";

const client = new Anthropic(); // reads ANTHROPIC_API_KEY
const sheet = "Sudadera Volcán, algodón 100 %, tallas S a L, $899 MXN, disponible.";
const product = await extractJson(client, Product, `Extract the product from this supplier sheet:\n${sheet}`);
console.log(product.price, product.inStock);
  1. new Anthropic() lee la clave de ANTHROPIC_API_KEY, y sheet es una ficha de proveedor ilustrativa.
  2. extractJson devuelve un objeto con el tipo de Product: product.price es number y product.inStock es boolean, sin conversiones a mano.

Si no necesitas reintentos, el SDK tiene client.messages.parse(), que valida y devuelve parsed_output. En la 1.4.0 lanza un AnthropicError si fallan el JSON o zod, y no mira stop_reason: una respuesta cortada llega como un error de parseo más. Por eso aquí usamos create() y validamos nosotros.

Para las pruebas, un cliente falso guarda cada pedido tal como saldría por la red (JSON.parse(JSON.stringify(body))) y devuelve, en orden, cinco respuestas: el JSON dentro de un bloque ```json, texto antes del JSON, tipos equivocados, una respuesta cortada con stop_reason: "max_tokens" y, al final, el JSON válido. Lo corrimos con Node 22.22.3, que ejecuta archivos .ts sin opciones extra, zod 4.6.7 y @anthropic-ai/sdk 1.4.0. Esta es la salida:

$ node --test --test-reporter=spec extract.test.ts
✔ retries each failure with its error and returns the valid object (9.5142ms)
✔ sends the schema in output_config.format (0.5039ms)
✔ stops on a refusal without retrying (0.6876ms)
✔ gives up after maxAttempts (1.6116ms)
ℹ tests 4
ℹ suites 0
ℹ pass 4
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 257.4801
  1. Con maxAttempts: 5, la función pasa por las cinco respuestas y devuelve el objeto válido. La prueba revisa el error que lleva cada reintento y que el quinto pedido suba max_tokens a 2048 sin la respuesta cortada.
  2. El pedido lleva output_config.format con type: "json_schema", additionalProperties: false y los cinco campos en required.
  3. Una negativa termina en error después de un solo pedido.
  4. Tres respuestas inválidas seguidas terminan en No valid JSON after 3 attempts, sin un cuarto pedido.

Errores comunes

  • Confiar solo en el prompt. «Responde solo en JSON» funciona casi siempre. Para algo que corre sin supervisión, usa el esquema.
  • «Reparar» el JSON con expresiones regulares. Quitar las comillas invertidas o recortar del primer { al último } esconde el problema y no detecta un corte. Nuestra recomendación: trata cualquier texto que no parsea como un fallo y reintenta con el error.
  • Reintentar sin el error, o sin límite. Sin el error, el modelo no sabe qué corregir; sin tope, el bucle gasta tokens hasta que alguien lo nota.
  • Reintentar una negativa o reenviar una respuesta cortada. La primera no cambia; la segunda necesita más max_tokens, no una corrección.
  • Creer que el esquema exige .positive() o .min(). La API no admite esas restricciones: el SDK las pasa a la descripción y solo tu safeParse las hace cumplir.
  • Dar por hecho que las mayúsculas de un enum coinciden. No están garantizadas. Nuestra función rechaza el valor y reintenta; para no gastar un intento, normalízalo antes de validar.
  • Importar zod 3 con el helper del SDK. En zod 3.25.x, "zod" es la versión 3 y el helper falla; importa desde "zod/v4".
  • Seguir con output_format. Está obsoleto y, sin su encabezado beta, da 400. Pásalo a output_config.format.
  • Poner datos sensibles en el esquema. El esquema se guarda en caché hasta 24 horas, aparte de los mensajes, y la documentación prohíbe incluir datos de salud protegidos (PHI) en él. Usa nombres de campo y valores de enum genéricos.

Preguntas frecuentes

¿Qué modelos de Claude admiten structured outputs?

Según la documentación consultada el 2 de noviembre de 2026, todos. La lista incluye claude-opus-5-5, claude-sonnet-5-5 y claude-haiku-5-5, además de modelos anteriores como claude-haiku-4-5-20251001. Es una función estable: con output_config.format no necesitas encabezado beta.

¿Structured outputs o strict tool use?

Resuelven cosas distintas. Structured outputs (output_config.format) controla la respuesta de Claude, lo que dice. Strict tool use (strict: true en una herramienta) garantiza los argumentos con los que llama a tus funciones. Para extraer datos y usarlos en tu código, structured outputs; para un agente que llama herramientas, strict tool use. Se pueden usar juntos en el mismo pedido.

¿Necesito zod si ya uso structured outputs?

Sí. Cubre lo que el esquema no garantiza (cortes, negativas, mayúsculas de un enum), hace cumplir lo que la API no admite, como un precio positivo, y te da el tipo en TypeScript. Si cambias de modelo o de proveedor, la validación sigue igual.

¿Por qué el primer pedido con un esquema tarda más?

Porque la API compila el esquema en una gramática la primera vez que lo ve. Según la documentación, la gramática queda en caché 24 horas desde el último uso y cambiar la estructura del esquema la invalida. Ojo: cambiar output_config.format también invalida el caché de prompts de esa conversación.

Checklist

  • El pedido lleva el esquema en output_config.format con type: "json_schema", no solo en el prompt.
  • Cada objeto tiene additionalProperties: false y los campos que necesitas están en required.
  • El esquema no usa nada que la API no admita, o lo convierte el helper del SDK.
  • Tu código valida con zod cada respuesta, también con structured outputs activo.
  • refusal detiene el proceso; max_tokens repite con más tokens, sin reenviar lo cortado.
  • Un fallo de JSON.parse o de zod vuelve al modelo con el error exacto.
  • Hay un límite de intentos y un error claro al llegar a él.
  • Con zod 3.25.x importas desde "zod/v4".
  • Las pruebas usan un cliente falso con respuestas rotas, sin llamar a la API.

Un esquema, una validación y un reintento con el error convierten «casi siempre JSON» en un objeto válido o en un error que puedes revisar. Si el modelo sigue sin entender qué extraer, el problema está en las instrucciones: revisa cómo armar un prompt para crear una landing con IA y qué contexto darle a un agente de IA. Y cuando el fallo esté en tu código y no en la respuesta, mira cómo reportarle un bug a la IA.

¿Viste esto en Instagram? Comenta JSON en el Reel y te mando la guía.

Escrito por

Luis Morales

Luis Morales

Desarrollador frontend y Shopify, EcomLabs

@luismoralesdev en Instagram

Publicado el 3 de noviembre de 2026

← Blog