json schema

一、簡介

　　我們先看下面的json數據

{
    "id": 1,
    "name": "g2",
　　 "desc":"b2"

}

假設, 我們要求id為long型, id、name非空。desc可空。如何衡量json數據是有效的呢？現在流行的json schema 是用來校驗json數據是否合法。

詳情請移至 https://spacetelescope.github.io/understanding-json-schema/

二、keyWords介紹

1、keyWords速記表

關鍵詞	注釋
$schema	聲明當前文檔是標准的 JSON Schema 文檔，當然，這個關鍵詞並不是必需的。
title	題目, 不是必須的
description	描述,不是必須的
type	屬性類型, eg : 字符、數字
properties	json串出現的屬性
patternProperties	正則表達匹配 json串出現的屬性
additionalProperties	①、true ： json串可以出現除schema定義之外屬性 　　false ：json串不可以出現除schema定義之外屬性 ②、 "additionalProperties": { "type": "string" } json串可以出現除schema定義之外"字符"屬性
required	存放必要屬性列表。json串必須出現required要求的屬性
dependencies	依賴出現
size	屬性個數
minimum	給值設置的約束條件，表示可以接受的最小值。
exclusiveMinimum	true ： 不包括最小值
maximum	給值設置的約束條件，表示可以接受的最大值。
exclusiveMaximum	true ： 不包括最大值
multipleOf	如果通過這個關鍵字的值分割實例的結果是一個數字則表示緊靠 "multipleOf" 的數字實例是有效的。

 

 2、具體使用如下

                 type關鍵字                

①、type = object, properties關鍵字是必需的。

②、type =  array, items關鍵字是必需的。

 

              porperties關鍵字           

{
  "type": "object",
  "properties": {
    "number": {
      "type": "number"
    },
    "name": {
      "type": "string"
    }
  }
}

 

              additionalProperties關鍵字             

"additionalProperties": false ：json串只能出現schema定義的屬性。

"additionalProperties": { "type": "string" } ：json串能出現不在schema定義范圍內的屬性, 但屬性的類型必須為string

{
  "type": "object",
  "properties": {
    "number": {
      "type": "number"
    },
    "name": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

 

              required關鍵字               

"required": ["name"]  ： json串必須出現name屬性

{
  "type": "object",
  "properties": {
    "number": {
      "type": "number"
    },
    "name": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": ["name"]
}

 

            dependencies關鍵字             

"dependencies": {
    "number": ["name"] }

number的出現必須依賴在name的基礎上, 換而言之 , number出現,則name必須出現;name的出現與number並沒有毛關系

{
  "type": "object",
  "properties": {
    "number": {
      "type": "number"
    },
    "name": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": ["name"],
  "dependencies": {
    "number": ["name"]
  }
}

 

            patternProperties關鍵字             

"patternProperties": {
    "^S_": { "type": "string" }, "^I_": { "type": "integer" } }
以s、I開頭的屬性必須是String類型

{
  "type": "object",
  "properties": {
    "number": {
      "type": "number"
    },
    "name": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": ["name"],
  "dependencies": {
    "number": ["name"]
  },
   "patternProperties": {
    "^S_": { "type": "string" },
    "^I_": { "type": "integer" }
  }
}

 

          enum關鍵字             

{
  "type": "string",
  "enum": ["red", "amber", "green"]
}

 

           anyOf關鍵字             

anyOf: 對所有屬性范疇生效。所有屬性字符串長度最大不能》5

{
  "anyOf": [
    { "type": "string", "maxLength": 5 },
    { "type": "number", "minimum": 0 }
  ]
}

　　

           allOf關鍵字               

allOf ： type必須相同。不能即String、又number

{
  "allOf": [
    { "type": "string" },
    { "maxLength": 5 }
  ]
}

 

 

            oneOf關鍵字              

{
  "type": "number",
  "oneOf": [
    { "multipleOf": 5 },
    { "multipleOf": 3 }
  ]
}

　　

            not關鍵字                  

{
  "not": {
    "type": "string"
  }
}

　　

            $schema關鍵字               

schema ： 聲明json片段是json schema模式, 並不是 普通json串, 同時也聲明了json schema版本

 

三、拓展

1、復用

{
  "type": "object",
  "properties": {
    "street_address": { "type": "string" },
    "city":           { "type": "string" },
    "state":          { "type": "string" }
  },
  "required": ["street_address", "city", "state"]
}

如果我們想復用上述的json串, 可以使用definitions關鍵字。json結構定義如下 ： 

{
  "definitions": {
    "address": {
      "type": "object",
      "properties": {
        "street_address": { "type": "string" },
        "city":           { "type": "string" },
        "state":          { "type": "string" }
      },
      "required": ["street_address", "city", "state"]
    }
  }
}

如何引用 ？  可以使用$ref關鍵字

{ "$ref": "#/definitions/address" }

或者

{ "$ref": "definitions.json#/address" }

例子如下 ：

schema定義

{
  "$schema": "http://json-schema.org/draft-04/schema#",

  "definitions": {
    "address": {
      "type": "object",
      "properties": {
        "street_address": { "type": "string" },
        "city":           { "type": "string" },
        "state":          { "type": "string" }
      },
      "required": ["street_address", "city", "state"]
    }
  },

  "type": "object",

  "properties": {
    "billing_address": { "$ref": "#/definitions/address" },
    "shipping_address": { "$ref": "#/definitions/address" }
  }
}

目標匹配json數據

{
  "shipping_address": {
    "street_address": "1600 Pennsylvania Avenue NW",
    "city": "Washington",
    "state": "DC"
  },
  "billing_address": {
    "street_address": "1st Street SE",
    "city": "Washington",
    "state": "DC"
  }
}

　　

2、延伸屬性

json schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",

  "definitions": {
    "address": {
      "type": "object",
      "properties": {
        "street_address": { "type": "string" },
        "city":           { "type": "string" },
        "state":          { "type": "string" }
      },
      "required": ["street_address", "city", "state"]
    }
  },

  "type": "object",

  "properties": {
    "billing_address": { "$ref": "#/definitions/address" },
    "shipping_address": {
      "allOf": [
        { "$ref": "#/definitions/address" },
        { "properties":
          { "type": { "enum": [ "residential", "business" ] } },
          "required": ["type"]
        }
      ]
    }
  }
}

可匹配json

{
  "shipping_address": {
    "street_address": "1600 Pennsylvania Avenue NW",
    "city": "Washington",
    "state": "DC",
    "type": "business"
  }
}

 

四、參考文獻

關鍵字 ： https://spacetelescope.github.io/understanding-json-schema/reference/object.html

https://spacetelescope.github.io/understanding-json-schema/

例子 ： http://json-schema.org/example1.html

java jar 實現 ： https://github.com/daveclayton/json-schema-validator

json schema官網 ： http://json-schema.org/

json生成schema工具 ： http://jsonschema.net/#/