≡En resumen
- Con salidas estructuradas la respuesta de Claude siempre es un JSON que cumple tu esquema, sin reintentos ni limpieza de texto.
- Hay dos variantes: formato JSON para la respuesta y modo estricto para los argumentos de las herramientas.
- No todas las reglas de JSON Schema están soportadas y los objetos deben cerrarse con additionalProperties: false.
- Garantiza la forma, no la verdad: un campo puede ser válido y aun así contener un dato equivocado.
- Es la base para extraer datos de documentos, clasificar y conectar la IA con ERP, CRM o bases de datos.
01 ¿Qué son las salidas estructuradas?
Cuando un programa usa un modelo de IA, casi nunca quiere un párrafo: quiere datos. Un número de factura, una categoría, una lista de productos con precio. Durante años la solución fue pedir en el prompt «responde solo en JSON» y rezar: a veces el modelo añadía una frase delante, olvidaba una coma o se inventaba un campo, y el código fallaba.
Las salidas estructuradas eliminan ese problema. Le pasas a la Messages API de Claude un esquema y la generación queda restringida a respuestas que lo cumplen. El resultado es siempre un JSON válido con los campos y tipos que definiste.
02 Cómo funcionan en la API de Claude
Formato JSON de la respuesta
Con output_config.format de tipo json_schema, el texto que devuelve Claude es un JSON que cumple el esquema.
Herramientas en modo estricto
Con strict: true en una herramienta, los argumentos que propone Claude se validan exactamente contra su input_schema.
Helpers de los SDK
Los SDK oficiales permiten definir el esquema con Pydantic o Zod y devuelven el objeto ya validado y tipado.
Las dos variantes se pueden combinar: un agente puede usar herramientas estrictas mientras trabaja y entregar el resultado final con formato JSON. Si quieres entender bien la segunda pieza, repasa qué es el tool use de Claude.
03 Ejemplo práctico: extraer datos de un correo
Un cliente escribe: «Necesito 12 cajas de guantes talla M y 3 de talla L para el jueves en la tienda de Elche». Defines un esquema con productos (lista de objetos con referencia, talla y cantidad entera), fecha_entrega en formato date y punto_entrega como enumeración de tus tiendas.
La respuesta llega como un objeto JSON con dos productos, la fecha resuelta y la tienda «Elche» elegida de la lista permitida. Tu código lo inserta directamente en el ERP; solo revisas los casos en los que algún campo llega vacío.
04 Salidas estructuradas frente a los métodos anteriores
| Método | Cómo funciona | Fiabilidad del formato | Situación actual |
|---|---|---|---|
| Pedirlo en el prompt | Instrucción tipo «responde solo en JSON» | Alta, pero sin garantía | Sigue siendo útil para formatos flexibles |
| Prefijar la respuesta | Empezar el turno del asistente con una llave | Media-alta | Los modelos recientes de Claude ya no admiten el prefijado |
| Forzar una herramienta | Definir una herramienta ficticia y obligar a usarla | Alta | Los modelos más recientes rechazan forzar herramientas |
| Salidas estructuradas | La API restringe la generación al esquema | Garantizada salvo corte o rechazo | Método recomendado |
05 Limitaciones que debes conocer
- ✓Todos los objetos del esquema deben declarar additionalProperties: false.
- ✓Se admiten tipos básicos, enum, const, anyOf, allOf, referencias y formatos como date, email o uuid; no se admiten esquemas recursivos ni límites como minimum o maxLength (los SDK de Python y TypeScript los quitan y los validan en tu lado).
- ✓No se puede combinar con las citas de documentos en la misma petición.
- ✓Si la respuesta se corta por max_tokens o el modelo rechaza la petición, el JSON puede no estar completo: comprueba el stop_reason.
- ✓El primer uso de un esquema nuevo tarda algo más mientras se compila; después queda en caché durante 24 horas.
- ✓Esquemas muy grandes o profundos consumen más tokens y pueden alcanzar límites de complejidad.
06 Casos de uso para empresas
Extracción de documentos
Facturas, albaranes, contratos o CV convertidos en registros listos para tu base de datos.
Clasificación
Correos, tickets o reseñas etiquetados con categorías cerradas de una enumeración.
Enriquecimiento de catálogo
Atributos de producto (material, talla, color) extraídos de descripciones libres.
Formularios conversacionales
Un chat que recoge datos y entrega al CRM un objeto completo y validado.
Evaluación y moderación
Puntuaciones y motivos en un formato fijo para comparar resultados.
Integración entre sistemas
La IA como pieza intermedia que traduce texto libre a la API de otro programa.
Son la pieza que hace fiables las soluciones de inteligencia artificial para empresas que alimentan otros sistemas: sin un formato garantizado, cada integración necesita parches para los casos raros. Por eso las usamos por defecto cuando conectamos IA a un ERP o un CRM en proyectos de desarrollo web a medida.
07 Cómo diseñar un buen esquema
-
1
Empieza por el consumidor
Diseña el esquema a partir de lo que necesita el sistema que recibirá el JSON, no de lo que contiene el documento.
-
2
Usa enumeraciones
Si un campo tiene valores cerrados (estado, categoría, tienda), decláralos en enum para evitar variantes.
-
3
Describe cada campo
Las descripciones del esquema funcionan como instrucciones: indica unidades, formato y qué hacer si falta el dato.
-
4
Permite el vacío
Usa null o un campo de revisión para los datos que pueden no existir, en vez de obligar a inventarlos.
-
5
Prueba con casos reales
Valida con documentos difíciles (escaneados, incompletos, en otro idioma) antes de automatizar.
Las instrucciones generales sobre el tono o las reglas de extracción siguen yendo en el system prompt; el esquema solo fija la forma. Si necesitas un validador, un generador de esquemas o ejemplos de integración, revisa nuestro listado de herramientas y recursos para Claude.
Preguntas frecuentes sobre Salidas estructuradas (structured outputs)
Es una función de la API que obliga a Claude a responder con un JSON que cumple el esquema que defines, de modo que tu código puede procesarlo sin errores de formato.
Pedirlo en el prompt funciona casi siempre, pero no está garantizado. Con salidas estructuradas la API restringe la generación y el formato es válido salvo que la respuesta se corte o se rechace.
Es la variante de salidas estructuradas para el uso de herramientas: con strict: true, los argumentos que propone Claude cumplen exactamente el esquema de entrada de la herramienta.
No. Garantizan la estructura y los tipos, no la exactitud del contenido. Sigue validando los datos importantes con reglas de negocio o revisión humana.
Funcionan en los modelos actuales y en varios anteriores. Consulta la lista de modelos compatibles en la documentación oficial antes de elegir uno.
Sí. Los SDK oficiales de Python y TypeScript aceptan modelos de Pydantic y esquemas de Zod y devuelven la respuesta ya validada como objeto.
Sí. Las salidas estructuradas funcionan con la Batches API, con streaming, con el conteo de tokens y con el pensamiento extendido. Lo que no admiten es combinarse con las citas de documentos.
Fuentes consultadas
Sobre el autor
Development Manager en appyweb
Dirige el equipo de desarrollo de appyweb: aplicaciones web y móviles, SaaS, integraciones y arquitectura de software.
Ver perfil y artículos → Ver perfil en LinkedIn ↗