基本的な使い方

このページでは、スキーマの作成、データのパース、推論型の使用の基本について説明します。Zod のスキーマ API に関する完全なドキュメントについては、スキーマの定義を参照してください。

スキーマの定義

他のことをする前に、まずスキーマを定義する必要があります。このガイドの目的のために、単純なオブジェクトスキーマを使用します。

import * as z from "zod"; 
 
const Player = z.object({ 
  username: z.string(),
  xp: z.number()
});

データのパース

任意の Zod スキーマを指定して、.parse を使用して入力を検証します。有効な場合、Zod は入力の強く型付けされたディープクローンを返します。

Player.parse({ username: "billie", xp: 100 }); 
// => { username: "billie", xp: 100 } を返す

注意 — スキーマで async refinements（リファインメント）や transforms（変換）などの非同期 API を使用している場合は、代わりに .parseAsync() メソッドを使用する必要があります。

await Player.parseAsync({ username: "billie", xp: 100 });

エラー処理

検証が失敗すると、.parse() メソッドは、検証の問題に関する詳細情報を含む ZodError インスタンスをスローします。

try {
  Player.parse({ username: 42, xp: "100" });
} catch(error){
  if(error instanceof z.ZodError){
    error.issues; 
    /* [
      {
        expected: 'string',
        code: 'invalid_type',
        path: [ 'username' ],
        message: 'Invalid input: expected string'
      },
      {
        expected: 'number',
        code: 'invalid_type',
        path: [ 'xp' ],
        message: 'Invalid input: expected number'
      }
    ] */
  }
}

try/catch ブロックを回避するために、.safeParse() メソッドを使用して、正常にパースされたデータまたは ZodError のいずれかを含むプレーンな結果オブジェクトを取得できます。結果の型は判別共用体（discriminated union）なので、両方のケースを便利に処理できます。

const result = Player.safeParse({ username: 42, xp: "100" });
if (!result.success) {
  result.error;   // ZodError インスタンス
} else {
  result.data;    // { username: string; xp: number }
}

注意 — スキーマで async refinements（リファインメント）や transforms（変換）などの非同期 API を使用している場合は、代わりに .safeParseAsync() メソッドを使用する必要があります。

await schema.safeParseAsync("hello");

型推論

Zod はスキーマ定義から静的型を推論します。z.infer<> ユーティリティを使用してこの型を抽出し、好きなように使用できます。

const Player = z.object({ 
  username: z.string(),
  xp: z.number()
});
 
// 推論された型を抽出
type Player = z.infer<typeof Player>;
 
// コード内で使用
const player: Player = { username: "billie", xp: 100 };

場合によっては、スキーマの入力型と出力型が異なることがあります。たとえば、.transform() API は入力をある型から別の型に変換できます。これらの場合、入力型と出力型を個別に抽出できます。

const mySchema = z.string().transform((val) => val.length);
 
type MySchemaIn = z.input<typeof mySchema>;
// => string
 
type MySchemaOut = z.output<typeof mySchema>; // z.infer<typeof mySchema> と同等
// number

基本をカバーしたので、次は Schema API（スキーマ API）に飛び込みましょう。

スキーマの定義

データのパース

エラー処理

型推論

On this page