Structured Outputs OpenAI API: respuestas JSON con esquema
Structured Outputs OpenAI API permite hacer que la respuesta de un modelo compatible siga un JSON Schema definido por tu aplicación. Esto facilita crear APIs, formularios, flujos de extracción, agentes y sistemas backend que necesitan datos con una estructura predecible en lugar de texto libre.
¿Qué es Structured Outputs OpenAI API?
Structured Outputs OpenAI API es una capacidad que obliga al modelo a responder siguiendo una estructura JSON definida por el desarrollador. En vez de recibir texto libre o simplemente JSON válido, puedes especificar campos, tipos y restricciones mediante JSON Schema.
Qué permite hacer Structured Outputs OpenAI API
Structured Outputs facilita integrar modelos con aplicaciones que esperan datos estructurados.
Generar JSON estructurado
El modelo produce una salida compatible con un esquema definido.
Usar JSON Schema
Define campos, tipos y relaciones esperadas.
Integrar backends
Facilita consumir la respuesta directamente desde aplicaciones.
Extraer datos
Convierte contenido no estructurado en objetos predecibles.
Generar interfaces
Permite producir estructuras que luego una aplicación puede renderizar.
Agentes
Facilita pasar información estructurada entre pasos de un workflow.
Cómo funciona Structured Outputs en OpenAI API
Tu aplicación define la estructura, el modelo genera una respuesta compatible y tu backend puede procesarla.
Defines el esquema
Especificas campos, tipos y restricciones.
El modelo responde
La salida se genera siguiendo la estructura indicada.
Tu aplicación procesa
El JSON puede utilizarse directamente en el workflow.
Structured Outputs vs JSON Mode
Ambos pueden producir JSON, pero no ofrecen el mismo nivel de garantía estructural.
| Aspecto | Structured Outputs | JSON Mode |
|---|---|---|
| JSON válido | Sí | Sí |
| Respeta un schema | Sí | No garantiza un schema concreto |
| Uso recomendado | Aplicaciones con estructura definida | Compatibilidad con JSON simple |
| API moderna | json_schema |
json_object |
En la referencia actual
de Responses API,
json_object
se mantiene como JSON mode antiguo,
mientras json_schema
es la opción preferida
para modelos compatibles.
Ejemplo de Structured Outputs OpenAI API
En Responses API, puedes indicar que el formato de salida utilice JSON Schema.
Respuesta estructurada
{
"model": "gpt-5.6-sol",
"input": "Extrae el nombre, email y tipo de cliente.",
"text": {
"format": {
"type": "json_schema",
"name": "cliente",
"schema": {
"type": "object",
"properties": {
"nombre": {
"type": "string"
},
"email": {
"type": "string"
},
"tipo": {
"type": "string"
}
},
"required": [
"nombre",
"email",
"tipo"
],
"additionalProperties": false
},
"strict": true
}
}
}Responses API evoluciona, por lo que conviene comprobar siempre la referencia del SDK o endpoint que estés utilizando.
Qué define un JSON Schema
El schema indica qué estructura debe tener la respuesta final.
| Elemento | Función |
|---|---|
type |
Define el tipo de dato esperado |
properties |
Define los campos del objeto |
required |
Indica qué campos son obligatorios |
enum |
Restringe un campo a valores concretos |
items |
Define la estructura de elementos de un array |
additionalProperties |
Controla campos adicionales no definidos |
Qué significa strict: true
Structured Outputs está diseñado para que la respuesta respete el schema proporcionado.
Adherencia al esquema
Cuando utilizas
strict: true,
el objetivo
es que el output
coincida con
la estructura
definida por
el desarrollador.
Un objeto puede respetar perfectamente el schema y aun contener un valor factual incorrecto. Debes validar también la calidad de los datos.
Ejemplo de output estructurado
Una respuesta compatible con el schema anterior podría verse así.
Objeto procesable
{
"nombre": "Empresa Ejemplo",
"email": "contacto@ejemplo.cl",
"tipo": "empresa"
}Structured Outputs también funciona con funciones
OpenAI introdujo Structured Outputs tanto para respuestas directas como para Function Calling.
strict dentro de una función
{
"type": "function",
"name": "crear_cliente",
"strict": true,
"parameters": {
"type": "object",
"properties": {
"nombre": {
"type": "string"
},
"email": {
"type": "string"
}
},
"required": [
"nombre",
"email"
],
"additionalProperties": false
}
}Usa Structured Outputs para estructurar una respuesta. Usa Function Calling cuando quieres que el modelo solicite una acción externa.
Ver Function Calling →Structured Outputs vs Function Calling
Ambas tecnologías utilizan schemas, pero resuelven problemas distintos.
| Aspecto | Structured Outputs | Function Calling |
|---|---|---|
| Objetivo | Dar formato a la respuesta | Solicitar una acción externa |
| Resultado | JSON estructurado | Argumentos de una función |
| Ejecución backend | No necesariamente | Sí |
| Schema | Describe la respuesta | Describe los argumentos |
Extraer datos con Structured Outputs OpenAI API
La extracción de información es uno de los casos más claros de Structured Outputs.
Extraer datos desde emails.
Convertir documentos en objetos JSON.
Clasificar solicitudes de usuarios.
Detectar entidades y campos concretos.
Generar datos para guardar en bases de datos.
Structured Outputs para generar interfaces
OpenAI también ha mostrado Structured Outputs como una base para generar interfaces dinámicas.
La respuesta puede describir componentes
En lugar de pedir HTML libre, una aplicación puede definir un schema con componentes permitidos y renderizarlos posteriormente de forma controlada.
Structured Outputs dentro de workflows agentic
Los agentes suelen intercambiar información entre múltiples pasos.
Analizar
Un modelo interpreta la solicitud.
Estructurar
Produce un objeto con campos definidos.
Actuar
Otro componente consume esos datos.
Qué ocurre si el modelo rechaza una solicitud
Structured Outputs no elimina los mecanismos de seguridad del modelo.
Una negativa puede ser diferente al schema esperado
OpenAI introdujo un indicador de rechazo para que las aplicaciones puedan detectar cuándo el modelo se negó a responder en lugar de producir el objeto estructurado.
No asumas que cada respuesta contendrá necesariamente el objeto de negocio que esperabas.
Una generación puede terminar antes de completar el schema
Structured Outputs mejora la adherencia al formato, pero una respuesta puede interrumpirse antes de finalizar.
Límite de tokens.
Condición de parada.
Error durante la generación.
Rechazo del modelo.
Structured Outputs y llamadas paralelas de funciones
OpenAI ha documentado una limitación importante cuando se combinan schemas estrictos con llamadas paralelas.
Desactívalas cuando necesites adherencia estricta
En escenarios
donde necesitas
que los argumentos
respeten estrictamente
el schema,
OpenAI recomienda
utilizar
parallel_tool_calls: false.
Casos de uso de Structured Outputs OpenAI API
Structured Outputs encaja especialmente bien cuando el resultado debe ser consumido por software.
CRM: convertir mensajes en datos de clientes.
Ecommerce: clasificar productos y atributos.
Soporte: detectar categoría, prioridad y acción sugerida.
Documentos: extraer campos de contratos, facturas o formularios.
Agentes: pasar estados estructurados entre pasos.
Apps: producir datos directamente consumibles por frontend o backend.
Clasificar una solicitud de soporte
Un schema puede limitar categorías y prioridades aceptadas.
Salida controlada
{
"type": "object",
"properties": {
"categoria": {
"type": "string",
"enum": [
"facturacion",
"soporte_tecnico",
"ventas",
"otro"
]
},
"prioridad": {
"type": "string",
"enum": [
"baja",
"media",
"alta"
]
},
"resumen": {
"type": "string"
}
},
"required": [
"categoria",
"prioridad",
"resumen"
],
"additionalProperties": false
}El schema no sustituye la validación de negocio
Structured Outputs controla la forma de la respuesta, pero tu aplicación sigue siendo responsable de validar reglas reales.
Valida estructura
Tipos, campos y valores permitidos.
Valida negocio
Usuarios, permisos, stock, fechas, precios y reglas reales.
Modelos compatibles con Structured Outputs
La compatibilidad depende del modelo y del tipo de uso.
Comprueba la ficha del modelo
OpenAI distingue entre Structured Outputs utilizados como formato de respuesta y los utilizados dentro de Function Calling. Antes de producción, confirma que el modelo elegido soporta la modalidad necesaria.
Comparar modelos →Buenas prácticas con Structured Outputs OpenAI API
Un JSON bien formado no debe considerarse automáticamente confiable.
Valida los datos en el backend.
No utilices valores del modelo directamente para operaciones críticas.
Usa enums cuando el dominio tenga opciones cerradas.
Utiliza
additionalProperties: false
cuando quieras
limitar campos extras.
Contempla refusals y respuestas incompletas.
Registra errores de validación para mejorar prompts y schemas.
Cuándo conviene utilizar Structured Outputs
Structured Outputs es especialmente útil cuando otra parte del sistema consume la respuesta.
Cuando necesitas JSON predecible.
Cuando un backend procesa automáticamente la respuesta.
Cuando quieres extraer campos concretos.
Cuando necesitas enums, arrays u objetos anidados.
Cuando varios pasos de un agente deben intercambiar datos estructurados.
Cuándo no necesitas Structured Outputs
No todas las respuestas necesitan convertirse en objetos JSON.
Contenido editorial
Artículos, explicaciones o conversaciones pueden funcionar mejor como texto.
Acción externa
Si necesitas ejecutar una acción, Function Calling puede ser la opción adecuada.
Costos de Structured Outputs OpenAI API
Structured Outputs forma parte de la generación realizada por el modelo.
El schema también forma parte de la solicitud
Schemas grandes pueden aumentar el contexto que debe procesar el modelo. Por eso conviene mantenerlos claros y tan simples como permita el caso de uso.
Structured Outputs puede reducir lógica de reintentos y parsing manual, algo que también tiene valor operativo.
Ver precios OpenAI API →Structured Outputs y los límites de OpenAI API
El uso de respuestas estructuradas continúa sujeto a los límites del modelo y del proyecto.
Planifica schemas y salidas grandes
Objetos extensos, listas largas o respuestas muy detalladas pueden consumir más tokens de salida.
Ver límites OpenAI API →Documentación oficial de Structured Outputs OpenAI API
Structured Outputs forma parte de las capacidades para generación estructurada de OpenAI API.
JSON Schema y Responses API
Consulta formatos de respuesta, JSON Schema, strict mode y compatibilidad actual.
Consultar documentación oficial →Guías relacionadas con Structured Outputs OpenAI API
Continúa explorando APIs, herramientas y capacidades de OpenAI.
FAQ sobre Structured Outputs OpenAI API
Respuestas sobre JSON Schema, strict mode, JSON mode, funciones y Responses API.
Structured Outputs OpenAI API permite hacer que la respuesta siga un JSON Schema definido por el desarrollador.
Su objetivo es producir una salida JSON que respete el schema proporcionado cuando se utiliza la configuración compatible.
No. JSON Mode garantiza principalmente JSON válido, mientras Structured Outputs permite exigir una estructura definida mediante JSON Schema.
Indica que la salida debe adherirse al schema proporcionado dentro de las capacidades soportadas.
Sí. OpenAI permite usar strict mode dentro de definiciones de funciones para obtener argumentos compatibles con el schema.
No. Una respuesta puede respetar perfectamente la estructura y aun contener información incorrecta.
La aplicación debe contemplar un posible rechazo en lugar del objeto estructurado esperado.
Sí. Es uno de los casos de uso más importantes: convertir texto o documentos en campos estructurados.
Sí, siempre que la característica de JSON Schema utilizada sea compatible con la implementación actual del modelo y API.
No. Tu aplicación debe seguir validando permisos, existencia de recursos, reglas de negocio y cualquier condición que dependa de datos reales.
Continúa con Prompt Caching en OpenAI API
Ya sabes cómo generar respuestas siguiendo un schema. El siguiente paso es aprender cómo reducir costo y latencia cuando una aplicación reutiliza grandes partes del mismo contexto.
Ver Prompt Caching →