JSON Schema en prompts
Restrinja la estructura de la salida.
JSON Schema en prompts es una lección gratuita de AI Prompt Engineering en CoddyKit. Esta es la lección 2 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de AI Prompt Engineering, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de AI Prompt Engineering incluye 4 lecciones en total.
El esquema como contrato de salida
Un JSON Schema describe declarativamente la forma de una salida válida: tipos, claves obligatorias, restricciones de valores y anidamiento. Cuando se pasa a una API de salida estructurada, se convierte en un contrato estricto; cuando se incluye en un prompt, se convierte en una guía sólida.
Dominar la creación de esquemas es la habilidad fundamental de la generación estructurada.
La opción strict lo cambia todo
En el modo estricto, los proveedores exigen que todas las propiedades aparezcan en required y que additionalProperties sea false. Los campos opcionales se expresan como una unión con null, no mediante su omisión.
{
'type': 'object',
'properties': {
'name': {'type': 'string'},
'nickname': {'type': ['string', 'null']}
},
'required': ['name', 'nickname'],
'additionalProperties': False
}Restricción de valores escalares
Traslade la validación al esquema en lugar de hacerla durante el postprocesamiento:
enumpara opciones fijas.minimum/maximumpara rangos numéricos.patternpara cadenas validadas mediante expresiones regulares.formatpara indicaciones comodate-timeoemail.
{
'rating': {'type': 'integer', 'minimum': 1, 'maximum': 5},
'sku': {'type': 'string', 'pattern': '^[A-Z]{3}-[0-9]{4}$'},
'created': {'type': 'string', 'format': 'date-time'}
}Arrays y tuplas
Use items para arrays homogéneos y añada minItems/maxItems para limitar su longitud. Para las tuplas posicionales, proporcione un array de esquemas mediante prefixItems.
{
'tags': {
'type': 'array',
'items': {'type': 'string'},
'minItems': 1,
'maxItems': 5
}
}Uniones discriminadas con oneOf
Modele resultados polimórficos con oneOf y un campo discriminador. El modelo elige exactamente una rama y su deserializador decide qué hacer según la etiqueta.
{
'oneOf': [
{'type': 'object', 'properties': {
'kind': {'const': 'email'},
'address': {'type': 'string', 'format': 'email'}},
'required': ['kind', 'address']},
{'type': 'object', 'properties': {
'kind': {'const': 'phone'},
'number': {'type': 'string'}},
'required': ['kind', 'number']}
]
}Generación de esquemas a partir de tipos
Escribir esquemas manualmente propicia errores. Derívelos de modelos tipados para que el esquema y su código nunca diverjan.
from pydantic import BaseModel
class Invoice(BaseModel):
total: float
currency: str
paid: bool
schema = Invoice.model_json_schema()
# pass schema directly to response_formatLas descripciones también son prompts
El modelo lee cada description del esquema. Úselas para orientar la semántica, no solo para documentar los campos.
Por ejemplo, una descripción como 'código de país ISO-3166 alpha-2, en mayúsculas' mejora significativamente la precisión del campo. Trate las descripciones como micro-prompts integrados en el contrato.
{
'country': {
'type': 'string',
'description': 'ISO-3166 alpha-2 code, uppercase, e.g. US, TR, DE'
}
}Incrustar el esquema en el prompt
Cuando el proveedor no ofrece compatibilidad nativa, incluya el esquema en el prompt y exija que se cumpla. Combínelo con un único ejemplo en contexto y una instrucción explícita de solo JSON, sin prosa.
SYSTEM = (
'You output ONLY JSON matching this schema. No markdown, no commentary.\n'
'Schema:\n' + json.dumps(schema) + '\n'
'If a value is unknown, use null.'
)Evitar el exceso de esquema
Los esquemas demasiado profundos o con demasiadas ramas confunden al modelo y aumentan el coste en tokens. Directrices:
- Mantenga el anidamiento superficial; aplane la estructura cuando sea posible.
- Prefiera enums a las cadenas de texto libres.
- Divida un esquema enorme en varias llamadas centradas.
- Algunos proveedores limitan la profundidad de anidamiento y el número total de propiedades; compruebe sus límites.
Referencias y reutilización
Use $defs y $ref para reutilizar subesquemas (por ejemplo, un Address usado en facturación y envío). Tenga en cuenta que algunos modos estrictos limitan la profundidad de la recursión, así que compruebe la compatibilidad antes de depender de referencias autorreferenciales.
{
'$defs': {
'Address': {'type': 'object', 'properties': {
'city': {'type': 'string'}}, 'required': ['city'],
'additionalProperties': False}
},
'type': 'object',
'properties': {
'billing': {'$ref': '#/$defs/Address'},
'shipping': {'$ref': '#/$defs/Address'}
},
'required': ['billing', 'shipping'],
'additionalProperties': False
}Validar el propio esquema
Existe una clase sutil de errores: el esquema está mal formado, no la salida. Ejecute un linter y valide los esquemas en CI con el metasquema de JSON Schema, y haga pasar un objeto de ejemplo de ida y vuelta por su validador antes de publicar.
import jsonschema
jsonschema.Draft202012Validator.check_schema(schema)
# also: validate a known-good sample
jsonschema.validate(sample_obj, schema)Comprobación rápida
En el modo de JSON Schema estricto de un proveedor, ¿cómo se expresa correctamente un campo opcional?
Resumen
Ahora puede crear esquemas precisos:
- el modo strict exige que todos los campos sean obligatorios y que additionalProperties sea false.
- Restrinja los valores escalares con enum, range, pattern y format.
- Modele el polimorfismo con discriminadores oneOf.
- Genere esquemas a partir de modelos tipados y trate las descripciones como micro-prompts.
- Valide el propio esquema en CI.
A continuación: aplicar esquemas a las llamadas de herramientas y funciones.
Preguntas frecuentes
¿La lección «JSON Schema en prompts» es gratis?
Sí — el texto completo de «JSON Schema en prompts» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de AI Prompt Engineering, actualiza a CoddyKit PRO. El curso de AI Prompt Engineering incluye 4 lecciones en total.
¿Qué aprenderé en «JSON Schema en prompts»?
Restrinja la estructura de la salida. Practicas AI Prompt Engineering con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.
¿Necesito experiencia previa para empezar AI Prompt Engineering?
No se requiere experiencia previa. AI Prompt Engineering en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 2 de 4.
¿Cuánto tiempo toma la lección «JSON Schema en prompts»?
La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.
¿Puedo escribir y ejecutar código en esta lección de AI Prompt Engineering?
Sí. Cada lección de AI Prompt Engineering incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.
Todas las lecciones de este curso
- Por qué usar salidas estructuradas
- JSON Schema en prompts
- Schemas de herramientas y funciones
- Bucles de reparación y validación