我已經發送了足夠的 API 來了解專案需要 JSON 架構的確切時刻。它從來都不是開始的。三週後,當第二個團隊開始消耗您的端點時,有人發送格式錯誤的請求正文,並且 null 滑入一個每個人都認為總是一根字串的欄位。突然間,您需要一份合約 - 一份文件,其中顯示機器可以強制執行的形式,"這就是有效負載的樣子。"該文件是 JSON 模式,從已經傳回真實資料的端點手動編寫文件是後端工作中最乏味的工作之一。
TL;DR: 將 JSON 樣本貼到其中 JSON 模式產生器,選擇 Draft-07 或 2020-12,它推斷出一個模式 - 類型,
required欄位、合併的數組項目和字串格式,例如date-time和uuid. 它完全在您的瀏覽器中運行,因此攜帶令牌和個人資料的有效負載永遠不會離開頁面。將輸出視為強大的初稿,然後用只有您知道的限制來收緊它。
我為 toolz。dev 建立了這個工具,因為我一直用手做同樣的事情:打開響應體,瞇著眼睛看它,然後將其形狀逐個子句轉錄成模式子句。它是重複的,重複的轉錄是錯誤隱藏的地方。本指南解釋了生成器的工作原理、推理在哪些地方可靠、哪些地方需要您的判斷以及生成的模式如何適合真實的驗證工作流程。
什麼是 JSON 模式?為什麼要從資料產生 JSON 模式?
JSON Schema 是用來描述 JSON 結構的詞彙表,維護為 本身就是一個規範 而不是作為約定。模式本身就是一個 JSON 文檔,它聲明每個欄位的預期類型、需要哪些欄位、嵌套物件和陣列的形狀以及 - 以及 - 等關鍵字 pattern, enum, minimum, 和 format - 實際上允許什麼值。幾乎每種語言的驗證器都會讀取模式並告訴您給定的文件是否符合要求。這是 JSON 世界最接近跨越服務邊界的類型系統的東西。
從樣本產生模式而不是從頭開始編寫的原因在於,大多數模式都是機械的。行走有效負載並記錄並引用;這是一個字串,這是一個整數,該物件具有這些鍵和引用;這正是機器應該做的工作類型。是什麼 不是 機械是語意層:知道這一點 status 可能只是四根弦之一 age 不能消極,那個 email 必須符合真實的地址模式。 Generation 處理機械鷹架,以便您可以將注意力集中在重要的約束上。您從已經符合現實的文件開始並添加規則,而不是從空白文件開始並希望記住每個欄位。
還有信任維度。當您手動輸入模式時,您會對您所擁有的內容進行編碼 相信 端點返回。信念偏離現實 - 新增字段,整數變為可為空,傳回單一物件的端點開始傳回數組。從實際回應產生的模式錨定在您捕獲該服務當天真正發送的內容。當您調試驗證為何在暫存中通過而在生產中失敗時,該錨點非常值得。
生成器如何推導出模式
引擎解析您的 JSON 並遞歸地遍歷該值,為結構的每個部分發出一個模式節點。這些規則故意保守,因為太鬆散的模式是沒有用的,而太嚴格的模式會拒絕有效的資料。
對於標量,它是區分的 integer 從 number - 42 成為 integer, 4.2 成為 number - 因為這種區別對於驗證者和任何閱讀該模式的人來說都是有意義的。布林值和 null 映射到自己的類型。字串變成 type: string,如果格式偵測開啟,引擎會根據一組眾所周知的模式檢查該值並對其進行標記: date-time, date, time, email, uri, uuid, 和 ipv4.
對於對象,它記錄每個鍵,為每個值推斷一個模式,並且 - if required 啟用推理 - 標記該位置的每個物件中都存在所需的鍵。對於表示所有鍵的單一物件;有趣的情況是數組。
對於物件數組,生成器執行比樸素行走更有用的操作。而不是為每個元素或擴展發出單獨的模式 anyOf 它的形狀幾乎相同,它將數組中的所有物件合併為一個 items 描述單一元素的模式。每個元素中都需要一個鍵;僅某些元素中存在的鍵是可選的。這反映了真實 API 集合的行為方式:大多數記錄都攜帶的分頁清單 avatarUrl 但有些則不然。合併後的模式捕獲並引用;這些欄位總是出現,有時這些欄位會出現並引用;在一個可讀的定義中。您可以在內建範例中看到這一點,其中 members 數組有兩個物件 - 一個帶有 active 欄位和沒有 - 以及產生的項目模式標記的欄位和欄位 id 和 role 需要但離開 active 可選的。
對於混合標量數組,引擎將元素類型折疊為單一元素類型 type 數組 - ["integer", "string", "boolean"] - 而不是冗長的結合。當物件和非物件形狀真正混合在一個陣列中時,它會回落到 anyOf,這是 " 的正確 JSON 模式構造。這些替代方案之一。&引用;
如何使用 JSON 模式產生器
步驟 1:貼上代表性樣品
放入 API 回應、固定裝置、設定檔或 Webhook 主體。為了提高準確性,您可以做的最重要的事情就是貼上一個 代表 樣本。如果您有來自真實回應的多筆記錄,請將它們全部包含在數組中 - 生成器將合併它們並正確推斷可選性。單記錄樣本告訴引擎它看到的每個欄位始終存在,這通常是錯誤的。在貼上自己的物件之前,先載入內建樣本,以了解如何處理嵌套物件、物件陣列和格式化字串。
第二步:選擇方言
選擇 Draft-07 以獲得跨驗證庫的最廣泛相容性,或選擇 2020-12 以獲得當前規範。該工具寫入正確的內容 $schema 標識符放在根上,以便您的驗證器應用正確的規則。對於此產生器產生的物件和陣列形狀,兩種方言的結構輸出是相同的;明顯的差異是標識符。如果您不確定工具支援哪些工具,draft-07 是安全預設值 - 它具有任何版本中最廣泛的庫支援。
第三步:設定您的選項
添加一個 title 如果您想要該模式自行記錄。決定是否發射 required - 大多數時候您想要它,但在早期探索期間,您可能更喜歡更寬鬆的模式。除非您看到誤報,否則請繼續開啟格式偵測。並開啟嚴格模式(additionalProperties: false) 當模式保護您完全控制的內容(例如設定檔或請求正文)時,您希望拒絕而不是忽略意想不到的金鑰。
第 4 步:產生、審查和匯出
按生成,然後批判性地讀取輸出。檢查一下 required 與您的意圖相符,整數與數字的結果是正確的,並且任何檢測到的格式都是正確的而不是巧合。當它看起來正確時,複製模式或將其下載為 .json 文件已準備好放入您的驗證器或儲存庫。
一個可行的例子
從假設中考慮這個反應 /projects 終點:
{
"id": "5b2a1f6e-8c3d-4a1b-9f7e-2c1d3e4f5a6b",
"name": "Toolz",
"createdAt": "2026-01-14T09:30:00Z",
"score": 4.8,
"members": [
{ "id": 1, "role": "owner", "active": true },
{ "id": 2, "role": "editor" }
]
}
生成器產生一個模式,其中 id 是一個字串 format: "uuid", createdAt 是一個字串 format: "date-time", score 是一個 number (不是整數,因為是小數),並且 members 是一個數組 items 模式需要 id 和 role 但不是 active. 最後一個細節就是回報:從兩個範例成員中,它正確地推斷出這一點 active 是可選的。在大型有效載荷上手動推理正是產生器消除的那種小心、無聊的工作。
推理結束、判斷開始的地方
我想直接討論限制,因為直接交給生產的生成模式是一個錯誤。推理看到類型和結構;它看不到意圖。
它不可能知道這一點 role 是一個枚舉 owner, editor, 和 viewer - 從樣本中它只知道 role 是一個字串。它不可能知道這一點 score 範圍從0到5,那個 name 具有最大長度,或者看起來像是 UUID 的程式碼實際上是一個不透明的標識符,應該保持普通字串。它推斷 required 從存在開始,將需要標記恰好出現在樣本中的可選字段,直到您更正為止。它根據您提供的數據起作用:如果您的樣本從未包含 a null 對於可為空的字段,模式將不知道該字段可以為空。
正確的心理模型是鷹架。生成器準確地建構框架 - 每個欄位、其類型、嵌套、數組形狀、基於存在的所需清單。然後,您新增語義約束:枚舉、模式、數字界限以及引擎從一個值看不到的任何格式。這比從無到有更快、更不容易出錯,因為繁瑣的結構轉錄已經完成並且正確。
Draft-07 與 2020-12:你應該選擇哪一個?
| 考慮 | 草案-07 | 2020-12 |
|---|---|---|
| 圖書館支援 | 最廣泛;幾乎到處都支援 | 成長;檢查你的驗證器 |
| 狀態 | 部署廣泛,穩定 | 當前規範 |
$schema 價值 |
http://json-schema.org/draft-07/schema# |
https://json-schema.org/draft/2020-12/schema |
| 數組項目關鍵字 | items 對於單項模式 |
items / prefixItems 為元組拆分 |
| 最好的時候 | 最大相容性很重要 | 您想要最新的規格功能 |
對於此工具產生的模式 - 物件、所需清單、單一項目形狀的陣列 - 兩種方言表達相同的結構。實際決策取決於您的驗證庫支援什麼。如果您將模式連接到已建立的堆疊中,請與驗證器文件的版本相符。如果您重新開始並且沒有限制,Draft-07 仍然是其無與倫比的生態系統支援的務實選擇。
常見用例
記錄現有的 API。 當您繼承沒有模式的端點時,從真實回應產生端點可以在幾秒鐘內為您提供準確的起始文件。然後您將其細化為已發布的合約。這自然地與客戶端程式碼的生成類型配對 - 同一樣本可以提供 json 到打字稿 工具,因此您的伺服器合約和客戶端類型來自相同的事實來源。
驗證請求機構。 對於您控制的請求主體,從有效範例產生模式,開啟嚴格模式以拒絕意外金鑰,並新增枚舉並限制您的端點強制執行。現在,格式錯誤的請求會在邊緣失敗,並出現明顯的驗證錯誤,而不是在處理程序深處導致令人困惑的故障。
配置文件驗證。 讀取 JSON 配置的應用程式從模式中受益匪淺。從已知的良好配置中產生一個配置,收緊它,並在啟動時進行驗證,以便配置鍵中的拼字錯誤會大聲失敗,而不是默默地停用功能。
測試和固定裝置。 模式兼作測試資產。在 CI 中驗證您的夾具,以便在產生誤導性綠色測試之前捕獲變形的夾具。
服務之間的合約測試。 當兩個服務就有效負載達成一致時,共享模式就是合約。從真實訊息產生它並對其進行細化,為兩個團隊提供可以獨立驗證的文件。
隱私:為什麼它會在您的瀏覽器中運行
API 樣本是開發人員處理的最敏感的文字之一。它們通常包含存取令牌、會話識別碼、電子郵件地址、內部記錄 ID,偶爾還包含永遠不應該貼上到隨機 Web 表單中的個人資料。這正是 JSON 模式產生器在客戶端完成所有工作的原因。瀏覽器中的 JavaScript 中會發生解析、推理和序列化。伺服器上沒有任何內容上傳、記錄或儲存。您可以透過在產生時開啟網路標籤或與網路斷開連接來驗證這一點 - 該工具仍然有效。我關心這一點,因為我不會使用將我的有效負載運送給其他人的工具'伺服器,我不會要求你這樣做。同樣的原理貫穿整個 toolz。dev,這是我在 中詳細提出的論點 線上工具中的資料隱私 寫下來。
它如何適合更廣泛的 JSON 工具包
模式是更大的 JSON 工作流程中的一個工件。在產生模式之前,它有助於擁有乾淨、有效的輸入 - json 格式化程式 將格式化和驗證有效負載,以便您不會將格式錯誤的文字輸入產生器。在擁有模式後,您通常需要輸入應用程式程式碼,這就是位置 json 到打字稿 進來。如果您的管道在格式之間移動, JSON 到 YAML 轉換器處理許多配置和 CI 系統期望的轉換。我已經寫過這些部分如何在 中連接 JSON 工具終極指南,以及關於組裝更廣泛的套件 web 開發人員工具包 概述。連接工具包的要點是,單一樣本可以流過多種工具 - 模式、類型、格式轉換 - 無需離開瀏覽器。
問號
如何從 JSON 產生 JSON 模式？
將 JSON 貼到編輯器中,選擇 Draft-07 或 2020-12,然後按 Generate。該工具推斷每個欄位的類型,提取所需的鍵,並輸出可以直接複製到驗證器中的模式。沒有上傳任何內容 - 推理完全在您的瀏覽器中運行。
Draft-07 和 2020-12 有什麼區別？
它們是 JSON 模式規範的兩個版本。 Draft-07 在各個庫中具有最廣泛的支持,並且是安全的預設值。 2020-12 是目前版本,並更改了數組和子模式的表達方式等。對於物件和數組形狀,該工具產生的結構是相同的;主要的可見差異是 $schema 標識符。
工具如何決定需要哪些欄位？
當密鑰出現在產生器看到的每個物件中時，它都被標記為必需。 對於一個表示每個鍵的單一物件；對於一組物件，它意味著所有元素中都存在的鍵。 僅出現在某些記錄中的密鑰被排除在外，這反映了 API 如何省略可選欄位。 您可以完全關閉所需的現場檢測。
一組物件會發生什麼事？
這些物件合併為一個 items 描述單一元素的架構,並且該屬性被鍵入為其數組。每個元素中都存在的鍵變得必填;僅某些元素中存在的鍵保持可選。這可以保持模式的可讀性,而不是產生大的模式 anyOf 形狀幾乎相同。
它檢測到哪些字串格式？
它認識到 date-time, date, time, email, uri, uuid, 和 ipv4 字串並添加匹配項 format 關鍵字。檢測是單一樣本的最佳努力,因此請查看結果 - 看起來像是 UUID 的程式碼將被標記為 UUID。如果您喜歡純字串類型,可以停用格式偵測。
我可以從單一樣本產生模式嗎？
是的,但一個樣本只顯示一種可能的形狀。作為樣本中的數字的欄位可能為空或在其他地方為字串,並且需要標記恰好存在的可選欄位。樣本(最好是幾個真實記錄)越具代表性,推斷的類型和所需清單就越準確。
生成的模式是否準備好進行生產驗證？
將其視為一個強有力的起點,而不是一個完成的文件。推理準確地捕獲類型、結構和所需字段,但語義限制 - 枚舉、字串模式、數字最小值和最大值、從一個值看不到的格式 - 仍然需要手動添加。生成消除了乏味的鷹架,因此您可以專注於這些規則。
我的 JSON 上傳到伺服器了嗎？
不。整個推理引擎在瀏覽器中以 JavaScript 形式運行。沒有任何內容被傳輸、記錄或儲存。您可以在生成時查看網路選項卡或與網路斷開連接來確認這一點 - 該工具仍然有效。
