I am creating this issue to have a place to discuss organizational aspects of spec extensions. Before 1.0, the priority was obviously given to the base spec, but now it seems to be a proper time to start creating the infrastructure for extensions. I am sure that these topics have been discussed by the spec editors privately, and I hope that the rest of us could get some visibility into what is being planned in this regard.

Some humble suggestions of mine are below.

It would be very useful to have a registry of extensions, and it is great that it is being planned. Registered extensions could stay in the forked repositories where they were born. I believe that the discoverability aspect of the registry would encourage people to wrap up their ideas into words. Registered extensions can be discussed in the issue trackers of the forked repos or in the tracker of the upstream repo.

Among registered extensions, some can be awarded status of approved (or whatever it may be called) by the editors based on their perceived value and quality. Since power of the spec is in its implementations, it would be great if major implementations were supporting some common set of extensions. The notion of approved extensions could be a mechanism to communicate to the implementors which extensions the editors see as promising. The implementors could take this into consideration while doing research on which extensions to support. My view is that the popularity of the extensions should not be among criteria to approve them, it should be just a way of the editors to indicate their opinion. Some approved extensions may end up being implemented by only a few libraries and never actually become popular.

Some of approved extensions can later become official, i.e., be pulled into the upstream repo.

I think that implementations should be recommended to report compliance with the base spec and its registered extensions in a human-readable format. The entry for each implementation on the page Implementations should be extended to include a link to a compliance report, maintained and hosted by the implementation. The format of that report should be standardized by the JSON API project. It can be, for example, the following:

• Highest version of JSON API base spec supported:
  • fully: NO
  • partially: 1.2
• The following features of the base spec supported, as defined in the following versions of the base spec:
  • pagination of primary data: 1.0 (offset-based and cursor-based)
  • pagination of relationship data: NO
  • related in relationships: 1.1
  • sparse fieldsets: NO
  • ...
• The following versions of the registered extensions supported:
  • Bulk (bulk): YES
  • Stellar (author/stellar): 1.0

The minimum list of features of the base spec to be reported on should be defined by the JSON API project, the implementation should be free to extend it, and also free to comment on the level/strategy/etc. Reporting on support of registered extensions should be optional (it is assumed here that some of the listed extensions are versioned). It is assumed that these compliance reports are versioned by implementations, and the report for the latest stable version is made available via the link on the page Implementations.

Availability of such standardized data could provide a way for potential users to easily screen implementations without researching their websites and can help increase rate of adoption of the spec. Availability of data on support of extensions could give information which extensions are good candidates to become official or to be rolled into the base spec.

When the number of implementations and extensions grows high, somebody may provide an API and/or webapp to display/search these compliance data.