What is the current maintenance status of the JSON:API spec?
Version 1.1 was long awaited and landed September 2022. With the addition of profiles and extensions, future adjustments to the spec are less likely to be dramatic in nature. That said, there’s still organizational work to be done, e.g. with regards a valid JSON Schema for both 1.0 and 1.1.
The PR for publishing an updated 1.0-compatible schema broke the well-known URL at https://jsonapi.org/schema and the new schema isn’t available on jsonapi.org at all, only in the codebase.
I don’t point this out to nitpick - open-source software is a huge maintenance burden. It’s not entirely clear who the current list of maintainers are, and it would be nice to have some idea of the governance structure for the project so issues like this can be addressed. We should be able to celebrate maintainers who have less bandwidth now as opposed to in the past, and still have a sustainable path forward.
@jelhan it seems you’ve been most active lately, do you have any thoughts on this? I am happy to help as I can. I am working on Drupal’s new schema-generation feature set and it would be great to highlight JSON:API’s schema compatibility as a part of that.
To summarize, thank you to all the maintainers who have gotten us to this point. What’s next for the project?
The JSON:API specification is actively maintained and improved from my side. Even though other editors do not have much capacities at the moment. I hope that we can see further improvements. Building up an ecosystem of profiles and extensions is the most important step forward in my perspective.
Personally I struggle with the JSON Schema. It’s a complex topic for a specification like this. The existing schema was never production ready looking at the list of issues reported with it. I’m not an expert on JSON Schema. Especially not on maintaining a base schema, which is inherited by many projects.
I tend moving out the JSON Schema to another repository and maintaining it independently from the specification. This would allow us handing it over to members of the community with more knowledge and time to work on it as well. But I need to align with @dgeb and other editors on that thoughts first.
Your delineation between the spec itself and the JSON Schema which describes it is a useful one. Right now they are in a monorepo and any changes to the schema require a maintainer sign-off, and as you indicate it may not be an area of expertise for them.
While the prior published JSON Schema was not particularly complete, the recently-merged PR improves this significantly and provides test coverage as well. Unfortunately, it’s not publicly-available (outside of linking directly to the repo) and broke the schema at the well-known URL that matches the schema ID.
If I could propose some steps forward:
Create and merge a PR relatively soon to make the schema from PR 1600 available at jsonapi.org and serve it from https://jsonapi.org/schema. Even if it may not be perfect (I’m not aware of any bugs in it currently, though) it’s way better than what was there prior and fixes schema validation for end-users.
Create a new repo under the json-api organization for managing and publishing the schema. As for jsonapi.org, I think that would mean the domain would need to be served through a reverse-proxy rather than GitHub pages directly, since we would need to send schema requests to one repo and spec/general website requests to the other. This is easy enough to do but would require some sort of infrastructure sponsorship (similar to the Discourse server, I’m guessing… and I am also happy to help with this if need be.)
Publish the 1.1 JSON Schema via the new repo (and presumably with maintainers who can move that along under its own governance and review process.)
Obviously, I have a near-term vested interest in at least fixing the public schema availability, but the other action items would be great to do “soon,” as well.
Thanks again, looking forward to your and others’ feedback.