Description
Limitations of the current implementation lists have been raised in several GitHub issues.
The problems raised could be summarized as:
- Hard to identify implementations, which are actively maintained and have seen major adoption.
- Many implementations haven't seen active development for a long-time.
- Need to look into documentation for each of them to identify supported features.
Enriching implementation list with additional data in a machine-readable way has been discussed as a solution. This would allow to sort and filter the list in a meaningful way.
Additional data could be grouped in two categories:
- Data, which must be provided and updated manually.
- Data, which could be derived automatically.
One example for the latter are:
- Date of last release,
- GitHub stars,
- Number of downloads in last week / last month / last year
I think we should focus discussion on the data, which needs to be added manually. That one is causing relevant maintenance costs. Especially to keep it up-to-date. We should try to gather as much data automatically as possible. And we should evaluate carefully for every data maintained manually if it's worth the effort.
I think we need the following data to be maintained manually.
- name
- description
- package manager
- package name
- type (client-side, server-side, both)
- programming language
- features
- parsing JSON:API documents
- generating JSON:API documents
- compound documents
- routing (for client-side frameworks: use provided links; for server-side frameworks: register links for collections, single object, relationships and related resources)
- self links
- relationship links
- pagination
- sorting
- filtering
- validation
- extensions
- profiles
For features potential value could be either:
- supported
- partly supported
- not supported
- unknown
Having unknown as an explicit state will ease migration and adding additional features to the list later.
I hope that we can collect other data automatically using information about package manager and package name. But we need to double check if that's true for all package registries. Especially if we can derive GitHub repository from package registry.
I have good experience using YAML as authoring format and JSON schema to validate the data. YAML makes it easy for everyone to edit using GitHub Web editor. JSON schema - especially if using enums - helps to enforce consistent spelling and avoid issues like having JavaScript and Javascript.