AI Tools · Function

zodSchema

zodSchema converts a Zod schema into an AI SDK-compatible schema. It is useful for structured data generation and tools, especially when conversion options such as references must be configured.

How it works

Call zodSchema with a Zod schema and, optionally, conversion settings. It produces an AI SDK-compatible schema that contains the generated JSON Schema representation together with validation behavior, making it suitable for structured generation and tool definitions.

Syntax

zodSchema(zodSchema, options?)

Parameters

Name	Type	Description
`zodSchema`	`z.Schema`	The Zod schema definition.
`options`	`object`	Additional options for the schema conversion.
`options.useReferences`	`boolean`	Enables support for references in the schema; defaults to false.

Returns

A Schema object compatible with the AI SDK, containing both the JSON Schema representation and validation functionality.

Key points

Converts a Zod schema into an AI SDK-compatible JSON Schema object.
Accepts the schema definition plus optional conversion configuration.
Returns a typed schema suitable for AI SDK operations.
Use it for structured data generation and tool definitions.
The SDK performs the underlying Zod-to-JSON-Schema conversion.
The useReferences option enables schema references when required.

Common mistakes

Set useReferences: true for recursive schemas such as those built with z.lazy; without references, recursive conversion is not supported.
Reference-enabled schemas may not work with every model or provider, so check provider support before using recursive references.

Example: Convert a Zod schema

import { zodSchema } from 'ai';
import { z } from 'zod';

const userSchema = zodSchema(
  z.object({
    name: z.string(),
    age: z.number().int(),
  }),
);

console.log(userSchema);

Wraps a Zod object so it can be supplied wherever the AI SDK expects a schema.

When to use it

Convert Zod validation models

You need an AI SDK schema from an existing Zod definition.

Generate structured data

A structured-generation operation needs a typed output shape.

Define tool schemas

A tool needs validated, model-visible input parameters.

Handle recursive schemas

A recursive Zod definition must be represented with references.

Interview questions

QWhat does zodSchema return?

zodSchema converts a Zod schema into an AI SDK-compatible schema. The result includes both a JSON Schema representation and validation functionality.

Follow-up: Why use the helper instead of passing a Zod object directly? Use it when conversion options such as useReferences must be specified.

QWhat are the function's parameters?

The first parameter is the Zod schema definition. The optional second parameter contains conversion settings, including useReferences, which defaults to false.

Follow-up: When should useReferences be enabled? Enable it for recursive schemas, for example schemas using z.lazy, subject to provider support.

QWhen should an explicit zodSchema call be used?

Zod objects can often be passed directly to AI SDK functions because the SDK converts them internally. zodSchema is useful when explicit schema conversion configuration is needed.

Follow-up: Where can the resulting schema be used? It can support structured data generation and tool definitions.

generateText
tools
jsonSchema
generate structured data

Source: zodSchema. Checked 2026-10-15.