JSON Schema Validation Errors: Reading and Fixing ajv Output

When ajv validates data against a schema and finds a constraint violation, it creates an error object with five standard fields: instancePath, schemaPath, keyword, params, and message. These fields together give you a precise description of what failed, where in the data it failed, which schema rule was violated, and what the specific mismatch was. Understanding each field is necessary to write useful validation error handlers.

The instancePath field is a JSON Pointer string that locates the failing value within the data document. A JSON Pointer uses forward slashes as separators, so a path of /user/email points to the email property inside the user object. When the instancePath is an empty string, the error applies to the root data object itself. For required keyword errors, instancePath points to the parent object that is missing a property, not to the missing property itself. The missing property name is found in the params field instead.

The keyword field tells you which schema constraint failed. Common keywords include type (the value has the wrong data type), required (a mandatory property is absent), additionalProperties (the data contains a property not listed in the schema), minimum and maximum (a number is out of range), minLength and maxLength (a string is too short or too long), pattern (a string does not match a regular expression), and format (a string does not conform to a named format such as email or date-time). Each keyword has a corresponding params object with additional detail.

The params field varies by keyword. For a type error, params contains a type property with the expected type name. For a required error, params contains missingProperty with the name of the absent field. For an additionalProperties error, params contains additionalProperty with the name of the unexpected field. For a minimum error, params contains limit with the minimum value and exclusive indicating whether the minimum is exclusive. Reading params is essential for building precise error messages because the message field alone often lacks enough specificity to identify the exact problem.

The instancePath field is the most important piece of information in an ajv error object when you need to connect a validation failure to a specific input field. It is formatted as a JSON Pointer as defined by RFC 6901, which uses forward slashes to separate path segments. A leading slash means the path is absolute from the root of the validated document. So /address/city refers to the city property within the address object at the top level of the data.

