Validazzjoni b'JSON Schema u Zod
F'din il-paġna
Lezzjoni aġġornata fit-3 ta’ Novembru 2026 abbażi tad-dokumentazzjoni ta’ OpenAI:
temperatureutop_phuma 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ċifikawreasoning={"effort": "none"}(Responses API) jewreasoning_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