🔍 TL;DR
El modo JSON impone la sintaxis JSON, no la conformidad del esquema — los campos faltantes, los tipos incorrectos y los valores de enum no válidos requieren correcciones en el prompt. Tres técnicas cierran la brecha: (1) incrustar el esquema como plantilla JSON directamente en el prompt, (2) incluir un ejemplo de salida válida, (3) añadir una instrucción por campo que cubra tipo, formato y manejo de null. Apunta a un 95%+ de tasa de aprobación en un conjunto de prueba de 20 casos antes de desplegar. Usa YAML en lugar de JSON para prompts libres sin enforcement de API — los modelos producen menos errores de sintaxis.
El diseño del prompt determina la fiabilidad de la salida estructurada
📍 In One Sentence
La fiabilidad de salida estructurada es el porcentaje de respuestas del modelo que son analizables, contienen todos los campos requeridos, usan tipos de datos correctos y tienen valores de enum válidos — el modo JSON garantiza solo el primero de estos cuatro.
💬 In Plain Terms
Piensa en el modo JSON como el corrector ortográfico: detecta errores de sintaxis pero no errores de significado. Un prompt que solo se basa en el modo JSON es como un documento que pasó el corrector ortográfico — estructuralmente válido pero potencialmente incompleto o con tipos incorrectos.
Las APIs de modo JSON y tool_use imponen JSON analizable, pero no garantizan la completitud de campos, los tipos de datos correctos o los valores de enum válidos — esos fallos requieren correcciones a nivel de prompt, no cambios en la API. Los fallos más comunes de salida estructurada ocurren dentro de JSON sintácticamente válido: campos requeridos faltantes porque el modelo los trató como opcionales, fechas formateadas como cadenas relativas en lugar de ISO 8601, valores de enum mal escritos o abreviados, y campos nullable que devuelven cadenas vacías en lugar de null.
Tres intervenciones a nivel de prompt cierran consistentemente la brecha de fiabilidad. La incrustación del esquema hace que la estructura de salida sea inequívoca. Un solo ejemplo de salida válida elimina la ambigüedad de formato. Las instrucciones a nivel de campo eliminan los errores de tipo y manejo de null. Juntas, estas tres elevan la fiabilidad de salida estructurada al 95%+ en GPT-4o, Claude 4.6 Sonnet y Gemini 2.5 Pro — con o sin modo JSON nativo.
| Tipo de fallo | Qué lo causa en el prompt | Corrección en el prompt |
|---|---|---|
| Campo requerido faltante | El modelo infiere que el campo es opcional a partir de la descripción en lenguaje natural | Etiqueta cada campo requerido explícitamente: "title REQUIRED" o lista los campos requeridos por separado |
| Tipo de datos incorrecto | Nombre de campo ambiguo sin anotación de tipo | Añade anotación de tipo en el prompt: "amount (integer, not string)" |
| Valor de enum no válido | Enum no listado completo — el modelo inventa un valor plausible | Lista todos los valores de enum explícitamente: "status: one of 'active', 'inactive', 'pending'" |
| Confusión null vs cadena vacía | Sin instrucción que distinga null de "" | Añade: "Return null if unknown. Never return empty string for unknown values." |
| Campos extra no declarados | El modelo añade contexto útil no incluido en el esquema | Añade: "Return only the fields specified. Do not add fields not listed in the schema." |
Incrustar el esquema directamente en el prompt
Incrusta el esquema de salida esperado como plantilla JSON directamente en el prompt, no como descripción en lenguaje natural. Los modelos que ven la estructura antes de generarla producen menos omisiones de campos y errores de tipo que los modelos que solo reciben una descripción en prosa de lo que quieres.
Un esquema en el prompt usa el formato exacto que esperas en la salida: nombres de campos, profundidad de anidamiento y marcadores de posición de valores. Coloca la plantilla del esquema después de tu instrucción de tarea y antes de cualquier ejemplo. Usa valores de marcador de posición que comuniquen el tipo esperado: `"amount": 0` comunica integer; `"amount": 0.00` comunica float; `"created_at": "YYYY-MM-DDTHH:MM:SSZ"` comunica el formato ISO 8601 que esperas.
❌ Solo descripción en lenguaje natural
Extrae los detalles del pedido del siguiente texto y devuélvelos como JSON. Incluye el ID del pedido, el nombre del cliente, el importe total, los artículos pedidos y el estado del pedido. Texto: {{text}}
✅ Esquema incrustado como plantilla JSON
Extrae los detalles del pedido del siguiente texto y devuélvelos como JSON que coincida exactamente con este esquema: { "order_id": "string", "customer_name": "string", "total_amount": 0.00, "status": "string", "items": [ { "name": "string", "quantity": 0, "unit_price": 0.00 } ] } Devuelve solo JSON válido. No incluyas ningún texto fuera del objeto JSON. Texto: {{text}}
Mostrar al modelo un ejemplo de salida válida
Añadir un ejemplo de salida concreto y realista al prompt eleva la fiabilidad de la salida estructurada en 5–8 puntos porcentuales en comparación con prompts que solo tienen esquema. El ejemplo muestra al modelo el formato exacto, el orden de los campos, el estilo de los valores y la convención de comillas que esperas — reduciendo la ambigüedad que la definición del esquema por sí sola no puede eliminar.
Coloca el ejemplo después de la plantilla del esquema y etiquétalo claramente ("Ejemplo de salida:" o "Aquí hay una respuesta válida:"). Usa valores de marcador de posición realistas — no "foo", "bar" o "ejemplo" — porque los modelos aprenden del estilo de los valores.
❌ Solo esquema — sin ejemplo de salida
Extrae los detalles del producto de la reseña a continuación y devuelve JSON con este esquema: { "product_name": "string", "rating": 0, "sentiment": "string", "key_features": ["string"] } Reseña: {{review}}
✅ Esquema + un ejemplo de salida realista
Extrae los detalles del producto de la reseña a continuación y devuelve JSON con este esquema: { "product_name": "string", "rating": 0, "sentiment": "string", "key_features": ["string"] } Ejemplo de salida: { "product_name": "Auriculares WH-1000XM5", "rating": 4, "sentiment": "positive", "key_features": ["cancelación de ruido", "batería de 30 horas", "ajuste cómodo"] } Reseña: {{review}}
Escribir instrucciones a nivel de campo para salida de alto riesgo
Para prompts de producción donde la corrección de los campos es crítica, añade una instrucción por campo requerido: el tipo de datos, el formato esperado, el manejo de null y los valores de enum permitidos donde corresponda. Las instrucciones a nivel de campo eliminan la ambigüedad que causa errores de tipo.
Las instrucciones de campo van en una sección separada después de la plantilla del esquema, antes del ejemplo. Etiqueta la sección "Requisitos de campo:" o "Reglas del esquema:". Mantén cada instrucción en una oración.
| Tipo de campo | Patrón de instrucción | Instrucción de ejemplo |
|---|---|---|
| String | Formato, longitud máxima, caracteres no permitidos | "title (string, máx 100 caracteres, sin etiquetas HTML)" |
| Number | Integer vs float, precisión, unidades | "price (float, exactamente 2 decimales, USD, sin símbolo de moneda)" |
| Date | Formato, zona horaria | "created_at (string, ISO 8601: YYYY-MM-DDTHH:MM:SSZ, zona horaria UTC)" |
| Enum | Todos los valores permitidos listados verbatim | "status (string, exactamente uno de: 'active', 'inactive', 'pending')" |
| Boolean | solo true/false — rechazar yes/no/1/0 | "is_verified (boolean, solo true o false — no 1/0 ni yes/no)" |
| Nullable | Cuándo devolver null vs cadena vacía vs omitir | "description (string o null — devuelve null si desconocido, cadena vacía solo si se sabe que está en blanco)" |
| Array | Mínimo/máximo de elementos, tipo de elemento, manejo de array vacío | "tags (array de strings, 0–5 elementos, devuelve [] si ninguno — nunca devuelve null)" |
❌ Solo esquema — sin instrucciones de campo
Devuelve JSON con estos campos: { "invoice_id": ..., "amount": ..., "due_date": ..., "status": ..., "line_items": [...] }
✅ Esquema + instrucciones a nivel de campo
Devuelve JSON con estos campos: { "invoice_id": "string", "amount": 0.00, "due_date": "YYYY-MM-DD", "status": "string", "line_items": [{"description": "string", "quantity": 0, "unit_price": 0.00}] } Requisitos de campo: - invoice_id: string, formato INV-XXXXXX (ej. INV-004821) - amount: float, 2 decimales, total USD incluyendo impuestos - due_date: string, fecha ISO 8601 (YYYY-MM-DD), no un datetime - status: string, exactamente uno de: 'paid', 'unpaid', 'overdue', 'cancelled' - line_items: array de objetos, 1 o más elementos, devuelve [] si no se encuentran líneas - Si no se puede determinar ningún campo, devuelve null para ese campo
Elige JSON para APIs, YAML para prompts, CSV para datos tabulares
Usa JSON cuando la salida se alimenta en una API o base de datos con enforcement de JSON disponible. Usa YAML para prompts libres sin enforcement de API — los modelos producen menos errores de sintaxis en YAML porque no requiere llaves de cierre, secuencias de escape ni conciencia de comas finales. Usa CSV solo para datos tabulares planos.
La diferencia de fiabilidad entre JSON y YAML en prompting libre (sin enforcement de API) proviene de la complejidad de la sintaxis. JSON requiere que cada cadena esté entre comillas, cada objeto esté cerrado con una llave y cada coma sea correcta. YAML usa sangría en su lugar — que los modelos manejan de forma más consistente.
- Usa JSON si tu sistema posterior tiene un analizador JSON y el enforcement de API está disponible — el enforcement elimina los errores de sintaxis por completo
- Usa YAML si generas sin enforcement de API y tu equipo convierte a JSON antes del procesamiento posterior
- Usa CSV solo para datos tabulares planos — en el momento en que necesites un objeto anidado o un array en una celda, cambia a JSON o YAML
- Usa tablas Markdown solo para salida legible por humanos — no son analizables por máquinas sin herramientas adicionales
| Formato | Fiabilidad sin enforcement de API | Mejor para | Evita cuando |
|---|---|---|---|
| JSON | 80–85% con esquema en el prompt | APIs, bases de datos, consumidores con tipo seguro | No hay enforcement de API y está involucrado anidamiento complejo |
| YAML | 88–92% con esquema en el prompt | Salida legible por humanos, datos estilo configuración, sin enforcement de API | El sistema posterior requiere JSON sin un paso de conversión |
| XML | 85–90% con esquema en el prompt | Transformación de documentos, integración con sistemas heredados | Datos simples de clave-valor (XML añade verbosidad innecesaria) |
| CSV | 95%+ para datos planos | Datos tabulares, exportaciones a hojas de cálculo, pipelines de datos | Los datos tienen estructura anidada o jerárquica |
| Tablas Markdown | Alta para tablas simples | Informes, documentación, salida tabular legible por humanos | Se requiere procesamiento posterior legible por máquinas |
Pedir al modelo que corrija su propia salida malformada
Cuando un prompt de salida estructurada falla la validación, envía un prompt de corrección que contenga la instrucción original, la salida malformada y el error de validación específico. Los modelos recuperan salida válida de sus propias respuestas malformadas en el 60–75% de los casos sin reescribir el prompt por completo.
Un prompt de corrección tiene tres partes requeridas: (1) una reafirmación de cómo debe ser la salida (el esquema o formato), (2) la salida malformada exactamente como la devolvió el modelo, y (3) el error de validación específico — "campo requerido 'invoice_id' faltante", "amount es una cadena, se esperaba float".
❌ Reintento vago — sin contexto de error
Devolviste una salida no válida. Por favor, inténtalo de nuevo y devuelve JSON válido. {{original_prompt}}
✅ Prompt de corrección con esquema, salida y errores específicos
Tu respuesta anterior falló la validación. Corrige solo los errores listados a continuación y devuelve el JSON corregido. Esquema esperado: { "invoice_id": "string", "amount": 0.00, "status": "string" } Tu respuesta anterior: { "invoice_id": null, "amount": "150.00", "status": "PAID" } Errores de validación: - invoice_id es null pero es un campo de cadena requerido — extráelo de la entrada - amount es una cadena ("150.00") pero debe ser un float (150.00) - status debe ser en minúsculas: usa 'paid', no 'PAID' Devuelve solo el objeto JSON corregido.
Patrones de prompt para arrays, enums y campos nullable
Los arrays, enums y campos nullable son las tres fuentes más comunes de fallos de salida estructurada que el esquema en el prompt por sí solo no previene. Cada uno requiere un patrón de instrucción específico en el prompt.
| Tipo de datos | Fallo común | Patrón de prompt que lo previene |
|---|---|---|
| Array (0 elementos) | El modelo devuelve null en lugar de [] | "Devuelve un array vacío [] si no hay elementos presentes. Nunca devuelves null para campos de array." |
| Array (1+ elementos) | El modelo devuelve un objeto único en lugar de array cuando solo se encuentra un elemento | "Siempre devuelve un array, incluso cuando solo hay un elemento. Los elementos únicos deben estar envueltos: {...}" |
| Enum (2–5 valores) | El modelo abrevia o inventa valores similares | "status: exactamente uno de: 'active', 'inactive', 'pending' — sin abreviaturas ni variantes" |
| Enum (6+ valores) | El modelo inventa valores que no están en la lista | Lista todos los valores en una lista numerada, luego: "Usa solo los valores de la lista anterior. No abrevies ni combines valores." |
| Campo nullable | El modelo devuelve "" en lugar de null, u omite el campo por completo | "Devuelve null si el valor es desconocido. Devuelve cadena vacía '' solo si se sabe que el campo está en blanco. Siempre incluye el campo — no lo omitas." |
| Integer vs float | El modelo devuelve float cuando se espera integer, o cadena para ambos | "score (integer — sin decimales, ej. 4 no 4.0)" o "price (float — exactamente 2 decimales, ej. 12.99 no 13)" |
| Objeto anidado | El modelo aplana el objeto anidado a claves planas (ej. "address.city" en lugar de {"address": {"city": ...}}) | Muestra la estructura anidada completa en la plantilla del esquema con sangría correcta. La descripción en lenguaje natural del anidamiento frecuentemente se aplana a claves planas. |
Medir la fiabilidad de la salida estructurada de tu prompt
Apunta a una tasa de aprobación del 95%+ en un conjunto de prueba de 20 casos antes de desplegar cualquier prompt de salida estructurada en producción. Mide la fiabilidad a nivel de campo, no solo en general.
- 1Define criterios de aprobación/fallo para cada campo del esquema. Para cada campo: el tipo es correcto, el campo requerido está presente, el valor de enum está en la lista permitida, el formato de fecha coincide con el patrón requerido.
- 2Construye un conjunto de prueba de 20 casos. Diez entradas de ruta feliz (datos típicos y bien formados), cinco casos límite (campos opcionales faltantes, texto largo, valores inusuales), cinco entradas adversariales (instrucciones incrustadas en valores de campos, fechas extremas, tipos ambiguos).
- 3Ejecuta a temperatura 0 y registra aprobación/fallo por campo. Ejecuta los 20 casos a temperatura 0 para obtener resultados deterministas y repetibles. Registra si cada campo aprueba o falla en cada caso de prueba.
- 4Corrige el campo con la tasa de aprobación más baja y vuelve a probar. Añade o refuerza una instrucción de campo: tipo, formato, manejo de null o valores de enum. Vuelve a ejecutar los 20 casos. Una adición de instrucción dirigida normalmente eleva la tasa de aprobación general en 5–15 puntos porcentuales.
- 5Valida el prompt en un segundo modelo. Ejecuta el conjunto completo de 20 casos contra un segundo modelo usando el mismo prompt. Un prompt al 95%+ en GPT-4o pero al 70% en Claude 4.6 Sonnet es dependiente del modelo.
5 errores comunes en prompts de salida estructurada
Los cinco errores más comunes en prompts de salida estructurada producen todos el mismo síntoma — fallos intermitentes o sistemáticos — pero requieren correcciones diferentes.
❌ Describir el esquema en lenguaje natural en lugar de incrustarlo
Why it hurts: Las descripciones en lenguaje natural son ambiguas — "una lista de elementos" podría significar un array, una cadena separada por comas o una lista numerada
Fix: Incrusta el esquema esperado como plantilla JSON directamente en el prompt.
❌ No especificar cómo manejar valores faltantes o desconocidos
Why it hurts: Los modelos inventan valores plausibles para campos desconocidos en lugar de devolver null — las fechas se convierten en "desconocido", los importes en 0, los IDs faltantes en "N/A"
Fix: Añade manejo explícito de null para cada campo nullable: "Devuelve null si el valor no se puede determinar. No adivines ni inventes valores."
❌ Probar solo contra el modelo en el que se desarrolló el prompt
Why it hurts: La fiabilidad de salida estructurada varía significativamente entre modelos — un prompt al 95% en GPT-4o puede fallar al 70% en Claude 4.6 Sonnet
Fix: Ejecuta cada prompt de salida estructurada contra al menos 2 modelos antes de tratarlo como agnóstico al modelo.
❌ Reintentar la salida fallida con exactamente el mismo prompt
Why it hurts: Un prompt fallido reintentado a temperatura 0 produce el mismo fallo cada vez
Fix: Usa un prompt de corrección con el error de validación específico y la salida malformada, o diagnostica el patrón de fallo y añade una instrucción de campo dirigida al prompt base.
❌ Tratar el modo JSON como una solución completa de salida estructurada
Why it hurts: El modo JSON previene la salida no analizable pero no los fallos de conformidad del esquema — un modelo usando el modo JSON puede devolver JSON válido con campos faltantes, tipos incorrectos y valores de enum no válidos
Fix: Siempre incluye el esquema en el prompt e instrucciones de campo incluso cuando uses el modo JSON impuesto por API.
Preguntas frecuentes
Las preguntas más comunes sobre el prompting de salida estructurada cubren el límite entre el modo JSON y el diseño del prompt, cuántos ejemplos incluir y cómo mejorar sistemáticamente un prompt que falla.
¿El modo JSON hace innecesario el esquema en el prompt?
No. El modo JSON impone la sintaxis JSON analizable, no la conformidad del esquema. Un modelo usando el modo JSON puede devolver JSON válido con campos requeridos faltantes, tipos de datos incorrectos o valores de enum no válidos. El esquema en el prompt y las instrucciones de campo abordan los fallos de conformidad del esquema; el modo JSON solo previene la salida no analizable. Los dos enfoques son complementarios, no alternativos.
¿Cuántos ejemplos de salida debo incluir en el prompt?
Un ejemplo suele ser suficiente y añade la mayor ganancia de fiabilidad. Un segundo ejemplo añade valor solo cuando tus datos tienen una estructura significativamente diferente dependiendo de las condiciones de entrada. Más allá de dos ejemplos, el costo de longitud del prompt supera el beneficio de fiabilidad para la mayoría de las tareas de salida estructurada.
¿Debo usar JSON o YAML para salida estructurada sin enforcement de API?
Usa YAML cuando generas sin enforcement de API y la salida no necesita ser analizada por un sistema que espera JSON. Los modelos producen menos errores de sintaxis en YAML porque no requiere llaves de cierre, secuencias de escape ni seguimiento de comas finales. Usa JSON cuando la salida se alimenta directamente en una API, base de datos o sistema posterior que requiere JSON.
¿Cuál es la forma más rápida de mejorar un prompt con una tasa de aprobación del 70%?
Ejecuta el conjunto de prueba a nivel de campo, no solo en general. Encuentra el campo con la tasa de aprobación individual más baja, añade una instrucción explícita que cubra tipo, formato y manejo de null, luego vuelve a ejecutar. Una sola instrucción de campo dirigida normalmente eleva la tasa de aprobación general en 5–15 puntos porcentuales.
¿Cómo obtengo salida estructurada fiable de un modelo sin modo JSON nativo?
Incrusta el esquema JSON completo como plantilla en el prompt, incluye un ejemplo de salida válida, añade instrucciones a nivel de campo y ejecuta a temperatura 0. Analiza y valida cada salida; envía un prompt de corrección para cualquier fallo de validación. Los prompts bien diseñados alcanzan 85–92% de fiabilidad en la mayoría de los modelos a temperatura 0 sin modo JSON nativo.
¿Cuál es el tamaño correcto del conjunto de prueba para un prompt de salida estructurada?
20 casos mínimo: 10 entradas de ruta feliz (datos típicos y bien formados), 5 casos límite (valores inusuales, campos opcionales faltantes, entradas largas), y 5 entradas adversariales.
¿Cuándo debo usar un prompt de corrección vs corregir el prompt base?
Usa un prompt de corrección cuando los fallos son raros — menos del 10% de las salidas. Corrige el prompt base cuando los fallos son sistemáticos: el mismo campo faltante o el mismo error de tipo apareciendo en múltiples casos de prueba.
¿El orden de los campos en el esquema afecta la fiabilidad de la salida estructurada?
Sí. Coloca los campos requeridos primero y los campos opcionales o nullable al final. Los modelos ponderan más los elementos del esquema anteriores al decidir qué incluir. Este efecto de ordenamiento es consistente en GPT-4o y Claude 4.6 Sonnet.
Lecturas relacionadas
- Salida estructurada y modo JSON: cuándo y cómo usarlo — Configuración del modo JSON a nivel de API para GPT-4o, Claude y Gemini con tabla de cumplimiento del modelo
- Cómo controlar la salida: formato, temperatura y decodificación restringida — mecánicas de decodificación restringida, temperatura y top-p para tareas estructuradas
- Cómo evaluar la calidad del prompt: métricas, pruebas y lista de verificación — construcción de conjuntos de prueba de 20 casos, puntuación binaria de aprobación/fallo
- Cómo probar prompts en diferentes modelos — ejecutar el mismo prompt en GPT-4o, Claude 4.6 Sonnet y Gemini 2.5 Pro para encontrar fallos específicos del modelo
- Zero-Shot vs Few-Shot Prompting — cuándo añadir ejemplos a un prompt y cuántos incluir para diferentes tipos de tarea
Fuentes
- Documentación de Structured Outputs de OpenAI — especificación técnica para response_format y modo JSON en la API de OpenAI
- Documentación de uso de herramientas de Anthropic — cómo el parámetro tool_use de Claude impone la salida estructurada a nivel de API
- Documentación de GenerationConfig de Google Gemini — configuración de responseMimeType de Gemini para salida JSON nativa
- Benchmark BAML: compromisos de precisión en salida estructurada — evidencia sobre las diferencias de fiabilidad entre generación restringida y no restringida entre modelos
- Marco de Gestión de Riesgos de IA del NIST — principios de gobernanza para la validación de salida de IA en sistemas de producción