Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Validazzjoni b'JSON Schema u Zod

Lezzjoni 11 / 16 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Validazzjoni b’JSON Schema u Zod
  2. Għaliex tivvalida wara li tirċievi
  3. Validazzjoni f’Python b’jsonschema
  4. Validazzjoni b’Pydantic
  5. Validazzjoni b’Zod (TypeScript/Node.js)
  6. Mudell: erġa’ pprova b’korrezzjoni
  7. Bank tat-test għal stedien tal-kalendarju
  8. Punti Ewlenin

Lezzjoni aġġornata fit-3 ta’ Novembru 2026 abbażi tad-dokumentazzjoni ta’ OpenAI: temperature u top_p huma aċċettati biss b’sforz ta’ raġunament ta’ none, filwaqt li l-mudelli GPT-5.6 jirraġunaw b’mod awtomatiku (medium). Għalhekk, is-sejħiet li jistabbilixxu dawn il-parametri għandhom jispeċifikaw reasoning={"effort": "none"} (Responses API) jew reasoning_effort="none" (Chat Completions). Sorsi: L-użu ta’ GPT-6 · GPT-5.6 Terra.

Validazzjoni b’JSON Schema u Zod

L-Output Strutturat jiggarantixxi l-istruttura tar-rispons, iżda mhux il-validità semantika tad-data. Kamp “email” jista’ jkun fih stringa li mhix indirizz elettroniku validu. Il-validazzjoni fuq in-naħa tal-klijent bl-użu ta’ JSON Schema jew Zod hija l-kumplament essenzjali għal pipeline robusta.

Għaliex tivvalida wara li tirċievi

Eżamina x’jiggarantixxi l-API, u d-diviżjoni tax-xogħol issir ċara. L-Output Strutturat ta’ OpenAI jiżgura li l-JSON huwa sintattikament validu, li t-tipi ddikjarati jiġu rrispettati—stringa tibqa’ stringa, integer jibqa’ integer—li l-kampijiet kollha meħtieġa huma preżenti, u li l-valuri mrażżna minn enum jappartjenu għall-lista. Fuq dawn l-erba’ punti, tista’ tikteb il-kodiċi tiegħek b’kunfidenza.

Kollox ieħor jaqa’ fuqek, u jkopri erba’ familji ta’ problemi. Ir-restrizzjonijiet tal-format jaħarbu mill-iskema stretta: xejn ma jwaqqaf il-mudell milli jirritorna jean.dupont(at)example.fr f’kamp email, jew data fil-format 15/03/2026 meta tkun qed tistenna ISO. Il-limiti lanqas huma vverifikati, la għat-tul tal-stringa u lanqas għall-firxa tan-numri: età ta’ 350 tgħaddi mingħajr ma tgħajjar għajn. Il-konsistenza bejn il-kampijiet tibqa’ barra mill-portata—end_date qabel start_date hija JSON perfettament valida. U l-validità tan-negozju m’għandha l-ebda raġuni li tħasseb lill-API: SIRET (ID tan-negozju Franċiż) irid ikun fjamek u erba’ ċifri, iżda dik hija għarfien tad-dominju tiegħek, mhux tad-decoder.

Dawn l-erba’ familji jaqsmu karatteristika kbira: ma jikkawżaw l-ebda żball viżibbli. Email malformata maħżuna fid-database mhux se timmanifesta ruħha sakemm il-kampanja tal-email tibbounce ġimgħat wara. Għalhekk ir-regola: ivvalida qabel ma tippersisti, qatt wara.

Validazzjoni f’Python b’jsonschema

Il-konsegwenza prattika hija li għandek bżonn żewġ skemi għall-istess data. L-ewwel tmur lill-API, intenzjonalment ħafifa, limitata għal dak li l-modalità stretta taċċetta. It-tieni tibqa’ miegħek u ġġorr ir-restrizzjonijiet fini—format, pattern, minimum, maximum. Din id-duplikazzjoni apparenti hija separazzjoni ta’ responsabbiltajiet: waħda tifframma l-ġenerazzjoni, l-oħra tiddefendi l-ħażna tiegħek. Fl-eżempju hawn taħt, biss l-enum tar-rwol jidher fiż-żewġ naħat, għax hija l-unika restrizzjoni li ż-żewġ livelli jistgħu jesprimu.

import json
from jsonschema import validate, ValidationError

# Schema għall-API ta' OpenAI (stretta, mingħajr format/pattern)
api_schema = {
    "type": "object",
    "properties": {
        "email": {"type": "string"},
        "age": {"type": "integer"},
        "role": {"type": "string", "enum": ["admin", "user", "viewer"]}
    },
    "required": ["email", "age", "role"],
    "additionalProperties": False
}

# Schema estiża għall-validazzjoni fuq in-naħa tal-klijent
validation_schema = {
    "type": "object",
    "properties": {
        "email": {
            "type": "string",
            "format": "email",
            "pattern": r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z]{2,}$"
        },
        "age": {
            "type": "integer",
            "minimum": 0,
            "maximum": 150
        },
        "role": {"type": "string", "enum": ["admin", "user", "viewer"]}
    },
    "required": ["email", "age", "role"]
}

