JsonSchema用法

簡介

JSON Schema是基於JSON格式，用於定義JSON數據結構以及校驗JSON數據內容。
JSON Schema官網地址：http://json-schema.org/

JsonSchema類似於xml的schema和DTD的作用，主要是用來規范json的格式。

關鍵字及其描述

關鍵字	描述
$schema	表示該JSON Schema文件遵循的規范
title	為該JSON Schema文件提供一個標題
description	關於該JSON Schema文件的描述信息
type	表示待校驗元素的類型（例如，最外層的type表示待校驗的是一個JSON對象，內層type分別表示待校驗的元素類型為，整數，字符串，數字）
properties	定義待校驗的JSON對象中，各個key-value對中value的限制條件
requiredv	定義待校驗的JSON對象中，必須存在的key
minimum	用於約束取值范圍，表示取值范圍應該大於或等於minimum
exclusiveMinimum	如果minimum和exclusiveMinimum同時存在，且exclusiveMinimum的值為true，則表示取值范圍只能大於minimum
maximum	用於約束取值范圍，表示取值范圍應該小於或等於maximum
exclusiveMaximum	如果maximum和exclusiveMaximum同時存在，且exclusiveMaximum的值為true，則表示取值范圍只能小於maximum
multipleOf	用於約束取值，表示取值必須能夠被multipleOf所指定的值整除
maxLength	字符串類型數據的最大長度
minLength	字符串類型數據的最小長度
pattern	使用正則表達式約束字符串類型數據

JSON Schema關鍵字詳解

JsonSchema代碼：

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "TestInfo",
    "description": "some information about test",
    "type": "object",
    "properties": {
        "name": {
            "description": "Name of the test",
            "type": "string"
        },
        "age": {
            "description": "age of test",
            "type": "integer"
        }
    },
    "required": [
        "name"
    ]
}

詳細解釋：

• $schema:用於指定JSONSchema的版本信息，該值由官方提供，不可亂寫。該關鍵字可以省略。
• title：當前schema的標題信息。可以省略
• description：當前節點的描述
• type：當前節點的類型，最外層type代表json的最外層是什么樣的類型。例如上方的例子中，符合該JsonSchema的json數據必需是一個JsonObject而不能是一個JsonArray
• properties：代表當前節點的子節點信息。例如上方的例子中，符合該JsonSchema的json數據的信息可以存在“name”節點和“age”節點。按照上面的配置required信息來看，name是必需要有的，而age是非必需的。
• required： 是一個數組類型，代表當前節點下必需的節點key。例如上方例子中，規定了json的格式必需要有name節點。

符合上述JsonSchema的json數據如下：

第一種（不含有age節點，只含有name一個節點或者name及其若干個節點）：

{
  "name": "upuptop"
}

第二種（含有age節點，age節點的值必需為integer類型）：

{
  "name": "upuptop",
  "age": 123,
  "create_time": "2019-12-12"
}

type的常用取值

type取值	對應的python數據類型
object	Object
array	List
integer	int
number	float或int
null	None
boolean	Boolean
string	String

關鍵字詳解

最外層type為object時

• properties

該關鍵字的值是一個對象。

用於指定JSON對象中的各種不同key應該滿足的校驗邏輯，如果待校驗JSON對象中所有值都能夠通過該關鍵字值中定義的對應key的校驗邏輯，
每個key對應的值，都是一個JSON Schema，則待校驗JSON對象通過校驗。
從這里，我們可以看到，只要待校驗JSON對象的所有key分別都通過對應的JSON Schema的校驗檢測，這個對象才算是通過校驗。

"properties": {
    "name": {
      "description": "姓名必須由2-3個字組成",
      "type": "string",
      "maxLength": 3,
      "minLength": 2
    },
    "age": {
      "description": "年齡必須大於18歲。並且不能超過60歲",
      "type": "integer",
      "minimum": 18,
      "maximum": 60
    }
  }

解釋：每個key對應的值，都是一個JSON Schema:例如上方例子中，每一個key(name/age)對應的值都是一個JSONSchema，JSONSchema中的關鍵字及描述都可以使用。

• required

該關鍵字的值是一個數組，而數組中的元素必須是字符串，而且必須是唯一的。

該關鍵字限制了JSON對象中必須包含哪些一級key。
如果一個JSON對象中含有required關鍵字所指定的所有一級key，則該JSON對象能夠通過校驗。

"required": ["id","name","price"]

• minProperties、maxProperties

這兩個關鍵字的值都是非負整數。規定最多節點個數與最少節點個數。

