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

Esquemas Zod em TypeScript

Aula 9 de 12 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Zod: O equivalente em TypeScript do Pydantic
  2. Definir um esquema simples
  3. Tipos de que vai precisar
  4. Esquemas aninhados
  5. Uma chamada completa com o SDK da Mistral
  6. Descrever campos com .describe()
  7. Gestão de erros
  8. Pontos-chave

Atualizado a 3 de novembro de 2026 após compilação com o SDK @mistralai/mistralai 3.5.0, Zod 4.6 e TypeScript 7.0.2. O exemplo original importava Mistral por predefinição, mas o SDK apenas oferece uma exportação nomeada. Além disso, lia uma variável response em main() que só existia dentro de extractBook(). O acesso a parsed ignorava o facto de choices e message serem opcionais nos tipos do SDK e tratava parsed como um Book, quando o seu tipo é na realidade unknown. A importação de ZodError era desnecessária: chat.parse() valida com safeParse e nunca lança exceções. A chave da API já não está codificada diretamente. Fontes: Mistral TypeScript SDK · exemplo oficial chat.parse.

Zod: O equivalente em TypeScript do Pydantic

Se trabalha com TypeScript ou JavaScript, o Zod é a biblioteca de validação de esquemas utilizada pelo SDK da Mistral para Saídas Estruturadas Personalizadas. Desempenha exatamente o mesmo papel que o Pydantic em Python: definir um esquema rigoroso que o modelo deve seguir. Tudo o que aprendeu sobre esquemas aplica-se aqui, com diferenças apenas na sintaxe.

Instale o SDK e o Zod num único comando:

npm install @mistralai/mistralai zod

O Zod funciona nativamente com TypeScript e fornece inferência automática de tipos — a sua principal vantagem em relação à escrita manual de interfaces.

Definir um esquema simples

Construa um esquema Zod com z.object(), atribuindo um validador a cada campo. A linha z.infer faz a diferença: deduz o tipo TypeScript a partir do esquema, pelo que não precisa de manter duas declarações paralelas que poderiam divergir.

import { z } from "zod";

const ContactSchema = z.object({
  name: z.string(),
  email: z.string(),
  phone: z.string(),
  company: z.string(),
});

// O TypeScript infere automaticamente o tipo
type Contact = z.infer<typeof ContactSchema>;
// => { name: string; email: string; phone: string; company: string }

Tipos de que vai precisar

O Zod cobre todas as necessidades para saídas estruturadas. O esquema de bilhete abaixo reúne casos comuns: campos básicos, um campo anulável para um bilhete não atribuído, um enum para prioridade e arrays tipados.

import { z } from "zod";

const TicketSchema = z.object({
  // Tipos básicos
  title: z.string(),
  description: z.string(),
  ticketId: z.number(),
  confidence: z.number(),
  isUrgent: z.boolean(),

  // Opcional (pode ser nulo)
  assignee: z.string().nullable(),

  // Enum (valores restritos)
  priority: z.enum(["low", "medium", "high", "critical"]),

  // Listas
  tags: z.array(z.string()),
  relatedIds: z.array(z.number()),
});

type Ticket = z.infer<typeof TicketSchema>;

Uma nuance merece atenção: enquanto o Python distingue int e float, o Zod conhece apenas z.number(). Tenha este mapeamento em mente ao portar um esquema de uma linguagem para a outra.

Pydantic (Python)Zod (TypeScript)
strz.string()
int, floatz.number()
boolz.boolean()
list[str]z.array(z.string())
Optional[str]z.string().nullable()
Enumz.enum([...])

Esquemas aninhados

Tal como com o Pydantic, um esquema pode conter outro: basta referenciar a constante. A composição lê-se então do mais interno para o mais externo: o endereço dentro da empresa, a empresa dentro da pessoa.

import { z } from "zod";

const AddressSchema = z.object({
  street: z.string(),
  city: z.string(),
  postalCode: z.string(),
  country: z.string(),
});

const CompanySchema = z.object({
  name: z.string(),
  industry: z.string(),
  address: AddressSchema,
});

const PersonSchema = z.object({
  firstName: z.string(),
  lastName: z.string(),
  email: z.string(),
  role: z.string(),
  company: CompanySchema,
});

type Person = z.infer<typeof PersonSchema>;

Uma chamada completa com o SDK da Mistral

Eis a mesma extração de livros da lição de Python, portada para TypeScript. Três pontos requerem atenção. O parâmetro é responseFormat em camelCase. Deve testar parsed antes de o utilizar: o SDK valida a resposta contra o esquema com safeParse e, se o JSON estiver truncado ou não corresponder ao esquema, deixa parsed como undefined em vez de lançar um erro. Por fim, o SDK não transporta o tipo do seu esquema: declara parsed como unknown. Passar o objeto através de BookSchema.parse() torna-o tipado como Book e revalida-o no processo.

