JSON轉Schema

從 JSON 範例整理出結構草稿

JSON 轉 Schema 會讀取你貼上的 JSON 樣例，依照其中看得到的值與巢狀結構產生 JSON Schema。JSON 是資料格式；JSON Schema 則以另一份 JSON 文件描述資料的形狀，例如某欄位是字串、數字、布林值、物件或陣列，讓人整理介面契約、文件或驗證規則時有一份可編輯的起點。

一份樣例只能呈現當下提供的內容。例如物件中出現 name、active，結果可以描述這兩個欄位及其觀察到的型別；但樣例沒有出現的欄位、其他回應情況、值域限制、格式要求與欄位相依關係，不能只靠這一份資料得知。Schema 裡的 properties 用來描述屬性，required 則列出必須出現的屬性名稱；不要把「有列在 properties」直接解讀成「一定必填」。

輸入接受 JSON 值，包括物件、陣列及基本值。生成器以樣例推斷結構，並提供根型別名稱與「所有屬性可選」設定；它不是用既有 Schema 驗證 JSON 的工具，也沒有讓使用者選擇草案版本的欄位。規格細節可參考 IETF RFC 8259 對 JSON 的定義，以及 JSON Schema 官方規格入口與 Core 規範。

準備樣例並檢查輸出

1. 整理有效的 JSON

   貼入與實際資料形狀相近的範例。字串與欄位名稱使用雙引號，並確認括號、冒號和逗號完整；若格式錯誤，輸出不會是可用的 Schema。資料量不必刻意放大，但應包含重要的巢狀物件與陣列案例。

2. 設定根型別名稱與屬性選項

   根型別名稱預設為 Root，可依你的文件或程式慣例調整。「所有屬性可選」會影響生成結果對屬性必要性的處理；切換後，請特別檢視輸出的 required，並依真正的資料契約修正。

3. 觀察自動更新的 Schema

   修改輸入或設定後，結果會自動重新產生。檢查根型別、巢狀 properties、陣列的 items、空值與 required 清單；若資料可能出現多種型別或不同欄位組合，準備其他樣本對照並手動補足。

4. 複製或下載後實際驗證

   確認輸出符合專案採用的 JSON Schema 方言，再複製或下載。接著用專案中的驗證器測試多筆有效及無效資料；若輸出含有 $schema，依該宣告確認相容性。頁面未提供方言選擇，因此不要先假定輸出適用所有驗證器。

必填欄位與版本相容問題

輸出中的 properties 欄位都會是必填嗎？

不能只看 properties 判斷。檢查輸出的 required 清單，並確認「所有屬性可選」設定是否符合預期；最後仍要依資料契約決定欄位是否必須出現。

只貼一筆 JSON，就能知道所有欄位都有哪些嗎？

不行。輸出反映提供的樣例，未出現的可選欄位或另一種回應形狀無法從單筆資料推知。建議比較多種代表性樣本，並由規格負責人補上樣本之外的條件。

這個工具能選 Draft 7 或 2020-12 嗎？

目前介面沒有 JSON Schema 草案版本的選擇項。檢視輸出中的 $schema 宣告；若沒有版本宣告，請依專案要求明確指定或調整，並以實際使用的驗證器測試相容性。

生成後可以直接拿來驗證正式資料嗎？

可作為起稿，但請先補齊業務規則並用多筆正反例測試。樣例通常不會交代額外欄位策略、字串格式、數值上下限、欄位依存或所有允許的資料組合，不能視為完整契約。

樣例不等於完整資料契約

推斷結果只根據你提供的 JSON。未出現在樣例中的欄位、欄位允許缺漏的條件、合法值清單、數字範圍、日期格式及欄位間依賴，都需要從 API 文件、產品規格或實際資料流程確認。陣列也應以不同元素及空陣列等代表情形檢查，避免把單一元素誤當成全部可能。

正式採用前，請核對 required、items、型別分支及 $schema，再以目標驗證器測試；工具不會替你驗證既有 JSON 是否符合某個 Schema，也不會替代完整的介面設計。貼上資料前請移除存取憑證、個人資料與未公開內容，使用可公開的去識別化範例即可。