@segment/ajv-human-errors

ajv-human-errors

Human-readable error messages for Ajv (Another JSON Schema Validator).

By default, Ajv error messages leave a little bit to be desired. ajv-human-errors provides an Error object that can return errors that are more easily readable by humans. For example, ajv-human-errors changes "should NOT have additional properties" to "The root value has an unexpected property, c, which is not in the list of allowed properties (a, d)."

You can also override the error message entirely using the "errorMessage" schema keyword, like you can with ajv-errors (see below).

The following Ajv options must be set to true for ajv-human-errors to work with the errors returned by Ajv:

• allErrors
• verbose
• jsonPointers

The following features of JSON Schema are not yet implemented (but will return their "raw" Ajv error messages):

• patternProperties
• allOf
• oneOf
• Nested array schemas
• const
• if/then/else
• contentEncoding/contentMediaType

Usage

const Ajv = require('ajv')
const AjvValidationError = require('@segment/ajv-human-errors')

const ajv = new Ajv({
  allErrors: true,
  verbose: true,
  jsonPointers: true
})

ajv.validate(
  { type: 'string' },
  1234
)

const err = new AjvValidationError(ajv.errors)
console.log(err.message)
// 'The root value should be a string but it was a number.'

The AjvValidationError object can be passed to JSON.stringify() for a list of all errors:

[
  {
    "message": "The value at .arr should be unique but elements 1 and 4 are the same.",
    "path": "$.arr",
    "pointer": "/arr",
    "value": [0, 1, 2, 0, 1]
  },
  // ...
]

Options

The AjvValidationError constructor accepts the following options:

• fieldLabels (default: 'title') Change the labels used for fields. Allowed values:

  • 'js' JavaScript object accessor notation. Example: "The value at .for.bar should be a number but it was a string."

  • 'jsonPath' JSON Path notation. Example: "The value at $.foo.bar should be a number but it was a string."

  • 'jsonPointer' JSON Pointer notation. Example: "The value at /foo/bar should be a number but it was a string."

  • 'title' Uses the title property of the schema rule that failed validation. If your schema is:

    { "type": "object", "properties": { "foo": { "title": "Number of Foo" "type": "integer" } } }

    Then the resulting error message would look like: "Number of Foo should be an integer but it was a string."

• includeOriginalError (default: false) Include the original Ajv error object on the data property of each error in the AjvValidationError instance:

  const err = new AjvValidationError(ajv.errors, { includeOriginalError: true })
  err.errors.forEach(e => console.log(e.original))
  // {
  //   params: { ... },
  //   parentSchema: { ... },
  //   schema: '...',
  //   schemaPath: '...'
  // }
  

• includeData (default: false) Include the value of the field that failed validation on the data property of each error in the AjvValidationError instance.

  const err = new AjvValidationError(ajv.errors, { includeOriginalError: true })
  err.errors.forEach(e => console.log(e.data))
  // 'oops, this should be a number'
  

Schema Options

If you want to override an error message entirely, you can set an "errorMessage" keyword in your schema. For example, this schema:

{
  "type": "string",
  "errorMessage": "should be a bag of bytes"
}

Returns this error message when given a non-string object:

"The root value should be a bag of bytes."