JSON-schema's en validatie
Op deze pagina
JSON-schema’s en validatie
Een functieschema is geen validatie-infrastructuur: het is het enige contract tussen het model en uw code. Er bestaat geen ander kanaal. Het model leest uw implementatie niet, kent uw interne conventies niet en zal niet raden dat een veld date de ISO-indeling verwacht in plaats van de Franse indeling.
Alles wat niet in het schema staat, wordt overgelaten aan de willekeurige inferenties van het model. Dit verklaart de inspanningsverhouding die in deze les wordt aanbevolen: het is beter om tien minuten aan een schema te besteden dan twee uur aan het debuggen van wispelturige argumenten.
Structuur van een functieschema
Elke functie die in tools wordt gedeclareerd, volgt het JSON Schema-formaat. Hier is de volledige structuur:
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
}
Strikte modus
Strikte modus verandert waarschijnlijkheid in een garantie. Zonder deze modus produceert het model doorgaans conforme argumenten – maar ontdekt u de uitzonderingen pas in productie, bij randgevallen. Met strikte modus wordt conformiteit door de constructie gegarandeerd op het decoderingsniveau. Schakel dit standaard in: de beperkingen die het oplegt, hieronder in detail beschreven, zijn een kleine prijs om een hele klasse bugs te elimineren.
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
}]
Beperkingen van de strikte modus
In de strikte modus gelden bepaalde regels:
- Alle velden moeten in
requiredstaan additionalPropertiesmoetfalsezijn- Optionele typen gebruiken
anyOfmetnull - Geen
pattern,minLengthofmaxLengthop het hoogste niveau
# Optioneel veld in strikte modus
"commentaire": {
"anyOf": [
{"type": "string"},
{"type": "null"}
],
"description": "Optional free-text comment"
}
Validatie aan de clientzijde
Strikte modus garandeert de vorm, nooit de betekenis. Een goed gevormde datum kan in het verleden liggen, een correct getypeerde identifier komt mogelijk niet overeen met een bestaande klant, en een geldig bedrag kan de toegestane limiet overschrijden. Deze regels vallen onder bedrijfslogica: geen enkel JSON-schema kan ze uitdrukken, en ze moeten in uw code worden geverifieerd. Bij afkeuring stuurt u een foutbericht terug naar het model dat uitlegt wat er misging.
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}"})
# Bedrijfslogica na validatie
return creer_facture(**args)
Effectieve beschrijvingen
Schrijf een functiebeschrijving als instructies voor een nieuwe collega: wanneer de functie moet worden aangeroepen, en vooral wanneer niet. Dat tweede deel vergeten we systematisch, terwijl het de meeste foutieve aanroepen oplost. “Niet gebruiken voor gearchiveerde bestellingen” voorkomt een onnodige round-trip die drie zinnen met een positieve beschrijving niet hadden kunnen stoppen.
# Slecht: te vaag
{
"name": "get_data",
"description": "Retrieve data"
}
# Goed: specifiek en contextueel
{
"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."
}
Parameterbeschrijvingen
Op parameterniveau is de vijand het impliciete. Een eenheid (euro’s of centen?), een indeling (ISO of lokaal?), een conventie (interne ID of klantreferentie?) die niet worden opgeschreven, worden geraden – soms correct, soms niet, zonder enig signaal daarover. De enum is hier uw beste hulpmiddel: deze beschrijft niet alleen de verwachte waarde, maar beperkt deze ook.
"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."
}
}
Geneste schema’s en referenties
Een diep genest schema is moeilijk voor u om opnieuw te lezen en voor het model om correct in te vullen. Als u drie niveaus bereikt, is de vraag niet hoe u het beter schrijft, maar of de functie niet te veel doet: twee functies met een duidelijke reikwijdte zijn bijna altijd te verkiezen boven één configureerbare functie die beide gevallen afdekt.
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
}]
Belangrijkste punten
- Schakel
strict: truein om conformiteit van argumenten te garanderen - Valideer nog steeds aan de clientzijde met
jsonschemavoor bedrijfsregels - Schrijf precieze beschrijvingen: dit is de belangrijkste hefboom voor kwaliteit
- Gebruik
enumom geaccepteerde waarden te beperken - Splits complexe schema’s op in herbruikbare substructuren