When converting instancePath values to field names for display in a user interface, you typically want to strip the leading slash. In JavaScript, err.instancePath.replace(/^\//, '') produces a dot-notation-like path if you then replace remaining slashes with dots. For arrays, the path includes the numeric index, such as /items/2/price, which means the price field in the third element of the items array.

For required keyword errors, the instancePath is the path to the containing object, not the path to the missing field. This is because the error is about the object failing to satisfy its required constraint, and the missing field does not exist in the data to be pointed to. The actual missing field name is in err.params.missingProperty. A robust error mapper must check the keyword and handle required errors differently from type, pattern, and other field-level errors.

The allErrors option in the ajv constructor is critical for diagnosing complex validation failures. By default, ajv stops after the first error it encounters. This means that if a submitted form has five invalid fields, you will only see one error object. Setting allErrors to true causes ajv to collect every error before returning, which lets you surface all field problems to the user in a single validation pass. This is almost always the right behavior for form validation, though it can be slightly slower for large data documents with many violations.

Required errors are the most common ajv validation failures in API contexts. They occur when a request body omits a field that the schema lists in the required array. The fix is almost always to add the missing field to the data before submitting it, but the error message from ajv does not always make clear which field is absent. The missingProperty value in params.missingProperty gives you the exact field name.

If you are designing a schema and find that required errors appear for fields that should be optional, move those fields out of the required array. Only list a property in required if the application truly cannot function without it. Optional fields that have sensible default values should not be required. Use the default keyword in the schema to document the default, though ajv does not populate defaults by default and requires the useDefaults option to be enabled.

AdditionalProperties errors appear when the data contains a property that is not listed in the schema's properties object and the schema sets additionalProperties to false. This is a common choice for API request schemas to prevent clients from sending fields that the server does not recognize, which could indicate a typo or a protocol version mismatch. The error tells you the exact extra property name in params.additionalProperty. The fix is either to remove that property from the data or to add it to the schema's properties if it is a legitimate field that was simply not documented.

When you are validating data for an API that should accept any extra fields without complaint, either omit the additionalProperties: false constraint from your schema or set additionalProperties to true explicitly. Note that without additionalProperties: false, extra fields are silently accepted and do not appear in any validation errors. If you want to allow extra fields but still know which unexpected fields were received, you will need to compare the data keys against the schema's properties keys manually outside of ajv.

Pattern errors occur when a string value does not match a regular expression defined in the schema. The error message includes the pattern, but not an explanation of what the pattern means in human terms. When exposing pattern errors in user interfaces, replace the raw pattern string with a human-readable description of the expected format. The ajv-errors package lets you override any keyword's error message with a custom string, which is valuable for all user-facing validation messages.

Raw ajv error messages are technically accurate but often not suitable for direct display to end users. A message like 'must match format email' or 'must have required property email' is clear to a developer but may confuse a user filling out a registration form. The ajv ecosystem provides two approaches to customizing error messages: the ajv-errors package for schema-level message definitions, and application-level error mapping in your validation handler.

The ajv-errors package extends schemas with an errorMessage keyword that accepts either a string for a single custom message or an object mapping keyword names to specific messages. For example, a schema property can define errorMessage: { type: 'Enter a valid number', minimum: 'Value must be at least 0' }. The package rewrites the ajv error array to replace matching errors with the custom messages. This approach keeps the custom message logic close to the schema definition, which is convenient when schemas are shared across server and client.

Application-level error mapping is more flexible because it does not require modifying the schema. Your validation handler receives the raw ajv errors and converts them into a structured response format. This approach is better when the same schema is used for validation in multiple contexts with different error message requirements, such as an API that returns JSON errors and a web server that renders error messages in HTML templates.

One subtlety is that ajv may produce multiple errors for the same field when using combiners such as oneOf or anyOf. When a data value fails all branches of a oneOf, ajv produces errors for each branch plus a top-level oneOf error. Deduplicating these for user display requires filtering to keep only the most specific errors. A common heuristic is to keep errors with the longest instancePath and discard errors whose schemaPath includes '/oneOf/' or '/anyOf/'.

One of the most confusing behaviors in ajv v8 is that the format keyword does not throw an error by default when the value violates the format constraint. Instead, format validation is silently skipped unless you explicitly install and register the ajv-formats package. This means that an email field containing 'notanemail' will pass validation if ajv-formats is not installed, even though the schema specifies format: 'email'. Developers often discover this only after going to production and finding that invalid email addresses are being stored in the database.

The ajv-formats package provides implementations for the standard JSON Schema formats defined in the specification, including email, uri, date, date-time, time, ipv4, ipv6, uuid, and several others. After installing the package, you must call addFormats(ajv) before compiling any schemas that use the format keyword. Calling addFormats after compilation does not retroactively add format validation to already-compiled validators.

For email format specifically, ajv-formats validates the general structure of an email address but does not verify that the domain exists or that the mailbox accepts messages. Applications that need stricter email validation should combine ajv-formats with a dedicated email validation library or apply a custom pattern to the field.

Another silent failure mode occurs when ajv v8 encounters a schema keyword it does not recognize. In strict mode, which is the default in ajv v8, unknown keywords cause a compilation error with the message 'strict mode: unknown keyword'. This is actually helpful because it catches typos in keyword names. However, when migrating schemas from ajv v6 or from other validators that used non-standard keywords, this strict mode error prevents compilation. You can disable strict mode with { strict: false } in the constructor options, but it is better to remove or update the unrecognized keywords so the schema is valid against the JSON Schema specification.

Compiling a JSON Schema with ajv is an expensive operation relative to the actual validation step. ajv converts the schema into an optimized JavaScript validation function, which involves parsing the schema, resolving any $ref references, and generating efficient code. If you call ajv.compile inside a request handler, you pay this compilation cost on every request, which can significantly impact throughput for high-volume APIs.

The correct pattern is to compile schemas once during application startup and store the resulting validate functions in module-level variables or a validation registry. Each call to ajv.compile returns a validate function that is synchronous and stateless and can be called concurrently from multiple requests without any issues. The validate function stores the latest error array in validate.errors after each call, which is overwritten on each subsequent call. If you need to preserve error arrays for logging or debugging after an asynchronous operation, copy the errors array before yielding control.

When an application has many schemas, organize them in a validation module that exports named validate functions. This makes it clear which schemas have been compiled and prevents duplicate compilation. If schemas reference other schemas via $ref, add the referenced schemas to ajv using ajv.addSchema before compiling the referencing schema. Using addSchema rather than compile for shared schemas prevents ajv from compiling the shared schema separately each time it is referenced.

For REST APIs, the validation middleware pattern is efficient and reusable. A middleware factory accepts a schema and returns an Express middleware function that runs the pre-compiled validator. If validation fails, the middleware sends a 400 response with the error details. If validation passes, it calls next. This pattern centralizes validation logic and ensures schemas are compiled once at startup. Combining this with TypeScript types generated from the same JSON Schema, using a tool such as json-schema-to-typescript, creates a single source of truth that enforces consistency between runtime validation and compile-time type checking.