Spring til hovedindhold
Dansk— Vælg et sprog
Menu

JSON-skemaer og validering

Lektion 2 af 20 Udvikler
På denne side
  1. JSON-skemaer og validering
  2. Struktur for funktionsskemaer
  3. Streng tilstand (Strict Mode)
  4. Validering på klientsiden
  5. Effektive beskrivelser
  6. Næstede skemaer og referencer
  7. Vigtige pointer

JSON-skemaer og validering

Et funktionsskema er ikke blot valideringsrør: det er den eneste kontrakt mellem modellen og din kode. Der findes ingen anden kanal. Modellen læser ikke din implementering, kender ikke dine interne konventioner og vil ikke gætte på, at et date-felt forventer ISO-format i stedet for fransk format.

Alt, der ikke er skrevet i skemaet, overlades til modellens tilfældige slutninger. Dette forklarer den ubalance i indsats, som anbefales i denne lektion: det er bedre at bruge ti minutter på et skema end to timer på at fejlsøge ustabile argumenter.

Struktur for funktionsskemaer

Alle funktioner, der erklæres i tools, følger JSON Schema-formatet. Her er den fulde struktur:

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
}

Streng tilstand (Strict Mode)

Streng tilstand omdanner sandsynlighed til en garanti. Uden den producerer modellen normalt kompatible argumenter – og du opdager undtagelserne i produktionen, når kanttilfælde opstår. Med den sikres overholdelse ved konstruktion på dekodningsniveauet. Aktiver den som standard: de begrænsninger, den pålægger, og som er detaljeret nedenfor, er en lille pris at betale for at eliminere en hel klasse af fejl.

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
}]

Begrænsninger i streng tilstand

I streng tilstand gælder visse regler:

  • Alle felter skal være i required
  • additionalProperties skal være false
  • Valgfrie typer bruger anyOf med null
  • Ingen pattern, minLength, maxLength på topniveau
# Valgfrit felt i streng tilstand
"commentaire": {
    "anyOf": [
        {"type": "string"},
        {"type": "null"}
    ],
    "description": "Optional free-text comment"
}

Validering på klientsiden

Streng tilstand garanterer formen, aldrig betydningen. En velformateret dato kan ligge i fortiden, en korrekt typed identifikator matcher måske ingen kunde, og et gyldigt beløb kan overstige den autoriserede grænse. Disse regler er forretningslogik: intet JSON-skema kan udtrykke dem, og de skal verificeres i din kode – med en fejlmeddelelse sendt tilbage til modellen, der forklarer, hvad der gik galt, hvis afvisning sker.

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}"})

    # Forretningslogik efter validering
    return creer_facture(**args)

Effektive beskrivelser

Skriv en funktionsbeskrivelse som instrukser til en ny kollega: hvornår den skal kaldes, og især hvornår den ikke skal kaldes. Det er den anden del, vi systematisk glemmer, alligevel løser den de fleste fejlagtige kald – „brug ikke til arkiverede ordrer” forhindrer en unødvendig rundtur, som tre sætninger med positiv beskrivelse ikke ville have stoppet.

# Dårligt: for vagt
{
    "name": "get_data",
    "description": "Retrieve data"
}

# Godt: specifikt og kontekstuelt
{
    "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."
}

Parameterbeskrivelser

På parameterniveau er fjenden det implicitte. En enhed (euro eller cent?), et format (ISO eller lokalt?), en konvention (internt ID eller kundereference?), der ikke er skrevet, vil blive gættet – nogle gange korrekt, nogle gange ikke, uden signal i nogen af delene. enum er dit bedste værktøj her: det beskriver ikke den forventede værdi, det begrænser den.

"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."
    }
}

Næstede skemaer og referencer

Et dybt næstet skema er svært for dig at genlæse og for modellen at udfylde korrekt. Hvis du når tre niveauer, er spørgsmålet ikke, hvordan du skriver det bedre, men om funktionen gør for meget: to funktioner med klart omfang er næsten altid at foretrække frem for én konfigurerbar funktion, der dækker begge tilfælde.

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
}]

Vigtige pointer

  • Aktiver strict: true for at garantere overholdelse af argumenter
  • Valider stadig på klientsiden med jsonschema for forretningsregler
  • Skriv præcise beskrivelser: de er den primære kvalitetsløftestang
  • Brug enum til at begrænse accepterede værdier
  • Opdel komplekse skemaer i genanvendelige understrukturer