JSON Schema validator error messages are often difficult to interpret, especially when working with complex or poorly structured schemas. This package consumes the standard error output produced by JSON Schema validators and converts it into clear, human-friendly messages, making it easier for users to understand validation failures and how to fix them.
This module is designed for node.js (ES Modules, TypeScript) and browsers. It should work in Bun and Deno as well, but the test runner doesn't work in these environments, so this module may be less stable in those environments.
npm install @hyperjump/json-schema-errors
@hyperjump/json-schema-errors works with any JSON Schema validator that
follows the official JSON Schema Output
Format.
In this example, we’ll showcase it with the
@hyperjump/json-schema validator.
@hyperjump/json-schema-errors uses the output from the validator, the
schema(s) used to validate the JSON instance, and the JSON instance to build its
results. Because it uses the schema, even if you didn't do your validation with
@hyperjump/json-schema, you still need to register your schemas with that
package in order for this package to do its job.
import { registerSchema, validate } from "@hyperjump/json-schema/draft-2020-12";
import { BASIC } from "@hyperjump/json-schema/experimental";
import { jsonSchemaErrors } from "@hyperjump/json-schema-errors";
const schemaUri = "https://example.com/schema/string";
registerSchema({
$schema: "https://json-schema.org/draft/2020-12/schema",
type: "string"
});
const instance = 42;
const output = await validate(schemaUri, instance, BASIC);
const errors = await jsonSchemaErrors(output, schemaUri, instance);
console.log(errors);
// [
// {
// message: "Expected a string",
// instanceLocation: "#",
// schemaLocations: ["https://example.com/main#/type"]
// }
// ]
If using this package with the results from another validator, you still need to
register the schema. Here's an example using @cfworker/json-schema.
import { jsonSchemaErrors } from "@hyperjump/json-schema-errors";
import { registerSchema } from "@hyperjump/json-schema/draft-2020-12";
import { Validator } from "@cfworker/json-schema";
import type { Schema } from "@cfworker/json-schema";
const schemaUri = "https://example.com/main";
const schema: Schema = {
$schema: "https://json-schema.org/draft/2020-12/schema",
type: "string"
};
const validator = new Validator(schema);
const instance = 42;
const output = validator.validate(instance);
registerSchema(schema, schemaUri);
const errors = await jsonSchemaErrors(output, schemaUri, instance);
console.log(errors);
// [
// {
// message: "Expected a string",
// instanceLocation: "#",
// schemaLocations: ["https://example.com/main#/type"]
// }
// ]
https://json-schema-errors.hyperjump.io
@hyperjump/json-schema-errors uses a two phase process. In order to support a
custom keyword we'll need to register a handler for each phase of the process.
Normalization: This phase takes the raw error output from the validator
and converts it to a NormalizedOutput.
Error Handling: This phase takes the NormalizedOutput and uses it to
generate the error messages that will be presented to the user.
Here's an example of adding support for a simple keyword called startsWith.
startsWith takes a string and asserts that a string JSON instance starts with
the value of startsWith.
import { setNormalizationHandler, addErrorHandler } from "@hyperjump/json-schema-errors";
import { getSchema } from "@hyperjump/json-schema/experimental";
import * as Schema from "@hyperjump/browser";
import * as Instance from "@hyperjump/json-schema/instance/experimental";
import type { ErrorObject } from "@hyperjump/json-schema-errors";
const KEYWORD_URI = "https://example.com/keyword/startsWith";
setNormalizationHandler(KEYWORD_URI, {
evalute() {
// Only applicator keywords need to return a value
}
});
addErrorHandler(async (normalizedErrors, instance, localization) => {
const errors: ErrorObject = [];
for (const schemaLocation in normalizedErrors[KEYWORD_URI]) {
if (normalizedErrors[KEYWORD_URI][schemaLocation]) {
continue;
}
const keyword = await getSchema(schemaLocation);
const startsWith = Schema.value(keyword) as string;
errors.push({
message: "Expected a string that starts with '${startsWith}'",
instanceLocation: Instance.uri(instance),
schemaLocations: [schemaLocation]
});
}
return errors;
});
Simple applicator keywords that just evaluate subschemas and don't make any
assertions of their own don't need an error handler, only a normalization
handler. For example, support for the allOf keyword could look like the
following.
import { setNormalizationHandler, evaluateSchema } from "@hyperjump/json-schema-errors";
const KEYWORD_URI = "https://json-schema.org/keyword/allOf";
setNormalizationHandler(KEYWORD_URI, {
evaluate(allOf, instance, context) {
return allOf.map((schemaLocation) => evaluateSchema(schemaLocation, instance, context));
},
simpleApplicator: true
});
See the anyOf or oneOf normalization and error handlers for an example of
implementing an applicator that also asserts.
This package has some unique features to help focus error messaging to be more helpful. In this section we list some examples showing those features.
Contributions are welcome! Please create an issue to propose and discuss any changes you'd like to make before implementing it. If it's an obvious bug with an obvious solution or something simple like a fixing a typo, creating an issue isn't required. You can just send a PR without creating an issue. Before submitting any code, please remember to run all of the following scripts.