zodとは何か

最初は「型のライブラリらしい」「バリデーションもできるらしい」くらいでしかわかっていなかったので、あらためてまとめつつ理解してみる。 あらためて理解してみるシリーズ第2弾である。

TypeScript自体がすでに型を持っているので、さらにライブラリの「Zod」が必要なのかが分かりにくい。 この記事では、どんな問題を解決するためのライブラリかという観点で整理していこうと思う。

Zodは何をするライブラリか

簡単にいうと、Zodは実行時に値を検証するためのライブラリである。
そして、その検証ルールからTypeScriptの型も取り出せる。

例えば次のように書ける。

import { z } from "zod";

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
});

この定義があると、

  • idは数値であること
  • nameは文字列であること
  • emailはメール形式であること

を実行時にチェックできる。
さらに、このschemaからTypeScriptの型も作れる。

type User = z.infer<typeof UserSchema>;

つまりZodは、「型定義」と「値の検証」をできるだけ同じ場所にまとめるための道具である。

TypeScriptの型だけではなぜ足りないのか

TypeScriptは便利だが、コンパイル時の型チェックしかしてくれない。
言い換えると、「コードを書く人に対して」安全性を高めてくれるが、「外から入ってくる値が本当に正しいか」は保証することはできない。

例えばAPIからこんな値が返ってきたとする。

const data = await fetch("/api/user").then((res) => res.json());

このdataは、実行時には何が入ってくるか分からない。
TypeScriptでUserと注釈を付けても、実際のJSONが壊れていたら意味がない。

つまり、次の2つは別物である。

  • TypeScriptの型
    • 開発時にコードの整合性を見る
  • Zodの検証
    • 実行時に実データが正しいかを見る

TypeScriptではint8やint64を区別できるのか

ここで一つ気になりやすいのが、数値型の細かい区別である。

TypeScriptでは、基本的に数値はnumberとして扱われる。
つまり、JavaやGoやRustのように、

  • int8
  • int32
  • int64
  • float

のような細かい数値型を標準で区別しているわけではない。

このため、TypeScriptだけでは「これは8bit整数」「これは64bit整数」といった表現はほぼできない。
少なくとも、言語機能として自然に区別できるわけではない。

ではZodを使うとどうなるか。

実行時の制約としてはかなり表現できるが、TypeScriptの型そのものが増えるわけではない。

例えばint8的な制約なら、こう書ける。

const int8Schema = z.number().int().min(-128).max(127);
const uint8Schema = z.number().int().min(0).max(255);

これで、

  • 整数であること
  • 範囲内であること

は検証できる。
ただし、z.infer<typeof int8Schema>で得られる型は、実質的にはnumberである。

つまりZodがやってくれるのは、

  • numberの中での制約チェック
  • 値がその範囲に収まるかの検証

であって、TypeScriptの型システムにint8という新しい数値型を追加してくれるわけではない。

int64は特に注意が必要

int64のような大きい整数を扱うときは、さらに注意が必要である。
JavaScriptのnumberは64bit整数を完全に安全に扱えるわけではなく、安全整数の範囲に制限がある。

そのため、バックエンドがint64を返してくるときは、次の2パターンを分けて考えた方がよい。

1. 安全整数の範囲に収まる前提

この場合は、普通にz.number().int()で扱ってもよいことが多い。

const idSchema = z.number().int();

2. 大きいIDやlong値が来る可能性がある

この場合は、文字列として受ける方が安全なことがある。

const int64AsStringSchema = z.string().regex(/^-?\d+$/);

APIの設計によっては、巨大な整数をJSON上では文字列で返すことも多い。
このケースでは、フロントで無理にnumberにせず、まず文字列として検証し、必要ならあとでBigIntなどへ変換する方が安全である。

つまりZodで数値制約はかなり書けるが、JavaScript自体の数値表現の限界は超えられない、という点は注意が必要である。

Zodが活躍する場所

Zodは、外部から値を受け取る箇所で特に役立つ。

例えば次のような場面で便利である。

  • フォーム入力
  • URLクエリパラメータ
  • APIレスポンス
  • APIリクエストbody
  • 環境変数
  • CMSやMarkdownのfrontmatter

どれも共通しているのは、コードの外から値が渡されるという点である。

業務でも、こうした外部の値が想定した型と違うために起きるバグに、何度も遭遇した。

確認すれば分かることでも、思い込みのためにすぐ気づけない場合も多い。そのため、できるだけ人の確認に頼らず、不正な値をはじけるようにしたい。

バックエンドから渡される値の型チェックにも使えるのか

フロントエンドでは、バックエンドから返ってくるJSONをつい信用してしまいがちである。
しかし実際には、次のようなズレは普通に起こる。

  • numberのはずが文字列で返ってくる
  • nullが来ない前提なのにnullが返る
  • フィールド名が一部変わっている
  • 配列のはずがオブジェクトになっている
  • バージョン違いでレスポンス形式が変わる

TypeScriptの型注釈だけでは、このズレは防げない。

なぜならfetch().json()の結果は、実行時にはただの不確定な値だからである。

例えば次のように書く。

const UserSchema = z.object({
  id: z.number().int(),
  name: z.string(),
  email: z.string().email(),
});

const json = await fetch("/api/user").then((res) => res.json());
const result = UserSchema.safeParse(json);

