格式校驗利器：JSON Schema 簡介

JSON 是什麼

JSON，全稱 JavaScript Object Notation. 是 JS 的數據結構的子集。相信你們對 JSON 也很是熟悉了。JSON 一共只有六種數據結構，這裏列舉他們在 JS 和 Python 中的叫法以及在 JSON 中的例子：

JS	Python3	JSON
string	string	"ABC"
number	int/float	123 -1.23
boolean	bool	true false
null	None	null
object	dictnu	{"key": "value"}
array	list	["ABC", 123, true]

因爲 JSON 是 JS 語法的子集，因此下文中我都會使用 JS 的稱呼。

得益於 JSON 極致的簡單和 JS 的普遍使用，JSON 很快流行了起來。可是簡單也有簡單的壞處，人們逐漸發現 JSON 缺乏一些必要的功。

JSON Schema 是什麼？

當先後端使用 JSON 通訊的時候，雙方須要驗證 JSON 的數據格式，好比驗證 array 的長度、number 的大小、甚至於相似 object 中有某兩個屬性不能並存等等要求。固然這些規則均可以使用代碼進行驗證，可是這樣寫起來太繁瑣了，因此爲了描述並校驗 JSON 的格式，JSON Schema 誕生了。

這裏有一個很是簡單的 JSON Schema 的例子：

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "properties": {
        "name":  { "type": "string" },
        "email": { "type": "string" },
    	"age": {
            "type": "integer",
            "minimum": 0,
            "exclusiveMinimum": false,
        },
    	"telephone": {
            "type": "string",
            "pattern": "^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$"
        }
    },
	"required": ["name", "email"],
  "additionalProperties": false
}
複製代碼

上面這個 JSON 描述了這樣的一個 JSON：

• 類型是 object
• 有四個屬性：
  • name：
    • 類型爲 string
  • email：
    • 類型爲 string
  • Age：
    • 類型爲整數
    • 這個整數要大於等於 0
  • telephone：
    • 類型爲 string
    • 須要符合這個正則表達式
• 上面這四個屬性中必須出現有的 name 和 email，剩下的兩個是可選的
• 除了這四個屬性外，不容許出現其餘屬性

好比說，這樣的一個 JSON 就符合這些要求：

{
    "name": "Sherlock Holmes",
    "email": "sherlock@gmail.com",
    "age": 164
}
複製代碼

能夠看到，JSON Schema 自己也是一個 JSON。同一個 JSON，同一個世界先後端都能看懂，那麼的話這個 JSON Schema 就既能夠做爲執行代碼，又能夠做爲文檔。這種統一確保了代碼和文檔不會脫節，省去了寫文檔的功夫。畢竟程序員最討厭的就是沒有文檔的代碼和寫文檔了。

Understanding JSON Schema

在這裏，我強烈推薦閱讀 Understanding JSON Schema，以致於我要專門寫一章來介紹它。這是一個很是適合初學者的教程，有着及其清晰的例子。雖然截止寫稿時其版本還停留在 draft-04，不過瑕不掩瑜，依然是我心中最優秀的 JSON Schema 教程。

在這裏列一下 Understanding JSON Schema 的大綱，方便查漏補缺：

• Type-specific keywords
  • string
    • minLength
    • maxLength
    • pattern
  • Numeric types
    • types: integer, number
    • multipleOf
    • range: minimum, exclusiveMinimum, maximum, exclusiveMaximum
  • object
    • properties
    • additionalProperties
    • required
    • size: minProperties, maxProperties
    • dependencies
    • patternProperties
  • array
    • items
    • length: minItems, maxItems
    • uniqueItems
  • boolean
  • null
• Generic keywords
  • Metadata: title, description, default
  • Enumerated values: enum
• Combining schemas
  • allOf
  • anyOf
  • oneOf
  • not
• The $schema keyword
• Regular Expressions

版本

截止到今天，JSON Schema 一共有 7 個版本，最新的是 draft-07。不一樣版本之間並不（徹底）兼容，因此最佳實踐是在寫 JSON Schema 的時候使用 $schema 關鍵字標記當前使用的是哪一個規範。

下面舉個例子，展現了 draft-04 和 draft-06 中「大於」和「大於等於」寫法：

大於：

{
    "$schema": "https://json-schema.org/draft-06/schema#",
    "type": "number",
    "exclusiveMinimum": 0
}
複製代碼

{
    "$schema": "https://json-schema.org/draft-04/schema#",
    "type": "number",
    "minimum": 0,
    "exclusiveMinimum": true
}
複製代碼

大於等於：

{
    "$schema": "https://json-schema.org/draft-06/schema#",
    "type": "number",
    "minimum": 0
}
複製代碼

{
    "$schema": "https://json-schema.org/draft-04/schema#",
    "type": "number",
    "minimum": 0,
    "exclusiveMinimum": false
}
複製代碼

注：在 draft-04 中，exclusiveMinimum 的默認值就是 false，因此能夠不寫。

在 draft-04 中，exclusiveMinimum 的值是 boolean，draft-06 中改爲了 number。在相同含義的狀況下，新版的寫法的確更加簡潔。

關於不一樣版本之間的區別能夠查看官網的 Migrating from older drafts 一節。

總結

JSON Schema 做爲一個驗證 JSON 的通用語法，我認爲它成功完成了本身的任務。雖然有一些諸如可讀性不高，寫法繁瑣的缺點，可是我認爲這些都是必要的妥協。

原文連接：ocavue.com/jsonschema.…