Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Validação com JSON Schema e Zod

Aula 11 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Validação com JSON Schema e Zod
  2. Por que validar após a receção
  3. Validação em Python com jsonschema
  4. Validação com Pydantic
  5. Validação com Zod (TypeScript/Node.js)
  6. Padrão: nova tentativa com correção
  7. Banco de teste para convites de calendário
  8. Pontos-chave

Lição atualizada em 3 de novembro de 2026 com base na documentação da OpenAI: temperature e top_p só são aceites com um esforço de raciocínio de none, enquanto os modelos GPT-5.6 raciocinam por padrão (medium). As chamadas que definem estes parâmetros devem, portanto, especificar reasoning={"effort": "none"} (API de Respostas) ou reasoning_effort="none" (Chat Completions). Fontes: Utilizar o GPT-6 · GPT-5.6 Terra.

Validação com JSON Schema e Zod

A Saída Estruturada garante a estrutura da resposta, mas não a validade semântica dos dados. Um campo «email» pode conter uma cadeia de caracteres que não seja um endereço de e-mail válido. A validação do lado do cliente utilizando JSON Schema ou Zod é o complemento essencial para um pipeline robusto.

Por que validar após a receção

Faça um balanço do que a API garante e a divisão de trabalho torna-se clara. A Saída Estruturada da OpenAI assegura que o JSON é sintaticamente válido, que os tipos declarados são respeitados — uma cadeia de caracteres permanece uma cadeia de caracteres, um inteiro permanece um inteiro —, que todos os campos obrigatórios estão presentes e que os valores restringidos por um enum pertencem à lista. Nestes quatro pontos, pode escrever o seu código com confiança.

Todo o resto depende de si, abrangendo quatro famílias de problemas. As restrições de formato escapam ao esquema estrito: nada impede o modelo de devolver jean.dupont(at)example.fr num campo email, ou uma data no formato 15/03/2026 quando espera ISO. Os limites também não são verificados, nem para o comprimento da cadeia de caracteres nem para o intervalo numérico: uma idade de 350 passará sem pestanejar. A consistência entre campos permanece fora de alcance — uma end_date anterior à start_date é um JSON perfeitamente válido. E a validade comercial não tem razão para preocupar a API: um SIRET (identificador de empresa francês) deve ter catorze dígitos, mas esse é o conhecimento do seu domínio, não do descodificador.

Estas quatro famílias partilham uma característica assustadora: não causam erros visíveis. Um e-mail mal formatado guardado na base de dados só se manifestará quando a campanha de e-mail falhar semanas mais tarde. Daí a regra: valide antes de persistir, nunca depois.

Validação em Python com jsonschema

A consequência prática é que precisa de dois esquemas para os mesmos dados. O primeiro vai para a API, intencionalmente leve, limitado ao que o modo estrito aceita. O segundo fica consigo e transporta as restrições de granularidade fina — format, pattern, minimum, maximum. Esta aparente duplicação é uma separação de preocupações: um enquadra a geração, o outro defende o seu armazenamento. No exemplo abaixo, apenas o enum de função aparece em ambos, porque é a única restrição que ambos os níveis podem expressar.

import json
from jsonschema import validate, ValidationError

# Esquema para a API OpenAI (estrito, sem 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
}

# Esquema estendido para validação do lado do cliente
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]:
    """Valida a resposta do LLM contra o esquema estendido."""
    try:
        validate(instance=data, schema=validation_schema)
        return True, "Válido"
    except ValidationError as e:
        return False, f"Erro: {e.message}"

Validação com Pydantic

O Pydantic é frequentemente mais conveniente do que o jsonschema para validação em Python, e a diferença reside no que obtém no output. O jsonschema diz-lhe sim ou não e deixa-o com um dicionário, manipulado via data["email"] sem assistência do editor. O Pydantic devolve um objeto tipado: o preenchimento automático funciona, um erro de digitação num nome de atributo é detetado no momento da escrita e os dados circulam thereafter sem conversão.

O modelo ContactExtraction expressa limites diretamente nas declarações de campo. O field_validator em date_extraction cobre o caso que nenhuma anotação de tipo consegue apanhar: a cadeia de caracteres é de facto uma cadeia de caracteres, mas deve representar uma data real — 2026-02-31 satisfaz qualquer pattern razoável, mas não existe. A função de extração mostra a cadeia completa, desde o esquema leve enviado para a API até à instanciação validada.

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

