# @apideck/better-ajv-errors

> Human-friendly JSON Schema validation for APIs

Latest version **0.3.7** (published 2026-03-28) · MIT license · 0 weekly downloads

## Install

```sh
npm install @apideck/better-ajv-errors
pnpm add @apideck/better-ajv-errors
yarn add @apideck/better-ajv-errors
bun add @apideck/better-ajv-errors
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.3.7 |
| Published | 2026-03-28 |
| First published | 2021-05-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=10 |
| Dependencies | 2 |
| Unpacked size | 77 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 44 |
| Author | Apideck |
| Maintainers | gdewilde, nicklloyd, ritiksingh7, samzani, lagoni, jakeprins, gmenoiaa |
| Keywords | apideck, ajv, json, schema, json-schema, errors, human |

## Links

- npm: https://www.npmjs.com/package/@apideck/better-ajv-errors
- Repository: https://github.com/apideck-libraries/better-ajv-errors
- Homepage: https://github.com/apideck-libraries/better-ajv-errors#readme
- Issues: https://github.com/apideck-libraries/better-ajv-errors/issues
- npm.io page: https://npm.io/package/@apideck/better-ajv-errors

## Dependencies (2)

- [leven](https://npm.io/package/leven.md) ^3.1.0
- [jsonpointer](https://npm.io/package/jsonpointer.md) ^5.0.1

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 0.3.7 (latest) — 2026-03-28
- 0.3.6 — 2022-06-28
- 0.3.5 — 2022-06-28
- 0.3.4 — 2022-05-25
- 0.3.3 — 2022-02-09
- 0.3.2 — 2021-12-23
- 0.3.1 — 2021-11-30
- 0.3.0 — 2021-11-23
- 0.2.7 — 2021-11-12
- 0.2.6 — 2021-10-05
- 0.2.5 — 2021-07-09
- 0.2.4 — 2021-06-10
- 0.2.3 — 2021-05-26
- 0.2.2 — 2021-05-26
- 0.2.1 — 2021-05-14
- … 1 more at https://npm.io/package/@apideck/better-ajv-errors/versions

## README

[![npm (scoped)](https://img.shields.io/npm/v/@apideck/better-ajv-errors?color=brightgreen)](https://npmjs.com/@apideck/better-ajv-errors) [![npm](https://img.shields.io/npm/dm/@apideck/better-ajv-errors)](https://npmjs.com/@apideck/better-ajv-errors) [![GitHub Workflow Status](https://img.shields.io/github/workflow/status/apideck-libraries/better-ajv-errors/CI)](https://github.com/apideck-libraries/better-ajv-errors/actions/workflows/main.yml?query=branch%3Amain++)

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

> Human-friendly JSON Schema validation for APIs


- Readable and helpful [ajv](https://github.com/ajv-validator/ajv) errors
- API-friendly format
- Suggestions for spelling mistakes
- Minimal footprint: 1.56 kB (gzip + minified)

![better-ajv-errors output Example](https://user-images.githubusercontent.com/8850410/118274790-e0529e80-b4c5-11eb-8188-9097c8064c61.png)

## Install

```bash
$ yarn add @apideck/better-ajv-errors
```

or

```bash
$ npm i @apideck/better-ajv-errors
```

Also make sure that you've installed [ajv](https://www.npmjs.com/package/ajv) at version 8 or higher.

## Usage

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

```ts
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](https://github.com/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.

---
_Source: https://npm.io/package/@apideck/better-ajv-errors · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._