GSoC 2025: Better JSON Schema Errors

[jdesrosiers]

Create a JavaScript library to convert standard JSON Schema output into clear, human-friendly error messages. The library should follow the examples set by existing tools like Atlassian's better-ajv-errors and Apideck's @apideck/better-ajv-errors, but use the standard JSON Schema output format introduced in draft-2019-09 instead of ajv's proprietary format.

Expected Outcomes

• A library that transforms standard JSON Schema validation outputs into concise, easy-to-understand error messages.
• A mechanism for loading and managing additional language packs to support presenting error messages in multiple languages.
• Customization options for users to override default error messages or add custom ones.
• Tested for compatibility with multiple implementations using the standard output format, including @hyperjump/json-schema.
• Published on npm with proper versioning, a clear README, and example use cases.

Skills Required

• JavaScript: Strong understanding of JavaScript and best practices for building libraries.
• JSON Schema Specification: Familiarity with the JSON Schema standard, particularly the error output format introduced in draft-2019-09.
• Error Message Design: Ability to translate structured error output into concise and meaningful human-friendly messages.
• Library Development: Experience creating, testing, and documenting JavaScript libraries.
• Open Source Practices: Understanding of Git, GitHub, and how to maintain a project for open source contributions.
• Testing: Familiarity with Test-Driven Development (TDD) or Behavior-Driven Development (BDD) methodologies.
• Collaboration: Comfortable using pair programming tools like VSCode LiveShare and participating in pair programming sessions for real-time collaboration.

Mentor(s)

• @jdesrosiers

Expected Difficulty

Medium

Expected Time Commitment

175 hours

[jviotti]

I'm very interested in the outcome of this to improve my own validator. Let me know if I can help in any way

[heysujal]

Thanks @jdesrosiers for this idea.
I am interested to work on this idea in the upcoming GSoC event, if this gets accepted.
I have never built a JavaScript library before, so I am not aware about the best practices just yet but I have strong understanding of JavaScript. I have also got the Open Source Practices and Collaboration part covered. I will be needing to work on Testing, Library Development and familiarising myself more with JSONSchema part.

To gain more understanding of JSONSchema standard, I am going through the docs.
I am excited to get a chance to work on this one. Would you like to any guidance/resources to prepare for this project idea?

[jdesrosiers]

Thanks for your interest @heysujal. IMO, there's no better way to get familiar with JSON Schema than to write a bunch of schemas. I suggest picking some domain and write some schemas to model it. It just needs to be complex enough to explore past the basics.

[Julian]

(This is obviously a really good idea -- I want/wanted at some point soon to have Bowtie collect and compare error messages from implementations, so definitely keen to see where this goes).

[gregsdennis]

I'd like to see the rules generalized somehow so that non-JS implementations can also be made.

Also worth mentioning the challenges described in my blog post around the ambiguity of determining a "right" error.

[jdesrosiers]

I'd like to see the rules generalized somehow so that non-JS implementations can also be made.

That would be nice. However, I don't think the "rules" used by this project are necessarily the rules everyone would want to use. How you present an error doesn't have any one correct answer. For example, of the two libraries I linked, one is optimized for CLIs and the other is optimized for APIs. We can certainly make a test suite in JSON like our validation test suite, but that's probably not what's needed. In any case, the test suite would be a comprehensive set of examples that could be used as a reference for others making similar tools. They can use the test cases to make sure their implementation covers the same situations nicely even if they choose to handle them differently.