{"id":17632354,"url":"https://github.com/ajv-validator/ajv-errors","last_synced_at":"2025-04-07T07:10:01.620Z","repository":{"id":43721506,"uuid":"83965405","full_name":"ajv-validator/ajv-errors","owner":"ajv-validator","description":"Custom error messages in JSON Schemas for Ajv validator","archived":false,"fork":false,"pushed_at":"2023-10-10T11:47:59.000Z","size":119,"stargazers_count":289,"open_issues_count":39,"forks_count":18,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-31T05:07:32.942Z","etag":null,"topics":["ajv","errors","json-schema","validator"],"latest_commit_sha":null,"homepage":"https://ajv.js.org","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ajv-validator.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null},"funding":{"github":"epoberezkin","tidelift":"npm/ajv-errors"}},"created_at":"2017-03-05T11:36:48.000Z","updated_at":"2025-03-15T19:02:50.000Z","dependencies_parsed_at":"2024-01-26T03:02:36.441Z","dependency_job_id":"dc1f0757-3538-4164-9623-67274cb35b30","html_url":"https://github.com/ajv-validator/ajv-errors","commit_stats":{"total_commits":90,"total_committers":7,"mean_commits":"12.857142857142858","dds":0.4,"last_synced_commit":"7efe8c29c3ea461eef29335e0199742dbc18e791"},"previous_names":["epoberezkin/ajv-errors"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajv-validator%2Fajv-errors","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajv-validator%2Fajv-errors/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajv-validator%2Fajv-errors/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajv-validator%2Fajv-errors/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ajv-validator","download_url":"https://codeload.github.com/ajv-validator/ajv-errors/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247608151,"owners_count":20965952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ajv","errors","json-schema","validator"],"created_at":"2024-10-23T01:06:40.059Z","updated_at":"2025-04-07T07:10:01.576Z","avatar_url":"https://github.com/ajv-validator.png","language":"TypeScript","funding_links":["https://github.com/sponsors/epoberezkin","https://tidelift.com/funding/github/npm/ajv-errors","https://tidelift.com/subscription/pkg/npm-ajv-errors?utm_source=npm-ajv-errors\u0026utm_medium=referral\u0026utm_campaign=enterprise\u0026utm_term=repo","https://tidelift.com/security"],"categories":[],"sub_categories":[],"readme":"# ajv-errors\n\nCustom error messages in JSON-Schema for Ajv validator\n\n[![build](https://github.com/ajv-validator/ajv-errors/workflows/build/badge.svg)](https://github.com/ajv-validator/ajv-errors/actions?query=workflow%3Abuild)\n[![npm](https://img.shields.io/npm/v/ajv-errors.svg)](https://www.npmjs.com/package/ajv-errors)\n[![coverage](https://coveralls.io/repos/github/ajv-validator/ajv-errors/badge.svg?branch=master)](https://coveralls.io/github/ajv-validator/ajv-errors?branch=master)\n[![gitter](https://img.shields.io/gitter/room/ajv-validator/ajv.svg)](https://gitter.im/ajv-validator/ajv)\n\n**Please note**\n\najv-errors v3 supports [ajv v8](https://github.com/ajv-validator/ajv).\n\nIf you are using ajv v6, you should use [ajv-errors v1](https://github.com/ajv-validator/ajv-errors/tree/v1)\n\n## Contents\n\n- [Install](#install)\n- [Usage](#usage)\n  - [Single message](#single-message)\n  - [Messages for keywords](#messages-for-keywords)\n  - [Messages for properties and items](#messages-for-properties-and-items)\n  - [Default message](#default-message)\n- [Templates](#templates)\n- [Options](#options)\n- [Supporters, Enterprise support, Security contact](#supporters)\n- [License](#license)\n\n## Install\n\n```\nnpm install ajv-errors\n```\n\n## Usage\n\nAdd the keyword `errorMessages` to Ajv instance:\n\n```javascript\nconst Ajv = require(\"ajv\").default\nconst ajv = new Ajv({allErrors: true})\n// Ajv option allErrors is required\nrequire(\"ajv-errors\")(ajv /*, {singleError: true} */)\n```\n\nSee [Options](#options) below.\n\n### Single message\n\nReplace all errors in the current schema and subschemas with a single message:\n\n```javascript\nconst schema = {\n  type: \"object\",\n  required: [\"foo\"],\n  properties: {\n    foo: {type: \"integer\"},\n  },\n  additionalProperties: false,\n  errorMessage: \"should be an object with an integer property foo only\",\n}\n\nconst validate = ajv.compile(schema)\nconsole.log(validate({foo: \"a\", bar: 2})) // false\nconsole.log(validate.errors) // processed errors\n```\n\nProcessed errors:\n\n```json5\n[\n  {\n    keyword: \"errorMessage\",\n    message: \"should be an object with an integer property foo only\",\n    // ...\n    params: {\n      errors: [\n        {keyword: \"additionalProperties\", instancePath: \"\" /* , ... */},\n        {keyword: \"type\", instancePath: \".foo\" /* , ... */},\n      ],\n    },\n  },\n]\n```\n\n### Messages for keywords\n\nReplace errors for certain keywords in the current schema only:\n\n```javascript\nconst schema = {\n  type: \"object\",\n  required: [\"foo\"],\n  properties: {\n    foo: {type: \"integer\"},\n  },\n  additionalProperties: false,\n  errorMessage: {\n    type: \"should be an object\", // will not replace internal \"type\" error for the property \"foo\"\n    required: \"should have property foo\",\n    additionalProperties: \"should not have properties other than foo\",\n  },\n}\n\nconst validate = ajv.compile(schema)\nconsole.log(validate({foo: \"a\", bar: 2})) // false\nconsole.log(validate.errors) // processed errors\n```\n\nProcessed errors:\n\n```json5\n[\n  {\n    // original error\n    keyword: type,\n    instancePath: \"/foo\",\n    // ...\n    message: \"should be integer\",\n  },\n  {\n    // generated error\n    keyword: \"errorMessage\",\n    message: \"should not have properties other than foo\",\n    // ...\n    params: {\n      errors: [{keyword: \"additionalProperties\" /* , ... */}],\n    },\n  },\n]\n```\n\nFor keywords \"required\" and \"dependencies\" it is possible to specify different messages for different properties:\n\n```javascript\nconst schema = {\n  type: \"object\",\n  required: [\"foo\", \"bar\"],\n  properties: {\n    foo: {type: \"integer\"},\n    bar: {type: \"string\"},\n  },\n  errorMessage: {\n    type: \"should be an object\", // will not replace internal \"type\" error for the property \"foo\"\n    required: {\n      foo: 'should have an integer property \"foo\"',\n      bar: 'should have a string property \"bar\"',\n    },\n  },\n}\n```\n\n### Messages for properties and items\n\nReplace errors for properties / items (and deeper), regardless where in schema they were created:\n\n```javascript\nconst schema = {\n  type: \"object\",\n  required: [\"foo\", \"bar\"],\n  allOf: [\n    {\n      properties: {\n        foo: {type: \"integer\", minimum: 2},\n        bar: {type: \"string\", minLength: 2},\n      },\n      additionalProperties: false,\n    },\n  ],\n  errorMessage: {\n    properties: {\n      foo: \"data.foo should be integer \u003e= 2\",\n      bar: \"data.bar should be string with length \u003e= 2\",\n    },\n  },\n}\n\nconst validate = ajv.compile(schema)\nconsole.log(validate({foo: 1, bar: \"a\"})) // false\nconsole.log(validate.errors) // processed errors\n```\n\nProcessed errors:\n\n```json5\n[\n  {\n    keyword: \"errorMessage\",\n    message: \"data.foo should be integer \u003e= 2\",\n    instancePath: \"/foo\",\n    // ...\n    params: {\n      errors: [{keyword: \"minimum\" /* , ... */}],\n    },\n  },\n  {\n    keyword: \"errorMessage\",\n    message: \"data.bar should be string with length \u003e= 2\",\n    instancePath: \"/bar\",\n    // ...\n    params: {\n      errors: [{keyword: \"minLength\" /* , ... */}],\n    },\n  },\n]\n```\n\n### Default message\n\nWhen the value of keyword `errorMessage` is an object you can specify a message that will be used if any error appears that is not specified by keywords/properties/items using `_` property:\n\n```javascript\nconst schema = {\n  type: \"object\",\n  required: [\"foo\", \"bar\"],\n  allOf: [\n    {\n      properties: {\n        foo: {type: \"integer\", minimum: 2},\n        bar: {type: \"string\", minLength: 2},\n      },\n      additionalProperties: false,\n    },\n  ],\n  errorMessage: {\n    type: \"data should be an object\",\n    properties: {\n      foo: \"data.foo should be integer \u003e= 2\",\n      bar: \"data.bar should be string with length \u003e= 2\",\n    },\n    _: 'data should have properties \"foo\" and \"bar\" only',\n  },\n}\n\nconst validate = ajv.compile(schema)\nconsole.log(validate({})) // false\nconsole.log(validate.errors) // processed errors\n```\n\nProcessed errors:\n\n```json5\n[\n  {\n    keyword: \"errorMessage\",\n    message: 'data should be an object with properties \"foo\" and \"bar\" only',\n    instancePath: \"\",\n    // ...\n    params: {\n      errors: [{keyword: \"required\" /* , ... */}, {keyword: \"required\" /* , ... */}],\n    },\n  },\n]\n```\n\nThe message in property `_` of `errorMessage` replaces the same errors that would have been replaced if `errorMessage` were a string.\n\n## Templates\n\nCustom error messages used in `errorMessage` keyword can be templates using [JSON-pointers](https://tools.ietf.org/html/rfc6901) or [relative JSON-pointers](http://tools.ietf.org/html/draft-luff-relative-json-pointer-00) to data being validated, in which case the value will be interpolated. Also see [examples](https://gist.github.com/geraintluff/5911303) of relative JSON-pointers.\n\nThe syntax to interpolate a value is `${\u003cpointer\u003e}`.\n\nThe values used in messages will be JSON-stringified:\n\n- to differentiate between `false` and `\"false\"`, etc.\n- to support structured values.\n\nExample:\n\n```javascript\nconst schema = {\n  type: \"object\",\n  properties: {\n    size: {\n      type: \"number\",\n      minimum: 4,\n    },\n  },\n  errorMessage: {\n    properties: {\n      size: \"size should be a number bigger or equal to 4, current value is ${/size}\",\n    },\n  },\n}\n```\n\n#### Using property names in error messages\n\nProperty names can be used in error messages with the relative JSON-pointer (e.g. `0#`). \n\nExample: \n```javascript\nconst schema = {\n  type: \"object\",\n  properties: {\n    size: {\n      type: \"number\",\n    },\n  },\n  additionalProperties: {\n    not: true,\n    errorMessage: “extra property is ${0#}”\n  }\n}\n```\n\n## Options\n\nDefaults:\n\n```json5\n{\n  keepErrors: false,\n  singleError: false,\n}\n```\n\n- _keepErrors_: keep original errors. Default is to remove matched errors (they will still be available in `params.errors` property of generated error). If an error was matched and included in the error generated by `errorMessage` keyword it will have property `emUsed: true`.\n- _singleError_: create one error for all keywords used in `errorMessage` keyword (error messages defined for properties and items are not merged because they have different instancePaths). Multiple error messages are concatenated. Option values:\n  - `false` (default): create multiple errors, one for each message\n  - `true`: create single error, messages are concatenated using `\"; \"`\n  - non-empty string: this string is used as a separator to concatenate messages\n\n## Supporters\n\n[Roger Kepler](https://www.linkedin.com/in/rogerkepler/)\n\n## Enterprise support\n\najv-errors package is a part of [Tidelift enterprise subscription](https://tidelift.com/subscription/pkg/npm-ajv-errors?utm_source=npm-ajv-errors\u0026utm_medium=referral\u0026utm_campaign=enterprise\u0026utm_term=repo) - it provides a centralised commercial support to open-source software users, in addition to the support provided by software maintainers.\n\n## Security contact\n\nTo report a security vulnerability, please use the\n[Tidelift security contact](https://tidelift.com/security).\nTidelift will coordinate the fix and disclosure. Please do NOT report security vulnerability via GitHub issues.\n\n## License\n\n[MIT](https://github.com/epoberezkin/ajv-errors/blob/master/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajv-validator%2Fajv-errors","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fajv-validator%2Fajv-errors","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajv-validator%2Fajv-errors/lists"}