Esquemas JSON y validación
En esta página
Esquemas JSON y validación
Un esquema de función no es tubería de validación: es el único contrato entre el modelo y tu código. No existe otro canal. El modelo no lee tu implementación, desconoce tus convenciones internas y no adivinará que un campo date espera formato ISO en lugar de formato francés.
Cualquier cosa que no esté escrita en el esquema será decidida por las inferencias aleatorias del modelo. Esto explica el desequilibrio de esfuerzo recomendado en esta lección: es mejor dedicar diez minutos a un esquema que dos horas a depurar argumentos erráticos.
Estructura del esquema de función
Cada función declarada en tools sigue el formato JSON Schema. Esta es la estructura completa:
tool_definition = {
"type": "function",
"name": "creer_facture",
"description": "Create an invoice for an existing customer",
"parameters": {
"type": "object",
"properties": {
"client_id": {
"type": "string",
"description": "Unique customer identifier (format: CLI-XXXXX)"
},
"lignes": {
"type": "array",
"description": "List of billing line items",
"items": {
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "Product or service description"
},
"quantite": {
"type": "integer",
"minimum": 1,
"description": "Number of units"
},
"prix_unitaire": {
"type": "number",
"minimum": 0,
"description": "Unit price excluding tax in euros"
}
},
"required": ["description", "quantite", "prix_unitaire"]
}
},
"devise": {
"type": "string",
"enum": ["EUR", "USD", "GBP"],
"default": "EUR"
},
"echeance_jours": {
"type": "integer",
"enum": [30, 45, 60, 90],
"description": "Payment deadline in days"
}
},
"required": ["client_id", "lignes"],
"additionalProperties": False
},
"strict": True
}
Modo estricto
El modo estricto convierte la probabilidad en una garantía. Sin él, el modelo suele producir argumentos conformes, y descubres las excepciones en producción, en casos límite. Con él, la conformidad está asegurada por construcción a nivel de decodificación. Actívalo por defecto: las restricciones que impone, detalladas justo debajo, son un pequeño precio a pagar por eliminar toda una clase de errores.
tools = [{
"type": "function",
"name": "enregistrer_commande",
"description": "Record a new order",
"parameters": {
"type": "object",
"properties": {
"produit": {"type": "string"},
"quantite": {"type": "integer"},
"urgent": {"type": "boolean"}
},
"required": ["produit", "quantite", "urgent"],
"additionalProperties": False
},
"strict": True
}]
Restricciones del modo estricto
En modo estricto, se aplican ciertas reglas:
- Todos los campos deben estar en
required additionalPropertiesdebe serfalse- Los tipos opcionales usan
anyOfconnull - Sin
pattern,minLength,maxLengthen el nivel superior
# Campo opcional en modo estricto
"commentaire": {
"anyOf": [
{"type": "string"},
{"type": "null"}
],
"description": "Optional free-text comment"
}
Validación en el cliente
El modo estricto garantiza la forma, nunca el significado. Una fecha bien formada puede estar en el pasado, un identificador bien tipado puede no coincidir con ningún cliente y un importe válido puede superar el límite autorizado. Estas reglas son lógica de negocio: ningún esquema JSON las expresa y deben verificarse en tu código; en caso de rechazo, envía al modelo un mensaje de error que explique qué ha fallado.
import json
from jsonschema import validate, ValidationError
SCHEMA_FACTURE = {
"type": "object",
"properties": {
"client_id": {"type": "string", "pattern": "^CLI-[0-9]{5}$"},
"lignes": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"description": {"type": "string", "minLength": 1},
"quantite": {"type": "integer", "minimum": 1},
"prix_unitaire": {"type": "number", "minimum": 0}
},
"required": ["description", "quantite", "prix_unitaire"]
}
}
},
"required": ["client_id", "lignes"]
}
def executer_fonction(name: str, arguments: str) -> str:
args = json.loads(arguments)
try:
validate(instance=args, schema=SCHEMA_FACTURE)
except ValidationError as e:
return json.dumps({"error": f"Invalid arguments: {e.message}"})
# Lógica de negocio tras la validación
return creer_facture(**args)
Descripciones eficaces
Escribe la descripción de una función como instrucciones para un nuevo compañero: cuándo llamarla y, sobre todo, cuándo no llamarla. Es esa segunda parte la que olvidamos sistemáticamente, pero resuelve la mayoría de las llamadas erróneas; «no usar para pedidos archivados» evita un viaje innecesario que tres frases de descripción positiva no habrían detenido.
# Malo: demasiado vago
{
"name": "get_data",
"description": "Retrieve data"
}
# Bueno: específico y contextual
{
"name": "rechercher_produits_catalogue",
"description": "Search for products in the e-commerce catalog. "
"Returns name, price, stock, and category. "
"Use for questions about availability or pricing."
}
Descripciones de parámetros
A nivel de parámetro, el enemigo es lo implícito. Una unidad (¿euros o céntimos?), un formato (¿ISO o local?) o una convención (¿ID interno o referencia de cliente?) que no estén escritos serán adivinados; a veces correctamente, a veces no, sin señal alguna en ningún sentido. El enum es tu mejor herramienta aquí: no describe el valor esperado, lo restringe.
"properties": {
"date_debut": {
"type": "string",
"description": "Start date in ISO 8601 format (YYYY-MM-DD). "
"Defaults to today's date if not specified."
},
"statut": {
"type": "string",
"enum": ["actif", "inactif", "suspendu"],
"description": "Filter by account status. "
"'actif' = accounts in service, "
"'suspendu' = temporarily frozen accounts."
}
}
Esquemas anidados y referencias
Un esquema profundamente anidado es difícil de releer para ti y de rellenar correctamente para el modelo. Si llegas a tres niveles, la pregunta que debes hacerte no es cómo escribirlo mejor, sino si la función está haciendo demasiado: dos funciones con un alcance claro son casi siempre preferibles a una función configurable que cubra ambos casos.
adresse_schema = {
"type": "object",
"properties": {
"rue": {"type": "string"},
"code_postal": {"type": "string"},
"ville": {"type": "string"},
"pays": {"type": "string", "enum": ["FR", "BE", "CH", "LU"]}
},
"required": ["rue", "code_postal", "ville", "pays"]
}
tools = [{
"type": "function",
"name": "creer_livraison",
"description": "Create a delivery with shipping and destination addresses",
"parameters": {
"type": "object",
"properties": {
"expedition": adresse_schema,
"destination": adresse_schema,
"poids_kg": {"type": "number", "minimum": 0.1}
},
"required": ["expedition", "destination", "poids_kg"],
"additionalProperties": False
},
"strict": True
}]
Puntos clave
- Activa
strict: truepara garantizar la conformidad de los argumentos - Valida aún así en el cliente con
jsonschemapara las reglas de negocio - Escribe descripciones precisas: son la principal palanca de calidad
- Usa
enumpara restringir los valores aceptados - Divide los esquemas complejos en subestructuras reutilizables