1 つの POST リクエストで任意の JSON レスポンスを Zod スキーマに変換します

サードパーティ API にアクセスして JSON 応答を取得すると、その応答に対する Zod スキーマが必要になります。 手動プロセス: 応答を見つめ、フィールドを数え、どれが NULL 可能かを判断し、ネストされたオブジェクトを処理し、 タイプアウトする z.object そして z.string() あらゆる物件に。 1 つのタイプミスと、 検証では不正なデータが静かに渡されます。

フラット 5 フィールド オブジェクトの場合、これには数分かかります。 ネストされた料金を含む Stripe 支払いインテントの場合、 メタデータや 30 以上のフィールドを含めると、自分のキャリアの選択に疑問を持ち始めるほど時間がかかります。

ボトイ /v1/schema/json-to-zod エンドポイントはこれを排除します。 任意の JSON を POST して、完全な JSON を取得します ゾッドスキーマが戻ってきました。 リクエストが 1 つあれば、CLI をインストールしたり、npm パッケージを設定したりする必要はありません。

API呼び出し

JSON オブジェクトとオプションのスキーマ名を送信します。

カール

応答：

Node.js

パイソン

エンドポイントは、有効な JSON をすべて受け入れます。 json 分野。 オブジェクト、配列、深くネストされた 構造物。 それはすべて機能します。 の name フィールドはオプションであり、デフォルトは "Root"。

実際の例: Stripe 支払いインテント

こちらはリアルなストライプ payment_intent ネストされた応答 metadata そして charges オブジェクト。 これは、Zod スキーマを手書きする種類のペイロードです。 すぐに痛くなる。

リクエスト本文:

API は次の Zod スキーマを返します。

ネストされたすべてのオブジェクトが独自のものになります z.object。 の charges.data 配列が生成する ある z.array 正しいアイテムの形状を使用してください。 ブール値、数値、文字列は次から検出されます。 価値観。 これをコードベースにコピーし、追加します import { "z" } from "zod"、そしてあなたは持っています Stripe 応答のランタイム検証済みタイプを 30 秒以内に取得します。

TypeScript インターフェイスでも機能します

実行時検証なしで TypeScript 型が必要な場合は、 /v1/schema/json-to-typescript エンドポイントは同じ JSON 入力からインターフェイスを生成します。

応答：

同じ入力形式、同じ name パラメータ。 使用 json-to-zod 必要なとき ランタイム検証 (API ハンドラー、フォーム解析、Webhook ペイロード)。 使用 json-to-typescript コンパイル時の型安全性のみが必要な場合。

プロジェクト用の codegen スクリプトを構築する

真の力は、スキーマ生成を自動化するときに現れます。 このスクリプトはライブ API 応答を取得します。 それぞれを Zod スキーマに変換し、出力を src/schemas/ ディレクトリ。

#!/bin/bash
set -euo pipefail

API_BASE="https://api.botoi.com/v1"
OUTPUT_DIR="./src/schemas"

mkdir -p "\$OUTPUT_DIR"

generate_schema() {
  local name=\$1
  local url=\$2
  local output_file="\$OUTPUT_DIR/\$(echo "\$name" | tr '[:upper:]' '[:lower:]').ts"

  echo "Fetching \$url ..."
  local json_response
  json_response=\$(curl -s "\$url")

  echo "Generating Zod schema for \$name ..."
  local zod_response
  zod_response=\$(curl -s -X POST "\$API_BASE/schema/json-to-zod" \\
    -H "Content-Type: application/json" \\
    -d "{
      \\"json\\": \$json_response,
      \\"name\\": \\"\$name\\"
    }")

  local schema
  schema=\$(echo "\$zod_response" | jq -r '.data.zod')

  cat > "\$output_file" << SCHEMAEOF
import { z } from "zod";

\$schema

export type \$name = z.infer<typeof \${name}Schema>;
SCHEMAEOF

  echo "Wrote \$output_file"
}

# Add your API endpoints here
generate_schema "UserProfile" "https://api.example.com/users/1"
generate_schema "Order" "https://api.example.com/orders/latest"
generate_schema "Product" "https://api.example.com/products/42"

echo "Done. Generated \$(ls "\$OUTPUT_DIR"/*.ts | wc -l) schema files."

実行する:

Fetching https://api.example.com/users/1 ...
Generating Zod schema for UserProfile ...
Wrote ./src/schemas/userprofile.ts
Fetching https://api.example.com/orders/latest ...
Generating Zod schema for Order ...
Wrote ./src/schemas/order.ts
Fetching https://api.example.com/products/42 ...
Generating Zod schema for Product ...
Wrote ./src/schemas/product.ts
Done. Generated 3 schema files.

生成された各ファイルは次のようになります。

このスクリプトを package.json として "codegen:schemas" そしてそれを実行します アップストリーム API が変更されるたびに。 Zod スキーマは実際の応答形状と同期したままになります。 TypeScript 型はスキーマから自動的に派生されます。

これが役立つとき

• 新しいサードパーティ API のオンボーディング。 API を 1 回ヒットし、応答を Zod に変換します スキーマを作成し、フィールド名を推測するのではなく、検証された型を使用して構築を開始します。
• JavaScript から TypeScript への移行。 API レスポンスが流れている場合 型なしコードでは、実際のデータからスキーマを生成して、型カバレッジを高速に取得します。
• スキーマの同期を維持します。 CI で codegen スクリプトをスケジュールに従って実行して検出します アップストリーム API が応答の形状を変更したとき。
• プロトタイピング。 概念実証のために検証済みの型が必要だが、それを望まない場合 来週廃棄する可能性のある API のスキーマを手作りする時間を費やすためです。