Referencia de Tipos de Campo y Restricciones de Salida Estructurada
No todas las construcciones de JSON Schema son aplicadas por output_config.format. Esta página es una tabla de referencia rápida de lo que es compatible, lo que no, y qué sucede cuando se usa una construcción no compatible de todos modos.
Consulte esto antes de diseñar un esquema con algo más allá de tipos básicos, enum y anidación simple.
Cómo Usar Esta Referencia
- Escanee primero la tabla de Constructos Soportados al diseñar un nuevo esquema; cíñase a estas construcciones para obtener la garantía más sólida.
- Escanee la tabla de Constructos No Soportados antes de agregar una restricción como un rango numérico o un límite de longitud de cadena; no hará lo que espera.
- Cuando una construcción no sea compatible, use el manejo del lado del cliente del SDK (abajo) o mueva la restricción a su propio paso de validación posterior.
- Vuelva a visitar esta página en cualquier momento en que un esquema que espera que se aplique no parezca comportarse según lo restringido.
Constructos Soportados
| Constructo | Ejemplo | Notas |
|---|---|---|
| Tipos básicos | "type": "object", "array", "string", "integer", "number", "boolean", "null" | La base de cada esquema; combínelos libremente. |
enum | {"type": "string", "enum": ["bajo", "medio", "alto"]} | Restringe un campo a un conjunto fijo de valores; la herramienta estándar para campos de estilo de clasificación. |
const | {"const": "factura"} | Fija un campo a exactamente un valor literal. |
anyOf | {"anyOf": [{"type": "string"}, {"type": "integer"}]} | Permite que un campo coincida con cualquiera de varios subesquemas. |
allOf | {"allOf": [{"$ref": "#/$defs/Base"}, {"properties": {...}}]} | Combina múltiples subesquemas que deben coincidir todos. |
$ref / $def | {"$ref": "#/$defs/Direccion"} | Composición/reutilización estándar de esquemas; lo que Pydantic emite para modelos anidados. |
format de cadena | date-time, time, date, duration, email, hostname, uri, ipv4, ipv6, uuid | Restringe la forma de una cadena sin una expresión regular personalizada. |
additionalProperties: false | {"type": "object", "additionalProperties": False} | Requerido en cada objeto del esquema, no opcional. |
schema = {
"type": "object",
"properties": {
"id": {"type": "string", "format": "uuid"},
"status": {"type": "string", "enum": ["abierto", "cerrado"]},
"created_at": {"type": "string", "format": "date-time"},
},
"required": ["id", "status", "created_at"],
"additionalProperties": False,
}No Soportados
| Constructo | Ejemplo (no se aplicará) | Qué hacer en su lugar |
|---|---|---|
| Esquemas recursivos | Un objeto cuyas propiedades se refieren a sí mismo (directa o indirectamente a través de ciclos $ref) | Aplane la forma, o divida la extracción en múltiples llamadas secuenciales. |
| Restricciones de rango numérico | minimum, maximum, multipleOf | Valide el rango del número usted mismo después de analizar (un field_validator de Pydantic es un lugar natural para esto). |
| Restricciones de longitud de cadena | minLength, maxLength | Valide la longitud de la cadena usted mismo después de analizar. |
| Restricciones complejas de matrices | por ejemplo, minItems, maxItems, uniqueItems en combinación con otras palabras clave de matriz | Valide la forma/longitud de la matriz usted mismo después de analizar. |
additionalProperties establecido en algo que no sea false | "additionalProperties": true o un objeto de esquema | Siempre use additionalProperties: false; este es el único valor que el motor de aplicación de la API admite. |
from pydantic import BaseModel, field_validator
class Invoice(BaseModel):
total: float
@field_validator("total")
@classmethod
def total_in_range(cls, v: float) -> float:
# El esquema en sí no puede aplicar este rango; hágalo aquí en su lugar.
if not (0 <= v <= 1_000_000):
raise ValueError("total fuera del rango esperado")
return vManejo del SDK de Restricciones No Soportadas
| SDK | Comportamiento |
|---|---|
Python (anthropic) | Elimina automáticamente las restricciones no compatibles del esquema antes de enviarlo a la API, y luego las valida en el lado del cliente contra la respuesta. |
TypeScript (@anthropic-ai/sdk) | Mismo comportamiento de eliminación automática y validación en el lado del cliente que el SDK de Python. |
# Aún puedes escribir minLength en tu esquema para documentación/intención;
# el SDK lo elimina antes de que la solicitud salga y lo verifica en el lado del cliente
# una vez que la respuesta regresa, en lugar de ignorarlo silenciosamente de principio a fin.
schema = {
"type": "object",
"properties": {"codigo": {"type": "string", "minLength": 4}},
"required": ["codigo"],
"additionalProperties": False,
}Requisitos de Objeto de un Vistazo
| Regla | Se aplica a | Consecuencia si se omite |
|---|---|---|
required enumera cada propiedad que necesita presente | Cada objeto en el esquema, incluidos los anidados | Los campos omitidos se vuelven opcionales; el modelo puede omitirlos. |
additionalProperties: false | Cada objeto en el esquema, incluidos los anidados | El objeto queda abierto a campos adicionales no solicitados. |
| Anidación superficial (2-3 niveles) | El esquema en su conjunto | Las estructuras profundas o recursivas corren el riesgo de caer en territorio no compatible. |
Trampas
- Agregar
minimum/maximumy asumir que la API rechaza valores fuera de rango. No lo aplica; el campo se validará siempre que sea del tipo numérico correcto. Solución: agregue unfield_validatorde Pydantic (o equivalente) para verificar el rango después de analizar. - Establecer
additionalPropertiesa un objeto de esquema para permitir "campos extra de un tipo específico". Solofalseliteral es compatible. Solución: si necesita campos extra flexibles, modélalos explícitamente como una propiedad conocida (por ejemplo, un objetometadata) en lugar de depender deadditionalProperties. - Diseñar un esquema autorreferencial para datos en forma de árbol. Los esquemas recursivos no son compatibles. Solución: limite la profundidad explícitamente en el esquema (por ejemplo,
childrencomo un tipo anidado de profundidad fija) o represente el árbol como una lista plana con referencias padre en su lugar.
Preguntas Frecuentes
¿Qué sucede si uso minLength en mi esquema?
- Los SDK de Python y TypeScript lo eliminan del esquema enviado a la API y, en cambio, lo validan en el lado del cliente una vez que llega la respuesta.
- No es aplicado por la restricción en tiempo de generación de la API; trátelo como una verificación del lado del cliente, no como una garantía en tiempo de generación.
¿Puedo expresar "uno de un conjunto fijo de cadenas" de una manera compatible?
{"type": "string", "enum": ["borrador", "enviado", "pagado"]}- Sí,
enumes totalmente compatible y es la forma estándar de restringir un campo a valores fijos.
¿Es `additionalProperties` siempre requerido?
- Sí, cada objeto en el esquema debe establecer
additionalProperties: false. No hay ningún valor compatible aparte defalse.
¿Puedo anidar objetos tres o cuatro niveles de profundidad?
- Dos a tres niveles es confiable. El anidamiento muy profundo aumenta el riesgo de encontrar una construcción no compatible o un esquema que la API rechaza.
- Prefiera aplanar formas anidadas profundamente donde los datos lo permitan.
¿Los esquemas recursivos son rechazados directamente, o simplemente no se aplican?
- Los esquemas recursivos no son compatibles con esta función; evite que una propiedad haga referencia a su propio tipo contenedor, directa o a través de un ciclo
$ref.
¿Funciona `$ref` como lo hace en JSON Schema estándar?
- Sí, la composición
$ref/$defes compatible, y es exactamente lo quemodel_json_schema()de Pydantic genera para tiposBaseModelanidados.
¿Puedo validar rangos numéricos de alguna otra manera?
- Sí, dado que
minimum/maximum/multipleOfno se aplican, agregue unfield_validatorde Pydantic o una verificación manual después de queclient.messages.parse()devuelva un resultado.
¿Los formatos de cadena como email y uuid se aplican realmente?
- Sí, los valores de
formatque incluyenemail,uuid,date-time,date,time,duration,hostname,uri,ipv4yipv6son compatibles.
¿Cuál es el subconjunto más seguro de JSON Schema para diseñar?
- Tipos básicos,
enum,const,anyOf/allOf,$ref/$def, valores deformatde cadena compatibles, además derequiredyadditionalProperties: falseen cada objeto. - Cualquier cosa fuera de esa lista debe tratarse como no verificada hasta que consulte esta página.
¿Una restricción no compatible causa un error en la solicitud?
- No necesariamente; los SDK de Python y TypeScript eliminan las restricciones no compatibles automáticamente en lugar de generar un error, y luego las validan en el lado del cliente.
- No confíe en un error para saber que una restricción no funciona; consulte esta referencia en su lugar.
¿Pueden las matrices tener longitudes restringidas?
- Las restricciones complejas de matrices como
minItems/maxItems/uniqueItemsno son compatibles. - Valide la longitud o unicidad de la matriz usted mismo después de que llegue la respuesta.
Relacionado
- Definir un JSON Schema para output_config.format - las convenciones de
required/additionalPropertiesque esta referencia asume. - Validar y Analizar Respuestas Estructuradas en Python - dónde encaja la validación del lado del cliente de restricciones no compatibles en su código.
- Manejar Salida JSON Malformada o Truncada - un modo de fallo relacionado pero separado de las construcciones de esquema no compatibles.
Versiones de Stack: Escrito contra la línea de modelos Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y el SDK oficial de Python
anthropic(última versión 0.x). Los nombres de modelos, versiones de SDK y precios cambian rápidamente; verifique los detalles actuales en platform.claude.com/docs antes de confiar en ellos.