def validate_response(data: dict) -> tuple[bool, str]:
    """Tivvalida r-rispons tal-LLM kontra l-iskema estiża."""
    try:
        validate(instance=data, schema=validation_schema)
        return True, "Valid"
    except ValidationError as e:
        return False, f"Error: {e.message}"

Validazzjoni b’Pydantic

Pydantic spiss ikun aktar konvenjenti minn jsonschema għall-validazzjoni f’Python, u d-differenza tinsab f’dak li tikseb fl-output. jsonschema jgħidlek iva jew le u jħallik b’dizzjunarju, manipulat permezz ta’ data["email"] mingħajr l-ebda għajnuna mill-editur. Pydantic jirritorna oġġett ittajpjat: l-awtokompletament jaħdem, żball fit-tipa fl-isem tal-attribut jiġi skopert waqt il-kitba, u d-data tiċċirkola wara mingħajr konverżjoni.

Il-mudell ContactExtraction jesprimi l-limiti direttament fid-dikjarazzjonijiet tal-kamp. Il-field_validator fuq date_extraction ikopri l-każ li l-ebda annotazzjoni tat-tip ma tista’ taqbad: l-istringa hija tabilħaqq stringa, iżda trid tirrappreżenta data reali—2026-02-31 tissodisfa kwalunkwe pattern raġonevoli iżda ma teżistix. Il-funzjoni ta’ estrazzjoni turi l-katina sħiħa, mill-iskema ħafifa mibgħuta lill-API sal-istanzjazzjoni vvalidata.

from pydantic import BaseModel, Field, field_validator
from pydantic import EmailStr
from datetime import date

class ContactExtraction(BaseModel):
    """Skema ta' validazzjoni għall-estrazzjoni tal-kuntatti."""
    last_name: str = Field(min_length=2, max_length=100)
    first_name: str = Field(min_length=2, max_length=100)
    email: EmailStr
    phone: str = Field(pattern=r"^\+?[0-9\s\-\.]{10,15}$")
    company: str
    title: str
    extraction_date: str

    @field_validator("extraction_date")
    @classmethod
    def validate_date(cls, v):
        try:
            date.fromisoformat(v)
            return v
        except ValueError:
            raise ValueError(f"Invalid date: {v}")

def extract_and_validate(text: str) -> ContactExtraction:
    """Testraġi kuntatt u tivvalida d-data."""
    # Schema għall-API (mingħajr restrizzjonijiet fini)
    api_schema = {
        "type": "object",
        "properties": {
            "last_name": {"type": "string"},
            "first_name": {"type": "string"},
            "email": {"type": "string"},
            "phone": {"type": "string"},
            "company": {"type": "string"},
            "title": {"type": "string"},
            "extraction_date": {"type": "string"}
        },
        "required": ["last_name", "first_name", "email", "phone",
                      "company", "title", "extraction_date"],
        "additionalProperties": False
    }

    response = client.responses.create(
        model="gpt-5.6-terra",
        instructions="Extract contact information. "
                     "Date format: YYYY-MM-DD.",
        input=text,
        text={
            "format": {
                "type": "json_schema",
                "name": "contact",
                "schema": api_schema,
                "strict": True
            }
        }
    )

    data = json.loads(response.output_text)
    # Validazzjoni ta' Pydantic b'restrizzjonijiet fini
    return ContactExtraction(**data)

Validazzjoni b’Zod (TypeScript/Node.js)

Jekk il-backend tiegħek huwa f’TypeScript, Zod huwa l-għodda ta’ referenza, u ġġib vantaġġ li Pydantic m’għandux bżonn jipprovdi: z.infer tidderiva t-tip ta’ TypeScript direttament mill-iskema ta’ validazzjoni. Tiddeskrivi l-forma darba biss, u l-kompilatur imbagħad jaf l-istruttura ta’ Invoice mingħajr ma żżomm interfaċċja parallela, allura m’hemm l-ebda riskju ta’ diverġenza.

L-iskema tal-fattura hawn taħt turi d-diviżjoni tax-xogħol: fuq in-naħa tal-API, siret hija sempliċiment stringa; fuq in-naħa ta’ Zod, trid tkun eżattament fjamek u erba’ karattri u fiha biss ċifri. Il-parse finali jqajjem eċċezzjoni jekk id-data ma taqbilx, u dik hija l-imġiba mixtieqa—żball għoli li jinterrompi l-ipproċessar tad-dokumenti huwa aħjar minn fattura b’SIRET fantasma maħżuna fid-database fost għaxart elef oħra.

import { z } from "zod";
import OpenAI from "openai";

const client = new OpenAI();

// Schema ta' Zod b'validazzjonijiet fini
const InvoiceSchema = z.object({
  number: z.string().regex(/^[A-Z]{2}-\d{4}-\d{4}$/),
  date: z.string().date(),
  amount_excl_tax: z.number().positive(),
  vat_rate: z.number().min(0).max(100),
  amount_incl_tax: z.number().positive(),
  supplier: z.object({
    name: z.string().min(2),
    siret: z.string().length(14).regex(/^\d+$/),
  }),
});

