結構定義轉換
JSON Schema ⇄ Zod 轉換器
這是雙向轉換工具:可由 JSON Schema 產生 Zod 結構描述,也能由 Zod 程式碼寫出 JSON Schema。雙向對應 required 與 .optional()、enum、聯集(oneOf / anyOf)、巢狀物件、["string", "null"] 與 .nullable()、additionalProperties: false 與 .strict(),以及字串 format(email、uri、uuid、date-time)與長度、樣式、數值範圍的限制。同一檔案內的 $ref(含遞迴)會成為具名的定義,allOf 會成為 .and(),也會對應元組、default 與 description。指向外部檔案的 $ref 或 if/then 等無法轉換之處,會視為 any 並以警告顯示。Zod 程式碼只會被讀取,不會被執行。所有處理都在瀏覽器內完成,貼上的結構描述不會被傳送。
由 JSON 範例產生 JSON Schema
貼上範例 JSON,即可產生描述它的 JSON Schema(2020-12):型別、必要的鍵、可為 null 的值與 format。陣列中只有部分元素才有的鍵會成為選填。
指南使用方式與特色
- 選擇「JSON Schema → Zod」並貼上結構定義,就會產生 `z.object({ ... })` 形式的 Zod 結構定義與 `z.infer` 型別別名。
- 選擇「Zod → JSON Schema」則是反向轉換。就算保留 `import` 行或 `export const user =` 也沒關係,剖析器會取出以 `z.` 開頭的運算式。
- 不在 `required` 中的屬性會加上 `.optional()`;反向轉換時,沒有 `.optional()` 的屬性則會被收進 `required`。
- 字串的細節也是雙向對應:`format: "email"` 會變成 `.email()`,`minLength` 會變成 `.min()`。
- `$ref`、`allOf` 這類無法轉換的內容會以警告顯示在結果下方,不會默默產生壞掉的結果。
FAQ常見問題
這和從 JSON 範例產生 Zod 的「JSON to Zod」有什麼不同?
輸入不同。JSON to Zod 是從 API 回應之類的「值範例」推論型別,因此無法得知哪些欄位是必填、字串的 format 是什麼。本工具以 JSON Schema 本身為輸入,所以 required、enum、minLength、format:email 等限制會直接反映到 Zod 的鏈式呼叫(.optional() / .enum() / .min() / .email())。若您手上已經有 OpenAPI 或 JSON Schema 定義,這條路徑更精確。required 與 .optional() 如何對應?
兩者的預設值剛好相反。JSON Schema 是「列在 required 陣列中才是必填」,Zod 則是「沒有 .optional() 就是必填」。轉換器會吸收這個差異:轉成 Zod 時,不在 required 中的屬性會加上 .optional();反向轉換時,沒有 .optional() 的屬性會被收進 required 陣列。使用 $ref 的結構定義也能轉換嗎?
同一檔案內的參照($defs 或 definitions,含遞迴)會展開為具名的定義。指向外部檔案或不存在路徑的參照會變成 z.any() 並顯示警告,因此若共用定義放在其他檔案,請先合併成一個檔案再貼上。產生的 Zod 可以直接用於正式環境的驗證嗎?
可以當作骨架,但原本就不在 JSON Schema 裡的業務規則(允許的信箱網域、欄位之間的一致性等)不會被產生出來。另外 pattern 會轉成 z.string().regex(),若原本的正規表示式不相容於 ECMAScript,行為可能會不同。產生後請務必確認內容。
使用情境主要應用情境
從 OpenAPI 定義產生前端型別與驗證
OpenAPI 的 components.schemas 就是 JSON Schema,直接貼上即可同時取得 Zod 結構定義與 z.infer 型別,避免伺服器契約與前端驗證逐漸脫節。把既有的 Zod 結構定義輸出成 API 契約
如果專案中是先寫 Zod 結構定義,可以用反向轉換產生 JSON Schema,貼進 OpenAPI 的 components 或文件中。把手寫的驗證改為結構定義驅動
要取代大量 if 判斷時,只要有既有的 JSON Schema,就能一次產生完整的 Zod 起點,較不會漏掉必填欄位與 enum。讓 AI 產生的 JSON Schema 真的能用
把 LLM 產出的 JSON Schema 直接貼上,轉換成能在 TypeScript 中運作的 Zod 結構定義,同時獲得靜態型別與執行期驗證。
注意注意事項與限制
同一檔案內的 $ref 會展開,但不支援外部參照與條件分支
同一檔案內的 $ref($defs、definitions、遞迴)會展開為具名的定義,allOf 會成為 .and() 交集。指向外部檔案的 $ref、if/then/else、not 與 patternProperties 不支援,會在轉換結果下方以警告顯示,請手動補上這些部分。Zod → JSON Schema 是以文字方式剖析程式碼
為了讓一切在瀏覽器內完成,工具不會執行程式碼,而是當作文字剖析。支援 z.object / z.array / z.union / z.enum / z.literal / z.record 與常見的鏈式方法,但透過變數參照的結構定義,或 .refine() 這類任意函式無法用 JSON Schema 表達,因此會被忽略。pattern 的正規表示式會原樣搬移
JSON Schema 的 pattern 會轉成 z.string().regex(),反向時其內容會回到 pattern。JSON Schema 也允許不相容於 ECMAScript 的正規表示式,直接搬移可能導致行為改變。請務必檢查產生的結果
本工具用來產生移轉的起點。業務規則與欄位之間的一致性檢查,只要原始結構定義中沒有就不會被產生;用於正式環境驗證前請先確認內容。
