6.0 KiB
在使用 JSON Schema(如在 Fastify 或其他支持 JSON Schema 验证的系统中)时,type
关键字定义了数据类型。以下是一般支持的数据类型列表:
-
string:表示字符串。还可以配合
format
代表特定格式的字符串,如date-time
,email
,hostname
,ipv4
,ipv6
,uri
, 等。 -
number:表示任意数值,包括浮点数。
-
integer:表示整数。
-
boolean:表示布尔值 true 或 false。
-
object:表示关键字和值的集合,关键字必须为字符串。可以进一步描述对象的属性、所需的属性、属性的依赖性等。
-
array:表示一组有序的元素(项),项可以是任何类型。可以进一步定义项类型、数组长度等。
-
null:表示 null 值。
JSON Schema 还支持复合类型,例如:
- 使用 enums 定义一组固定的值。
- 使用
oneOf
,anyOf
,allOf
, 和not
关键字定义更复杂的逻辑组合。
例如,如果你希望属性接受字符串或 null 两种类型,可以使用 type
关键字的数组形式:
{
"type": ["string", "null"]
}
需要注意的是,除了上述的基本数据类型,JSON Schema 还支持定义更细致的限制条件,比如:
- 对于字符串:
minLength
,maxLength
, 和正则表达式pattern
- 对于数值:
minimum
,maximum
,exclusiveMinimum
,exclusiveMaximum
,multipleOf
- 对于对象:
properties
,additionalProperties
,required
,patternProperties
,minProperties
,maxProperties
- 对于数组:
items
,additionalItems
,minItems
,maxItems
,uniqueItems
,contains
还可以通过 default
, examples
, 和 const
等关键字提供更多信息。
上述列表涵盖了 JSON Schema Draft-07 和之后版本中的常见数据类型和功能。根据具体实施和使用的 JSON Schema 草案版本(Draft),可能会有细微差别。确保查看你使用的 JSON Schema 草案版本文档以获取完整信息。
oneOf
,anyOf
,allOf
和 not
是 JSON Schema 中用于组合其他规则的关键字。它们允许您对多个条件进行逻辑运算,以更精细地定义数据的结构。
-
oneOf
: 表示只有一个架构应匹配数据。如果多个架构都匹配数据,验证将失败。这类似于 "XOR" 的逻辑关系。示例:
{ "oneOf": [ { "type": "string" }, { "maxLength": 5 } ] }
这个示例声明了数据可以是一个字符串,或者长度最大为 5 的字符串。如果数据不是字符串,或者长度超过 5,验证将失败。
-
anyOf
: 表示至少有一个架构应匹配数据。只有当至少一个架构满足条件时,验证才会通过。示例:
{ "anyOf": [ { "type": "string" }, { "maxLength": 5 } ] }
这个示例声明了数据可以是一个字符串,或者长度最大为 5 的字符串。只要满足其中一个条件,即可通过验证。
-
allOf
: 表示所有架构都必须匹配数据。只有当所有架构条件都满足时,验证才会通过。示例:
{ "allOf": [ { "type": "string" }, { "minLength": 2 }, { "maxLength": 5 } ] }
这个示例要求数据必须是一个长度介于 2 和 5 之间的字符串,同时满足三个条件。
-
not
: 表示数据不能匹配给定的架构。如果数据满足not
中描述的架构,则验证将失败。示例:
{ "not": { "type": "null" } }
这个示例要求数据不能是
null
。如果数据是null
,则验证将失败。
这些组合关键字能够根据特定的需求对数据施加更复杂的约束和规则。您可以根据您的条件使用适当的组合关键字来定义数据的结构和验证规则。
在 JSON Schema 中,当你在定义数组类型的时候,有几个关键字可以用来更精确地描述数组的结构和约束:
-
items
: 用来指定数组中每个元素的架构。它可以是单个架构,适用于数组中的所有元素,或者是一个架构数组,适用于数组中每个位置的元素。示例(所有元素相同架构):
{ "type": "array", "items": { "type": "string" } }
在这个例子中,数组中的所有元素都必须是字符串。
示例(特定位置架构):
{ "type": "array", "items": [ { "type": "number" }, { "type": "string" } ] }
在这个例子中,数组的第一个元素必须是数字,第二个元素必须是字符串。
-
additionalItems
: 当使用架构数组定义items
时,additionalItems
关键字规定了数组中额外元素的架构(即超出items
数组定义的元素的架构)。示例:
{ "type": "array", "items": [ { "type": "number" }, { "type": "string" } ], "additionalItems": { "type": "string" } }
在这个例子中,第三个及以后的元素都必须是字符串。
-
minItems
: 指定数组的最小长度。示例:
{ "type": "array", "minItems": 2 }
数组至少要有两个元素。
-
maxItems
: 指定数组的最大长度。示例:
{ "type": "array", "maxItems": 5 }
数组最多可以有五个元素。
-
uniqueItems
: 要求数组中的所有元素都是唯一的。如果设置为true
,则不允许有重复的元素。示例:
{ "type": "array", "uniqueItems": true }
所有的元素应该都是独一无二的。
-
contains
: 确保数组至少包含一个符合提供的架构的元素。示例:
{ "type": "array", "contains": { "type": "string", "pattern": "^a" } }
这个架构要求数组至少包含一个以字母“a”开头的字符串。
这些关键字可以单独使用,也可以组合使用,以便根据具体的需要为数组数据结构定义详细的限制和规则。