json-schema
json 作为现在流行的文件格式,在 Api, Config 等方面被大范围使用,而通常的问题就是不可验证,借助 json-schema ,不但可以验证 json 文件的正确性,还能在 json 编辑器中提供实时验证,自动完成,属性提示的好东东。那么为什么还不用它呢。
示例架构文件
以下是最常用的架构文件,用这个做为示例你能知道最常用的功能。
{
"id": "http://json-schema.org/draft-04/schema#",
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Core schema meta-schema",
"definitions": {
"schemaArray": {
"type": "array",
"minItems": 1,
"items": { "$ref": "#" }
},
"positiveInteger": {
"type": "integer",
"minimum": 0
},
"positiveIntegerDefault0": {
"allOf": [ { "$ref": "#/definitions/positiveInteger" }, { "default": 0 } ]
},
"simpleTypes": {
"enum": [ "array", "boolean", "integer", "null", "number", "object", "string" ]
},
"stringArray": {
"type": "array",
"items": { "type": "string" },
"minItems": 1,
"uniqueItems": true
}
},
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uri"
},
"$schema": {
"type": "string",
"format": "uri"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"default": {},
"multipleOf": {
"type": "number",
"minimum": 0,
"exclusiveMinimum": true
},
"maximum": {
"type": "number"
},
"exclusiveMaximum": {
"type": "boolean",
"default": false
},
"minimum": {
"type": "number"
},
"exclusiveMinimum": {
"type": "boolean",
"default": false
},
"maxLength": { "$ref": "#/definitions/positiveInteger" },
"minLength": { "$ref": "#/definitions/positiveIntegerDefault0" },
"pattern": {
"type": "string",
"format": "regex"
},
"additionalItems": {
"anyOf": [
{ "type": "boolean" },
{ "$ref": "#" }
],
"default": {}
},
"items": {
"anyOf": [
{ "$ref": "#" },
{ "$ref": "#/definitions/schemaArray" }
],
"default": {}
},
"maxItems": { "$ref": "#/definitions/positiveInteger" },
"minItems": { "$ref": "#/definitions/positiveIntegerDefault0" },
"uniqueItems": {
"type": "boolean",
"default": false
},
"maxProperties": { "$ref": "#/definitions/positiveInteger" },
"minProperties": { "$ref": "#/definitions/positiveIntegerDefault0" },
"required": { "$ref": "#/definitions/stringArray" },
"additionalProperties": {
"anyOf": [
{ "type": "boolean" },
{ "$ref": "#" }
],
"default": {}
},
"definitions": {
"type": "object",
"additionalProperties": { "$ref": "#" },
"default": {}
},
"properties": {
"type": "object",
"additionalProperties": { "$ref": "#" },
"default": {}
},
"patternProperties": {
"type": "object",
"additionalProperties": { "$ref": "#" },
"default": {}
},
"dependencies": {
"type": "object",
"additionalProperties": {
"anyOf": [
{ "$ref": "#" },
{ "$ref": "#/definitions/stringArray" }
]
}
},
"enum": {
"type": "array",
"minItems": 1,
"uniqueItems": true
},
"type": {
"anyOf": [
{ "$ref": "#/definitions/simpleTypes" },
{
"type": "array",
"items": { "$ref": "#/definitions/simpleTypes" },
"minItems": 1,
"uniqueItems": true
}
]
},
"allOf": { "$ref": "#/definitions/schemaArray" },
"anyOf": { "$ref": "#/definitions/schemaArray" },
"oneOf": { "$ref": "#/definitions/schemaArray" },
"not": { "$ref": "#" }
},
"dependencies": {
"exclusiveMaximum": [ "maximum" ],
"exclusiveMinimum": [ "minimum" ]
},
"default": {}
}
快速参考
根对象
必须存在,因为 schema.json 应该是一个合法的 json 文件。架构对象类型。
id
可选属性,字符串类型,使用相对锚点(文档内)或绝对URL的方式定义当前结构定义对象的唯一标识。
在此示例中是一个绝对的URL
$schema
可选属性,字符串类型,表示引用架构,通常是 schema.json 文件根对象的第一个属性。 常用的根架构为 "http://json-schema.org/draft-04/schema#"
。
在此示例中它与 id
相同,因为此文档就是根架构文件
description
可选属性,字符串类型,表示对当前元数据对象的说明,通常 json 编辑器会在工具提示中显示。
definitions
可选属性,一个对象,其中每一个属性表示一个定义,值为架构对象类型。可以在文档的其它部分通过 { "$ref": "#/definitions/{属性名}" }
来引用架构对象类型。
multipleOf
可选属性,一个正整数,当值为数值并可以被此值整除时才有效。
maximum
可选属性,一个数值,表示最大值。
exclusiveMaximum
可选属性,布尔值,默认为 false, 表示值是否不包括 maximum
自身,也就是说验证时使用 value < maximum
还是 value <= maximum
。
minimum
可选属性,一个数值,表示最小值。
exclusiveMinimum
可选属性,布尔值,默认为 false, 表示值是否不包括 minimum
自身,也就是说验证时使用 value > minimum
还是 value >= minimum
。
maxLength
可选属性,整数或零。用于 "type":"string"
时表示值的最大长度。
minLength
可选属性,整数或零。用于 "type":"string"
时表示值的最小长度。
pattern
可选属性,字符串类型的正则表达式,用于 "type":"string"
时的正则格式验证。
items
可选属性,当 type:"array"
时表示对数组成员的架构对象类型。
additionalItems
可选属性,当 type:"array"
时表示附加的数组成员的架构对象类型。 如果为布尔值,表示此对象中是否可以附加其它未声明属性。
maxItems
可选属性,正整数或零,当 type:"array"
时表示数组的最大成员数量。
minItems
可选属性,正整数或零,当 type:"array"
时表示数组的最小成员数量。
uniqueItems
可选属性,布尔值,当 type:"array"
时表示数组的成员是否必须唯一。
maxProperties
可选属性,正整数或零,当 type:"object"
时表示对象中的最大属性数量。
minProperties
可选属性,正整数或零,当 type:"object"
时表示对象中的最小属性数量。
required
可选属性,数组类型,提供必须的属性名数组。
properties
可选属性,一个对象,用于 "type":"object"
时,其中每一个属性都表示此架构对象的一个属性信息(子架构),值为架构对象类型。
patternProperties
可选属性,一个对象,类似 properties
,但属性名为一个正则表达式。
additionalProperties
可选属性,当 type:"object"
时表示附加的属性成员的架构对象类型。 如果为布尔值,表示此对象中是否可以附加其它未声明属性。
dependencies
可选属性,一个对象,其中每一个属性表示一个定义,定义可以表示一种自定义类型的数据。
enum
可选属性,一个数组,元素为任何类型,表示可选的值列表,通常 json 编辑器可以通过此数组提供自动完成。
type
字符串类型或字符串类型元素的数组,对象元数据属性,表示此对象的类型
可用的基本简单类型包括:
- array - 数组
- boolean - 布尔值
- integer - 整数
- null - 空值
- number - 数值
- object - 对象
- string - 字符串
allOf
可选属性,一个数组,至少一个元素,其中每一个元素都表示一个架构对象类型,表示需要满足所有的架构对象类型的验证。
anyOf
可选属性,一个数组,至少一个元素,其中每一个元素都表示一个架构对象类型,表示需要至少满足其中之一的架构对象类型的验证。
oneOf
可选属性,一个数组,至少一个元素,其中每一个元素都表示一个架构对象类型,表示需要满足且只能满足其中之一的架构对象类型的验证。
not
可选属性,架构对象类型,表示不能是特定架构
default
任意类型,表示当前对象的默认值。
$ref
字符串属性,提供一个引用 URI,表示引用一个架构对象类型,可在任何需要架构对象类型的地方使用。