Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Validointi JSON Scheman ja Zodin avulla

Oppitunti 11 / 16 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Validointi JSON Scheman ja Zodin avulla
  2. Miksi validoida vastaanoton jälkeen
  3. Python-validointi jsonschema-kirjastolla
  4. Validointi Pydanticilla
  5. Validointi Zodilla (TypeScript/Node.js)
  6. Malli: uudelleenyritys korjauksella
  7. Testipenkki kalenterikutsuille
  8. Keskeiset asiat

Oppitunti päivitetty 3. marraskuuta 2026 OpenAI:n dokumentaation perusteella: temperature ja top_p hyväksytään vain, kun päättelytaso on none, kun taas GPT-5.6-mallit käyttävät oletusarvoisesti päättelyä (medium). Näitä parametreja asettavien kutsujen on siksi määritettävä reasoning={"effort": "none"} (Responses API) tai reasoning_effort="none" (Chat Completions). Lähteet: Using GPT-6 · GPT-5.6 Terra.

Validointi JSON Scheman ja Zodin avulla

Rakenteellinen tulostus (Structured Output) takaa vastauksen rakenteen, mutta ei datan semanttista oikeellisuutta. “Sähköposti”-kenttä voi sisältää merkkijonon, joka ei ole kelvollinen sähköpostiosoite. Asiakaspään validointi JSON Scheman tai Zodin avulla on välttämätön täydennys robustille putkistolle.

Miksi validoida vastaanoton jälkeen

Kartoita, mitä API takaa, niin työnjako selkiytyy. OpenAI:n Rakenteellinen tulostus varmistaa, että JSON on syntaktisesti kelvollinen, että ilmoitetut tyypit pysyvät oikeina – merkkijono pysyy merkkijonona, kokonaisluku kokonaislukuna – että kaikki vaaditut kentät ovat läsnä ja että enum:lla rajoitetut arvot kuuluvat listaan. Näissä neljässä kohdassa voit kirjoittaa koodisi luottavaisin mielin.

Kaikki muu on sinun vastuullasi, ja se kattaa neljä ongelmaryhmää. Muotorajoitukset jäävät tiukan skeeman ulkopuolelle: mikään ei estä mallia palauttamasta arvoa jean.dupont(at)example.fr email-kentässä tai päivämäärää muodossa 15/03/2026, kun odotat ISO-muotoa. Rajoja ei myöskään tarkisteta, ei merkkijonon pituudelle eikä numeroiden alueelle: 350 vuoden ikä menee läpi ilman hälytystä. Kenttien välinen johdonmukaisuus jää myös tavoittamattomiin – end_date, joka on aiempi kuin start_date, on täysin kelvollista JSONia. Liiketoiminnan sääntöjen noudattaminen ei kuulu API:n huoliin: SIRET-tunnuksen (ranskalainen yritystunnus) on oltava neljätoista numeroa, mutta tämä on toimialatuntemustasi, ei dekooderin tehtävä.

Näillä neljällä ryhmällä on yksi pelottava yhteinen piirre: ne eivät aiheuta näkyviä virheitä. Väärin muotoiltu sähköpostiosoite, joka tallennetaan tietokantaan, ei paljastu ennen kuin sähköpostikampanja palautuu viikkoja myöhemmin. Siksi sääntö on: valido ennen pysyvää tallennusta, älä koskaan jälkeen.

Python-validointi jsonschema-kirjastolla

Käytännön seurauksena tarvitset samaa dataa varten kaksi skeemaa. Ensimmäinen lähetetään API:lle; se on tarkoituksellisen kevyt ja rajoittuu siihen, mitä tiukka tila hyväksyy. Toinen jää sinulle ja sisältää hienosäätöiset rajoitukset – format, pattern, minimum, maximum. Tämä näennäinen päällekkäisyys on vastuuerottelua: toinen kehystää generoinnin, toinen puolustaa tallennustasi. Alla olevassa esimerkissä vain roolin enum esiintyy molemmissa, koska se on ainoa rajoitus, jonka molemmat tasot voivat ilmaista.

import json
from jsonschema import validate, ValidationError

# Skeema OpenAI API:lle (tiukka, ei 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
}

# Laajennettu skeema asiakaspään validointiin
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]:
    """Validoi LLM-vastauksen laajennettua skeemaa vasten."""
    try:
        validate(instance=data, schema=validation_schema)
        return True, "Valid"
    except ValidationError as e:
        return False, f"Error: {e.message}"

Validointi Pydanticilla

Pydantic on usein kätevämpi kuin jsonschema validointiin Pythonissa, ja ero piilee siinä, mitä saat tulosteeksi. jsonschema kertoo vain kyllä tai ei ja jättää sinut dictionaryn kanssa, jota käsitellään muodossa data["email"] ilman editorin apua. Pydantic palauttaa tyypitetyn objektin: automaattinen täydennys toimii, attribuutin nimen kirjoitusvirhe havaitaan kirjoitusvaiheessa, ja data kiertää jatkossa ilman muunnoksia.

