@apideck/better-ajv-errors

What is @apideck/better-ajv-errors?

@apideck/better-ajv-errors is a utility package designed to provide more human-readable error messages for JSON schema validation using Ajv. It enhances the default error messages provided by Ajv, making it easier to understand and debug validation issues.

What are @apideck/better-ajv-errors's main functionalities?

Human-readable error messages

This feature provides more understandable error messages when JSON schema validation fails. The code sample demonstrates how to use @apideck/better-ajv-errors to enhance the error messages from Ajv.

{"const Ajv = require('ajv');":"","const betterAjvErrors = require('@apideck/better-ajv-errors');":"","const ajv = new Ajv();":"","const schema = {":"","  type: 'object',":"","  properties: {":"","    name: { type: 'string' },":"","    age: { type: 'integer' }":"","  },":"","  required: ['name', 'age']":"","};":"","const data = { name: 'John' };":"","const validate = ajv.compile(schema);":"","const valid = validate(data);":"","if (!valid) {":"","  const output = betterAjvErrors(schema, data, validate.errors, { format: 'js' });":"","  console.log(output);":"","}":""}

Other packages similar to @apideck/better-ajv-errors

ajv-errors

ajv-errors is a package that allows custom error messages in Ajv. It provides a way to define custom error messages for specific validation keywords, offering more control over the error output. Unlike @apideck/better-ajv-errors, which focuses on making default error messages more readable, ajv-errors allows for custom error message definitions.

ajv-i18n

ajv-i18n is a package that provides internationalization (i18n) support for Ajv error messages. It translates Ajv error messages into different languages. While @apideck/better-ajv-errors focuses on making error messages more human-readable in English, ajv-i18n is useful for applications that need to support multiple languages.

README

@apideck/better-ajv-errors 👮‍♀️

Human-friendly JSON Schema validation for APIs

• Readable and helpful ajv errors
• API-friendly format
• Suggestions for spelling mistakes
• Minimal footprint: 1.56 kB (gzip + minified)

Install

$ yarn add @apideck/better-ajv-errors

or

$ npm i @apideck/better-ajv-errors

Also make sure that you've installed ajv at version 8 or higher.

Usage

After validating some data with ajv, pass the errors to betterAjvErrors

import Ajv from 'ajv';
import { betterAjvErrors } from '@apideck/better-ajv-errors';

// Without allErrors: true, ajv will only return the first error
const ajv = new Ajv({ allErrors: true });

const valid = ajv.validate(schema, data);

if (!valid) {
  const betterErrors = betterAjvErrors({ schema, data, errors: ajv.errors });
}

API

betterAjvErrors

Function that formats ajv validation errors in a human-friendly format.

Parameters

• options: BetterAjvErrorsOptions
  • errors: ErrorObject[] | null | undefined Your ajv errors, you will find these in the errors property of your ajv instance (ErrorObject is a type from the ajv package).
  • data: Object The data you passed to ajv to be validated.
  • schema: JSONSchema The schema you passed to ajv to validate against.
  • basePath?: string An optional base path to prefix paths returned by betterAjvErrors. For example, in APIs, it could be useful to use '{requestBody}' or '{queryParemeters}' as a basePath. This will make it clear to users where exactly the error occurred.

Return Value

• ValidationError[] Array of formatted errors (properties of ValidationError below)
  • message: string Formatted error message
  • suggestion?: string Optional suggestion based on provided data and schema
  • path: string Object path where the error occurred (example: .foo.bar.0.quz)
  • context: { errorType: DefinedError['keyword']; [additionalContext: string]: unknown } errorType is error.keyword proxied from ajv. errorType can be used as a key for i18n if needed. There might be additional properties on context, based on the type of error.

Related

• atlassian/better-ajv-errors was the inspiration for this library. Atlassian's library is more focused on CLI errors, this library is focused on developer-friendly API error messages.