{"id":37424210,"url":"https://github.com/hyperjump-io/json-schema-errors","last_synced_at":"2026-04-29T13:35:19.931Z","repository":{"id":293516428,"uuid":"984278130","full_name":"hyperjump-io/json-schema-errors","owner":"hyperjump-io","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-20T19:19:11.000Z","size":386,"stargazers_count":11,"open_issues_count":7,"forks_count":14,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-04-20T21:20:22.860Z","etag":null,"topics":["json-schema"],"latest_commit_sha":null,"homepage":"http://json-schema-errors.hyperjump.io/","language":"JavaScript","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/hyperjump-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["hyperjump-io"]}},"created_at":"2025-05-15T17:09:12.000Z","updated_at":"2026-04-20T19:19:08.000Z","dependencies_parsed_at":"2025-05-15T18:46:49.647Z","dependency_job_id":"b82b8966-2d0b-49e9-bfa7-090be521da85","html_url":"https://github.com/hyperjump-io/json-schema-errors","commit_stats":null,"previous_names":["jdesrosiers/better-json-schema-errors","hyperjump-io/json-schema-errors"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hyperjump-io/json-schema-errors","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperjump-io%2Fjson-schema-errors","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperjump-io%2Fjson-schema-errors/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperjump-io%2Fjson-schema-errors/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperjump-io%2Fjson-schema-errors/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperjump-io","download_url":"https://codeload.github.com/hyperjump-io/json-schema-errors/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperjump-io%2Fjson-schema-errors/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32427791,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T13:34:34.882Z","status":"ssl_error","status_checked_at":"2026-04-29T13:34:29.830Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["json-schema"],"created_at":"2026-01-16T06:11:05.028Z","updated_at":"2026-04-29T13:35:19.919Z","avatar_url":"https://github.com/hyperjump-io.png","language":"JavaScript","funding_links":["https://github.com/sponsors/hyperjump-io"],"categories":[],"sub_categories":[],"readme":"# Hyperjump - JSON Schema Errors\n\nJSON Schema validator error messages are often difficult to interpret,\nespecially when working with complex or poorly structured schemas. This package\nconsumes the standard error output produced by JSON Schema validators and\nconverts it into clear, human-friendly messages, making it easier for users to\nunderstand validation failures and how to fix them.\n\n## Installation\n\nThis module is designed for node.js (ES Modules, TypeScript) and browsers. It\nshould work in Bun and Deno as well, but the test runner doesn't work in these\nenvironments, so this module may be less stable in those environments.\n\n```bash\nnpm install @hyperjump/json-schema-errors\n```\n\n## Usage\n\n`@hyperjump/json-schema-errors` works with any JSON Schema validator that\nfollows the official [JSON Schema Output\nFormat](https://json-schema.org/draft/2020-12/json-schema-core#name-output-structure).\nIn this example, we’ll showcase it with the\n[@hyperjump/json-schema](https://github.com/hyperjump-io/json-schema) validator.\n\n`@hyperjump/json-schema-errors` uses the output from the validator, the\nschema(s) used to validate the JSON instance, and the JSON instance to build its\nresults. Because it uses the schema, even if you didn't do your validation with\n`@hyperjump/json-schema`, you still need to register your schemas with that\npackage in order for this package to do its job.\n\n```TypeScript\nimport { registerSchema, validate } from \"@hyperjump/json-schema/draft-2020-12\";\nimport { BASIC } from \"@hyperjump/json-schema/experimental\";\nimport { jsonSchemaErrors } from \"@hyperjump/json-schema-errors\";\n\nconst schemaUri = \"https://example.com/schema/string\";\nregisterSchema({\n  $schema: \"https://json-schema.org/draft/2020-12/schema\",\n\n  type: \"string\"\n});\n\nconst instance = 42;\nconst output = await validate(schemaUri, instance, BASIC);\nconst errors = await jsonSchemaErrors(output, schemaUri, instance);\nconsole.log(errors);\n// [\n//   {\n//     message: \"Expected a string\",\n//     instanceLocation: \"#\",\n//     schemaLocations: [\"https://example.com/main#/type\"]\n//   }\n// ]\n```\n\nIf using this package with the results from another validator, you still need to\nregister the schema. Here's an example using `@cfworker/json-schema`.\n\n```TypeScript\nimport { jsonSchemaErrors } from \"@hyperjump/json-schema-errors\";\nimport { registerSchema } from \"@hyperjump/json-schema/draft-2020-12\";\nimport { Validator } from \"@cfworker/json-schema\";\nimport type { Schema } from \"@cfworker/json-schema\";\n\nconst schemaUri = \"https://example.com/main\";\n\nconst schema: Schema = {\n  $schema: \"https://json-schema.org/draft/2020-12/schema\",\n  type: \"string\"\n};\nconst validator = new Validator(schema);\n\nconst instance = 42;\nconst output = validator.validate(instance);\n\nregisterSchema(schema, schemaUri);\nconst errors = await jsonSchemaErrors(output, schemaUri, instance);\nconsole.log(errors);\n// [\n//   {\n//     message: \"Expected a string\",\n//     instanceLocation: \"#\",\n//     schemaLocations: [\"https://example.com/main#/type\"]\n//   }\n// ]\n```\n\n## API\n\nhttps://json-schema-errors.hyperjump.io\n\n## Custom Keywords and Error Handlers\n\n`@hyperjump/json-schema-errors` uses a two phase process. In order to support a\ncustom keyword we'll need to register a handler for each phase of the process.\n\n1. **Normalization**: This phase takes the raw error output from the validator\n   and converts it to a `NormalizedOutput`.\n\n2. **Error Handling**: This phase takes the `NormalizedOutput` and uses it to\n   generate the error messages that will be presented to the user.\n\nHere's an example of adding support for a simple keyword called `startsWith`.\n`startsWith` takes a string and asserts that a string JSON instance starts with\nthe value of `startsWith`.\n\n```TypeScript\nimport { setNormalizationHandler, addErrorHandler } from \"@hyperjump/json-schema-errors\";\nimport { getSchema } from \"@hyperjump/json-schema/experimental\";\nimport * as Schema from \"@hyperjump/browser\";\nimport * as Instance from \"@hyperjump/json-schema/instance/experimental\";\nimport type { ErrorObject } from \"@hyperjump/json-schema-errors\";\n\nconst KEYWORD_URI = \"https://example.com/keyword/startsWith\";\n\nsetNormalizationHandler(KEYWORD_URI, {\n  evalute() {\n    // Only applicator keywords need to return a value\n  }\n});\n\naddErrorHandler(async (normalizedErrors, instance, localization) =\u003e {\n  const errors: ErrorObject = [];\n\n  for (const schemaLocation in normalizedErrors[KEYWORD_URI]) {\n    if (normalizedErrors[KEYWORD_URI][schemaLocation]) {\n      continue;\n    }\n\n    const keyword = await getSchema(schemaLocation);\n    const startsWith = Schema.value(keyword) as string;\n\n    errors.push({\n      message: \"Expected a string that starts with '${startsWith}'\",\n      instanceLocation: Instance.uri(instance),\n      schemaLocations: [schemaLocation]\n    });\n  }\n\n  return errors;\n});\n```\n\nSimple applicator keywords that just evaluate subschemas and don't make any\nassertions of their own don't need an error handler, only a normalization\nhandler. For example, support for the `allOf` keyword could look like the\nfollowing.\n\n```TypeScript\nimport { setNormalizationHandler, evaluateSchema } from \"@hyperjump/json-schema-errors\";\n\nconst KEYWORD_URI = \"https://json-schema.org/keyword/allOf\";\n\nsetNormalizationHandler(KEYWORD_URI, {\n  evaluate(allOf, instance, context) {\n    return allOf.map((schemaLocation) =\u003e evaluateSchema(schemaLocation, instance, context));\n  },\n  simpleApplicator: true\n});\n```\n\nSee the `anyOf` or `oneOf` normalization and error handlers for an example of\nimplementing an applicator that also asserts.\n\n## Examples\n\nThis package has some unique features to help focus error messaging to be more\nhelpful. In this section we list some examples showing those features.\n\n## Contributing\n\nContributions are welcome! Please create an issue to propose and discuss any\nchanges you'd like to make before implementing it. If it's an obvious bug with\nan obvious solution or something simple like a fixing a typo, creating an issue\nisn't required. You can just send a PR without creating an issue. Before\nsubmitting any code, please remember to run all of the following scripts.\n\n- npm test (Tests can also be run continuously using npm test -- --watch)\n- npm run lint\n- npm run type-check\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperjump-io%2Fjson-schema-errors","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperjump-io%2Fjson-schema-errors","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperjump-io%2Fjson-schema-errors/lists"}