指定了待校驗JSON對象中一級key的個數限制，minProperties指定了待校驗JSON對象可以接受的最少一級key的個數，而maxProperties指定了待校驗JSON對象可以接受的最多一級key的個數。

另外，需要注意的是，省略minProperties關鍵字和該關鍵字的值為0，具有相同效果。而，如果省略maxProperties關鍵字則表示對一級key的最大個數沒有限制。例如，如果限制一個JSON對象的一級key的最大個數為5，最小個數為1，則JSON Schema如下：

"minProperties": 1,
"maxProperties": 5

• patternProperties

該關鍵字的值是一個對象，該JSON對象的每一個一級key都是一個正則表達式，value都是一個JSON Schema。
指定符合正則表達式的key的規則。
只有待校驗JSON對象中的一級key，通過與之匹配的patternProperties中的一級正則表達式，
對應的JSON Schema的校驗，才算通過校驗。例如，如果patternProperties對應的值如下

"patternProperties": {
        "^a": {
            "type": "number"
        },
        "^b": {
            "type": "string"
        }
}

上面的JSON Schema表示，待校驗JSON對象中，所有以a開頭的一級key的value都必須是number，所有以b開頭的一級key的value都必須是string。

• additionalProperties

該關鍵字的值是一個JSON Schema。

如果待校驗JSON對象中存在，既沒有在properties中被定義，又沒有在patternProperties中被定義，那么這些一級key必須通過additionalProperties的校驗。

最外層type為array時

• items:

該關鍵字的值是一個有效的JSON Schema或者一組有效的JSON Schema。

當該關鍵字的值是一個有效的JSON Schema時，只有待校驗JSON數組中的所有元素均通過校驗，整個數組才算通過校驗。例如，如果items關鍵字的具體定義如下：

{
   "type": "array",
   "items": {
     "type": "string",
     "minLength": 5 
   }
}

上面的JSON Schema的意思是，待校驗JSON數組的元素都是string類型，且最小可接受長度是5。那么下面這個JSON數組明顯是符合要求的，具體內容如下：

["myhome", "green"]

那么下面這個JSON數據則是不符合要求，因為第一個元素的長度小於5，具體內容如下：

["home", "green"]

以上對於items的介紹是對於所有元素來規定的。

注意
下面對items的詳解，趨向於每一個元素的規則。

這里需要注意的是，如果items定義的有效的JSON Schema的數量和待校驗JSON數組中元素的數量不一致，那么就要采用“取小原則”。即，如果items定義了3個JSON Schema，但是待校驗JSON數組只有2個元素，這時，只要待校驗JSON數組的前兩個元素能夠分別通過items中的前兩個JSON Schema的校驗，那么，我們認為待校驗JSON數組通過了校驗。而，如果待校驗JSON數組有4個元素，這時，只要待校驗JSON數組的前三個元素能夠通過items中對應的JSON Schema的校驗，我們就認為待校驗JSON數組通過了校驗。

例如，如果items的值如下：

{
    "type": "array",
    "items": [
        {
            "type": "string",
            "minLength": 5
        },
        {
            "type": "number",
            "minimum": 10
        },
        {
            "type": "string"
        }
    ]
}

上面的JSON Schema指出了待校驗JSON數組應該滿足的條件，數組的第一個元素是string類型，且最小可接受長度為5，數組的第二個元素是number類型，最小可接受的值為10，數組的第三個元素是string類型。那么下面這兩個JSON數組明顯是符合要求的，具體內容如下：

["green", 10, "good"]
["helloworld", 11]

下面這兩個JSON數組卻是不符合要求的，具體內容如下：

["green", 9, "good"]
["good", 12]

• additionalItems

該關鍵字的值是一個有效的JSON Schema。主要規定除了items內部規定的元素之外的元素規則。只有在items是一個schema數組的時候才可以使用。

需要注意的是，該關鍵字只有在items關鍵字的值為一組有效的JSON Schema的時候，才可以使用，用於規定超出items中JSON Schema總數量之外的待校驗JSON數組中的剩余的元素應該滿足的校驗邏輯。當然了，只有這些剩余的所有元素都滿足additionalItems的要求時，待校驗JSON數組才算通過校驗。

其實，你可以這么理解，當items的值為一組有效的JOSN Schema的時候，一般可以和additionalItems關鍵字組合使用，items用於規定對應位置上應該滿足的校驗邏輯，而additionalItems用於規定超出items校驗范圍的所有剩余元素應該滿足的條件。如果二者同時存在，那么只有待校驗JSON數組同時通過二者的校驗，才算真正地通過校驗。

