Zod 4 リリース
(zod.dev)- スキーマ宣言およびバリデーションライブラリである Zod のバージョン 4 をリリース。大幅な性能向上と長年要望されていた機能を含む安定版の公開
- 速度とバンドルサイズが大きく改善され、新しいミニ版（v4-mini）はバンドルサイズを大幅に削減
- 新しい メタデータレジストリ と JSON Schema 変換、そして再帰型推論機能が追加
- エラーメッセージのカスタマイズ と多言語ロケールシステムなど、開発者体験が強化
- 今後ライブラリ構築に活用できる コアサブパッケージ の導入により、拡張性がさらに向上
Zod 4 の紹介
主なリリース案内
- 1年間にわたる活発な開発を経て、Zod 4 が安定版として公開
- Clerk の OSS Fellowship 支援を受けて開発が進行
- 現在は Zod 3 と並行して配布されており、Zod 4 への段階的な移行が容易
- 一部の破壊的変更の詳細は Migration guide で確認可能
成長の背景
- 2021年に公開された Zod 3 と比べ、Zod 4 は GitHub スター数と週間ダウンロード数が飛躍的に増加
- Zod 4 ははるかに高速で、軽量になり、TypeScript コンパイラの効率も改善
- 長期的に要望の多かった9つの主要イシュー が解決
ベンチマークと性能
- 速度向上:
- 文字列パース: 14.71倍高速
- 配列パース: 7.43倍高速
- オブジェクトパース（safeParse）: 6.5倍高速
- リポジトリ上で直接ベンチマークを実行できるスクリプトを提供
- 改良されたジェネリック構造により、
.extend()、.omit()などのメソッドチェーン時の コンパイル性能が10倍向上 - 大規模なスキーマやコードベースで TypeScript のコンパイル速度が大幅に改善
バンドルサイズと Zod Mini
- 基本バンドルサイズが 57%削減 され、v4 は v3 比で 2.3 倍小さいサイズを実現
- zod/v4-mini は関数ベースのツリーシェイク可能な API を提供し、バンドルサイズを 最大85%削減
- core と v4-mini の API 差分は公式ドキュメントで詳しく整理
- バンドラーで未使用メソッドを簡単に除去できるような構造に設計
メタデータレジストリと JSON Schema サポート
- typed metadata をスキーマに強い型付けで登録・管理可能
- グローバルレジストリ（
z.globalRegistry）で JSON Schema 互換メタデータの処理と自動取り込み機能を提供 .meta()、.describe()によりスキーマのドキュメント化が容易.toJSONSchema()により スキーマを JSON Schema 形式へ変換 でき、メタデータも自動反映
再帰型の自動推論
- 再帰オブジェクト型と相互再帰型を、別途型キャストなしで自然に定義・推論可能
- 既存の Zod 3 パターンより使い勝手が大きく向上
- 再帰・相互再帰型でも すべてのスキーマメソッド機能が利用可能
ファイル型と検証機能
- 新しい
file()型によりFileインスタンスの検証が可能 - ファイルサイズ（
min、max）や MIME タイプなど 多様なファイル制約の検証を提供
エラーメッセージとロケールシステム
- グローバルロケール API（
z.locales）により エラーメッセージの多言語対応 が可能 - 公式の
z.prettifyError関数により、ユーザーフレンドリーなエラーフォーマットを提供
フォーマット関数とテンプレートリテラル
- 既存の文字列フォーマット（
emailなど）はトップレベル関数へ昇格し、可読性とツリーシェイキングが改善 - 多様な メール正規表現 オプションを提供し、さまざまな検証要件に対応
- テンプレートリテラル型をサポート: 型システムで表現可能な文字列パターンや複雑な組み合わせを簡単に実装
新たに追加された数値および bigint フォーマット
- 固定幅の 整数・浮動小数点型（
int32、uint64など）をサポート - 安全な範囲内で自動的に 最小/最大制約 が追加されたスキーマを生成可能
z.stringbool の紹介
- 文字列ベースのブール値パース（
yes、noなど）が可能で、環境変数スタイルのパースにも対応 - truthy/falsy 値はカスタマイズ可能
エラーカスタマイズ API の統合
- 統一された
errorパラメータ により、エラーメッセージと処理ロジックの構造を整理 - 既存の複数のエラー関連 API（
message、invalid_type_error、errorMap）は deprecated
その他の主要改善点
- 判別可能ユニオン（discriminated unions） が多様なスキーマ、ネスト、組み合わせをサポート
.literal()が同時に複数の値を許容.refine()などのカスタム検証がより直感的に統合- transform 関連の
.overwrite()により、変換後の型を変更せずに後処理が可能
ライブラリ拡張性と新しいコア
- zod/v4/core により中核機能が別サブパッケージとして分離され、さまざまなライブラリ・プラットフォームとの統合/拡張が可能
- ライブラリ制作者向けのガイド文書と拡張例を提供
まとめ
- Zod 4 は 型安全性、性能、拡張性、開発者体験 をすべて大きく改善したデータ検証ライブラリとして位置づけられる
- 今後、追加の設計ポストやアップデートが予告
- 既存ユーザーとライブラリ制作者の双方に向けた幅広い支援を準備
快適なパース体験を
— Colin McDonnell @colinhacks
1件のコメント
Hacker Newsの意見
作者本人が意見の共有を求め、バージョン管理方式について詳しく説明しつつ、npmはZodのようなケースを扱うのに適していないと強調。多くのライブラリがZodのインターフェース/クラスを直接importして使っているため、Zodでメジャーバージョン変更が起きるとそれらのライブラリもすべて同時対応が必要になり、バージョン爆発が起こりうると指摘。Goに似た形で、破壊的変更は新しいサブパスを追加する方式を使い、TypeScript環境では
zod@^3.25.0ひとつで"zod/v3"と"zod/v4"を同時にサポートでき、最終利用者に段階的なアップグレード経路を提供できると説明Zodへの貢献に感謝し、特に
tscの性能向上と discriminated unions の改善に期待しているとの声。バージョン管理方式は十分理解できるが、推移的依存関係の衝突を気にしなくてよい自分のような利用者向けには、4.0.0パッケージとして単独提供するのもよさそうだと提案。"zod/v4"にimportを書き換える必要がある点はコード上のノイズになり、IDEの自動importとの衝突など追加の手間も生みそうだが、全体としては非常に有望なアップグレードだとして感謝を表明モバイルで記事を見ていて見落としていたら申し訳ないと断ったうえで、
.optional()に関する最大の不満点が今回の上位9/10件の課題解決に含まれているか質問。Zodが非常に優れているので、不便があっても使い続けていると述べ、すばらしいライブラリへの感謝を示す新バージョンのZodで大量の手作業ハックコードを削除できそうでありがたいとの声。自分ではtypo削減のために
zod-key-parserを使っているが、こうした機能がなぜ標準でライブラリに入っていないのか、対象範囲外と見なされているのか、それとも未実装なのかが気になるとして、関連する公開議論も共有短期的な痛みを最小化する方法がしばしば最善だと強調し、Python 2/3移行の大混乱を思い出すという意見
再帰型と discriminated union 形式を同時に使うケース（たとえばXMLをJSONの中に含める場合）でかなり苦労した経験を共有し、今回の更新で状況が大きく改善することを期待
zod/v4-miniimportに懐疑的だという意見。このせいでむしろバンドルサイズが増えるのではと推測。公式ドキュメントでは「多くの場合zod/v4を推奨」とされるため、アプリ開発者はzod/v4を使う一方、ライブラリ作者がバンドルサイズ削減のためにzod/v4-miniも追加すると、両方がバンドルに含まれて重複する恐れがある。もしzod/v4がzod/v4-miniのラッパーなら、この問題は減らせるのかと質問Zod 4の移行を容易にするため、v3とv4を
zod@3.25で同時提供する方式が導入されたが、この構造はnpmの依存関係管理の限界と絡み合い、v4をv3のように見せかける必要があったと批判。npmのpeer dependenciesシステムの非効率さも指摘作者本人が、Golang式のサブパス追加によるバージョン管理戦略をあらためて説明。npmの性質上、Zodエコシステムへの導入は難しいが、v3とv4を同時にサポートしつつ段階的マイグレーションを提供できる利点を強調
peer dependenciesが壊れているせいでv4をv3に偽装したという以前の意見には必ずしも同意しない、これは段階的移行のための手段だという指摘。少しずつ
"zod/v4"に置き換えていき、最後に完全なv4へ移行する構造だと説明多くの人が批判しているが、実際にはnpmの本質的な限界というより、大きな変更を含むライブラリを段階的に入れ替えられるようにした実用的な判断だと擁護
長年npmだけを使ってきたので偏見かもしれないが、v3からv4へ一気に移行するのではなく段階的にサポートする、これよりよい方法が何かあるのか気になるという声
Zod 4ベータですでに大きな改善を体験したものの、大規模コードベースではモジュール解決設定が難しく、うまくアップグレードできていない状況に言及。レガシーレイヤーなしでメジャーバージョンとしてだけ出してほしかった気持ちもあるが、「バージョン爆発」を防ぐための作者の説明も共有し、v3サポートを並行すれば衝撃波を和らげられるという自分の考えも添える
サーバーが返す型がエンドポイントごとに違ったり、一部フィールドが匿名ユーザーのように
nullで返ってきたりする複雑なケースで、サーバー応答をどんな型モデルで扱うべきかという質問。normalizeUser/normalizePostのような関数をいくつも作っていると管理がどんどん複雑になるが、実務ではどう解決しているのか経験共有を求めるdiscriminated union の例で解決方法を提示。共通スキーマ部分をオブジェクトとして定義し、状況に応じて拡張する方式を説明。ケースが非常に多ければ結局複雑にはなるが、schema validatorを使えば少なくとも体系的に保てると助言
理想的には、Userの型構造を単一の情報源（たとえば discriminated union 形式）として定めるのが最善。Pythonバックエンドを想定するなら、複数形態のPydanticモデル＋ユニオンと、OpenAPI/GraphQLコード生成によるTypeScriptクライアント型生成の構成を提案
実際の利用例がわかればさらによい答えができるが、union型に識別用プロパティ（例:
"user_type"）を入れると各フィールドへのアクセスが簡単になると説明。型システムが状況ごとに適切な属性を認識できるサーバーが直接型を公開すべきだという助言。クライアント側で別の型をいちいち書き直すのは非効率で、PythonバックエンドならPydanticでOpenAPI仕様を自動生成し、TypeScriptクライアントへ型を生成する方法を説明
GraphQLはこうしたケースに適するよう設計されていると言及。TypeScriptのGraphQLライブラリならクエリ結果の形を自動推論でき、選択したフィールドに応じて応答型を柔軟に生成できると説明
Zod 4は改善されたとはいえ、ArkTypeのほうが依然として圧倒的に高速だという意見。既存ライブラリでは後方互換性や文法維持のために性能限界があり、自分のプロジェクト分析では性能とTypeScriptでの使い勝手を理由にArkTypeを選んだという
ArkTypeの速度指標は見たが、その速度が実際の利用で何に効くのか気になるという反応。フォーム検証のような一般的な場面では影響が小さそうに見えるので、超高速APIの入力検証のような性能重視の用途で使っているのかと質問
ArkTypeは調査対象に含まれていなかったが、TypeScriptでの使い勝手を考えて探していたとのこと。それでもZodから移る予定はないと述べる
ArkTypeの使用体験はかなり難しく、Zodのほうが使いやすいので好みだという意見
TypeBoxではなくArkTypeを選んだ特別な理由を尋ねる声
Zodチームの新リリースを祝福しつつ、移行ガイドに並ぶ破壊的変更の多さを見ると、大規模にZodへ依存するプロジェクトでは負担が大きく管理も難しそうだという懸念。古いフロントエンドプロジェクトを維持してきた経験から、各ライブラリで大きな変化と文書不足が多い現在のJS進化の流れに物足りなさも感じるという声
複数の大規模Next.jsアプリを運用しているが、この1年で Next.js 14→15、Next.js pages→app router、React 18→19、Eslint 8→9、Tailwind 3→4 など大きくて難しい変更を次々に経験し、本当に大変だったと振り返る。いっそDjangoで作ればよかったと思ったこともあり、特に Tailwind 3→4 の移行が意外にも最もつらかったと回想
こうした問題を和らげるために、
miniエディションの同時提供戦略を導入したと説明。段階的移行を容易にし、tree shakingの最適性の面でもmini導入は代替ライブラリに対抗するため避けられなかったと述べるLLMのようなツールを使えば、それほど難しくなく移行できるのではという提案
Zodは既存の他の代替よりずっと優れているが、Web開発では同じデータ構造を複数の方法で記述しなければならないのが現実で、JSの入力検証、SwaggerによるAPI仕様、サーバー・クライアントそれぞれの別定義など、あまりに繰り返しが多く煩雑だという不満
TypeScriptが静的検査専用ツールであることへの残念さに触れつつ、ランタイムチェックまで求めるわけではないが、クラス/関数/オブジェクトの型データを外部で簡単に使えるようにしてほしいとの希望。現状では各ツールがそれぞれ独自のモデルやビルダーを定義しなければならず、重複が避けられない。標準化の試みであるStandard Schemaプロジェクトは主要な検証ライブラリと統合されつつあるようだが、API仕様やORM方面への拡張はまだ初期段階だと共有
この種のツールの核心は、一度定義すれば型安全性をアプリ全体に伝播できる点にあり、Zodスキーマを一種の single source of truth として使えることを強調
この煩雑さを嫌がる人の中には、実際にTypeScript（Zodを含む）ひとつに統合しようという提案には抵抗を示す人が多いことも付け加える
すべてのAPIやシステムは常に変化と実験の途上にあり、複雑なレイヤーが増えた現実は欠点ではあるが、「プロジェクトでとにかく動けばよい」という状況では、結局さらに仕事を増やすだけだという見方
全体としては
trpcのようなエンドツーエンドの型安全性も使えるが、そのためにはフロントエンドとバックエンドをともにTypeScriptへ統一する必要があり、Web以外のプラットフォーム（モバイルなど）には適用しづらいという実務上の限界も指摘専門家ではないが、スキーマベースのJSON-SchemaはTypeScript以外の言語でもvalidatorを実装できるのでよい選択かもしれないと考え、
ajv.js.orgのようなライブラリを例にZodとの比較を質問ZodはJSON形式だけでなく、JSオブジェクト全体（Date、クラスインスタンスなどJSONで表せないデータ）にもバリデーションできる。JSON変換過程にも使え、文字列ベースのスキーマを書いて、たとえばISO date stringを
Dateオブジェクトとして検証・変換することもできると説明Zod 4はZodスキーマのJSON-Schema変換をサポートしており（以前は外部ライブラリが必要だった）、Zodの大きな差別化要因は preprocess / refine 機能だと説明。検証前にコールバックを追加でき、MM/DD/YYYY を DD/MM/YYYY に変換してから検証するような柔軟な変換が可能で、これはJSON-Schemaではできないと強調
JSON-Schemaもよい選択で、その場合はTypeBoxが生成に向いているという意見。
avjも使えるし独自の検証システムも使える。独自検証のほうが高速だが同期専用で、avjは非同期検証にも対応するため、より深い検証が必要な場合に有利だと説明複数言語で使うならJSON-Schemaが最も一般的で、OpenAPIで包めばAPIドキュメントも自動生成できるのが利点だという意見
Zodを新規プロジェクトに導入し始めたばかりだが、今回のリリース時期が完璧だったと喜ぶ声。計画どおりならv4へ移行するために多くの変更が必要だったはずだが、タイミングが絶妙だったという
思った以上に否定的な意見が多くて驚いたという反応。v4初期版を試したとき新しいAPIは気に入ったが移行経路が心配で、別パッケージ名で出す案まで考えたものの、実際の作者の方法は非常に見事に問題を解決したと高く評価。依存関係の更新を待たずにすぐv4を採用できるようになったのは大きいという