JSON Schema校验

Drip Form 协议底层使用 JSON Schema¹规范配合 Ajv² 校验。

使用 JSON Schema 的好处

确保表单数据的格式统一（避免冗余、格式错误数据的提交）
方便前后端统一校验函数
无需开发常见校验场景（JSON Schema 和 Ajv 已经提供）
描述数据的格式

使用 Ajv 的好处

少写代码
无需编写数据校验逻辑
使用简洁、易于阅读和跨平台的 JSON Schema 协议立即校验数据
超级快速和安全
Ajv 生成代码以将 JSON 模式转换为对 v8 优化有效的超快速验证函数。
目前 Ajv 是最快和最符合标准的验证器
支持多个 JSON Schema 草案
包括最新的 2020-12 草案

回顾

在《unitedSchema 协议表单校验》文档中，我们学习以下内容

使用requiredMsg、minItems、minmum、maximum校验关键字
使用errMsg配置关键字错误文案

我们大致了解了如何使用 unitedSchema 配置校验。

接下来，我们将介绍 JSON Schema¹和 ajv²插件提供的关键字。

提示

关键字介绍顺序会按照数据格式（number、string、array、object）进行区分
boolean 和 null 无校验关键字；
关键字所属区分
- JSON Schema 提供的关键字后面会添加 JSON Schema 标志
- Ajv 提供的关键字会添加 Ajv 标志
- Drip Form 自定义校验关键字³会添加 Drip Form标志
本文档部分例子使用 JSON Schema¹ 和 Ajv² 文档中例子

number

倍数

multipleOf JSON Schema

例子1
例子2

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

校验通过：10、20
校验失败：11

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

校验通过：2.5、5、7.5
校验失败：11

范围

maximum/minimum JSON Schema

maximum例子
minimum例子

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

校验通过：1、9、10
校验失败：11

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

校验通过：10、11
校验失败：9

exclusiveMaximum/exclusiveMinmum JSON Schema

exclusiveMaximum例子
exclusiveMinmum例子

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

校验通过：1、9
校验失败：10、11

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

校验通过：11、12
校验失败：10、9

multipleOf JSON Schema

例子1
例子2

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

校验通过：10、20
校验失败：11

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

校验通过：2.5、5、7.5
校验失败：11

range Ajv

{
    "type": "number",
    "range": [2, 4]
}

校验通过：2、3、4、2.3
校验失败：1、5

exclusiveRange Ajv

{
    "type": "number",
    "exclusiveRange": [2, 4]
}

校验通过：2.11、3、3.99
校验失败：1、2、4、5

string

长度

minLength/maxLength JSON Schema

注意：这里不区分中英文长度，中英文长度均为1

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

校验通过：a我1、a我
校验失败：我、我爱13

gbkLength Drip Form

区分中英文长度

{
    "type": "string",
    "gbkLength": {
        "min": 2,
        "max": 3
    }
}

校验通过：爱、爱1
校验失败：1、我爱

rangeDelimiter Drip Form

使用分割符分割之后的最长最短输入校验。

{
    "type": "string",
    "rangeDelimiter": {
        // 使用英文逗号分割字符串
        "delimiter": ",",
        // 分割之后的最多4位
        "max": 4,
        // 分割之后最少2位
        "min": 2
    }
}

校验通过："1,2,3,4"、"1,2,3"、"1,2"
校验失败："1"、"1,2,3,4,5"

正则

pattern JSON Schema

pattern 的值是一个字符串，用于 new RegExp(value,"u")创建将用于测试数据的正则表达式

{
    "type": "string",
    "pattern": "[abc]+"
}

校验通过："a"、"abcd"、"cde"
校验失败："def"、""

regexp Ajv

此关键字允许在正则中使用带有标志的正则表达式，并且也可以不使用"u"标志（pattern默认存在"u"标志）

{
    "type": "string",
    "regexp": "/foo/i"
}

校验通过：Food、foo
校验失败：fog

转换

transform Ajv

此关键字允许在验证期间修改字符串。

支持的转换：

trim: 删除开头和结尾的空格
trimStart/ trimLeft: 从开始删除空格
trimEnd/ trimRight：从末尾删除空格
toLowerCase: 转换为小写
toUpperCase: 转换为大写

单个转换
多重转换

{
    "type": "string",
    "transform": ["trim"]
}

校验前：" MixCase "
校验后："MixCase"