另外，需要注意的是，如果items只是一個有效的JSON Schema，那么就不能使用additionalItems，原因也很簡單，因為items為一個有效的JSON Schema的時候，其規定了待校驗JSON數組所有元素應該滿足的校驗邏輯。additionalItems已經沒有用武之地了。

如果一個additionalItems的值如下：

{
    "type": "array",
    "items": [
        {
            "type": "string",
            "minLength": 5
        },
        {
            "type": "number",
            "minimum": 10
        }
    ],
    "additionalItems": {
        "type": "string",
        "minLength": 2
    }
}

上面的JSON Schema的意思是，待校驗JSON數組第一個元素是string類型，且可接受的最短長度為5個字符，第二個元素是number類型，且可接受的最小值為10，剩余的其他元素是string類型，且可接受的最短長度為2。那么，下面三個JSON數組是能夠通過校驗的，具體內容如下：

["green", 10, "good"]
["green", 11]
["green", 10, "good", "ok"]

下面JSON數組是無法通過校驗的，具體內容如下：

["green", 10, "a"]
["green", 10, "ok", 2]

• minItems、maxItems

這兩個關鍵字的值都是非負整數。
指定了待校驗JSON數組中元素的個數限制，minItems指定了待校驗JSON數組可以接受的最少元素個數，而maxItems指定了待校驗JSON數組可以接受的最多元素個數。

另外，需要注意的是，省略minItems關鍵字和該關鍵字的值為0，具有相同效果。而，如果省略maxItems關鍵字則表示對元素的最大個數沒有限制。

例如，如果限制一個JSON數組的元素的最大個數為5，最小個數為1，則JSON Schema如下：

"minItems": 1,
"maxItems": 5

• uniqueItems

該關鍵字的值是一個布爾值，即boolean（true、false）。

當該關鍵字的值為true時，只有待校驗JSON數組中的所有元素都具有唯一性時，才能通過校驗。當該關鍵字的值為false時，任何待校驗JSON數組都能通過校驗。
另外，需要注意的是，省略該關鍵字和該關鍵字的值為false時，具有相同的效果。例如：

"uniqueItems": true

當type的值為integer或者number時

integer和number的區別，integer相當於python中的int類型，而number相當於python中的int或float類型

• multipleOf

該關鍵字的值是一個大於0的number，即可以是大於0的int，也可以是大於0的float。只有待校驗的值能夠被該關鍵字的值整除，才算通過校驗。

如果含有該關鍵字的JSON Schema如下：

{
    "type": "integer",
    "multipleOf": 2
}

那么，2、4、6都是可以通過校驗的，但是，3、5、7都是無法通過校驗的，當然了，2.0、4.0也是無法通過校驗的，但是，並不是因為multipleOf關鍵字，而是因為type關鍵字。

如果含有multipleOf關鍵字的JSON Schema如下：

{
    "type": "number",
    "multipleOf": 2.0
}

那么，2、2.0、4、4.0都是可以通過校驗的，但是，3、3.0、3、3.0都是無法通過校驗的。

• maximum 、exclusiveMaximum

maximum該關鍵字的值是一個number，即可以是int，也可以是float。該關鍵字規定了待校驗元素可以通過校驗的最大值。即傳入的值必須小於maximum。
exclusiveMaximum該關鍵字和maximum一樣，規定了待校驗元素可以通過校驗的最大值，不同的是待校驗元素可以等於exclusiveMaximum指定的值。即比maximum多了一個他自身這個邊界值.

{
    "type": "number",
#  設定 maximum 為12.3 則傳入值必須小於12.3
#    "maximum": 12.3,
#  設定 exclusiveMaximum為12.3 則傳入值是小於等於12.3
    "exclusiveMaximum": 12.3
}

• minimum、exclusiveMinimum

minimum、exclusiveMinimum關鍵字的用法和含義與maximum、exclusiveMaximum相似。唯一的區別在於，一個約束了待校驗元素的最小值，一個約束了待校驗元素的最大值。

當type取值為string時

• maxLength

該關鍵字的值是一個非負整數。該關鍵字規定了待校驗JSON元素可以通過校驗的最大長度，即待校驗JSON元素的最大長度必須小於或者等於該關鍵字的值。

• minLength

該關鍵字的值是一個非負整數。該關鍵字規定了待校驗JSON元素可以通過校驗的最小長度，即待校驗JSON元素的最小長度必須大於或者等於該關鍵字的值。

• pattern

該關鍵字的值是一個正則表達式。只有待校驗JSON元素符合該關鍵字指定的正則表達式，才算通過校驗。

• format

