UnderstandingJSONSchema

博客动态

 0  232

优雅殿下 2022-02-26 15:55:51

悬赏：0 积分收藏

Understanding JSON Schema

json schema 在线校验器

译自：Understanding JSON Schema

{  "type": "object",  "properties": {    "first_name": { "type": "string" },    "last_name": { "type": "string" },    "birthday": { "type": "string", "format": "date" },    "address": {      "type": "object",      "properties": {        "street_address": { "type": "string" },        "city": { "type": "string" },        "state": { "type": "string" },        "country": { "type" : "string" }      }    }  }}

type字段

type字段可以是一个字符串或一个数组

如果是一个字符串则表示基本数据类型，如：42、42.0
```
{ "type": "number" }
```
如果是一个字符串，则表示数据可以是其中的任一基本类型，如：42、"Life, the universe, and everything"，但不能是结构化的数据类型，如：["Life", "the universe", "and everything"]
```
{ "type": ["number", "string"] }
```

jsonschema的五种基本类型

string
number
integer
object
array
boolean
null

string

{ "type": "string" }

可以表示的字符串如："This is a string"、""、"Déjà vu"(unicode字符)

length

用于限制字符串的长度

{  "type": "string",  "minLength": 2,  "maxLength": 3}

正则表达式

使用pattern字段设置正则表达式，具体参见官方说明

{   "type": "string",   "pattern": "^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$"}

数字类型

integer

{ "type": "integer" }

用于表示整数类型。需要注意的是，小数点的存在与否并不能判断它是一个整数还是浮点数，例如1和1.0都会被认为是整数，但3.1415926则是浮点数。

number

用于表示任意数字类型，即整数或浮点数

{ "type": "number" }

multiples

用于表示特定数字的倍数，如下可以是0、10、20，但23不是10的倍数，所以允许。

{    "type": "number",    "multipleOf" : 10}

range

使用minimum和maximum表示的数字范围(或使用exclusiveMinimum和exclusiveMaximum表示独占范围)

x ≥ minimum
x > exclusiveMinimum
x ≤ maximum
x < exclusiveMaximum

如下可以表示0，10，99，但-1和100、101是错误的：

{  "type": "number",  "minimum": 0,  "exclusiveMaximum": 100}

注意在JSON Schema Draft 4中exclusiveMinimum 和exclusiveMaximum的工作方式并不相同，它们表示一个boolean值，用于判断是否排除minimum 和maximum值

if exclusiveMinimum is false, x ≥ minimum.if exclusiveMinimum is true, x > minimum.

object

objects是JSON中的mapping类型，即将"keys"映射到"values"，"keys"必须是字符串，通常将每一对映射称为"属性"。

{ "type": "object" }

可以表达如下值：

{   "key": "value",   "another_key": "another_value"}

properties

属性是object中使用properties关键字定义的key-value对。properties的值是一个对象，每个key的值作为一个property的名称，且每个值都用来校验该属性。任何与properties的属性名不匹配的属性都将被忽略。

{  "type": "object",  "properties": {    "number": { "type": "number" },    "street_name": { "type": "string" },    "street_type": { "enum": ["Street", "Avenue", "Boulevard"] }  }}

上述表达式可以匹配

{ "number": 1600, "street_name": "Pennsylvania", "street_type": "Avenue" }

{ "number": 1600, "street_name": "Pennsylvania" }

```
{ }
```

{ "number": 1600, "street_name": "Pennsylvania", "street_type": "Avenue", "direction": "NW" }

但不能匹配

{ "number": "1600", "street_name": "Pennsylvania", "street_type": "Avenue" }

Pattern Properties

有时候期望对于某一类属性名称，匹配一个特定的模式，此时可以使用patternProperties：它使用正则表达式来进行模式匹配。如果一个属性的名称匹配到特定的正则表达式，则使用对于的模式来校验该属性的值。

如下表示使用S_开头的属性必须是字符串类型，而使用 I_ 开头的则必须是整数类型，并忽略不匹配正则表达式的属性。

{  "type": "object",  "patternProperties": {    "^S_": { "type": "string" },    "^I_": { "type": "integer" }  }}

上述表达式可以匹配

```
{ "S_25": "This is a string" }
```
```
{ "I_0": 42 }
```
```
{ "keyword": "value" }
```

但不能匹配：

```
{ "S_0": 42 }
```
```
{ "I_42": "This is a string" }
```

Additional Properties

additionalProperties关键字用于控制不在properties关键字或不在patternProperties正则表达式列表中的属性。默认情况下允许这类properties。将additionalProperties设置为false表示不允许额外的属性。

如下表达式不允许{ "number": 1600, "street_name": "Pennsylvania", "street_type": "Avenue", "direction": "NW" }