转换按照列出的顺序应用。

{
    "type": "string",
    "transform": ["trim", "toLowerCase"]
}

校验前：" MixCase "
校验后："mixcase"

格式

format JSON Schema

此关键字提供了一些常见语义的校验。比如：日期、url、ip地址等

format 支持以下格式

日期和时间
- date-time JSON Schema、Drip Form
- time JSON Schema
- date JSON Schema
- duration JSON Schema
- iso-time Ajv
- iso-date-time Ajv
电子邮件地址
- email JSON Schema
- idn-email JSON Schema
主机名
- hostname JSON Schema
- idn-hostname JSON Schema
ip 地址
- ipv4 JSON Schema
- ipv6 JSON Schema
资源标识符
- uuid JSON Schema
- uri JSON Schema
- uri-reference JSON Schema
- iri JSON Schema
- iri-reference JSON Schema
- uri-template Ajv
- url Ajv
- https Drip Form 是否是规范的 https url
其他
- regex Ajv
- json-pointer Ajv
- relative-json-pointer Ajv
- byte Ajv
- int32 Ajv
- int64 Ajv
- float Ajv
- double Ajv
- password Ajv
- binary Ajv
- color Drip Form 是否是颜色字符串（支持 rgba、rgb、hex 三种颜色）
- jsonObject Drip Form 是否是 json 对象字符串

格式实现规范详细了解

array

长度

minItems/maxItems JSON Schema

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

校验通过：[1,2]、[1,2,3]
校验失败：[1]、[1,2,3,4]

唯一性

uniqueItems JSON Schema

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

校验通过：[1,2]、[1,2,3]
校验失败：[1,2,1]、[{a: 1,b: 2},{b: 2,a: 1}]

uniqueItemProperties Ajv

{
    "type": "array",
    "uniqueItemProperties": ["id", "name"]
}

校验通过：[{id: 1},{id: 2},{id: 3}]

校验失败：

失败例子1
失败例子2

[
  {id: 1},
  {id: 1}, // duplicate "id"
  {id: 3},
]

[
  {id: 1, name: "taco"},
  {id: 2, name: "taco"}, // duplicate "name"
  {id: 3, name: "salsa"},
]

子项

items JSON Schema

普通数组
元祖

普通数组是指数组中每一项数据格式一致的数组。比如：[1,2,3]、['1','2','3']、[{a:1},{a:2}]

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

校验通过：[]、['1','2']
校验失败： [1]

元祖是指数组有固定顺序和长度限制，且格式不一致。比如：[1,'2']

{
    "type": "array",
    "minItems": 2,
    "additionalItems": false,
    "items": [
        {
            "type": "string"
        },
        {
            "type": "number"
        }
    ]
}

校验通过：['1',2]、['3',4]
校验失败： [1,2]

额外项

additionalItems JSON Schema

不允许存在多余子项
允许存在多余子项，不限制子项类型
允许存在多余子项，限制子项类型

{
  type: "array",
  items: [{type: "number"}, {type: "string"}],
  minItems: 2
  additionalItems: false
}

校验通过：[1,'2']
校验失败： []、[1]、[1,'2',3]、[1,2]

{
  type: "array",
  items: [{type: "number"}, {type: "number"}],
  additionalItems: true
}

校验通过：[]、 [1, 2]、[1, 2, 3]、[1, 2, "abc"]
校验失败： ["abc"]、[1, "abc", 3]

{
  type: "array",
  items: [{type: "number"}, {type: "number"}],
  additionalItems: {type: "string"}
}

校验通过： []、[1, 2]、[1, 2, "abc"]
校验失败： ["abc"]、[1, 2, 3]

包含

contains JSON Schema

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

校验通过：[1]、 [1, "foo"] （任何至少有一个整数的数组）
校验失败：[]、["foo", "bar"] （没有任何整数的数组）

maxContaines/minContains JSON Schema

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

校验通过：[1, 2]、[1, 2, 3, "foo"] （任何有 2 或 3 个整数的数组）
校验失败：[]、[1, "foo"]、[1, 2, 3, 4] （任何少于 2 个或多于 3 个整数的数组）

object

属性

properties JSON Schema

{
  type: "object",
  properties: {
    foo: {type: "string"},
    bar: {
      type: "number",
      minimum: 2
    }
  }
}

