一. 概念和用途

JSON Schema指的是數(shù)據(jù)交換中的一種虛擬的“合同”蓝牲。
JSON驗證器負責(zé)驗證語法錯誤班缎，JSON Schema負責(zé)提供一致性檢驗池摧。

JSON Schema可以解決下列有關(guān)一致性驗證的問題菇民。
1裁着、 值的數(shù)據(jù)類型是否正確：可以具體規(guī)定一個值是數(shù)字荸型、字符串等類型盹靴；
2、 是否包含所需的數(shù)據(jù)：可以規(guī)定哪些數(shù)據(jù)是需要的瑞妇，哪些是不需要的稿静；
3、 值的形式是不是我需要的：可以指定范圍辕狰、最小值和最大值改备。

特性和用途：

1. 用于描述數(shù)據(jù)結(jié)構(gòu)
   在描述 JSON 數(shù)據(jù)時，如果數(shù)據(jù)本身的復(fù)雜度很高蔓倍，高到三維四維悬钳，普通的標簽函數(shù)已經(jīng)無法表示這種層級結(jié)構(gòu)了盐捷，而 JSON Schema 利用 object 和 array 字段類型的反復(fù)嵌套，可以規(guī)避掉這個缺陷默勾。
   當(dāng)然碉渡，除了鍵值等基本信息，規(guī)范層面還提供了豐富的關(guān)鍵詞支持母剥，如果想通過自定義擴展字段滞诺，解決特定場景的業(yè)務(wù)需求，也是非常方便的环疼。

2. 用于構(gòu)建人機可讀的文檔
   計算機領(lǐng)域有個概念叫做自描述习霹。所謂自描述，可以理解為：文檔本身包含了自身與其他文檔交互相關(guān)的描述信息炫隶，不需要其他的配置文件或者額外信息來描述淋叶。
   而 JSON Schema 就是自描述的，它本身就是一份很完善的說明文檔等限，字段的含義說明爸吮、該如何取值、格式的要求等都清晰明了望门。

3. 用于生成模擬數(shù)據(jù)
   通過標簽函數(shù)生成模擬數(shù)據(jù)形娇，只能解決基本的格式要求。比如 string 類型的字段筹误，模擬出來的數(shù)據(jù)桐早，無非是一個隨機字符串。
   但在 JSON Schema 中厨剪，由于字段的描述不僅僅是類型哄酝，更多的約束條件，可以確保模擬數(shù)據(jù)更接近于真實數(shù)據(jù)祷膳。

4. 用于校驗數(shù)據(jù)陶衅，實現(xiàn)自動化測試
   接口數(shù)據(jù)的校驗工作么介，往往依賴于測試代碼邏輯和用例谷徙。如果用 JSON Schema 描述一個數(shù)據(jù)接口趁啸，就不需要再編寫測試代碼了怕轿，所有的邏輯都可以移植到 JSON Schema 中維護。配合 jsv弛针、tv4 等二方校驗工具裳朋，接口測試可以真正自動化匪蝙。

二. 基本用法

2.1 啟動架構(gòu)

聲明jsonschema：
$schema 架構(gòu)關(guān)鍵字敛摘，指出此架構(gòu)是根據(jù)標準的特定草稿編寫的门烂。
例如："$schema": "http://json-schema.org/draft-07/schema#"

$id 架構(gòu)關(guān)鍵字，定義模式的URI，并解析模式中其他URI引用的基URI屯远。
例如： "$id": "http://example.com/product.schema.json"

title 和 description 關(guān)鍵字是描述性的蔓姚，并不對數(shù)據(jù)具有約束作用，只是用來對文檔作補充說明

type驗證關(guān)鍵字定義我們的JSON數(shù)據(jù)的第一個約束慨丐，在這種情況下赂乐，它必須是一個JSON對象。

啟動架構(gòu)舉例：

{
   "$schema":  "[http://json-schema.org/draft-07/schema#](http://json-schema.org/draft-07/schema#)",
   "$id":  "[http://example.com/product.schema.json](http://example.com/product.schema.json)",
   "title":  "Product",
   "description":  "A product in the catalog",
   "type":  "object"
}