{  "type": "object",  "properties": {    "number": { "type": "number" },    "street_name": { "type": "string" },    "street_type": { "enum": ["Street", "Avenue", "Boulevard"] }  },  "additionalProperties": false}

还可以使用非boolean对额外的属性增加更加复杂的限制。如下表示进允许类型为字符串的额外属性，此时可以允许{ "number": 1600, "street_name": "Pennsylvania", "street_type": "Avenue", "direction": "NW" }，但不允许{ "number": 1600, "street_name": "Pennsylvania", "street_type": "Avenue", "office_number": 201 }

{  "type": "object",  "properties": {    "number": { "type": "number" },    "street_name": { "type": "string" },    "street_type": { "enum": ["Street", "Avenue", "Boulevard"] }  },  "additionalProperties": { "type": "string" }}

如下将additionalProperties和properties、patternProperties结合起来使用，例如{ "keyword": "value" }不匹配properties和patternProperties，但它匹配了additionalProperties，因此允许该对象。

{  "type": "object",  "properties": {    "builtin": { "type": "number" }  },  "patternProperties": {    "^S_": { "type": "string" },    "^I_": { "type": "integer" }  },  "additionalProperties": { "type": "string" }}

扩展封闭模式

需要注意由于additionalProperties只能识别相同子模式的属性，因此可能会限制使用Schema Composition关键字进行扩展。例如下述表达式本意是要求对象中包含"street_address", "city", "state"和"type"这几个字段：

{  "allOf": [    {      "type": "object",      "properties": {        "street_address": { "type": "string" },        "city": { "type": "string" },        "state": { "type": "string" }      },      "required": ["street_address", "city", "state"],      "additionalProperties": false    }  ],  "properties": {    "type": { "enum": [ "residential", "business" ] }  },  "required": ["type"]}

但对于下述对象，会因为将"type"认为是额外的属性，而无法通过additionalProperties的校验

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

但下述对象又由于缺少"type"而无法通过required的校验

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

由于additionalProperties只能识别相同子模式中的properties，它会将非"street_address", "city"和"state"的属性认为是额外的属性，一种解决方案是将additionalProperties转移到扩展的模式中，并在扩展的模式中重新定义属性

