Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Schémy JSON a validácia

Lekcia 2 z 20 Vývojár
Na tejto strane
  1. Schémy JSON a validácia
  2. Štruktúra schémy funkcie
  3. Prísny režim (Strict Mode)
  4. Validácia na strane klienta
  5. Efektívne popisy
  6. Vnorené schémy a referencie
  7. Kľúčové poznatky

Schémy JSON a validácia

Schéma funkcie nie je len technická súčasť validácie: je to jediná zmluva medzi modelom a tvojím kódom. Neexistuje žiadny iný kanál komunikácie. Model nečíta tvoju implementáciu, nepozná tvoje interné konvencie a nehádne, že pole date očakáva formát ISO namiesto francúzskeho formátu.

Všetko, čo nie je zapísané v schéme, prenecháš na náhodné inferencie modelu. To vysvetľuje nerovnováhu v úsilí, ktorú odporúčame v tejto lekcii: je lepšie stráviť desať minút tvorbou schémy než dve hodiny ladením erratických argumentov.

Štruktúra schémy funkcie

Každá funkcia deklarovaná v tools nasleduje formát JSON Schema. Tu je kompletná štruktúra:

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
}

Prísny režim (Strict Mode)

Prísny režim mení pravdepodobnosť na záruku. Bez neho model zvyčajne generuje vyhovujúce argumenty – a ty objavíš výnimky až v produkcii pri hraničných prípadoch. S ním je súlad zabezpečený už pri dekodovaní. Povoľ ho predvolene: obmedzenia, ktoré ukladá a ktoré sú podrobne popísane nižšie, sú malou cenou za odstránenie celej triedy chýb.

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

Obmedzenia prísneho režimu

V prísnom režime platia určité pravidlá:

  • Všetky polia musia byť v required
  • additionalProperties musí byť false
  • Voliteľné typy používajú anyOf s null
  • Žiadne pattern, minLength, maxLength na najvyššej úrovni
# Voliteľné pole v prísnom režime
"commentaire": {
    "anyOf": [
        {"type": "string"},
        {"type": "null"}
    ],
    "description": "Optional free-text comment"
}

Validácia na strane klienta

Prísny režim garantuje formu, nikdy nie význam. Dobre vytvorený dátum môže byť v minulosti, správne typovaný identifikátor sa nemusí zhodovať so žiadnym zákazníkom a platná suma môže prekročiť povolený limit. Tieto pravidlá sú business logika: žiadna JSON schéma ich nevyjadruje a musia byť overené vo tvojom kóde – pričom v prípade zamietnutia musíš modelu poslať späť chybovú správu vysvetľujúcu, čo sa pokazilo.

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

    # Business logic after validation
    return creer_facture(**args)

Efektívne popisy

Popis funkcie napíš ako inštrukcie pre nového kolegu: kedy ju zavolať a hlavne kedy ju nezavolať. Práve tú druhú časť systematicky zabúdame, hoci rieši väčšinu chybných volaní – „nepoužívať pre archivované objednávky“ zabráni zbytočnému spätnému volaniu, ktoré by tri vety pozitívneho popisu nezastavili.

# Zlé: príše všeobecné
{
    "name": "get_data",
    "description": "Retrieve data"
}

# Dobré: špecifické a kontextové
{
    "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."
}

Popisy parametrov

Na úrovni parametrov je nepriateľom implicitnosť. Jednotka (eurá alebo centy?), formát (ISO alebo lokálny?), konvencia (interné ID alebo referencia zákazníka?), ktoré nie sú zapísané, budú uhádnuté – niekedy správne, niekedy nie, bez akéhokoľvek signálu. enum je tu tvoj najlepší nástroj: neopisuje očakávanú hodnotu, ale obmedzuje ju.

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

Vnorené schémy a referencie

Hlboko vnorená schéma je ťažká na opätovné prečítanie pre teba aj na správne vyplnenie pre model. Ak dosiahneš tri úrovne, otázka neznie, ako ju napísať lepšie, ale či funkcia nerobí príliš veľa: dve funkcie s jasným rozsahom sú takmer vždy vhodnejšie než jedna konfigurovateľná funkcia pokrývajúca oba prípady.

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

Kľúčové poznatky

  • Povoľ strict: true pre garantovanie súladu argumentov
  • Stále validuj na strane klienta pomocou jsonschema pre business pravidlá
  • Píš presné popisy: sú hlavným pákou kvality
  • Používaj enum na obmedzenie akceptovaných hodnôt
  • Rozdeľ komplexné schémy na opakovane použiteľné podštruktúry