2.2 定義屬性

properties用于指定schema的參數(shù)咖气，定義各個鍵和它們的值類型
type關(guān)鍵字
{ "type": "string" }
當(dāng) type 為 object 類型時，properties 關(guān)鍵字是必需的
當(dāng) type 為 array 類型時挖滤，items 關(guān)鍵字是必需的崩溪。

title 關(guān)鍵字
標題，可省略

description關(guān)鍵字
注釋含義斩松，可省略

required關(guān)鍵字是一個字符串?dāng)?shù)組伶唯，驗證必需包含的鍵。

exclusiveMinimum關(guān)鍵字
該關(guān)鍵字的值為排除值惧盹。
例如：
"exclusiveMinimum": 0
代表必須是0以外的值

minimum關(guān)鍵字
“minimum”的值必須是一個數(shù)字乳幸，表示數(shù)字實例的包含下限。
如果實例是數(shù)字钧椰，則僅當(dāng)實例大于或等于“最小”時粹断，此關(guān)鍵字才會生效。

maximum關(guān)鍵字
“maximum”的值必須是一個數(shù)字嫡霞，表示數(shù)字實例的包含上限瓶埋。
如果實例是數(shù)字，則僅當(dāng)實例小于或等于“最大”時诊沪，此關(guān)鍵字才會生效养筒。

minItems關(guān)鍵字
修飾array的條目數(shù)
此關(guān)鍵字的值必須是非負整數(shù)。
如果數(shù)組實例的大小大于或等于此關(guān)鍵字的值端姚，則該實例對“minItems”有效晕粪。
省略此關(guān)鍵字的行為與值0相同。

maxItems關(guān)鍵字
此關(guān)鍵字的值必須是非負整數(shù)渐裸。
如果數(shù)組實例的大小小于或等于此關(guān)鍵字的值巫湘，則該實例對“maxItems”有效。

uniqueItems關(guān)鍵字
指出陣列中所有的項目必須是相對唯一的
id 的取值一定是唯一的橄仆，就像 css 中的 id 一樣在當(dāng)前文檔中是不可重復(fù)的
描述地址信息或位置信息

空對象{}
可以描述和校驗任意形式的json數(shù)據(jù)

2.3 架構(gòu)外的引用

可在schema內(nèi)部引用另外一個schema來合并驗證
目的：重用剩膘，可讀性和可維護性
ref關(guān)鍵字
例如：

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

ref的值為被引用的schema的$id

2.4 架構(gòu)內(nèi)的引用

可在schema內(nèi)部引用另外一個schema來合并驗證
definitions和ref關(guān)鍵字
例如：