該關鍵字的值可以是以下取值：date、date-time（時間格式）、email（郵件格式）、hostname（網站地址格式）、ipv4、ipv6、uri等等。

{
    "type": "string",
    "format": "email"
}

使用format關鍵字時，在實例化validator時必須給它傳format_checker參數,fromat_checker參數的值即使各種版本的JSON模式規范的驗證器類，如：

Draft7Validator
Draft6Validator
Draft4Validator

當你實例化validator時,如果沒有給它傳format_checker參數, jsonschema是不會自動校驗schema中的format關鍵字的.因此,你需要做以下步驟:
1.額外導入JSON Schema某個版本的模式規范如：from jsonschema import draft7_format_checker
2.實例化validator時傳入：validate(instance=json_data, schema=my_schema, format_checker=draft7_format_checker)

全類型可用

• enum

該關鍵字的值是一個數組，該數組至少要有一個元素，且數組內的每一個元素都是唯一的。
如果待校驗的JSON元素和數組中的某一個元素相同，則通過校驗。否則，無法通過校驗。

注意：該數組中的元素值可以是任何值，包括null。省略該關鍵字則表示無須對待校驗元素進行該項校驗。例如：

{
    "type": "number",
    "enum": [2, 3, null, "hello"]
}

• const

該關鍵字的值可以是任何值，包括null。如果待校驗的JSON元素的值和該關鍵字指定的值相同，則通過校驗。否則，無法通過校驗。

• allOf

該關鍵字的值是一個非空數組，數組里面的每個元素都必須是一個有效的JSON Schema。
只有待校驗JSON元素通過數組中所有的JSON Schema校驗，才算真正通過校驗。

• anyOf

該關鍵字的值是一個非空數組，數組里面的每個元素都必須是一個有效的JSON Schema。
如果待校驗JSON元素能夠通過數組中的任何一個~~~~JSON Schema校驗，就算通過校驗。

• oneOf

該關鍵字的值是一個非空數組，數組里面的每個元素都必須是一個有效的JSON Schema。
如果待校驗JSON元素能且只能通過數組中的某一個JSON Schema校驗，才算真正通過校驗。不能通過任何一個校驗和能通過兩個及以上的校驗，都不算真正通過校驗。

• not

該關鍵字的值是一個JSON Schema。只有待校驗JSON元素不能通過該關鍵字指定的JSON Schema校驗的時候，待校驗元素才算通過校驗。

• default

該關鍵字的值是沒有任何要求的。該關鍵字常常用來指定待校驗JSON元素的默認值，當然，這個默認值最好是符合要求的，即能夠通過相應的JSON Schema的校驗。
另外，需要注意的是，該關鍵字除了提示作用外，並不會產生任何實質性的影響。

type關鍵字

需要特別注意的是，type關鍵字的值可以是一個string，也可以是一個數組。
如果type的值是一個string，則其值只能是以下幾種：null、boolean、object、array、number、string、integer。
如果type的值是一個數組，則數組中的元素都必須是string，且其取值依舊被限定為以上幾種。只要帶校驗JSON元素是其中的一種，則通過校驗。

注意，以上JSON Schema只是為了展示部分關鍵字的用法，可能和實際應用略有不同。

dependencies關鍵字

依賴關系

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  
  "properties": {
  },
  "dependencies": {
    "age": [
      "name"
    ]
  },
 
}

上述schema表示，age依賴於name，如果age出現，name必須出現

$ref關鍵字

使用該關鍵字可以引用一個規范

"warehouseLocation": {
      "description": "Coordinates of the warehouse where the product is located.",
      "$ref": "https://example.com/geographical-location.schema.json"
    }

if-then-else 關鍵字

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "foo": {
      "type": "string"
    },
    "bar": {
      "type": "string"
    }
  },
  "if": {
    "properties": {
      "foo": {
        "enum": [
          "bar",
          "123"
        ]
      }
    },
    "required": [
      "foo"
    ]
  },
  "then": {
    "required": [
      "bar"
    ]
  },
  "else": {
    "required": [
      "cc"
    ]
  }
}

符合上述規則的json（最簡單的兩種方式）：

{
  "foo": "bar22",
  "cc": 123
}


{
  "foo": "bar",
  "bar": "123"
}

概述：

if條件為：key為foo的值是bar或者123 返回true，否則返回false
if返回true執行then：
    then的規則，bar必須存在
if返回false執行else
    else規則，cc必須存在

官方的參考文檔如下：
http://json-schema.org/latest/json-schema-validation.html
https://json-schema.org/implementations.html

本文參考：https://www.cnblogs.com/ChangAn223/articles/11234348.htm