Ajv

ajv-errors

自定义 JSON schema 中的错误信息插件。

安装

npm install ajv-errors
1

使用

向 Ajv 实例中添加errorMessage关键字：

var Ajv = require('ajv');
var ajv = new Ajv({allErrors: true, jsonPointers: true});
// Ajv options allErrors and jsonPointers are required
require('ajv-errors')(ajv /*, {singleError: true} */);
1
2
3
4

单个信息

用一条消息替换当前 schema 和子鸡 schema 中的所有错误:

var schema = {
  type: 'object',
  required: ['foo'],
  properties: {
    foo: { type: 'integer' }
  },
  additionalProperties: false,
  errorMessage: 'should be an object with an integer property foo only'
};

var validate = ajv.compile(schema);
console.log(validate({foo: 'a', bar: 2})); // false
console.log(validate.errors); // 处理后的错误信息
1
2
3
4
5
6
7
8
9
10
11
12
13

处理后的错误信息：

[
  {
    keyword: 'errorMessage',
    message: 'should be an object with an integer property foo only',
    // ...
    params: {
      errors: [
        { keyword: 'additionalProperties', dataPath: '' /* , ... */ },
        { keyword: 'type', dataPath: '.foo' /* , ... */ }
      ]
    }
  }
]
1
2
3
4
5
6
7
8
9
10
11
12
13

关键字信息

仅替换当前 schema 中的某些关键字错误。

var schema = {
  type: 'object',
  required: ['foo'],
  properties: {
    foo: { type: 'integer' }
  },
  additionalProperties: false,
  errorMessage: {
    type: 'should be an object', // 不会替换属性“foo”的内部“type”错误
    required: 'should have property foo',
    additionalProperties: 'should not have properties other than foo'
  }
};

var validate = ajv.compile(schema);
console.log(validate({foo: 'a', bar: 2})); // false
console.log(validate.errors); // 处理后的错误信息
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

处理后的错误信息:

[
  {
    // 原本的错误
    keyword: type,
    dataPath: '/foo',
    // ...
    message: 'should be integer'
  },
  {
    // 生成的错误
    keyword: 'errorMessage',
    message: 'should not have properties other than foo',
    // ...
    params: {
      errors: [
        { keyword: 'additionalProperties' /* , ... */ }
      ]
    },
  }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

对于关键字required和dependencies，可以为不同的属性指定不同的错误信息：

var schema = {
  type: 'object',
  required: ['foo', 'bar'],
  properties: {
    foo: { type: 'integer' },
    bar: { type: 'string' }
  },
  errorMessage: {
    type: 'should be an object', // 不会替换属性“foo”的内部“type”错误
    required: {
      foo: 'should have an integer property "foo"',
      bar: 'should have a string property "bar"'
    }
  }
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

属性和项的信息

替换属性/项(和更深层次)的错误，不管它们是在 schema 的什么地方创建的:

var schema = {
  type: 'object',
  required: ['foo', 'bar'],
  allOf: [{
    properties: {
      foo: { type: 'integer', minimum: 2 },
      bar: { type: 'string', minLength: 2 }
    },
    additionalProperties: false
  }],
  errorMessage: {
    properties: {
      foo: 'data.foo should be integer >= 2',
      bar: 'data.bar should be string with length >= 2'
    }
  }
};

var validate = ajv.compile(schema);
console.log(validate({foo: 1, bar: 'a'})); // false
console.log(validate.errors); // 处理后的错误信息
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

处理后的错误信息:

[
  {
    keyword: 'errorMessage',
    message: 'data.foo should be integer >= 2',
    dataPath: '/foo',
    // ...
    params: {
      errors: [
        { keyword: 'minimum' /* , ... */ }
      ]
    },
  },
  {
    keyword: 'errorMessage',
    message: 'data.bar should be string with length >= 2',
    dataPath: '/bar',
    // ...
    params: {
      errors: [
        { keyword: 'minLength' /* , ... */ }
      ]
    },
  }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

默认信息

当关键字errorMessage的值为一个对象。您可以指定出现任何未经关键字/属性/项目覆盖的错误时，使用的信息：

var schema = {
  type: 'object',
  required: ['foo', 'bar'],
  allOf: [{
    properties: {
      foo: { type: 'integer', minimum: 2 },
      bar: { type: 'string', minLength: 2 }
    },
    additionalProperties: false
  }],
  errorMessage: {
    type: 'data should be an object',
    properties: {
      foo: 'data.foo should be integer >= 2',
      bar: 'data.bar should be string with length >= 2'
    },
    _: 'data should have properties "foo" and "bar" only'
  }
};

var validate = ajv.compile(schema);
console.log(validate({})); // false
console.log(validate.errors); // 处理后的错误信息
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

处理后的错误信息：

[
  {
    keyword: 'errorMessage',
    message: 'data should be an object with properties "foo" and "bar" only',
    dataPath: '',
    // ...
    params: {
      errors: [
        { keyword: 'required' /* , ... */ },
        { keyword: 'required' /* , ... */ }
      ]
    },
  }
]
1
2
3
4
5
6
7
8
9
10
11
12
13
14

errorMessage的属性_中的消息替换了errorMessage是字符串时将被替换的相同错误。

模板

在errorMessage关键字中使用的自定义错误消息可以为模板，它们使用JSON指针或JSON相对指针来验证数据。这样的话就会插入值。请参阅相关文档。

插入值的模板语法是${<pointer>}。

错误消息中的值会转换为字符串：

  • 以区分false和"false"等类似情况。
  • 以支持结构性的值。
{
  "type": "object",
  "properties": {
    "size": {
      "type": "number",
      "minimum": 4
    }
  },
  "errorMessage": {
    "properties": {
      "size": "size should be a number bigger or equal to 4, current value is ${/size}"
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

配置项

默认：

{
  keepErrors: false,
  singleError: false
}
1
2
3
4
配置项 描述
keepErrors 保持原来的错误。默认是删除匹配到的错误(它们仍然在生成错误的params.error属性中)。如果一个错误被匹配并包含在由errorMessage关键字生成的错误中，那么将具有属性emUsed: true。
singleError 为errorMessage关键字中使用的所有关键字创建一个错误(为属性和项定义的错误消息不会合并，因为它们具有不同的数据路径dataPath)。多个错误消息会连接起来：

- false（默认值）：创建多个错误，每个错误都有信息。
- true 创建单个错误，错误信息通过";"进行连接。
- 非空的字符串：用作连接消息的分隔符。

← ajv-i18n →