GSoC 2025: Comprehensive JSON Schema linting for encouraging best practices and catching anti-patterns early

[jviotti]

Brief Description

Writing well-crafted schemas is extremely hard. Not only JSON Schema is a complex schema language and it is easy to shoot yourself in the foot, but as an organisation, we never properly encoded and shared what the best practices and anti-patterns are. As a consequence, our users (including users of API specifications like OpenAPI and AsyncAPI) don't know how to write great schemas, and don't even know what the quality of the schemas they already have is.

I kickstarted some of this work on my open-source tooling (https://github.com/sourcemeta/jsonschema/blob/main/docs/lint.markdown) and would like to take it to the next level.

Expected Outcomes

• Reach agreement on what the anti-patterns and best practices are across dialects, documenting these in the official JSON Schema organisation as a style guide / advice document in the JSON Schema website. In there, we can publish each rule with a stable URL so any linter out there can link to them when reporting failures, etc saving all of us time from actually explaining them in each tool 😅
• Extend popular open-source tooling made by TSC members and endorsed by the org (like the Sourcemeta JSON Schema CLI, but potentially others too) to encode the before-mentioned anti-patterns and best practices in a runnable form

Skills Required

• Strong communication skills, as the first point might involve talking to lots of people in the community and driving discussions to reach agreement.
• A good understanding of JSON Schema, enough to appreciate and understand what the discovered anti-patterns and best practices would be. Of course, we will mentor a lot in this area
• A good understanding of the programming language(s) used in the endorsed open-source linting tooling we will extend. The Sourcemeta JSON Schema CLI is written in C++ (it also has a library form that could be then used by other projects)

Mentors

• @jviotti
• @Relequestual

Expected Difficulty

Medium.

Expected Time Commitment

350 hours. We expect most of the time being spent driving discussions to reach agreement. Doing so often takes a lot of time!

[Honyii]

Great idea Juan, thanks for your submission.

[benjagm]

Hi Juan, have you seen the work done by @gregsdennis here:

https://github.com/json-schema-org/json-schema-linting

[jviotti]

Ah, very nice @benjagm. We should definitely take that as inspiration. Cool stuff. @gregsdennis Is it something you are actively working on?

[gregsdennis]

No. I started some Spectral stuff a year or so ago, but never got beyond a start. Feel free to overwrite what I've done.

[Relequestual]

Adding myself as a mentor as discussed with @jviotti =]

[cbum-dev]

Hi @jviotti and @Relequestual
I’ve been learning JSON Schema from the official docs for the past few weeks and now have a good understanding of it.I’ve also explored various linting methods, including the Sourcemeta JSON Schema Linting Guide and Json Schema Linting, to understand existing approaches.
I’m interested in contributing to this issue for GSoC 2025 if this project gets selected under the guidance of you.
To align with the project's needs, I'd love to get involved in community discussions on various linting methods and best practices. I'm also open to guidance on the most critical anti-patterns to focus on. Looking forward to your thoughts🙂.

[karenetheridge]

Please also see the prior work at

• Linter json-schema-spec#1079
• https://github.com/orgs/json-schema-org/discussions/323
• ..and the other issues linked from those.