Motivation

Since extensions URI are primarily used for identification purpose, there is no guarantee that extension authors may even provide a documentation. In such cases, it would be difficult for implementors to support extensions. And even if a documentation is provided, it is left to the implementor to interpret the document correctly. Moreover, the extension author may even change the documentation without communicating it with the implementors. To avoid such scenarios, it would be better if the author can define the extension in the form of a specification.

Design

Since extensions provide a means to “extend” the base specification by defining additional specification semantics, they can neither alter or remove existing specification semantics, nor can they specify implementation semantics. This means that any extension introducing new members or query params, can safely use a JSON Schema to define their changes especially since JSON Schema is being published for v1.1 . Moreover, the extension schema definition can be easily verified for compatibility with the base specification.

Retrieval

The extension author must support the jsonschema media-type i.e application/schema+json for the extension url.
Example:

For the following extension:

Content-Type: application/vnd.api+json; ext="https://jsonapi.org/ext/version"

The below given request should be Success and give the schema as response.

curl --header "Accept: application/schema+json" "https://jsonapi.org/ext/version"

For those extensions that are limited to just the processing rules(or restrictions), the response can return the primary documentation with the respective content-type.

Schema Definition

Since an extension can define additional parameters or modify existing query parameters in addition to introducing new document members, it is important to ensure that the schema covers all the three components i.e query parameters, request body definition and response body definition in a single schema document.

Changes in Spec

1. Section: https://jsonapi.org/format/1.1/#media-type-parameter-rules

Visiting an extension’s or a profile’s URI SHOULD return documentation that describes its usage.

2. Section: https://jsonapi.org/format/1.1/#extension-rules3.

An extension MAY impose additional processing rules or further restrictions and it MAY define new object members as described below.

When an extension defines new query parameters or document members, ...

PS: Due to English being my second language and the proposal still being in discussion stage, Im not suggesting any changes to the RFC.

Drawbacks

This design is limited to extensions introducing changes to the payload/params structure alone. Any changes in processing rules or restrictions cannot be defined using JSON Schema.

Alternatives

The author can provide the schema URL in the documentation if needed. However, this would impose an additional tax on the implementors on assuming that the structure is not changed.

Unresolved Questions

1. Should schema use the extension URL as $id?
2. Is there a better way to handle structure versioning other than url?