Make JSON Schema mandatory for extensions

[jugaadi]

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?

[jelhan]

Thanks a lot for writing down this proposal in such a structured way. There is a lot to explore and define regarding governance if extensions (and profiles). Thanks a lot for getting this discussion started!

To be honest I don't understand the motivation fully.

I share your concern that not all extension and profiles will be well written and maintained. It's the responsibility of the implementor to review every extension and profile before implementing. And reject implementation requests of extension is not well defined or maintained.

I don't see how requiring a JSON Schema instead of a written specification would address that issue. A JSON Schema could be wrong or missing as well. A maintainer might introduce breaking changes without approperiate versioning to an extension defined as JSON Schema as well.

it would be better if the author can define the extension in the form of a specification.

Extensions and profiles are specification. A specification could be given in different formats. I think there are good arguments to use the same or a similar form as used by base specification itself. E.g. using key words defined in BCP 14 as well. Currently the JSON:API keeps it up to the author to decide how to specify an extension or profile. I like that as it allows experiments like using JSON Schema only.

[jugaadi]

To be honest I don't understand the motivation fully.

When an extension author adds specification semantics, it requires the adopters to interpret the changes and handle it manually in their systems. However, such a specification is not reliable as is evident from the number of issues wrt v1.0. Using a constraint language like JSON Schema would enable the extension author to be more precise with the specification semantics. And now would be a good time to enforce it since we're formalising extensions in v1.1 . An extension author would find it relatively easy to write such a schema for the below reasons:

1. Trivial extension to v1.1 JSON Schema spec since it already covers the base components.
2. Take advantage of the vast JSON Schema ecosystem to write proper schemas.

This proposal however, does not in any way stop the extension author from defining a regular specification using BCP14 or any other format. It must be there since the scope of extension goes beyond keywords.

However, the above proposal is to do the following:

1. Define a formal path to access it ** if available **.
2. Make it mandatory in case the extension is introducing structural changes like new keywords.

Such a schema could be used by the implementors in the following ways:

1. Validate request/response data.
2. Generate Client/Server Code.
3. Use it to define their APIs.

Example: If the atomic operation was available in the form of json-schema, we can use that directly in our API and make use of validators like ajv to validate incoming request.