ContactExtraction-malli ilmaisee rajat suoraan kenttäilmoituksissa. date_extraction-kentän field_validator kattaa tapauksen, jota mikään tyyppimerkintä ei voi havaita: merkkijono on todellakin merkkijono, mutta sen on edustettava todellista päivämäärää – 2026-02-31 täyttää minkä tahansa järkevän pattern:n, mutta sitä ei ole olemassa. Ekstraktiofunktio näyttää koko ketjun kevyestä API:lle lähetetystä skeemasta validoituun instanssiin.

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

class ContactExtraction(BaseModel):
    """Validointiskeema kontaktien ekstraktiolle."""
    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:
    """Ekstrahoi kontaktin ja validoi datan."""
    # Skeema API:lle (ilman hienosäätöisiä rajoituksia)
    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)
    # Pydantic-validointi hienosäätöisine rajoituksineen
    return ContactExtraction(**data)

Validointi Zodilla (TypeScript/Node.js)

Jos backendisi on TypeScriptilla, Zod on viitekehys, ja se tuo etun, jota Pydanticin ei tarvitse tarjota: z.infer johtaa TypeScript-tyypin suoraan validointiskeemasta. Kuvailet muodon kerran, ja kääntäjä tuntee sen jälkeen Invoice:n rakenteen ilman, että sinun tarvitsee ylläpitää rinnakkaista rajapintaa, joten eroavuuden riskiä ei ole.

Alla oleva laskuskeema havainnollistaa työnjakoa: API-puolella siret on vain merkkijono; Zod-puolella sen on oltava tarkalleen neljätoista merkkiä pitkä ja sisällettävä vain numeroita. Lopullinen parse nostaa poikkeuksen, jos data ei täsmää, ja tämä on toivottu käyttäytyminen – kova ääni, joka keskeyttää dokumenttien käsittelyn, on parempi kuin kuvitteellinen SIRET-lasku tallennettuna tietokantaan kymmenien tuhansien muiden joukossa.

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

const client = new OpenAI();

// Zod-skeema hienosäätöisine validointeineen
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);

  // Zod-validointi hienosäätöisine rajoituksineen
  return InvoiceSchema.parse(data);
}

Malli: uudelleenyritys korjauksella

Kun validointi epäonnistuu, lähetä virhe takaisin mallille korjattavaksi. Tämä refleksi muuttaa epäonnistumisen luonteen: väärässä muodossa oleva päivämäärä ei ole enään käyttäjälle kupliva poikkeus, vaan muutaman sadan millisekunnin lisäkierros, jota kukaan ei huomaa. Mekanismi on yksinkertainen – injektoimme validointiviestin seuraavan yrityksen kehotteeseen, jolloin malli tietää tarkalleen, mikä meni pieleen, sen sijaan että arvaisi sokeasti toisen kerran.

Tämä mukavuus vaatii kuitenkin rajoja. Aseta yritysten enimmäismäärä, muuten mahdoton rajoitus – esimerkiksi ulkomaisille numeroille liian tiukka pattern – maksaa sinulle kutsuja silmukassa. Ja seuraa uudelleenyritysten määrää: jos neljäsosa ekstraktioistasi käy läpi uudelleenyrityksen, ongelma on alkuperäisessä kehotteessa tai skeemassa, ei mallissa.

def extract_with_retry(prompt: str, schema: dict,
                       validator, max_retries: int = 3) -> dict:
    """Ekstrahoi ja validoi automaattisella uudelleenyrityksellä."""
    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 requires 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}")

Testipenkki kalenterikutsuille

Rakenna Pydantic-skeema tapahtumien ekstraktioon – otsikko, päivämäärä, aika, sijainti, osallistujat – ja liitä se Rakenteellinen tulostus -kutsun taakse. Testaa viidellä sähköpostilla, jotka sisältävät kutsuja; varmista, että mukana on ainakin yksi, jossa aika on kirjoitettu auki (“torstaina myöhäisellä aamupäivällä”) ja yksi, jossa sijainti on implisiittinen (“kuten yleensä neuvotteluhuoneessa”). Nämä ovat tapauksia, jotka rikkovat validoinnin, ja ne dominoivat todellisessa sähköpostilaatikossa.

Lisää sitten automaattinen uudelleenyritys ja mittaa kahta lukua: ensimmäisen yrityksen onnistumisprosentti ja uudelleenyrityksen jälkeinen prosentti. Toinen kertoo, mitä korjaus tuo mukanaan, ensimmäinen sen, pitäisikö sinun työstää ohjeitasi uudelleen sen sijaan, että luottaisit toiseen mahdollisuuteen.

Keskeiset asiat

  • Rakenteellinen tulostus takaa rakenteen, ei semanttista oikeellisuutta
  • Käytä kahta skeemaa: yksi API:lle (tiukka), yksi asiakasvalidointiin
  • Pydantic (Python) ja Zod (TypeScript) ovat viitekehyksiä
  • Palauteen kanssa tehtävä uudelleenyritysmalli korjaa useimmat validointivirheet
  • Validoi aina asiakaspäässä ennen datan pysyvää tallennusta