「型定義だけじゃ、まだ不安」なあなたへ

TypeScriptでコードを書き、型定義を完璧に整えた。コンパイルエラーもゼロ。
それなのに、実行時にAPIから予期せぬデータが届いてアプリがクラッシュする……。そんな苦い経験はありませんか?

ZodでJSONバリデーションを簡略化する

TypeScriptの型はコンパイル時にのみ存在し、ブラウザで動くときには消えてしまいます。つまり、「外部から来るデータ」が本当に正しいかどうかは、実行時にチェックするしかないのです。

Zod:型安全を「ランタイム」に持ち込む

そこで登場するのが Zod です。
Zodは、データの「スキーマ(設計図)」を定義し、実行時にその通りであるかを厳格にチェックします。

  • 不適切なデータを入り口で遮断: string を期待していたのに null が来たら、即座にエラーを出して後続の処理を守ります。
  • 型定義も同時に手に入る: スキーマを定義すれば、そこから TypeScript の型も自動的に抽出できます(z.infer<T>)。

スキーマを書く手間を「ゼロ」に

Zodは非常に強力ですが、複雑なJSONに合わせてスキーマを手書きするのは、それなりに骨の折れる作業です。

当サイトの JSON→Zod変換ツール は、そんな「スキーマ定義の面倒くささ」を解消するために作りました。お手元のJSONを貼り付けるだけで、対応する Zod スキーマを一瞬で生成します。なお、手元にJSON SchemaやOpenAPI定義がある場合は JSON Schema ⇄ Zod 変換 のほうが正確です。値のサンプルからは分からない必須指定やformatが、そのまま保持されます。

基本的なワークフロー

  1. APIから返ってくるJSONをコピーする。
  2. ツールに貼り付けて、Zod スキーマ(z.object({...}))を生成。
  3. 生成されたコードをプロジェクトに貼り付けて、Schema.parse(data) でバリデーションを開始!
import { z } from 'zod';

// ツールで生成されたスキーマ
const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
});

// 実行時のチェックと型抽出が同時に行える
type User = z.infer<typeof UserSchema>;
const safeData = UserSchema.parse(rawData);

生成ルール:実際の出力を読む

次のJSONから生成されるスキーマを見ると、ツールの推論ルールがわかります。

{
  "users": [
    { "id": 1, "name": "Ada", "email": "a@example.com", "score": 10 },
    { "id": 2, "name": "Bob", "score": 9.5, "deletedAt": null }
  ],
  "tags": [],
  "meta": { "created-at": "2026-01-01T00:00:00Z", "page": 1, "note": null },
  "mixed": [1, "a"],
  "empty": {}
}

出力は次のとおりです。

import { z } from 'zod';

const schema = z.object({
    users: z.array(z.object({
        id: z.number(),
        name: z.string(),
        email: z.string().optional(),
        score: z.number(),
        deletedAt: z.null().optional(),
    })),
    tags: z.array(z.unknown()),
    meta: z.object({
        "created-at": z.string(),
        page: z.number(),
        note: z.null(),
    }),
    mixed: z.array(z.union([z.number(), z.string()])),
    empty: z.object({}),
});

type Schema = z.infer<typeof schema>;
  • 出力は import・const schema = …・type Schema = z.infer<typeof schema> の3部構成です。名前(schema / Schema)は、生成後に好きな名前へ変えてください
  • 整数も小数も z.number() になります(score のように 10 と 9.5 が混ざっても同じです)。整数だけにしたいときは、手で z.number().int() に直します
  • 配列は、全要素の形を1つにまとめます。一部の要素にしかないキー(email)は .optional() になります。値が null の要素しかないキー(deletedAt)は z.null().optional() になるので、本来の型に手で直します
  • 種類の違う値が混ざる配列は z.union([...]) になります。「何か、または null」の場合は .nullable() を使います
  • 空の配列は z.array(z.unknown())、空のオブジェクトは z.object({}) です。サンプルに要素がないと、型は決められません
  • created-at のように識別子として書けないキーは、引用符付きで出力します
  • 日時の文字列("2026-01-01T00:00:00Z")も z.string() です。z.string().datetime() で厳しく検証したいときは、手で直します

APIレスポンスでの実用例

実務では、一覧APIの一部フィールドだけが null になる、日付が文字列で返る、数値IDが文字列に変わる、といった小さなズレが起きます。

{
  "id": "123",
  "name": "Ada",
  "lastLoginAt": null
}

このJSONから生成したスキーマは、そのまま使うだけでなく、仕様に合わせて調整します。id を数値に変換する設計なら z.coerce.number()、ログイン日時が未設定でもよいなら z.string().datetime().nullable() のように直します。ツールでたたき台を作り、境界条件だけ人間がレビューする流れにすると、手書きミスを減らしながら現実のAPI仕様にも合わせられます。

まとめ

データの境界線を守ることは、システムの堅牢性を守ることです。
「たぶん大丈夫だろう」という推測を、Zodによる「確かな検証」に変えましょう。手書きの手間はツールに任せて、より本質的なロジックの実装に集中してください。

2026年11月に追加された機能

  • 同じ JSON から Valibot のスキーマ と JSON Schema(draft 2020-12) も生成できます。文字列の形式(日時・メール・UUID・URL)とルート名の指定も反映されます。
  • 配列の要素は 1 つにまとめられ、一部のオブジェクトにしか無いキーは省略可能(Valibot では v.optional、JSON Schema では required から外す)になります。

ツールで試す

よくある質問

TypeScriptの型があればZodは不要ですか?

TypeScriptの型はコンパイル時にのみ存在し、実行時には消えます。外部APIやフォーム入力など「外から来るデータ」が型どおりである保証はないため、実行時に検証するZodのようなライブラリが必要です。Zodなら z.infer で型も同時に得られるので、型と検証を二重管理せずに済みます。

Zodで型も生成できるなら、JSON→TypeScript変換は不要ですか?

実行時バリデーションが必要ならZodスキーマから z.infer で型を導出するのが一元管理できて便利です。一方、検証は不要で型だけ欲しい内部データならJSON→TypeScript変換の方がシンプルです。用途で使い分けてください。

生成したスキーマはそのまま使えますか?

たたき台としてはそのまま使えますが、実際のAPI仕様に合わせた調整を推奨します。文字列の数値を変換するなら z.coerce.number()、null許容なら .nullable()、任意項目なら .optional() のように、境界条件だけ人間がレビューすると手書きミスを減らせます。