Referencia de Tipos de Campo y Restricciones de Salida Estructurada

Q: ¿Puedo expresar "uno de un conjunto fijo de cadenas" de una manera compatible?

Sí, enum es totalmente compatible y es la forma estándar de restringir un campo a valores fijos.

Q: ¿Es additionalProperties siempre requerido?

Sí, cada objeto en el esquema debe establecer additionalProperties: false. No hay ningún valor compatible aparte de false.

Q: ¿Funciona $ref como lo hace en JSON Schema estándar?

Sí, la composición $ref/$def es compatible, y es exactamente lo que model_json_schema() de Pydantic genera para tipos BaseModel anidados.

Q: ¿Puedo validar rangos numéricos de alguna otra manera?

Sí, dado que minimum/maximum/multipleOf no se aplican, agregue un field_validator de Pydantic o una verificación manual después de que client.messages.parse() devuelva un resultado.

Q: ¿Los formatos de cadena como email y uuid se aplican realmente?

Sí, los valores de format que incluyen email, uuid, date-time, date, time, duration, hostname, uri, ipv4 y ipv6 son compatibles.

Q: ¿Cuál es el subconjunto más seguro de JSON Schema para diseñar?

Tipos básicos, enum, const, anyOf/allOf, $ref/$def, valores de format de cadena compatibles, además de required y additionalProperties: false en cada objeto. Cualquier cosa fuera de esa lista debe tratarse como no verificada hasta que consulte esta página.

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 v

Manejo 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/maximum y 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 un field_validator de Pydantic (o equivalente) para verificar el rango después de analizar.
Establecer additionalProperties a un objeto de esquema para permitir "campos extra de un tipo específico". Solo false literal es compatible. Solución: si necesita campos extra flexibles, modélalos explícitamente como una propiedad conocida (por ejemplo, un objeto metadata) en lugar de depender de additionalProperties.
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, children como 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í, enum es 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 de false.

¿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/$def es compatible, y es exactamente lo que model_json_schema() de Pydantic genera para tipos BaseModel anidados.

¿Puedo validar rangos numéricos de alguna otra manera?

Sí, dado que minimum/maximum/multipleOf no se aplican, agregue un field_validator de Pydantic o una verificación manual después de que client.messages.parse() devuelva un resultado.

¿Los formatos de cadena como email y uuid se aplican realmente?

Sí, los valores de format que incluyen email, uuid, date-time, date, time, duration, hostname, uri, ipv4 y ipv6 son 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 de format de cadena compatibles, además de required y additionalProperties: false en 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/uniqueItems no 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/additionalProperties que 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.

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 v

Manejo 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/maximum y 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 un field_validator de Pydantic (o equivalente) para verificar el rango después de analizar.
Establecer additionalProperties a un objeto de esquema para permitir "campos extra de un tipo específico". Solo false literal es compatible. Solución: si necesita campos extra flexibles, modélalos explícitamente como una propiedad conocida (por ejemplo, un objeto metadata) en lugar de depender de additionalProperties.
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, children como 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í, enum es 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 de false.

¿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/$def es compatible, y es exactamente lo que model_json_schema() de Pydantic genera para tipos BaseModel anidados.

¿Puedo validar rangos numéricos de alguna otra manera?

Sí, dado que minimum/maximum/multipleOf no se aplican, agregue un field_validator de Pydantic o una verificación manual después de que client.messages.parse() devuelva un resultado.

¿Los formatos de cadena como email y uuid se aplican realmente?

Sí, los valores de format que incluyen email, uuid, date-time, date, time, duration, hostname, uri, ipv4 y ipv6 son 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 de format de cadena compatibles, además de required y additionalProperties: false en 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/uniqueItems no 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/additionalProperties que 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.

Referencia de Tipos de Campo y Restricciones de Salida Estructurada

Buscar en la documentación

Referencia de Tipos de Campo y Restricciones de Salida Estructurada