{
... 
     "vegetables":  { 
       "type":  "array", 
       "items":  {  "$ref":  "#/definitions/veggie"  } 
     } 
   }, 
   "definitions":  { 
     "veggie":  { 
       "type":  "object", 
       "required":  [  "veggieName",  "veggieLike"  ], 
       "properties":  { 
         "veggieName":  { 
           "type":  "string", 
           "description":  "The name of the vegetable." 
         }, 
         "veggieLike":  { 
           "type":  "boolean", 
           "description":  "Do I like this vegetable?" 
         } 
...

三. 語法詞典

3.1 適用性

以下幾個關(guān)鍵字用于確定將哪些子模式應(yīng)用于數(shù)組項，對象屬性值和對象屬性名稱：

• items
• properties
• additionalItems
• contains
• patternProperties
• additionalProperties
• propertyNames

“contains”關(guān)鍵字僅要求其子模式對至少一個子實例有效盆顾，而其他關(guān)鍵字要求所有子模式對其應(yīng)用的所有子實例都有效怠褐。

3.1.1 關(guān)鍵字獨立

驗證關(guān)鍵字通常獨立運行，而不會影響彼此的結(jié)果您宪。但以下有幾個例外：
“additionalProperties”奈懒，其行為是根據(jù)“properties”和“patternProperties”定義的; 和
“additionalItems”奠涌，其行為是根據(jù)“items”定義的。

3.2 驗證關(guān)鍵字

3.2.1 任何實例類型的驗證關(guān)鍵字

type
該關(guān)鍵字的值必須是字符串或數(shù)組磷杏。如果它是一個數(shù)組溜畅，那么數(shù)組的元素必須是字符串，并且必須是唯一的极祸。
字符串可取值：
“null”慈格，“boolean”，“object”遥金，“array”浴捆，“number”或“string”
或”integer”，它匹配任意的整數(shù)

enum
該關(guān)鍵字的值必須是一個數(shù)組稿械。這個數(shù)組應(yīng)該至少有一個元素选泻。數(shù)組中的元素應(yīng)該是唯一的。
數(shù)組中的元素可以是任何值美莫，包括null页眯。

const
此關(guān)鍵字的值可以是任何類型，包括null厢呵。

3.2.2 數(shù)字實例的驗證關(guān)鍵字（數(shù)字和整數(shù)）

multipleOf
僅當(dāng)被這個關(guān)鍵詞的值除以之后的結(jié)果是一個整數(shù)時窝撵，這個數(shù)字的實例才是有效的。

maximum
“maximum”的值必須是一個數(shù)字述吸，表示數(shù)字實例的包含上限忿族。
如果實例是數(shù)字，則僅當(dāng)實例小于或等于“最大”時蝌矛，此關(guān)鍵字才會生效道批。

exclusiveMaximum
“exclusiveMaximum”的值必須是數(shù)字，表示數(shù)字實例的獨占上限入撒。
如果實例是數(shù)字隆豹，則實例僅在其值嚴格小于（不等于）“exclusiveMaximum”時才有效。

minimum
“minimum”的值必須是一個數(shù)字茅逮，表示數(shù)字實例的包含下限璃赡。
如果實例是數(shù)字，則僅當(dāng)實例大于或等于“最小”時献雅，此關(guān)鍵字才會生效碉考。

exclusiveMinimum
“exclusiveMinimum”的值必須是數(shù)字，表示數(shù)字實例的獨占下限挺身。
如果實例是數(shù)字侯谁，則實例僅在其值嚴格大于（不等于）“exclusiveMinimum”時才有效。

3.2.3 字符串的驗證關(guān)鍵字

maxLength
此關(guān)鍵字的值必須是非負整數(shù)。
如果字符串實例的長度小于或等于此關(guān)鍵字的值墙贱，則該字符串實例對此關(guān)鍵字有效热芹。

minLength
此關(guān)鍵字的值必須是非負整數(shù)。
如果字符串實例的長度大于或等于此關(guān)鍵字的值惨撇，則該字符串實例對此關(guān)鍵字有效伊脓。
省略此關(guān)鍵字的行為與值0相同。

pattern
該關(guān)鍵字的值必須是一個字符串魁衙。根據(jù)ECMA 262正則表達式方言报腔，該字符串應(yīng)該是有效的正則表達式。
如果正則表達式與實例成功匹配剖淀，則認為字符串實例有效榄笙。

3.2.4 Arrays 數(shù)組的驗證關(guān)鍵字

items
“items”的值必須是有效的JSON格式或有效的JSON數(shù)組。
此關(guān)鍵字確定子實例如何驗證數(shù)組祷蝌，而不直接驗證直接實例本身。
如果“items”是一個json對象帆卓，則如果陣列中的所有元素都成功驗證該schema巨朦，則驗證成功。
如果“items”是一個json數(shù)組剑令，則如果實例的每個元素都針對相同位置的schema進行驗證（如果有）糊啡，則驗證成功。
省略此關(guān)鍵字與空schema具有相同的行為吁津。

additionalItems
“additionalItems”的值必須是有效的JSON格式
此關(guān)鍵字確定子實例如何驗證數(shù)組棚蓄，而不直接驗證直接實例本身。
如果“items”是json數(shù)組碍脏，則如果位置大于“items”的位置的每個實例元素都對“additionalItems”進行驗證梭依，則驗證成功。
否則典尾，必須忽略“additionalItems”役拴，因為“items”模式（可能是空模式的默認值）應(yīng)用于所有元素。
省略此關(guān)鍵字與空schema具有相同的行為钾埂。

maxItems
此關(guān)鍵字的值必須是非負整數(shù)河闰。
如果數(shù)組實例的大小小于或等于此關(guān)鍵字的值，則該實例對“maxItems”有效褥紫。

minItems
此關(guān)鍵字的值必須是非負整數(shù)姜性。
如果數(shù)組實例的大小大于或等于此關(guān)鍵字的值，則該實例對“minItems”有效髓考。
省略此關(guān)鍵字的行為與值0相同部念。

uniqueItems
（唯一性校驗）
該關(guān)鍵字的值必須是布爾值。
如果此關(guān)鍵字的布爾值為false，則實例將成功驗證印机。如果它具有布爾值true矢腻，則實例在其所有元素都是唯一的情況下成功驗證。
省略此關(guān)鍵字的行為與false值相同射赛。

contains
此關(guān)鍵字的值必須是有效的JSON格式多柑。
如果至少有一個元素對給定的模式有效，則數(shù)組實例對“contains”有效楣责。

3.2.5 Objects 對象的驗證關(guān)鍵字

maxProperties
此關(guān)鍵字的值必須是非負整數(shù)竣灌。
如果對象實例的屬性數(shù)小于或等于此關(guān)鍵字的值，則對象實例對“maxProperties”有效秆麸。

minProperties
此關(guān)鍵字的值必須是非負整數(shù)初嘹。
如果對象實例的屬性數(shù)大于或等于此關(guān)鍵字的值，則該實例對“minProperties”有效沮趣。
省略此關(guān)鍵字的行為與值0相同屯烦。

required
該關(guān)鍵字的值必須是一個數(shù)組。這個數(shù)組的元素房铭，如果有的話驻龟，必須是字符串，并且必須是唯一的
如果數(shù)組中的每個項都是實例中屬性的名稱缸匪，則對象實例對此關(guān)鍵字有效翁狐。
省略此關(guān)鍵字與空數(shù)組具有相同的行為。

properties
“properties”的值必須是一個對象凌蔬。該對象的每個值必須是有效的JSON格式露懒。
此關(guān)鍵字確定子實例如何驗證對象，而不直接驗證直接實例本身砂心。
如果每一個出現(xiàn)在實例中的名稱懈词，同時也作為一個名稱包含在該關(guān)鍵字的值中，那么這個名稱的子實例辩诞，成功被相應(yīng)的schema驗證钦睡，則驗證為有效。
省略此關(guān)鍵字與空對象具有相同的行為躁倒。

patternProperties
“patternProperties”的值必須是一個對象荞怒。根據(jù)ECMA 262正則表達式方言，該對象的每個屬性名稱應(yīng)該是有效的正則表達式秧秉。該對象的每個屬性值必須是有效的JSON格式褐桌。
此關(guān)鍵字確定子實例如何驗證對象，而不直接驗證直接實例本身象迎。針對此關(guān)鍵字驗證原始實例類型總是成功的荧嵌。
如果對于與此關(guān)鍵字的值中顯示為屬性名稱的任何正則表達式匹配的每個實例名稱呛踊，驗證成功，則該名稱的子實例將成功驗證與匹配正則表達式對應(yīng)的每個模式啦撮。
省略此關(guān)鍵字與空對象具有相同的行為谭网。

additionalProperties
“additionalProperties”的值必須是有效的JSON模式。
此關(guān)鍵字確定子實例如何驗證對象赃春，而不直接驗證直接實例本身愉择。
使用“additionalProperties”進行驗證僅適用于與“properties”中的任何名稱都不匹配的實例名稱的子值，并且不匹配“patternProperties”中的任何正則表達式织中。
對于所有此類屬性锥涕，如果子實例針對“additionalProperties”架構(gòu)進行驗證，則驗證成功狭吼。
省略此關(guān)鍵字與空架構(gòu)具有相同的行為层坠。

dependencies
此關(guān)鍵字指定在實例是對象且包含特定屬性時計算的規(guī)則。
該關(guān)鍵字的值必須是一個對象刁笙。每個屬性指定一個依賴項破花。每個依賴項值必須是一個數(shù)組或一個有效的JSON Schema。
如果依賴項值是子模式疲吸，并且依賴項鍵是實例中的屬性旧乞，則整個實例必須針對依賴項值進行驗證。
如果依賴項值是一個數(shù)組磅氨，那么數(shù)組中的每個元素（如果有的話）必須是一個字符串，并且必須是唯一的嫡纠。如果依賴關(guān)鍵字是實例中的屬性烦租，則依賴關(guān)系值中的每個項必須是實例中存在的屬性。
省略此關(guān)鍵字與空對象具有相同的行為除盏。

propertyNames
“propertyNames”的值必須是有效的JSON格式叉橱。
如果實例是對象，則此關(guān)鍵字將驗證實例中的每個屬性名稱是否針對提供的schema進行驗證者蠕。請注意窃祝，schema正在測試的屬性名稱將始終為字符串。
省略此關(guān)鍵字與空架構(gòu)具有相同的行為踱侣。

3.2.6 使用條件應(yīng)用于子模式的關(guān)鍵字

這些關(guān)鍵字一起工作以基于另一個子模式的結(jié)果實現(xiàn)子模式的條件應(yīng)用粪小。

if
此關(guān)鍵字的值必須是有效的JSON格式。
此關(guān)鍵字的子模式的驗證結(jié)果對整體驗證結(jié)果沒有直接影響抡句。相反探膊，它控制了哪個“then”或“else”關(guān)鍵字被判斷。
成功驗證此關(guān)鍵字的子模式的實例必須對“then”關(guān)鍵字的子模式值（如果存在）有效待榔。
無法針對此關(guān)鍵字的子模式進行驗證的實例也必須對“else”關(guān)鍵字的子模式值（如果存在）有效逞壁。

then
此關(guān)鍵字的值必須是有效的JSON格式流济。
當(dāng)“if”存在且實例成功驗證其子模式時，如果實例也成功驗證此關(guān)鍵字的子模式腌闯，則valiation將成功對該關(guān)鍵字進行驗證绳瘟。
當(dāng)“if”不存在時，或者實例無法針對其子模式進行驗證時姿骏，此關(guān)鍵字無效糖声。

else
此關(guān)鍵字的值必須是有效的JSON格式。
當(dāng)“if”存在且實例無法針對其子模式進行驗證時工腋，如果實例成功驗證此關(guān)鍵字的子模式姨丈，則valiation將成功對該關(guān)鍵字進行驗證。
當(dāng)“if”不存在時擅腰，或者實例成功驗證其子模式時蟋恬，此關(guān)鍵字無效。

3.2.7 使用布爾邏輯應(yīng)用子模式的關(guān)鍵字

allOf
該關(guān)鍵字的值必須是非空數(shù)組趁冈。數(shù)組的每個項必須是有效的JSON模式歼争。
如果實例針對此關(guān)鍵字的值定義的所有模式成功驗證，則實例將針對此關(guān)鍵字成功驗證渗勘。

anyOf
該關(guān)鍵字的值必須是非空數(shù)組沐绒。數(shù)組的每個項必須是有效的JSON模式。
如果實例針對此關(guān)鍵字的值定義的至少一個模式成功驗證旺坠，則實例將針對此關(guān)鍵字成功驗證乔遮。

oneOf
該關(guān)鍵字的值必須是非空數(shù)組。數(shù)組的每個項必須是有效的JSON模式取刃。
如果實例針對此關(guān)鍵字的值定義的一個模式成功驗證蹋肮，則實例將針對此關(guān)鍵字成功驗證。

not
此關(guān)鍵字的值必須是有效的JSON模式璧疗。
如果實例無法針對此關(guān)鍵字定義的模式成功驗證坯辩，則該實例對此關(guān)鍵字有效。

3.3 使用"format"格式進行語義驗證

3.3.1 前言

僅結(jié)構(gòu)驗證可能不足以驗證實例是否滿足應(yīng)用程序的所有要求崩侠。
“format”關(guān)鍵字被定義為允許由權(quán)威資源準確描述的固定值子集的可互操作語義驗證漆魔。
此關(guān)鍵字的值稱為格式屬性。它必須是一個字符串却音。格式屬性通常只能驗證給定的一組實例類型改抡。如果要驗證的實例的類型不在此集合中，則此格式屬性和實例的驗證應(yīng)該成功系瓢。

3.3.2 定義的格式

• 日期和時間
• 電子郵件地址
• 主機名
• IP地址
• 資源標識符
• URI模版
• json指針
• 正則表達式

3.4 字符串編碼 非json數(shù)據(jù)

3.4.1 前言

本節(jié)中定義的屬性表示實例包含以JSON字符串編碼的非JSON數(shù)據(jù)雀摘。它們描述了內(nèi)容的類型及其編碼方式。
這些屬性提供了將JSON數(shù)據(jù)解釋為豐富的多媒體文檔所需的其他信息八拱。

contentEncoding
如果實例值是字符串阵赠，則此屬性定義字符串應(yīng)該被解釋為二進制數(shù)據(jù)涯塔，并使用此屬性命名的編碼進行解碼。
該屬性的值必須是一個字符串清蚀。
如果描述的實例不是字符串匕荸，則應(yīng)該忽略此屬性的值。

contentMediaType
此屬性的值必須是媒體類型
該屬性的值必須是一個字符串枷邪。
如果描述的實例不是字符串榛搔，則應(yīng)該忽略此屬性的值。
如果“contentEncoding”屬性不存在东揣，但實例值是一個字符串践惑，那么該屬性的值應(yīng)該指定一個文本文檔類型，字符集應(yīng)該是JSON字符串值被解碼到的字符集（對于其中默認為Unicode）嘶卧。
例1：

{
 "type": "string",
 "contentEncoding": "base64",
 "contentMediaType": "image/png"
}

此架構(gòu)描述的實例應(yīng)為字符串尔觉，其值應(yīng)可解釋為base64編碼的PNG圖像。

例2:

{
 "type": "string",
 "contentMediaType": "text/html"
}

此架構(gòu)描述的實例應(yīng)該是包含HTML的字符串芥吟，使用JSON字符串被解碼為的任何字符集（默認為Unicode）侦铜。

3.5 用definitions重用schema

“definitions”關(guān)鍵字為模式作者提供了標準化的位置，以便將可重用的JSON模式內(nèi)聯(lián)到更通用的模式中钟鸵。關(guān)鍵字不會直接影響驗證結(jié)果钉稍。
該關(guān)鍵字的值必須是一個對象。該對象的每個成員值必須是有效的JSON模式棺耍。
例如：

{
 "type": "array",
 "items": { "$ref": "#/definitions/positiveInteger" },
 "definitions": {
   "positiveInteger": {
     "type": "integer",
     "exclusiveMinimum": 0
   }
  }
}

這里是描述正整數(shù)數(shù)組的schema贡未，其中正整數(shù)約束是“definitions”中的子schema：

3.6 schema注釋

title
description
這兩個關(guān)鍵字的值必須是一個字符串。

default
此關(guān)鍵字的值沒有任何限制蒙袍。當(dāng)此關(guān)鍵字的多次出現(xiàn)適用于單個子實例時俊卤，實現(xiàn)應(yīng)該刪除重復(fù)項。
此關(guān)鍵字可用于提供與特定架構(gòu)關(guān)聯(lián)的默認JSON值左敌。建議默認值對關(guān)聯(lián)的模式有效。

readOnly
writeOnly
這些關(guān)鍵字的值必須是布爾值俐镐。當(dāng)這些關(guān)鍵字的多次出現(xiàn)適用于單個子實例時矫限，如果任何出現(xiàn)指定了一個真值，則結(jié)果值必須為true佩抹，否則必須為false叼风。

examples
該關(guān)鍵字的值必須是一個數(shù)組。對數(shù)組中的值沒有任何限制棍苹。當(dāng)此關(guān)鍵字的多次出現(xiàn)適用于單個子實例時无宿，實現(xiàn)必須提供所有值的平面數(shù)組，而不是數(shù)組數(shù)組枢里。