Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

JSON-schema's en validatie

Les 2 van 20 Ontwikkelaar
Op deze pagina
  1. JSON-schema’s en validatie
  2. Structuur van een functieschema
  3. Strikte modus
  4. Validatie aan de clientzijde
  5. Effectieve beschrijvingen
  6. Geneste schema’s en referenties
  7. Belangrijkste punten

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 required staan
  • additionalProperties moet false zijn
  • Optionele typen gebruiken anyOf met null
  • Geen pattern, minLength of maxLength op 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: true in om conformiteit van argumenten te garanderen
  • Valideer nog steeds aan de clientzijde met jsonschema voor bedrijfsregels
  • Schrijf precieze beschrijvingen: dit is de belangrijkste hefboom voor kwaliteit
  • Gebruik enum om geaccepteerde waarden te beperken
  • Splits complexe schema’s op in herbruikbare substructuren