Json Schema快速入門

JSON 模式是一種基于 JSON 格式定義 JSON 數據結構的規范。它被寫在 IETF 草案下并于 2011 年到期。JSON 模式：

• 描述現有數據格式。
• 干凈的人類和機器可讀的文檔。
• 完整的結構驗證，有利于自動化測試。
• 完整的結構驗證，可用于驗證客戶端提交的數據。

JSON Schema是數據接收方的第一道防線，也是數據發送方節約時間、保證數據正確的好工具。

JSON Schema可以解決下列有關一致性驗證的問題。

1、值的數據類型是否正確:可以具體規定與一個值是數字、字符串等類型;

2、是否包含所需的數據: 可以規定哪些數據是需要的，哪些是不需要的;

3、值的形式是不是我需要的:可以指定范圍、最小值和最大值。

---

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""minimun": 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"] }

關鍵字	描述	示例
minimum	最小值	?
exclusiveMinimum	如果存在“exclusiveMinimum”并且具有布爾值true，如果它嚴格意義上大于"minimum"的值則實例有效。	?
maximum	約束屬性，最大值	?
exclusiveMaximum	如果存在"exclusiveMinimum"并且具有布爾值true,如果它嚴格意義上小于"maximum"的值則實例有效。	?
multipleOf	是某數的倍數，必須大于0的整數	?

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"的值則實例有效。	?

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

進階

了解了上面的各個類型的定義及約定條件，就可以滿足大部分情況了。但為了寫出更好的json schema,我們再學習幾個關鍵字

$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" } }

?

?

?

轉載地址:https://www.jianshu.com/p/8278eb2458c4?winzoom=1

總結

以上是生活随笔為你收集整理的Json Schema快速入门的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。