JSON Schema validation for Human 👨‍🎤

Main goal of this library is to provide relevant error messages like the following:

Installation

npm i better-ajv-errors

Atlassian internal

npm i @atlassian/better-ajv-errors

Also install ajv, version 4.11.8 to 8, to validate data against JSON schemas. better-ajv-errors requires Node.js 22 or later.

Usage

First, you need to validate your payload with ajv. If it's invalid then you can pass validate.errors object into better-ajv-errors.

import Ajv from 'ajv';
import betterAjvErrors from 'better-ajv-errors';
// const Ajv = require('ajv');
// const betterAjvErrors = require('better-ajv-errors').default;
// Or
// const { default: betterAjvErrors } = require('better-ajv-errors');

// `allErrors` makes ajv report every error instead of stopping at the first one.
// ajv 6 and older also need `jsonPointers: true`.
const ajv = new Ajv({ allErrors: true });

// Load schema and data
const schema = ...;
const data = ...;

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

if (!valid) {
  const output = betterAjvErrors(schema, data, validate.errors);
  console.log(output);
}

better-ajv-errors leaves out errors that another error usually explains:

• A missing required property hides the other errors reported for that object, such as additionalProperties.
• An enum error is hidden when another error is reported at the same level.

API

betterAjvErrors(schema, data, errors, [options])

Returns formatted validation error to print in console. See options.format for further details.

schema

Type: Object

The JSON Schema you used for validation with ajv

data

Type: Object

The JSON payload you validate against using ajv

errors

Type: Array

Array of ajv validation errors

options

Type: Object

format

Type: string
Default: cli
Values: cli js

Use default cli output format if you want to print beautiful validation errors like following:

Or, use js if you are planning to use this with some API. Your output will look like following:

[
  {
    start: { line: 6, column: 15, offset: 70 },
    end: { line: 6, column: 26, offset: 81 },
    error:
      '/content/0/type must be equal to one of the allowed values: paragraph, codeBlock, blockquote',
    path: '/content/0/type',
    suggestion: 'Did you mean paragraph?',
  },
];

path is the instancePath of the ajv error. end is left out for required errors, and suggestion appears on some enum errors, naming the allowed value closest to the actual one.

indent

Type: number null
Default: null

If you have an unindented JSON payload and you want the error output indented.

This option has no effect when using the json option.

json

Type: string null
Default: null

Raw JSON payload used when formatting codeframe. Gives accurate line and column listings.