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)
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.parsefalla 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 de899. Es el peor, porqueJSON.parselo acepta y el error aparece más adelante: en JavaScript,"899" + 99da"89999". - Campos que faltan o sobran. No viene
inStock, o viene uncolorque nadie pidió.
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
}
}
}
}
modelymax_tokensson los de siempre. Según la documentación, structured outputs está disponible en todos los modelos; su lista incluyeclaude-opus-5-5,claude-sonnet-5-5yclaude-haiku-5-5.messageslleva la petición en lenguaje natural. El esquema no sustituye al prompt: dile qué extraer y de dónde.output_config.formatcontype: "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 encabezadostructured-outputs-2025-11-13y, sin él, la API responde 400.schemaes un JSON Schema normal:requiredcon todos los campos yadditionalProperties: falseen cada objeto, que la API exige.enumlimitacurrencya 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:
| Caso | Qué dice la documentación | Qué hace tu código |
|---|---|---|
| JSON que no parsea | No ocurre con el esquema activo | Lo atrapa igual: cuesta una línea |
| Campos y tipos | Garantizados para los campos de required | Valida con zod y tipa el resultado |
| Negativa | stop_reason: "refusal", estado 200, se cobra y la salida puede no cumplir el esquema | Se detiene sin reintentar |
| Límite de tokens | stop_reason: "max_tokens", salida incompleta; reintentar con más max_tokens | Repite con el doble |
Mayúsculas de un enum | No garantizadas: puede llegar "Conversation Topic 3" cuando el valor es "Conversation topic 3", sin error | Zod lo rechaza y reintenta |
| Orden de las propiedades | Primero las obligatorias, luego las opcionales | No 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\"]}"
}
}
pricesale como unnumbersin restricción:.positive()se volvióexclusiveMinimum: 0y pasó a la descripción, como pista para el modelo. La API no impide un precio negativo.currencytambién sale como texto con una descripción. En la 1.4.0 del SDK, el helper movió elenuma la descripción en lugar de dejarlo en el esquema, aunque la API sí admiteenum. 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:
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.parseo zod: devuelve el error. Agrega la respuesta como turnoassistanty un turnousercon 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.
- La primera línea es fija y dice qué pasó.
- Cada
✖es un problema dez.prettifyError, con su campo en la línea→ at:pricellegó como texto,currencycomo"mxn"einStockcomo"yes". - La última línea pide solo el objeto, sin explicaciones alrededor.
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}`);
}
Productes el esquema de zod: título, precio positivo, monedaMXNoUSD, tallas y disponibilidad. Los datos del ejemplo son ilustrativos.Clientdescribe solo lo que la función usa,messages.create. El cliente real del SDK cumple ese tipo, y uno falso también.extractJsonrecibe el cliente, el esquema, el prompt y opciones: modelo,maxTokens(1024) ymaxAttempts(3). Devuelvez.infer<S>, el tipo que sale del esquema.- Cada intento manda el historial y
output_config: { format: zodOutputFormat(schema) }. El helper incluye una funciónparseque no viaja: al serializar el pedido,JSON.stringifyla descarta. refusallanza un error de inmediato.max_tokensguarda el motivo, duplicamaxTokensy vuelve a pedir sin tocar el historial.- Junta el texto de los bloques
text, lo parsea y lo valida. Si pasa, devuelveresult.data, ya tipado; si no, el motivo es el texto dez.prettifyErroro el mensaje delSyntaxError. - Agrega la respuesta y el mensaje de corrección al historial.
text || "(empty)"evita mandar un turno vacío. - Tras
maxAttemptsintentos, 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);
new Anthropic()lee la clave deANTHROPIC_API_KEY, ysheetes una ficha de proveedor ilustrativa.extractJsondevuelve un objeto con el tipo deProduct:product.priceesnumberyproduct.inStockesboolean, 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
- 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 subamax_tokensa 2048 sin la respuesta cortada. - El pedido lleva
output_config.formatcontype: "json_schema",additionalProperties: falsey los cinco campos enrequired. - Una negativa termina en error después de un solo pedido.
- 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 tusafeParselas hace cumplir. - Dar por hecho que las mayúsculas de un
enumcoinciden. 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 aoutput_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
enumgené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.formatcontype: "json_schema", no solo en el prompt. - Cada objeto tiene
additionalProperties: falsey los campos que necesitas están enrequired. - 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.
refusaldetiene el proceso;max_tokensrepite con más tokens, sin reenviar lo cortado.- Un fallo de
JSON.parseo 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

Publicado el 3 de noviembre de 2026