import { Mistral } from "@mistralai/mistralai";
import { z } from "zod";

// 1. Definir o esquema
const BookSchema = z.object({
  title: z.string().describe("Book title"),
  authors: z.array(z.string()).describe("List of authors"),
  year: z.number().nullable().describe("Publication year"),
  genre: z.string().describe("Main literary genre"),
  summary: z.string().describe("Summary in 2-3 sentences"),
});

type Book = z.infer<typeof BookSchema>;

// 2. Criar o cliente
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

// 3. Chamar chat.parse()
async function extractBook(text: string): Promise<Book> {
  const response = await client.chat.parse({
    model: "mistral-large-latest",
    messages: [
      {
        role: "system",
        content: "You are an expert librarian. Extract book information.",
      },
      { role: "user", content: text },
    ],
    responseFormat: BookSchema,
    temperature: 0,
  });

  // 4. Aceder ao objeto analisado
  const message = response.choices?.[0]?.message;
  if (!message?.parsed) {
    throw new Error("Response missing, truncated, or non-compliant with schema");
  }
  // O JSON bruto permanece disponível em message.content
  console.log(`Raw JSON: ${message.content}`);
  // parsed é tipado como unknown: BookSchema.parse() devolve um Book tipado
  return BookSchema.parse(message.parsed);
}

// 5. Utilização
async function main() {
  const book = await extractBook(
    "I loved '1984' by George Orwell, published in 1949. A dystopian classic."
  );

  console.log(`Title: ${book.title}`);
  console.log(`Authors: ${book.authors.join(", ")}`);
  console.log(`Year: ${book.year}`);
  console.log(`Genre: ${book.genre}`);
}

main();

Descrever campos com .describe()

No Zod, .describe() desempenha o mesmo papel que Field(description=...) no Pydantic: dizer ao modelo o que o campo deve conter, especialmente quando o nome por si só é ambíguo. Um score sem descrição pode resultar numa escala de 0–100; com um intervalo explícito mencionado, segue a sua convenção.

const SentimentSchema = z.object({
  sentiment: z.enum(["positive", "negative", "neutral"]).describe(
    "Overall sentiment of the text"
  ),
  score: z.number().describe(
    "Confidence score between 0.0 and 1.0"
  ),
  keywords: z.array(z.string()).describe(
    "The 3–5 main keywords"
  ),
  summary: z.string().describe(
    "Summary in one sentence maximum"
  ),
});

Gestão de erros

O padrão de nova tentativa segue a mesma lógica que em Python, com uma assinatura genérica que o torna reutilizável para qualquer esquema. Não há necessidade de capturar um ZodError: chat.parse() não o lança; deixa parsed vazio. Esse caso, juntamente com erros de rede ou HTTP, desencadeia uma nova tentativa. A restrição z.ZodType<T> liga o esquema passado como argumento ao tipo de retorno: schema.parse() devolve um T, pelo que o chamador obtém um objeto corretamente tipado sem anotações extras.

// Continuação do mesmo ficheiro: client, z e BookSchema já estão definidos

async function safeExtract<T>(
  text: string,
  schema: z.ZodType<T>,
  maxRetries = 2
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const response = await client.chat.parse({
        model: "mistral-large-latest",
        messages: [
          { role: "system", content: "Extract the requested information." },
          { role: "user", content: text },
        ],
        responseFormat: schema,
        temperature: 0,
      });

      const parsed = response.choices?.[0]?.message?.parsed;
      if (!parsed) {
        throw new Error("Response missing or non-compliant with schema");
      }
      return schema.parse(parsed); // restaura o tipo T
    } catch (error) {
      console.error(`Attempt ${attempt + 1} failed:`, error);
      if (attempt === maxRetries) throw error;
    }
  }
  throw new Error("Unexpected failure");
}

// Utilização
try {
  const book = await safeExtract("My text here", BookSchema);
  console.log(book.title);
} catch (error) {
  console.error("Extraction failed:", error);
}

Pontos-chave

  • O Zod é o equivalente em TypeScript do Pydantic para Saídas Estruturadas Personalizadas
  • z.infer<typeof Schema> gera automaticamente o tipo TypeScript
  • .describe() adiciona instruções por campo, como Field(description=...) em Python
  • O SDK TypeScript da Mistral utiliza responseFormat (camelCase) em vez de response_format
  • Uma resposta não conforme deixa parsed como undefined (sem exceção): teste essa condição e tente novamente se necessário