Based on the discussions of deficiencies compared to GraphQL in #1272 I'm openeing this ticket to discuss the schema support.

This issue has also be raised in the Drupal implementation (https://www.drupal.org/project/jsonapi/issues/2822768) or the Crnk implementation (http://www.crnk.io/releases/stable/documentation/#_meta_module) among likely various others. Goal would be to have a standardized way to specify resources, which in turn would opened up many new possiblities:

• generic UIs to explore JSON API endpoints
• generation of client and server stubs in various programming languages to ease development
• more automated testing
• automation within user interfaces
• ...

what could the specification cover:

• definition of a primitive type system (dates, urls, boolean, string, etc.)
• definition of array types
• definition of complex types composed of attributes having a type
• definition of documents, resources, meta, links, relationship types basedon complex types.
• definition of custom types composed of any other type (primitve, array, complex, etc.)
• set of validation constraints (minimum length, regex pattern, not empty, etc.) that can be attache to types

the schema could be implemented with two formats:

• a low-level schema definition following the JSON:API specification
• a more lightweight/human-readable schema definition in a custom DSL similar to GraphQL and others that can be translated to the JSON:API-conform specification.

The former target automated processing/discovery, while the later is targered towards developers.

how could an implementation look like:

• JSON:API-conform schema resources could be make available JSON:API endpoint next to application-specific resources. This would be signaled to clients as profile (Introduce Profiles to v1.1 #1268)
• the schema definitions can be stored in one or more files with a given file suffix
• a reference implementation is provided to translate a DSL-based schema to a JSON:API-based schema.
• an (extensible) reference implementation translates JSON:API-based schema to client stubs for varous languages.
• reference implementations are made available as command line tools distributed as platform-independent docker images
• (later) a language service would provide syntax highlighting/code completing for IDEs
• the compliance test suite (Compliance test suite #1209) would contribute a schema definition of its own together with pairs of requests/responses to check both client and server implementations.

sources of inspiration for the DSL and JSON:API-based schema:

• graphql
• JSON Schema
• openapi/swagger
• protobuf/gRPC
• https://github.com/crnk-project/crnk-framework/tree/master/crnk-meta/src/main/java/io/crnk/meta/model ( for the JSON:API-base schema, but simpler at various places)

for the first or implementations I could potentially contribute quite a substantial part based on existing crnk code base if that is desired (in an independent/new github repository). I would also have time to work on the topic since it is quite important in my area and we want to avoid home-grown things.

could be targeted for a JSON:API 1.2 release.