`zodSchema()`

Zod 스키마를 AI SDK와 호환되는 JSON 스키마 객체로 변환해 주는 헬퍼 함수예요.

출처: 문서

본문

zodSchema는 Zod 스키마를 AI SDK와 호환되는 JSON 스키마 객체로 변환하는 헬퍼 함수예요. Zod 스키마와 선택적 설정을 입력으로 받아 타입이 지정된 스키마를 반환해요.

Zod 객체를 AI SDK 함수에 직접 전달할 수도 있어요. 내부적으로 AI SDK는 `zodSchema()`를 사용해 Zod 스키마를 JSON 스키마로 변환해요. 다만 `useReferences` 같은 옵션을 지정하고 싶다면 `zodSchema()` 헬퍼 함수를 대신 전달하면 돼요. Zod 스키마에 `.meta()`나 `.describe()`로 메타데이터를 추가할 때는 이 메서드들을 스키마 체인의 **맨 끝**에서 호출해야 해요.

메타데이터는 특정 스키마 인스턴스에 첨부되는데, 대부분의 스키마 메서드(.min(), .optional(), .extend() 등)는 이전 인스턴스의 메타데이터를 상속하지 않는 새 스키마 인스턴스를 반환해요. Zod의 불변성 때문에 .meta()나 .describe()가 체인의 마지막 메서드일 때만 메타데이터가 JSON 스키마 출력에 포함돼요.

// ❌ Metadata will be lost - .min() returns a new instance without metadata
z.string().meta({ describe: 'first name' }).min(1);

// ✅ Metadata is preserved - .meta() is the final method
z.string().min(1).meta({ describe: 'first name' });

재귀 스키마 예시

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

// Define a base category schema
const baseCategorySchema = z.object({
  name: z.string(),
});

// Define the recursive Category type
type Category = z.infer<typeof baseCategorySchema> & {
  subcategories: Category[];
};

// Create the recursive schema using z.lazy
const categorySchema: z.ZodType<Category> = baseCategorySchema.extend({
  subcategories: z.lazy(() => categorySchema.array()),
});

// Create the final schema with useReferences enabled for recursive support
const mySchema = zodSchema(
  z.object({
    category: categorySchema,
  }),
  { useReferences: true },
);

Import

import { zodSchema } from "ai"

API Signature

Parameters

zodSchema: z.Schema — Zod 스키마 정의.
options: object — 스키마 변환을 위한 추가 옵션.
- useReferences: boolean (선택) — 스키마에서 참조 지원을 활성화해요. z.lazy 같은 재귀 스키마에서 필요해요. 다만 모든 언어 모델과 프로바이더가 이런 참조를 지원하지는 않아요. 기본값은 false예요.

Returns

AI SDK와 호환되는 Schema 객체를 반환해요. JSON 스키마 표현과 검증 기능을 모두 담고 있어요.

더 알아보기 (Learn more)

전체 사이트맵