{  "allOf": [    {      "type": "object",      "properties": {        "street_address": { "type": "string" },        "city": { "type": "string" },        "state": { "type": "string" }      },      "required": ["street_address", "city", "state"]    }  ],  "properties": {    "street_address": true,//使用boolean表示必须出现该属性    "city": true,    "state": true,    "type": { "enum": [ "residential", "business" ] }  },  "required": ["type"],  "additionalProperties": false}

在 draft 2019-09可以使用unevaluatedProperties关键字解决这种问题

Unevaluated Properties

unevaluatedProperties 关键字与additionalProperties类似的，但它可以识别子模式的属性。因此上述例子可以写为：

{  "allOf": [    {      "type": "object",      "properties": {        "street_address": { "type": "string" },        "city": { "type": "string" },        "state": { "type": "string" }      },      "required": ["street_address", "city", "state"]    }  ],  "properties": {    "type": { "enum": ["residential", "business"] }  },  "required": ["type"],  "unevaluatedProperties": false}

这样就可以允许：

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

不允许：

{   "street_address": "1600 Pennsylvania Avenue NW",   "city": "Washington",   "state": "DC",   "type": "business",   "something that doesn't belong": "hi!"}

unevaluatedProperties的工作原理是收集所有在处理模式时成功验证的属性，并将其作为允许的属性列表使用。下面例子中仅在"type"为"business"时允许"department"属性。

{  "type": "object",  "properties": {    "street_address": { "type": "string" },    "city": { "type": "string" },    "state": { "type": "string" },    "type": { "enum": ["residential", "business"] }  },  "required": ["street_address", "city", "state", "type"],  "if": {    "type": "object",    "properties": {      "type": { "const": "business" }    },    "required": ["type"]  },  "then": {    "properties": {      "department": { "type": "string" }    }  },  "unevaluatedProperties": false}

上述表达式允许：

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

不允许：

{  "street_address": "1600 Pennsylvania Avenue NW",  "city": "Washington",  "state": "DC",  "type": "residential",  "department": "HR"}

Required Properties

默认情况下，properties关键字中的属性不是必须的，但可以通过required关键字指定需要的属性。

required关键字可以指定0或多个字符串数组，每个字符串都必须唯一。如下表达式要求对象中有"name"和"email"属性。

{  "type": "object",  "properties": {    "name": { "type": "string" },    "email": { "type": "string" },    "address": { "type": "string" },    "telephone": { "type": "string" }  },  "required": ["name", "email"]}

注意上述表达式不允许如下对象，这是因为null的类型不是"string"，而是"null"：

{  "name": "William Shakespeare",  "address": "Henley Street, Stratford-upon-Avon, Warwickshire, England",  "email": null}

属性名称

New in draft 6

属性的名称可以根据模式进行验证，而不考虑它们的值。如下强制所有的名称必须是有效的ASCII 字符

{  "type": "object",  "propertyNames": {    "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"  }}

由于对象的keys必须是字符串，这也意味着propertyNames的模式至少是：

{ "type": "string" }

size

properties的数目可以使用minProperties和maxProperties进行限制，值为整数。

{  "type": "object",  "minProperties": 2,  "maxProperties": 3}

array

表示一组有序的元组，数组中可以包含不同类型的元素。

{ "type": "array" }

允许：

```
[1, 2, 3, 4, 5]
```

[3, "different", { "types" : "of values" }]

JSON使用了两种数组方式：

List validation: 任意长度的数组，每个元素都使用相同的模式
Tuple validation: 固定长度的数组，每个元素都有可能使用不同的模式

item

List validation下使用item关键字来校验数组中的元素

{  "type": "array",  "items": {    "type": "number"  }}

如上表达式允许数组[1, 2, 3, 4, 5]、[]，但不允许[1, 2, "3", 4, 5]

Tuple 校验

假设为了表达一个地址："1600 Pennsylvania Avenue NW"。该地址是一个4元组[number, street_name, street_type, direction]

其中：

number: 地址号码，必须是数字
street_name: 街区名称，必须是字符串
street_type: 街区类型，必须来自一组固定的字符串值
direction: 城市象限，必须来自一组固定的字符串值

为了实现上述目的，需要使用prefixItems关键字，prefixItems表示一个数组，每个元素即一个模式，对应文档数组的相应索引，即第一个元素校验输入数组的第一个元素，第二个元素校验输入数组的第二个元素。

在 Draft 4 - 2019-09中，使用items关键字的另一种形式来进行元组验证。当items是一个多模式数组是，它的行为和prefixItems相同。

实现上述目的的表达式如下：

{  "type": "array",  "prefixItems": [    { "type": "number" },    { "type": "string" },    { "enum": ["Street", "Avenue", "Boulevard"] },    { "enum": ["NW", "NE", "SW", "SE"] }  ]}

允许：

```
[1600, "Pennsylvania", "Avenue", "NW"]
```

[10, "Downing", "Street"] //前三个元素

[1600, "Pennsylvania", "Avenue", "NW", "Washington"]

不允许：

["Palais de l'élysée"] //第一个元素不是数字

[24, "Sussex", "Drive"] //第三个元素不匹配

额外的元素

可以使用items关键字控制是否允许出现prefixItems中定义的元组之外的元素。

如果将items设置为false

{  "type": "array",  "prefixItems": [    { "type": "number" },    { "type": "string" },    { "enum": ["Street", "Avenue", "Boulevard"] },    { "enum": ["NW", "NE", "SW", "SE"] }  ],  "items": false}

将不允许：

[1600, "Pennsylvania", "Avenue", "NW", "Washington"] //包含额外元素

允许：

```
[1600, "Pennsylvania", "Avenue"]
```

可以使用非boolean的模式表示更复杂的限制，表示可以添加那些额外的元素：

{  "type": "array",  "prefixItems": [    { "type": "number" },    { "type": "string" },    { "enum": ["Street", "Avenue", "Boulevard"] },    { "enum": ["NW", "NE", "SW", "SE"] }  ],  "items": { "type": "string" }}

此时允许：

[1600, "Pennsylvania", "Avenue", "NW", "Washington"]

但不允许：

[1600, "Pennsylvania", "Avenue", "NW", 20500] //20500不是字符串

Contains

New in draft 6

contains关键字要求数组中至少出现一个特定模式的元素

如下不允许出现["life", "universe", "everything", "forty-two"]这种不带任何数字的数组：

{   "type": "array",   "contains": {     "type": "number"   }}

minContains / maxContains

New in draft 2019-09

和contains关键字配合使用，限制contains的模式次数。

{  "type": "array",  "contains": {    "type": "number"  },  "minContains": 2,  "maxContains": 3}

不允许：

```
["apple", "orange", 2]
```
```
["apple", "orange", 2, 4, 8, 16]
```

length

使用minItems和maxItems限制数组的长度

{  "type": "array",  "minItems": 2,  "maxItems": 3}

Uniqueness

将uniqueItems设置为true，确保数组中元素的唯一性

{  "type": "array",  "uniqueItems": true}

将不允许：

```
[1, 2, 3, 3, 4]
```

boolean

{ "type": "boolean" }

需要注意true和false要小写

null

{ "type": "null" }

需要注意的是，在JSON中null并不代表某些内容不存在

通用关键字

Annotations

JSON Schema中有一些关键字，这些关键字不用于校验，仅用于描述模式，这类"注释"关键字并不是必须的，但建议在实践中使用，由此可以实现模式的"自文档"。

title和description关键字必须是字符串。

default关键字指定了默认值，该值不会填充验证过程中缺失的值。一些非验证的工具，如文档生成器或格式生成器会使用该值来提示用户如何使用一个值。

New in draft 6：examples关键字提供了一组校验模式的例子，它并不用于校验，仅帮助读者解释模式的影响和目的。examples中不需要default，可以将default看作是另一个examples

New in draft 7：通常会在API上下文中使用boolean类型的readOnly和writeOnly关键字，前者表示不可修改某个值，当使用PUT请求修改值时，会响应400 Bad Request。writeOnly表示可以设置值，但将保持隐藏状态，即可以通过PUT请求设置一个值，但在无法通过GET请求检索到该值。

New in draft 2019-09 ：deprecated关键字用来表示未来将会移除该实例值。

{  "title": "Match anything",  "description": "This is a schema that matches anything.",  "default": "Default value",  "examples": [    "Anything",    4035  ],  "deprecated": true,  "readOnly": true,  "writeOnly": false}

Comments

New in draft 7 $comment

$comment关键字用于给模式添加注释，该值必须是字符串。

Enumerated values

enum关键字用于指定一组固定的值。它必须是一个数组，且最少包含一个元素，每个元素都是唯一的。

{  "enum": ["red", "amber", "green", null, 42]}

Constant values

New in draft 6

const关键字用于指定单个值。如下例，将country限制为"United States of America"，不允许出现其他值：

{  "properties": {    "country": {      "const": "United States of America"    }  }}

Media: 字符串编码的非JSON数据

JSON Schema中有一组关键字用于描述和选择性校验保存在JSON字符串中的非JSON数据。由于很难为所有媒体类型编写校验器，因此JSON 模式校验器不需要基于这些关键字验证JSON字符串的内容。但对于那些需要消费经过校验的JSON的应用来说非常有用。

contentMediaType

contentMediaType关键字用于指定字符串内容的MIME类型，参见 RFC 2046。IANA正式注册了一系列MIME类型，但具体支持的类型将取决于应用程序和操作系统。

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

可以允许"<!DOCTYPE html><html xmlns=\"http://www.w3.org/1999/xhtml\"><head></head></html>"

contentEncoding

contentEncoding关键字指定保存内容的编码类型，参见RFC 2054, part 6.1和RFC 4648。

可接受的值为7bit, 8bit, binary, quoted-printable, base16, base32和 `base64，如果没有指定，则与JSON文档的编码相同。

通常的用法如下：

如果编码的内容和JSON文档相同，则无需指定contentEncoding，按原样将内容包含在字符串中即可。包含基于文本的类型，如text/html 或application/xml
如果内容是二进制，将contentEncoding设置为base64，并使用Base64进行编码，这类包含很多媒体类型，如image/png或音频类型，如audio/mpeg.

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

可以允许"iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmJLR0QA/wD/AP+gvaeTAAAA..."

模式组合

JSON Schema中有一些关键字可以用于将模式组合到一起。注意，这并意味着它们会组合来自多个文件或JSON树的模式(尽管这些功能有助于实现这一点)，更多参见构建复杂模式。组合模式可能很简单，比如允许同时根据多个标准校验一个值。

这些关键字对应于众所周知的布尔代数概念，如AND、OR、XOR和NOT。你可以使用这些关键字来表达标准JSON Schema关键字无法表达的复杂限制。

这些关键字为：

allOf: (AND) 必须通过所有子模式的校验
anyOf: (OR) 必须通过任一个子模式的校验
oneOf: (XOR) 必须只能通过某一个子模式的校验
not: (NOT) 不能通过给定模式的校验

allOf

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

可以允许：

```
"short"
```
```
12
```

不允许：

```
"too long"
```
```
-5
```

oneOf

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

可以允许：

```
10
```
```
9
```

不允许：

```
2
```
```
15 // 同时是3和5的倍数
```

not

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

允许：

```
42
```
```
{ "key": "value" }
```

不允许：

```
"I am a string"
```

模式组合的特点

不合逻辑的模式

如下组合是不符合逻辑的，因为数据不可能既是字符串又是数字：

{  "allOf": [    { "type": "string" },    { "type": "number" }  ]}

分解模式

可以将"因子"放到子模式的公共部分之外，如下两种模式是等价的：

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

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

子模式条件

dependentRequired

dependentRequired关键字要求当对象中出现给定的属性时，要求出现特定的属性。例如，如果你有信用卡号，则必须保证还有一个账单地址，发明之如果没有信用卡号，那么也不需要账单地址了。使用dependentRequired关键字可以表示一个属性对其他属性的依赖关系。dependentRequired关键字的值是一个对象，对象中的每个条目会映射到属性的名称。

如下，当提供了credit_card属性时，也必须出现billing_address属性：

{  "type": "object",  "properties": {    "name": { "type": "string" },    "credit_card": { "type": "number" },    "billing_address": { "type": "string" }  },  "required": ["name"],  "dependentRequired": {    "credit_card": ["billing_address"]  }}

允许：

{  "name": "John Doe",  "credit_card": 5555555555555555,  "billing_address": "555 Debtor's Lane"}

{  "name": "John Doe" //没有提供credit_card，不产生依赖}

{  "name": "John Doe",  "billing_address": "555 Debtor's Lane" //billing_address并没有任何依赖}

不允许：

{  "name": "John Doe",  "credit_card": 5555555555555555}

dependentSchemas

dependentSchemas关键字要求当出现给定的属性时，应用特定的子模式。下面表示当出现credit_card时，要求出现billing_address，且billing_address必须是字符串

{  "type": "object",  "properties": {    "name": { "type": "string" },    "credit_card": { "type": "number" }  },  "required": ["name"],  "dependentSchemas": {    "credit_card": {      "properties": {        "billing_address": { "type": "string" }      },      "required": ["billing_address"]    }  }}

允许：

{  "name": "John Doe",  "credit_card": 5555555555555555,  "billing_address": "555 Debtor's Lane"}

{  "name": "John Doe",  "billing_address": "555 Debtor's Lane" //不存在credit_card}

If-Then-Else

New in draft 7，与编程语言中的if/then/else类似。

if	then	else	whole schema
T	T	n/a	T
T	F	n/a	F
F	n/a	T	T
F	n/a	F	F
n/a	n/a	n/a	T

例如，如果你想编写一个模式来处理United States 和Canada的地址，这两个国家的邮政编码格式不同，我们需要根据不同的国家来进行校验。如果地址在United States，则postal_code字段为zipcode：5位数字，后面跟4位可选的数字后缀。如果地址在Canada，则postal_code字段为6位字母数字串。

{  "type": "object",  "properties": {    "street_address": {      "type": "string"    },    "country": {      "default": "United States of America",      "enum": ["United States of America", "Canada"]    }  },  "if": {    "properties": { "country": { "const": "United States of America" } }  },  "then": {    "properties": { "postal_code": { "pattern": "[0-9]{5}(-[0-9]{4})?" } }  },  "else": {    "properties": { "postal_code": { "pattern": "[A-Z][0-9][A-Z] [0-9][A-Z][0-9]" } }  }}

允许：

{  "street_address": "1600 Pennsylvania Avenue NW",  "country": "United States of America",  "postal_code": "20500"}

{  "street_address": "1600 Pennsylvania Avenue NW",  "postal_code": "20500"}

{  "street_address": "24 Sussex Drive",  "country": "Canada",  "postal_code": "K1M 1M4"}

不允许：

{  "street_address": "24 Sussex Drive",  "country": "Canada",  "postal_code": "10000"}

{  "street_address": "1600 Pennsylvania Avenue NW",  "postal_code": "K1M 1M4"}

上例中并没有要求出现"country"属性，因此如果未定义"country"属性，默认行为会将"postal_code"验证为美国邮政编码。“default”关键字没有效果(只作提示作用)

上述方式只能处理两个国家的情况，如果要处理多个国家，可以将多个if和then成对包含到allOf中。

{  "type": "object",  "properties": {    "street_address": {      "type": "string"    },    "country": {      "default": "United States of America",      "enum": ["United States of America", "Canada", "Netherlands"]    }  },  "allOf": [    {      "if": {        "properties": { "country": { "const": "United States of America" } }      },      "then": {        "properties": { "postal_code": { "pattern": "[0-9]{5}(-[0-9]{4})?" } }      }    },    {      "if": {        "properties": { "country": { "const": "Canada" } },        "required": ["country"]      },      "then": {        "properties": { "postal_code": { "pattern": "[A-Z][0-9][A-Z] [0-9][A-Z][0-9]" } }      }    },    {      "if": {        "properties": { "country": { "const": "Netherlands" } },        "required": ["country"]      },      "then": {        "properties": { "postal_code": { "pattern": "[0-9]{4} [A-Z]{2}" } }      }    }  ]}

允许：

{  "street_address": "1600 Pennsylvania Avenue NW",  "country": "United States of America",  "postal_code": "20500"}

{  "street_address": "1600 Pennsylvania Avenue NW",  "postal_code": "20500"}

{  "street_address": "24 Sussex Drive",  "country": "Canada",  "postal_code": "K1M 1M4"}

{  "street_address": "Adriaan Goekooplaan",  "country": "Netherlands",  "postal_code": "2517 JX"}

不允许：

{  "street_address": "24 Sussex Drive",  "country": "Canada",  "postal_code": "10000"}

{  "street_address": "1600 Pennsylvania Avenue NW",  "postal_code": "K1M 1M4"}

上述"if"模式中的required字段是必须的，如果没有该字段，则会将该模式作为默认模式执行。例如，对于如下语句：

{  "street_address": "1600 Pennsylvania Avenue NW",  "postal_code": "K1M 1M4"}

如果按照上述表达式执行，结果为：

Message:JSON does not match all schemas from 'allOf'. Invalid schema indexes: 0.Schema path: #/allOf	Message:JSON does not match schema from 'then'.	Schema path:#/allOf/0/then/then		Message:String 'K1M 1M4' does not match regex pattern '[0-9]{5}(-[0-9]{4})?'.		Schema path:#/allOf/0/then/properties/postal_code/pattern

如果去掉所有的required字段，则会将所有if模式作为默认模式进行匹配校验，结果如下：

Message:JSON does not match all schemas from 'allOf'. Invalid schema indexes: 0, 2.Schema path:#/allOf	Message:JSON does not match schema from 'then'.	Schema path:#/allOf/2/then/then		Message:String 'K1M 1M4' does not match regex pattern '[0-9]{4} [A-Z]{2}'.		Schema path:#/allOf/2/then/properties/postal_code/pattern	Message:JSON does not match schema from 'then'.	Schema path:#/allOf/0/then/then		Message:String 'K1M 1M4' does not match regex pattern '[0-9]{5}(-[0-9]{4})?'.		Schema path:#/allOf/0/then/properties/postal_code/pattern

implication

可以使用模式组合关键字来表示"if-then"条件，

{  "type": "object",  "properties": {    "restaurantType": { "enum": ["fast-food", "sit-down"] },    "total": { "type": "number" },    "tip": { "type": "number" }  },  "anyOf": [    {      "not": {        "properties": { "restaurantType": { "const": "sit-down" } },        "required": ["restaurantType"]      }    },    { "required": ["tip"] }  ]}

允许：

{  "restaurantType": "sit-down",  "total": 16.99,  "tip": 3.4}

{  "restaurantType": "fast-food",  "total": 6.99}

```
{ "total": 5.25 }
```

不允许：

{  "restaurantType": "sit-down", //不满足anyOf  "total": 16.99}

声明一个Dialect

一个JSON Schema版本称为一个Dialect，Dialect表示用于评估模式的一组关键字和语义。每个发布的JSON Schama都是一个新的Dialect。

$schema

$schema关键字用于声明JSON Schema的dialect。$schema关键字的值也是模式的标识符，可用于根据$schema标识的dialect 验证模式是否有效。描述另一个模式的模式称为"meta-schema"。

$schema位于整个文档的根，它不适用于外部引用的($ref，$dynamicRef)文档。

Draft 4： http://json-schema.org/draft-04/schema#
Draft 6：http://json-schema.org/draft-06/schema#.
Draft 7：http://json-schema.org/draft-07/schema#.
Draft 2019-09：https://json-schema.org/draft/2019-09/schema.

Guidelines

可以使用Meta-data关键字提供帮助信息，因为这类字段并不会影响校验过程。

{  "type": "object",  "requiredProperties": {    "foo": { "type": "string" }  }}

允许：

```
{ "foo": "bar" }
```

{ "foo": 42 } //无法识别requiredProperties字段

构造复杂的模式

本章介绍如何使用工具来重用和构造模式。

Schema Identification

与其他编程语言类似，如果将模式分为多个逻辑单元，那么就可以互相引用。为了引用一个模式，需要一种方式来标识一个模式，称为non-relative URIs。

标识并不是必须的，只有在需要引用时才会用到标识。无标识的模式称为"匿名模式"。

URI术语有时可能不直观。在本文件中，使用了以下定义。
URI [1] 或非相对 URI: 包含一个 scheme (https)的完整URL，可能包含一个URL片段 (#foo)。有时，本文档会使用"非相对URI"来明确说明不允许使用相对URI
relative reference [2]: 不包含 scheme (https)的部分URL，可能包含一个片段(#foo).
URI-reference [3]: 相对引用或非相对URI，可能包含一个URL片段 (#foo)
absolute URI [4] 包含一个 scheme (https)的完整URL，但不包含URL片段 (#foo)

虽然使用URL来标识模式，但但这些标识并不需要网络可达。

基本URI

使用非相对URI可能会很麻烦，因此JSON模式中使用的所有URI都可能是URI引用，它们会根据模式的基本URI进行解析，从而生成非相对URI。本节描述如何确定模式的基本URI。

RFC-3986中定义了基本URI和相对引用解析。

检索URI

用于获取模式的URI称为“检索URI”。

假设使用URI引用了一个模式https://example.com/schemas/address，然后检索到以下模式。

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

此时该模式的基本URI与检索URI相同

$id

可以在模式的根使用$id关键字定义基本URI，$id的值是一个URI引用，没有根据检索URI解析的片段。

假设URIs https://example.com/schema/address 和 https://example.com/schema/billing-address都使用了如下模式：

{  "$id": "/schemas/address",  "type": "object",  "properties": {    "street_address": { "type": "string" },    "city": { "type": "string" },    "state": { "type": "string" }  },  "required": ["street_address", "city", "state"]}

无论使用两个URI中的哪一个来检索此模式，基本URI都是https://example.com/schemas/address，这是$id根据检索URI解析出的结果。

然而，在设置基本URI时使用相对引用可能会有问题。例如，不能将此模式用作匿名模式，由于没有检索URI，且无法对任何内容解析相对引用。出于这种原因，建议在使用$id声明基本URI时，使用完整的URI。

{  "$id": "https://example.com/schemas/address",  "type": "object",  "properties": {    "street_address": { "type": "string" },    "city": { "type": "string" },    "state": { "type": "string" }  },  "required": ["street_address", "city", "state"]}

JSON指针

除了表示一个模式文档，还可以标识子模式。最常见的方式是在指向该子模式的URI片段中使用JSON 指针。

JSON指针描述了一个斜杠分隔的路径，用于遍历文档中对象中的键。/properties/street_address意味着：

找到第一个键properties的值
在该对象中找到键street_address的值

URI https://example.com/schemas/address#/properties/street_address标识了下述模式的含注释的子模式

{  "$id": "https://example.com/schemas/address",  "type": "object",  "properties": {    "street_address":      { "type": "string" }, //标识该子模式    "city": { "type": "string" },    "state": { "type": "string" }  },  "required": ["street_address", "city", "state"]}

$anchor

一种不太常见的识别子模式的方法是使用$anchor关键字在模式中创建一个命名锚点，并在URI片段中使用该名称。锚点必须以字母开头，后跟任意数量的字母、数字-, _, :或.。

URI https://example.com/schemas/address#street_address标识了下述模式的含注释的子模式

{  "$id": "https://example.com/schemas/address",  "type": "object",  "properties": {    "street_address":      {        "$anchor": "street_address",//标识该子模式        "type": "string"            //标识该子模式      },    "city": { "type": "string" },    "state": { "type": "string" }  },  "required": ["street_address", "city", "state"]}

$ref

一个模式可以使用$ref关键字引用另一个模式。 $ref 是一个根据基本URI解析的URI引用。

假设需要定义一个客户记录，每个客户都可能有一个送货地址和账单地址。地址格式是相同的，都有一个街区地址、城市和国家。

$ref中的URL引用根据基本URI (https://example.com/schemas/customer)解析为 https://example.com/schemas/address.

{  "$id": "https://example.com/schemas/customer",  "type": "object",  "properties": {    "first_name": { "type": "string" },    "last_name": { "type": "string" },    "shipping_address": { "$ref": "/schemas/address" },    "billing_address": { "$ref": "/schemas/address" }  },  "required": ["first_name", "last_name", "shipping_address", "billing_address"]}

假设在匿名模式中使用$ref，则无法解析相对引用。如下例中，/properties/shipping_address的 $ref可以正常解析，但 /properties/billing_address 的 $ref则无法正常解析
{  "type": "object",  "properties": {    "first_name": { "type": "string" },    "last_name": { "type": "string" },    "shipping_address": { "$ref": "https://example.com/schemas/address" },    "billing_address": { "$ref": "/schemas/address" }  },  "required": ["first_name", "last_name", "shipping_address", "billing_address"]}

$def

$defs关键字提供了一个标准化的位置来保存子模式，以便在当前模式文档中重用。

扩展前面的客户模式示例，为name 属性使用公共模式。为此定义一个新的模式是没有意义的，它只会在该模式中使用，因此可以选择使用$defs。

{  "$id": "https://example.com/schemas/customer",  "type": "object",  "properties": {    "first_name": { "$ref": "#/$defs/name" },    "last_name": { "$ref": "#/$defs/name" },    "shipping_address": { "$ref": "/schemas/address" },    "billing_address": { "$ref": "/schemas/address" }  },  "required": ["first_name", "last_name", "shipping_address", "billing_address"],  "$defs": {    "name": { "type": "string" }  }}

$ref不仅仅有助于避免重复。它还可以用于编写更易于阅读和维护的模式。可以使用带有描述性名称的$defs来定义模式的复杂部分，并在需要的地方引用。

可以引用外部子模式，但通常将$ref限制为引用外部模式或$defs中定义的内部子模式。

递归

$ref关键字可以为指向的模式创建递归模式。例如，person模式中有一个children数组，而每个数组元素又是一个person实例：

{  "type": "object",  "properties": {    "name": { "type": "string" },    "children": {      "type": "array",      "items": { "$ref": "#" }    }  }}

允许：

{  "name": "Elizabeth",  "children": [    {      "name": "Charles",      "children": [        {          "name": "William",          "children": [            { "name": "George" },            { "name": "Charlotte" }          ]        },        {          "name": "Harry"        }      ]    }  ]}

上面创建了一个指向自身的模式，有效地在校验器中创建了一个“循环”。但需要注意，如下，在$ref引用另一个$ref可能会在解析器中导致无限循环。

{  "$defs": {    "alice": { "$ref": "#/$defs/bob" },    "bob": { "$ref": "#/$defs/alice" }  }}

Bundling

在子模式中使用$id时，它表示一个嵌入的模式，它的标识符是$id的值，该值根据它出现在其中的模式的基本URI进行解析。包含嵌入模式的模式文档称为复合模式文档。复合模式文档中每个带有$id的模式称为模式资源。

本例显示了捆绑到复合模式文档中的客户模式示例和地址模式示例：

{  "$id": "https://example.com/schemas/customer",  "$schema": "https://json-schema.org/draft/2020-12/schema",  "type": "object",  "properties": {    "first_name": { "type": "string" },    "last_name": { "type": "string" },    "shipping_address": { "$ref": "/schemas/address" },    "billing_address": { "$ref": "/schemas/address" }  },  "required": ["first_name", "last_name", "shipping_address", "billing_address"],  "$defs": {    "address": {      "$id": "/schemas/address",      "$schema": "http://json-schema.org/draft-07/schema#",      "type": "object",      "properties": {        "street_address": { "type": "string" },        "city": { "type": "string" },        "state": { "$ref": "#/definitions/state" }      },      "required": ["street_address", "city", "state"],      "definitions": {        "state": { "enum": ["CA", "NY", "... etc ..."] }      }    }  }}

无论模式资源是否捆绑，复合模式文档中的所有引用都必须相同。注意，客户模式中的$ref关键字没有变更。唯一的区别是，地址模式现在定义为/$defs/address，而不是单独的模式文档。你无法使用#/$defs/address引用地址模式，因为如果将模式拆分，该引用将不再指向地址模式。

此外还可以看到“$ref”：“#/definitions/state”解析为地址模式中的definitions关键字，而不是顶层模式中的definitions关键字，就像不使用嵌入模式时一样。

每个模式资源都是独立评估的，可以使用不同的JSON模式dialects。上面的示例中，地址模式资源使用Draft 7，而客户模式资源使用Draft 2020-12。如果嵌入式模式中没有声明$schema，则默认使用父模式的dialects。

本文来自博客园，作者：charlieroro，转载请注明原文链接：https://www.cnblogs.com/charlieroro/p/15939356.html

posted @ 2022-02-26 15:18 charlieroro 阅读(2) 评论(0) 编辑收藏举报

上一篇：简述LSM-Tree

下一篇：设计原则之【单一职责原则】

回帖

优雅殿下（王者段位）

2018 积分 (2)粉丝 (47)源码

小小码农，大大世界

温馨提示

您可以通过每日签到获得积分；
您也可以通过发布源码或者分享技术获得积分；

亦奇源码

UnderstandingJSONSchema

Understanding JSON Schema

type字段

jsonschema的五种基本类型

string

length

正则表达式

数字类型

integer

number

multiples

range

object

properties

Pattern Properties

Additional Properties

扩展封闭模式

Unevaluated Properties

Required Properties

属性名称

size

array

item

Tuple 校验

额外的元素

Contains

minContains / maxContains

length

Uniqueness

boolean

null

通用关键字

Annotations

Comments

Enumerated values

Constant values

Media: 字符串编码的非JSON数据

contentMediaType

contentEncoding

模式组合

allOf

oneOf

not

模式组合的特点

不合逻辑的模式

分解模式

子模式条件

dependentRequired

dependentSchemas

If-Then-Else

implication

声明一个Dialect

$schema

Guidelines

构造复杂的模式

Schema Identification

基本URI

检索URI

$id

JSON指针

$anchor

$ref

$def

递归

Bundling

优雅殿下 （王者 段位）

温馨提示

最新会员

优雅殿下（王者段位）