type Invoice = z.infer<typeof InvoiceSchema>;

async function extractInvoice(text: string): Promise<Invoice> {
  const response = await client.responses.create({
    model: "gpt-5.6-terra",
    instructions: "Extract invoice data.",
    input: text,
    text: {
      format: {
        type: "json_schema",
        name: "invoice",
        schema: {
          type: "object",
          properties: {
            number: { type: "string" },
            date: { type: "string" },
            amount_excl_tax: { type: "number" },
            vat_rate: { type: "number" },
            amount_incl_tax: { type: "number" },
            supplier: {
              type: "object",
              properties: {
                name: { type: "string" },
                siret: { type: "string" },
              },
              required: ["name", "siret"],
              additionalProperties: false,
            },
          },
          required: ["number", "date", "amount_excl_tax",
                     "vat_rate", "amount_incl_tax", "supplier"],
          additionalProperties: false,
        },
        strict: true,
      },
    },
  });

  const data = JSON.parse(response.output_text);

  // Validazzjoni ta' Zod b'restrizzjonijiet fini
  return InvoiceSchema.parse(data);
}

Mudell: erġa’ pprova b’korrezzjoni

Meta l-validazzjoni tfalli, ibgħat l-iżball lura lill-mudell għal korrezzjoni. Dan ir-rifless ibiddel in-natura tal-falliment: data fil-format żbaljat ma tibqax eċċezzjoni li titla’ sal-utent, iżda round trip addizzjonali ta’ ftit mijiet ta’ millisekondi li ħadd ma jinnota. Il-mekkaniżmu huwa sempliċi—nerġgħu ndaħħlu l-messaġġ ta’ validazzjoni fil-prompt tal-prova li jmiss, sabiex il-mudell ikun jaf eżattament x’mara ħażin minflok ma jipprova jindovina għat-tieni darba blind.

Dan il-kumdità teħtieġ fruntieri, madankollu. Illimita n-numru ta’ tentattivi, inkella restrizzjoni impossibbli—pattern wisq strett għan-numri barranin, pereżempju—se tiswielek sejħiet f’loop. U mmonitorja r-rata ta’ retry: jekk kwart mill-estrazzjonijiet tiegħek jgħaddu minn retry, il-problema tinsab fil-prompt inizjali jew fl-iskema, mhux fil-mudell.

def extract_with_retry(prompt: str, schema: dict,
                       validator, max_retries: int = 3) -> dict:
    """Testraġi u tivvalida b'retry awtomatiku."""
    last_error = None

    for attempt in range(max_retries):
        input_text = prompt
        if last_error:
            input_text += (f"\n\nWARNING: Your previous response had "
                          f"this validation error: {last_error}\n"
                          f"Correct and try again.")

        response = client.responses.create(
            model="gpt-5.6-terra",
            reasoning={"effort": "none"},  # temperature teħtieġ effort none
            input=input_text,
            text={"format": {"type": "json_schema",
                             "name": "data",
                             "schema": schema,
                             "strict": True}},
            temperature=0.1
        )

        data = json.loads(response.output_text)
        is_valid, error = validator(data)

        if is_valid:
            return data
        last_error = error

    raise ValueError(f"Failed after {max_retries} attempts: {last_error}")

Bank tat-test għal stedien tal-kalendarju

Ibni skema ta’ Pydantic biex testraġi avvenimenti—titlu, data, ħin, post, parteċipanti—imbagħad qabbadha wara sejħa ta’ Output Strutturat. Ittestja fuq ħames emails li fihom stedien, u żgur li tinkludi mill-inqas waħda fejn il-ħin huwa miktub b’kliem (“Il-Ħamis filgħodu tard”) u waħda fejn il-post huwa impliċitu (“kissoltu fil-kamra tal-laqgħat”). Dawn huma l-każijiet li jkissru l-validazzjoni, u jiddominaw f’kaxxa tal-posta reali.

Imbagħad żid retry awtomatiku u kejjel żewġ figuri: ir-rata ta’ suċċess fl-ewwel tentattiv u r-rata wara r-retry. It-tieni tgħidlek x’tixtri l-korrezzjoni, l-ewwel jekk għandekx terġa’ taħdem l-istruzzjonijiet tiegħek minflok ma tiddependi fuq it-tieni ċans.

Punti Ewlenin

  • L-Output Strutturat jiggarantixxi l-istruttura, mhux il-validità semantika
  • Uża żewġ skemi: waħda għall-API (stretta), waħda għall-validazzjoni tal-klijent
  • Pydantic (Python) u Zod (TypeScript) huma l-għodod ta’ referenza
  • Il-mudell ta’ retry b’feedback jikkoreġi l-biċċa l-kbira tal-iżbalji ta’ validazzjoni
  • Dejjem ivvalida fuq in-naħa tal-klijent qabel ma tippersisti d-data