if (!result.success) {
  console.error(result.error);
} else {
  console.log(result.data);
}

このようにすると、「バックエンドが返した値が本当に想定どおりか」を受け取った瞬間に確認できる。
そのため、フロントエンドとバックエンドの境界で起きる不整合を早めに見つけやすい。

特に次のような場面ではかなり有効である。

  • 自前APIを叩く画面
  • 外部APIを叩く処理
  • BFFから値をもらうフロント
  • 管理画面の一覧取得
  • CSV / JSONインポート

バックエンドがTypeScriptで書かれているかどうかに関係なく、受け取った側で最後に検証するという意味でZodは価値がある。

フロントとバックでschemaを共有する考え方

さらに進むと、フロントとバックエンドで同じschemaを共有したくなる。
これはかなり理にかなっている。

例えば同じZod schemaを共有できれば、

  • リクエストの検証
  • レスポンスの検証
  • フォーム入力の検証
  • TypeScriptの型推論

をある程度一本化できる。

ただし、最初から全部共通化しようとすると設計が重くなりやすい。
まずは「境界の入力値をZodで守る」くらいから始める方が現実的である。

パースするという考え方

Zodを使うときは、「validateする」より「parseする」と考えるとしっくりくる。

const user = UserSchema.parse(data);

これは「dataがUserSchemaに合っているなら、その形として扱う。合っていなければエラーにする」という意味になる。

もし例外を投げたくなければsafeParseも使える。

const result = UserSchema.safeParse(data);

if (!result.success) {
  console.error(result.error);
} else {
  console.log(result.data);
}

このsafeParseがかなり便利で、フォームやAPIハンドラで特に使いやすい。
成功時と失敗時が明確に分かれるので、エラーハンドリングを素直に書ける。

どこまで厳しく書くべきか

Zodを使い始めると、何でも厳密に書きたくなることがある。
ただ、最初から細かすぎるschemaを作ると運用が重くなる。

まずは次のような基本からで十分である。

  • 文字列か
  • 数値か
  • 配列か
  • オブジェクトか
  • 必須か任意か

そこから必要に応じて、

  • .email()
  • .min()
  • .max()
  • .url()
  • .regex()
  • .refine()

のような条件を足していくとよい。

最初から完璧なschemaを目指すより、「不具合が起きやすい境界から検証する」方が実務では進めやすい。

TypeScriptの型をZodにするのか、Zodから型を作るのか

ここもよく迷うところである。

結論からいうと、外部入力の境界ではZodを先に書いて、型はそこから作る方が分かりやすいことが多い。

理由は単純で、外から来る値で大事なのは「型定義」そのものよりも「本当にその値を受け入れてよいか」だからである。
つまり、検証ルールであるschemaを中心に定義し、型はそこから作ればよい。

一方で、内部ロジックだけの型は普通にTypeScriptのtypeやinterfaceを書けば十分なこともある。

AstroでもZodは相性が良い

ZodはReactやNext.jsだけのライブラリではない。
Astroのような構成でもかなり使いやすい。

このブログでも、記事のfrontmatterはZodベースで定義している。

例えばContent Collectionsのschemaでは、

  • titleは文字列
  • publishedAtは日付
  • tagsは文字列配列
  • draftは真偽値

といったルールを先に決めている。
これにより、記事を書くときのミスを早い段階で見つけやすくなる。

個人ブログのように、あとで自分が使う構成ほど、こうした仕組みが目立たないながらも役立つ。

Zodを使うときの注意点

便利なライブラリだが、何でもZodに寄せればよいわけではない。

注意したいのは次の点である。

1. schemaを複雑にしすぎない

複雑すぎるschemaは、逆に読みづらくなる。
特に.refine()を多用しすぎると、何を保証しているのか追いにくい。

2. 内部データまで全部parseしない

外部入力の境界では有効だが、完全に内部で生成した値まで毎回parseすると冗長になることがある。

3. エラーメッセージ設計は別途考える

Zodのエラーは開発には便利だが、そのままユーザー向け表示に使うには不親切なこともある。
フォームでは整形が必要になる場合が多い。

4. 数値型の厳密さを過信しない

Zodでint8的な制約や範囲制約は書けるが、JavaScriptのnumber自体が別の数値型になるわけではない。
特にint64相当の大きい値は、文字列で扱うべきケースがある。

まとめ

Zodは、型っぽい記法で書ける便利ライブラリというより、実行時に値を信頼してよいかを確認するための道具と理解すると分かりやすい。

大事なのは次の点である。

  • TypeScriptの型と、実行時の値検証は別物
  • Zodは外部から値を受け取る箇所で特に役立つ
  • schemaから型を作れるので、定義の重複を減らせる
  • AstroのfrontmatterやAPI、フォームでも使いやすい

TypeScriptを使っていると、型があるだけで安全に見えてしまう。
でも実際には、APIやフォームや環境変数のような外から来る値を扱う箇所が、一番不具合を起こしやすい。
その境界を守るためにZodを使う、と考えるとかなり整理しやすいと思う。

前後の記事

関連記事

技術(フロントエンド) 2026/3/1

Reactの状態管理を理解する

状態管理という言葉が何を指しているのか、なぜ必要になるのかを自分なりに整理する。