校验通过：{}、{foo: "a"}、{foo: "a", bar: 2}、{foo:'a',bar:2,c:3}（省略、多余属性均不影响）
校验失败：{foo: 1}、{foo: "a", bar: 1}

正则属性

patternProperties JSON Schema

{
  type: "object",
  patternProperties: {
    "^fo.*$": {type: "string"},
    "^ba.*$": {type: "number"}
  }
}

校验通过：{}、 {foo: "a"}、{foo: "a", bar: 1}
校验失败：{foo: 1}、{foo: "a", bar: "b"}

额外属性

additionalProperties JSON Schema

不允许存在多余子属性
允许存在多余子属性，不限制子属性类型
允许存在多余子属性，限制子属性类型

{
  type: "object",
  properties: {
    foo: {type: "number"}
  },
  additionalProperties: false
}

校验通过：{}、{foo:1}
校验失败： {a:3}、{foo:1,a:3}

默认additionalItems为true，即不限制额外的属性

{
  type: "object",
  properties: {
    foo: {type: "string"},
    bar: {
      type: "number",
      minimum: 2
    }
  },
  //可省略additionalItems
  additionalItems:true
}

校验通过：{}、{foo: "a"}、{foo: "a", bar: 2}、{foo:'a',bar:2,c:3}（省略、多余属性均不影响）
校验失败：{foo: 1}、{foo: "a", bar: 1}

{ type: "object", properties: { foo: {type: "number"} }, additionalProperties: {type: "string"} }

校验通过：{}、{a: "b"}、{foo: 1}、{foo: 1, bar: 2}、{foo: 1, bar: 2, a: "b"}
校验失败：{a: 3}、{foo: 1, baz: 3}

prohibited Ajv

禁止列表中的任何属性出现在对象中。

{
  type: "object",
  prohibited: ["foo", "bar"],
}

校验通过：{baz: 1}、{}
校验失败：{foo: 1}、{bar: 2}、{foo: 1, bar: 2}

必须属性

requriedMsg Drip Form

设置对象中某个属性必填，参考[表单校验必填](../../unitedSchema/schemaKeyword#必填)

allRequired Ajv

所有属性均要出现在对象中。

{
  type: "object",
  properties: {
    foo: {type: "number"},
    bar: {type: "number"},
  },
  allRequired: true,
}

校验通过：{foo: 1, bar: 2}、{foo: 1, bar: 2, baz: 3}
校验失败：{foo: 1}、{bar: 2}、{}

anyRequired Ajv

至少一个属性要出现在对象中。

{
  type: "object",
  anyRequired: ["foo", "bar"],
}

校验通过：{foo: 1}、{foo: 1, bar: 2}
校验失败：{}、{baz: 3}

oneRequired Ajv

只有一个属性出现在对象中。

{
  type: "object",
  oneRequired: ["foo", "bar"],
}

校验通过：{foo: 1}、{bar: 2, baz: 3}
校验失败：{}、{baz: 3}、{foo: 1, bar: 2}

patternRequired Ajv

每个正则表达式都应至少匹配数据对象中的一个属性名称

{
  type: "object",
  patternRequired: ["f.*o", "b.*r"],
}

校验通过：{foo: 1, bar: 2}、{foobar: 3}
校验失败：{}、{foo: 1}、{ bar: 2}

属性名称

propertyNames JSON Schema

对象中的每个属性名称都应根据此模式有效

{
  type: "object",
  propertyNames: {
    format: "email"
  }
}

校验通过：{"foo@bar.com": "any", "bar@bar.com": "any"}
校验失败：{foo: "any value"}

大小

minProperties/maxProperties JSON Schema

对象中的每个属性名称都应根据此模式有效

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

校验通过：{a:1,b:2}、{a:1,b:2,c:3}
校验失败：{foo: "any value"}、{a:1,b:2,c:3,d:4}

JSON Schema是一种声明性语言，允许您注释和验证 JSON↩
Ajv 是安全可靠且快速的 JSON Schema 验证器↩
Drip Form 依赖 Ajv 插件机制开发的自定义关键字。用于补齐 JSON Schema、Ajv 并不具备，但业务场景常见的关键字。更多细节了解自定义校验关键字 ↩

number​

倍数​

范围​

string​

长度​

正则​

转换​

格式​

array​

长度​

唯一性​

子项​

额外项​

包含​

object​

属性​

正则属性​

额外属性​

必须属性​

属性名称​

大小​