自訂註解將會繼續保留

上次，我寫了關於我們如何必須移除對未知關鍵字的支援。我以一個說明我們仍在尋找一種方法來支援非功能性自訂關鍵字（即簡單註解）的說明來結束那篇文章。

在這篇文章中，我想回顧一下解決方案以及我們如何得出該解決方案，以及一些我們構想並提供的其他解決方案的簡要概述。準備好，因為這將會是一趟溫和的旅程！

解決方案是什麼？

簡而言之 (tl;dr)，未來 JSON Schema 將會把任何以 x- 開頭的關鍵字視為註解。

選擇這個解決方案有幾個原因。

1. 特別關鍵字必然不能有任何與之關聯的功能。也就是說，它們永遠都只是註解；它們的值只是返回給使用者或應用程式，而沒有經過 schema 的任何處理。
2. 讓特別註解遵循慣例，可以很容易地識別它們。
3. 前綴是遵循的好慣例。
4. 保留這個前綴給特別註解表示，現在或未來都不會與詞彙表定義的關鍵字發生衝突（保持我們的相容性承諾）。
5. 開發人員通常熟悉 x- 前綴，因為它已在其他領域（如 HTTP 標頭）中常用來表示打算給理解它的接收者的自訂資料。

我們對於使用 x- 的一個猶豫是它的起源表示實驗行為。然而，在實踐中，這個前綴似乎被相當自由地用於任何自訂資料。由於我們使自訂資料成為我們明確的目的，因此它看起來很合適。

為什麼選擇前綴而不是其他解決方案？

在發布先前的部落格文章並盡可能地在網路上公開後，我們收到了回饋，指出自訂關鍵字被廣泛使用，而若不支援它們，將會比我們預期的更嚴重地破壞使用者的使用。雖然我們已經計畫仍支援註解自訂關鍵字，但我們不知道那會是什麼樣子。因此，我開始與團隊提出了一些鬆散的想法進行 討論。

該討論中有很多內容和許多想法，但我只在這裡列出一些重點。如果您對細節感興趣，請隨時閱讀該討論。

替代方案 #1 - 在新的關鍵字中定義前綴

此選項實際上建立在我們所選擇的選項上，方法是定義一個新的 Core 關鍵字（以 $ 開頭），該關鍵字將包含該 schema 使用的前綴。這是一個令人著迷的概念，它將允許 schema 作者使用他們想要的前綴。

然而，有人指出，為了使 meta-schema 驗證 schema，meta-schema 需要能夠讀取這個新的關鍵字，以取得前綴，這樣才能忽略以它開頭的關鍵字。這需要大量我們目前在 JSON Schema 中沒有的新機制，因此目前不太實際。

我們還注意到，我們無法確定這個關鍵字的範圍。它是否只會是關鍵字所使用的 schema 資源（以 $id 表示）？會是整個文件嗎？如果我們 $ref 到另一個沒有定義前綴的 schema 資源或文件，那該怎麼辦？在推斷意圖和要求太多重複之間存在某種平衡。

替代方案 #2 - 在新的關鍵字中列出要忽略的自訂關鍵字

此選項定義了一個新的 Core 關鍵字，例如 $ignored，該關鍵字將包含一個要忽略的關鍵字名稱陣列。這將允許 schema 作者明確定義他們想要使用的關鍵字。

與替代方案 #1 一樣，這存在 JSON Schema 目前沒有執行所需的 meta-schema 驗證的機制以及相同的範圍問題。schema 作者也可能忽略稍後會新增到規範或某些詞彙表的關鍵字，這表示它不應該被忽略，導致令人驚訝的錯誤驗證，並違反我們的相容性要求。

替代方案 #3 - 定義關鍵字的內嵌詞彙表

此選項允許在 meta-schema 的 $vocabulary 關鍵字內定義和描述詞彙表。這就像替代方案 #2，只是特別關鍵字是由詞彙表定義的，因此強制執行「無未知關鍵字」的正常 JSON Schema 程序不會擷取它們；它們將會是已知的。

我們反對這個選項，因為它需要對詞彙表進行許多進一步的開發，而詞彙表的概念無論如何仍在開發中。此解決方案也會將該開發偏向於解決此問題，這可能不是詞彙表概念的正確方向。

替代方案 #4 - 用於包含所有自訂註解的新關鍵字

此選項會建立一個新的 Core 關鍵字，例如 $extra，該關鍵字只是包含 schema 作者可能想要使用的所有自訂關鍵字。

不理想的是，這會在註解和它們嘗試註解的資料之間建立一個隔離層。但更重要的是，一個關鍵字只能建立單一註解（如同現在的定義），因此像 $extra 這樣的關鍵字會將所有註解歸為單一大型物件，而不是像個別關鍵字那樣更有針對性。

替代方案 #5 - 在選項背後支援未知的關鍵字

最後，此選項僅要求實作提供一個組態選項以允許未知的關鍵字，預設為「不允許」。雖然允許未知的關鍵字會違反我們的相容性承諾，但使用者明確設定此選項實際上是在承認該風險。

這感覺像是 退一步。它只是感覺不符合我們希望為此專案提供的支援精神。

我們如何選擇 x- 作為首選前綴？

在上一篇文章中，我連結到該討論並邀請大家支持他們偏好的想法或提出新的想法。我們看到的互動比過去還要多得多，這真是太棒了！

此外，我們在社群媒體上發布了有關該討論的訊息，我們甚至發現其他人在（例如在 reddit 上）建立的幾個貼文連結回部落格文章或討論（或兩者），並在該平台上進行討論。

一旦我們確定前綴選項看起來像是首選，我們的社群經理 Benjamin Granados 就建立了一份調查，列出該前綴可以是什麼的選項。它包括我們到目前為止在討論中提出的建議、x- 和一些容易輸入的符號，以及「自行選擇」選項。

我們有 53 位受訪者，這看起來可能不多，但比我們過去的受訪者還要多。結果清楚地顯示 x-（17 票）是首選前綴。「at」符號 @ 和星號 * 並列第二，各得 12 票。

太長；還是閱讀

未來，請在您的自訂註解關鍵字加上 x- 前綴。

這個解決方案的另一個優點是您不必等待下一個 JSON Schema 版本發布。您可以從今天開始更新您的 schema。x- 關鍵字與目前已發布的所有 JSON Schema 版本相容；它們仍然只會被收集為註解。當下一個版本發布時，您將已經完成遷移！

封面照片由 Mick Haupt 在 Unsplash 上拍攝