class ContactExtraction(BaseModel):
    """Esquema de validação para extração de contactos."""
    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"Data inválida: {v}")

def extract_and_validate(text: str) -> ContactExtraction:
    """Extrai um contacto e valida os dados."""
    # Esquema para a API (sem restrições de granularidade fina)
    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="Extraia informações de contacto. "
                     "Formato da data: AAAA-MM-DD.",
        input=text,
        text={
            "format": {
                "type": "json_schema",
                "name": "contact",
                "schema": api_schema,
                "strict": True
            }
        }
    )

    data = json.loads(response.output_text)
    # Validação Pydantic com restrições de granularidade fina
    return ContactExtraction(**data)

Validação com Zod (TypeScript/Node.js)

Se o seu backend estiver em TypeScript, o Zod é a ferramenta de referência, e traz uma vantagem que o Pydantic não precisa de fornecer: z.infer deriva o tipo TypeScript diretamente do esquema de validação. Descreve a forma uma vez e o compilador conhece então a estrutura de Invoice sem que tenha de manter uma interface paralela, pelo que não há risco de divergência.

O esquema de fatura abaixo ilustra a divisão de trabalho: do lado da API, siret é apenas uma cadeia de caracteres; do lado do Zod, deve ter exatamente catorze caracteres e conter apenas dígitos. O parse final lança uma exceção se os dados não se encaixarem, e esse é o comportamento desejado — um erro estridente que interrompe o processamento do documento é melhor do que uma fatura com SIRET fictício armazenada na base de dados entre dez mil outras.

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

const client = new OpenAI();

// Esquema Zod com validações de granularidade fina
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: "Extraia dados da fatura.",
    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);

  // Validação Zod com restrições de granularidade fina
  return InvoiceSchema.parse(data);
}

Padrão: nova tentativa com correção

Quando a validação falha, envie o erro de volta ao modelo para correção. Este reflexo altera a natureza da falha: uma data no formato errado deixa de ser uma exceção que sobe até ao utilizador, tornando-se numa ida e volta extra de algumas centenas de milissegundos que ninguém nota. O mecanismo é simples — reinjetamos a mensagem de validação no prompt da próxima tentativa, para que o modelo saiba exatamente o que correu mal em vez de adivinhar cegamente uma segunda vez.

Este conforto requer, no entanto, limites. Limite o número de tentativas, ou uma restrição impossível — um pattern demasiado estrito para números estrangeiros, por exemplo — custar-lhe-á chamadas num loop. E monitore a taxa de nova tentativa: se um quarto das suas extrações passar por uma nova tentativa, o problema está no prompt inicial ou no esquema, não no modelo.

def extract_with_retry(prompt: str, schema: dict,
                       validator, max_retries: int = 3) -> dict:
    """Extrai e valida com nova tentativa automática."""
    last_error = None

    for attempt in range(max_retries):
        input_text = prompt
        if last_error:
            input_text += (f"\n\nAVISO: A sua resposta anterior teve "
                          f"este erro de validação: {last_error}\n"
                          f"Corrija e tente novamente.")

        response = client.responses.create(
            model="gpt-5.6-terra",
            reasoning={"effort": "none"},  # temperature requer 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"Falhou após {max_retries} tentativas: {last_error}")

Banco de teste para convites de calendário

Construa um esquema Pydantic para extrair eventos — título, data, hora, localização, participantes — e ligue-o atrás de uma chamada de Saída Estruturada. Teste em cinco e-mails contendo convites, certificando-se de incluir pelo menos um onde a hora está escrita por extenso («quinta-feira no final da manhã») e um onde a localização é implícita («como habitualmente na sala de reuniões»). São estes os casos que quebram a validação e que dominam numa caixa de entrada real.

Em seguida, adicione a nova tentativa automática e meça dois valores: a taxa de sucesso à primeira tentativa e a taxa pós-nova tentativa. O segundo diz-lhe o que a correção lhe traz, o primeiro se deve retrabalhar as suas instruções em vez de contar com uma segunda hipótese.

Pontos-chave

  • A Saída Estruturada garante a estrutura, não a validade semântica
  • Utilize dois esquemas: um para a API (estrito), outro para validação do cliente
  • Pydantic (Python) e Zod (TypeScript) são as ferramentas de referência
  • O padrão de nova tentativa com feedback corrige a maioria dos erros de validação
  • Valide sempre do lado do cliente antes de persistir os dados