Validação com JSON Schema e Zod
Nesta página
Lição atualizada em 3 de novembro de 2026 com base na documentação da OpenAI:
temperatureetop_psó são aceites com um esforço de raciocínio denone, enquanto os modelos GPT-5.6 raciocinam por padrão (medium). As chamadas que definem estes parâmetros devem, portanto, especificarreasoning={"effort": "none"}(API de Respostas) oureasoning_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