JsonSchema（待完善ing...）
阿新 • • 發佈：2020-08-25
JSON 模式是一種基於 JSON 格式定義 JSON 資料結構的規範。
JSON 模式：
- 描述現有資料格式。乾淨的人類和機器可讀的文件。
- 完整的結構驗證，有利於自動化測試。
- 完整的結構驗證，可用於驗證客戶端提交的資料。
Json schema 格式：
Json schema 本身遵循Json規範，本身就是一個Json字串。
{ "$schema": "http://json-schema.org/draft-04/schema#", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "id": { "description": "The unique identifier for a product", "type": "integer" }, "name": { "description": "Name of the product", "type": "string" }, "price": { "type": "number", "minimum": 0, "exclusiveMinimum": true } }, "required": ["id", "name", "price"] }
json schema 最外層包含以下幾個欄位
| $schema | 描述 | 示例 |
|---|---|---|
| $schema | $schema 關鍵字狀態，表示這個模式與 v4 規範草案書寫一致。 | |
| title | 標題，用來描述結構 | |
| description | 描述 | |
| type | 型別 | |
| properties | 定義屬性 | |
| required | 必需屬性 |
上面只是一個簡單的例子，從上面可以看出Json schema 本身是一個JSON字串，由通過key-value的形式進行標示。
type 和 properties 用來定義json 屬性的型別。required 是對Object欄位的必段性進行約束。事實上,json Schema定義了json所支援的型別，每種型別都有0-N種約束方式。下一節我們來，細緻介紹一下。
Json schema 型別
Object
{ "$schema": "http://json-schema.org/draft-04/schema#", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "id": { "description": "The unique identifier for a product", "type": "integer" }, "name": { "description": "Name of the product", "type": "string" }, "price": { "type": "number", "minimum": 0, "exclusiveMinimum": true } }, "required": ["id", "name", "price"] }
object型別有三個關鍵字:type（限定型別）,properties(定義object的各個欄位),required（限定必需欄位）,如下：
| 關鍵字 | 描述 | 示例 |
|---|---|---|
| type | 型別 | . |
| properties | 定義屬性 | |
| required | 必需屬性 | |
| maxProperties | 最大屬性個數 | |
| minProperties | 最小屬性個數 | |
| additionalProperties | true or false or object | 參考 |
properties 定義每個屬性的名字和型別，方式如上例。
array
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Product",
"description": "A product from Acme's catalog",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"uniqueItems": true
}
array有三個單獨的屬性:items,minItems,uniqueItems:
關鍵字 | 描述 | 示例
items | array 每個元素的型別 | .
minItems | 約束屬性，陣列最小的元素個數 |
maxItems | 約束屬性，陣列最大的元素個數 |
uniqueItems | 約束屬性，每個元素都不相同 |
additionalProperties | 約束items的型別，不建議使用 | 示例
Dependencies | 屬性依賴 | 用法
patternProperties | 用法
string
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Product",
"description": "A product from Acme's catalog",
"type": "object",
"properties": {
"ip": {
"mail": "string",
"pattern":"w+([-+.]w+)*@w+([-.]w+)*.w+([-.]w+)*"
},
"host": {
"type": "phoneNumber",
"pattern":"((d{3,4})|d{3,4}-)?d{7,8}(-d{3})*"
},
},
"required": ["ip", "host"]
}
關鍵字 | 描述 | 示例
maxLength | 定義字串的最大長度，>=0 .
minLength | 定義字串的最小長度，>=0
pattern | 用正則表示式約束字串
integer
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Product",
"description": "A product from Acme's catalog",
"type": "object",
"properties": {
"name": {
"description": "Name of the product",
"type": "string"
},
"price": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true
}
},
"required": ["id", "name", "price"]
}
number
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Product",
"description": "A product from Acme's catalog",
"type": "object",
"properties": {
"name": {
"description": "Name of the product",
"type": "string"
},
"price": {
"type": "number",
"minimum": 0,
"exclusiveMinimum": true
}
},
"required": ["id", "name", "price"]
}
number | 關鍵字可以描述任意長度，任意小數點的數字。number型別的約束有以下幾個：
| 關鍵字 | 描述 | 示例 |
|---|---|---|
| minimum | 最小值 | . |
| exclusiveMinimum | 如果存在 "exclusiveMinimum" 並且具有布林值 true，如果它嚴格意義上大於 "minimum" 的值則例項有效。 | |
| maximum | 約束屬性，最大值 | |
| exclusiveMaximum | 如果存在 "exclusiveMinimum" 並且具有布林值 true，如果它嚴格意義上小於 "maximum" 的值則例項有效。 | |
| multipleOf | 是某數的倍數，必須大於0的整數 |
boolean
{
"type": "object",
"properties": {
"number": { "type": "boolean" },
"street_name": { "type": "string" },
"street_type": { "type": "string",
"enum": ["Street", "Avenue", "Boulevard"]
}
}
}
true or false
enum
{
"type": "object",
"properties": {
"number": { "type": "number" },
"street_name": { "type": "string" },
"street_type": {
"type": "string",
"enum": ["Street", "Avenue", "Boulevard"]
}
}
}
也可以這麼做
{
"type": "object",
"properties": {
"number": { "type": "number" },
"street_name": { "type": "string" },
"street_type": ["Street", "Avenue", "Boulevard"]
}
}
null
進階引數
$ref
$ref 用來引用其它schema,
示例如下：
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Product set",
"type": "array",
"items": {
"title": "Product",
"type": "object",
"properties": {
"id": {
"description": "The unique identifier for a product",
"type": "number"
},
"name": {
"type": "string"
},
"price": {
"type": "number",
"minimum": 0,
"exclusiveMinimum": true
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"uniqueItems": true
},
"dimensions": {
"type": "object",
"properties": {
"length": {"type": "number"},
"width": {"type": "number"},
"height": {"type": "number"}
},
"required": ["length", "width", "height"]
},
"warehouseLocation": {
"description": "Coordinates of the warehouse with the product",
"$ref": "http://json-schema.org/geo"
}
},
"required": ["id", "name", "price"]
}
}
definitions
當一個schema寫的很大的時候，可能需要建立內部結構體，再使用$ref進行引用，示列如下：
{
"type": "array",
"items": { "$ref": "#/definitions/positiveInteger" },
"definitions": {
"positiveInteger": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true
}
}
}
allOf
意思是展示全部屬性，建議用requires替代
不建議使用，示例如下
{
"definitions": {
"address": {
"type": "object",
"properties": {
"street_address": { "type": "string" },
"city": { "type": "string" },
"state": { "type": "string" }
},
"required": ["street_address", "city", "state"]
}
},
"allOf": [
{ "$ref": "#/definitions/address" },
{ "properties": {
"type": { "enum": [ "residential", "business" ] }
}
}
]
}
anyOf
意思是展示任意屬性，建議用requires替代和minProperties替代，示例如下：
{
"anyOf": [
{ "type": "string" },
{ "type": "number" }
]
}
oneOf
其中之一
{
"oneOf": [
{ "type": "number", "multipleOf": 5 },
{ "type": "number", "multipleOf": 3 }
]
}
not
非 * 型別
示例
{ "not": { "type": "string" } }