A couple months ago, @gabesullice and I requested feedback regarding the adoption of v1.1-RC1 of the spec, which was first published in December of 2018. You can read the request and responses in this issue, which also includes my analysis.

According to our own rules, we saw insufficient adoption of RC1 to move forward with finalization of v1.1, and we think we understand why. The main feature introduced in v1.1 (as of RC1) was "profiles", which are based on IETF RFC 6906. By design, profiles are limited in scope and can't be used to extend the spec to include new document elements and processing rules. Many developers seem to have chosen to sit out implementing v1.1 and wait for v1.2 to solve more pressing problems that can only be solved through extensions of the spec. And others have attempted to stretch the limits of profiles beyond their defined scope, since profiles represent the only "official" tool offered to customize the spec. Both scenarios are understandable, but not desirable.

Since then, Gabe and I have had our heads down trying to plot a new course for v1.1, and we're now ready to make a proposal to the community.

The gist of our proposal is that we would like to simplify and descope profiles as they're currently defined in v1.1-RC1 AND simultaneously introduce a complementary means to customize the spec: "extensions". While profiles can only specify meaning for members already reserved for users, extensions can only specify meaning for members reserved for the spec itself. Because any members added by extensions will be namespaced, extensions do not block any future expansion of the spec. Rather, most extensions should be viewed as a way to explore just such a future expansion.

The details of our proposal are discussed below, along with a few other significant changes planned for v1.1.

Simplify Profiles

The first part of our proposal is to scale back the complexity of profiles as they're defined in v1.1-RC1. The following simplifications are either planned or underway:

• Change profiles to be purely opt-in by the server to align with RFC 6906. A client may request one or more profiles (via the Accept header), but the server is under no obligation to honor that request in the response. The server can choose which profiles to apply, and should reflect those profiles in the returned Content-Type. The concept of a profile query param will be removed, since it also violated the spirit of RFC 6906. This change has been PR'd.

• Remove the ability for profiles to assign meaning to reserved query params such as filter and page. RFC 6906 states that "A profile MUST NOT change the semantics of the resource representation when processed without profile knowledge, so that clients both with and without knowledge of a profiled resource can safely use the same representation.". Since these params are intended to provide processing instructions, they are inappropriate for profiles.

• Move profile authoring guidelines out of the base spec. We can make recommendations for best practices in a non-normative way.

• Remove guarantees about profile registration and publication on jsonapi.org.

Introduce Extensions

Just as profiles can be negotiated via the profile media type parameter, extensions will be negotiable via the ext media type parameter. Unlike profiles, a server will be required to understand and apply every extension requested via Content-Type and Accept headers, or else respond with an error. In this way, clients can be guaranteed that their requests will be processed according to the base spec plus any extensions they've applied.

Extensions are strictly additive to the base spec, and can never impose rules about members already reserved for users. Any members introduced via extensions MUST be namespaced with a : prefix (e.g. local:id). Namespaces can only be used by extensions. Besides the fact that members are namespaced, most extensions could be merged with the base spec.

Extensions will become the means to define custom processing directions for query params such as filter and page.

Sharing Official and Community Extensions and Profiles

Extensions and profiles are both specified by URI, so we (the spec editors) have no means or desire to control which ones are used by the community.

However, we do feel a responsibility to provide a means to share extensions and profiles on the official site (jsonapi.org) just as we share implementations of the spec.

We plan to be cautious in particular about which extensions are seen as "official". We may choose not to support any community extensions at first on jsonapi.org as we wade into this new territory. Essentially, we have to be cautious about making the spec confusing through an endless array of conflicting extensions.

Since profiles are applied purely to "user space", we don't see the need to be so cautious about publishing community profiles.

First Official Extensions

Two of the longest awaited additions to the spec, Local identifiers and Operations, are proposed as the basis for the spec's first "official extensions". Content from the original PRs has been simplified, refactored, and reopened as new PRs that are compatible with the new extension proposal.

The "Atomic Operations" extension (#1437) will use the namespace atomic to emphasize the atomicity guarantee that motivates the need for operations. Operations will be requested via an atomic:operations member, and results returned as atomic:results.

The "Local Identitities" extension (#1436) will use the namespace local. Local identity members (local:id) can be used to identify resources that have not yet been assigned an id by the server. This fills a gap in the base spec in which resources without IDs assigned can't yet reference themselves in relationships. This extension will also be critical to enable resources in different operations to reference each other without IDs.

Note that neither of these extensions will be part of the base spec nor do they need to be versioned along with it. Care will be taken to allow side-by-side evolution. It's possible that one or both of these extensions will land in the base spec eventually (without namespaces of course).

Links Upgrade

The other change that we'd like to support for v1.1 has been PR'd and refined by Gabe for a while: Upgrade links to RFC8288-modelled web links. This PR should help improve hypermedia support by allowing params to be optionally added to links to convey more information about them.

Summary

All aspects of this proposal are either currently in development or already PR'd. We now want to reach out to the community for feedback and support in helping us reboot v1.1 of the spec ASAP. Please let us know your thoughts!