Apologies for the broadness of this issue, which overlaps with many other issues
(see #1195 for perhaps the most up to date history and list of issues). However,
I think it's vital that we agree on some fundamentals before moving forward to
accept means to describe and extend usage of the base specification.

When viewed from the perspective of conformance, there are effectively
three ways to consider expressing additional semantics for the base
specification:

• conformant - Semantics are expressed within the areas of the spec
  explicitly reserved for implementations.

• additive - Semantics are assigned to structural or procedural
  elements that are reserved but not specified.

• breaking - Structural or procedural elements are assigned semantics that
  conflict with the spec.

Each category is discussed below.

Breaking extensions

Although the concept of breaking extensions was considered in 2014-2015, there
has been significant pushback (see #614) against this concept. I believe there's
now fairly unanimous agreement from the editors and the community that creating
a new derivative media type would be preferable to allowing breaking extensions in
the spec.

Additive extensions

Additive extensions would cover allowing additional member(s) in the reserved
areas of the document structure. It's also possible for additive extensions to
dictate how clients and servers should interpret those additional members.

Let's look at a few examples of additive extensions that have been proposed:

• Bulk posting - This extension would allow multiple resources to be created
  in a single request. It would expect that top-level data be passed in as
  an array, and that servers create all resources or none. Created resources
  would be returned in an array.

• Side posting - This extension is being explored in [WIP] Sideposting draft #1197, which
  allows related resources to be created in the included array.

• Additive / subtractive fields - This extension has been proposed in
  Extra Fields #1176, which allows fields to be specified relative to an understanding
  of a default set of fields per type.

• Operations - I'll be proposing this extension in the next several days.
  It will introduce a new operations array that can be used to process
  multiple actions, including fetching and mutating resources, serially and
  transactionally.

We need to be extremely careful when discussing additive extensions. If
additive extensions are not curated by the editors of the spec itself, it is
inevitable that changes to the spec will break additive extensions.

A key requirement for additive extensions is that it would be technically
possible for them to eventually become part of the base spec, even if we choose
to keep them as extensions indefinitely. Therefore, additive extensions can
not express any demands on non-normative areas of the spec, such as meta
values.

To avoid fragmentation in implementations of the spec, we should not introduce
extensions with largely overlapping concerns. We should ensure that any additive
extensions can work together.

The usage of additive extensions must be negotiated, probably through a media
type parameter. For an overview of how media type parameter negotiation might
occur, see this deprecated page on extensions.

Conformant mechanisms

Mechanisms to describe spec structure and usage that fully conform to the spec
are tightly constrained. These constraints free us (the editors and the
community) from concerns about managing different implementations, ensuring the
reasoning behind each is sound, and restricting overlap.

Even within the constraints of the spec, there's still a lot of flexibility
available to implementations. There can be benefits to codifying and sharing
the choices made by implementations.

Although we do not need to be concerned about how Organization A is
using the page parameter, it would be nice if Organization A could share
their methodologies with the broader community so that Organization B might
benefit. And it would be even nicer if tooling were developed that shared these
understandings so that Organization C could benefit without thinking deeply
about the implementation.

This aligns quite well with the concept of a "profile" as described in
RFC 6906:

A media type defines both the semantics and the serialization of a
specific type of content. In many cases, media types have some
built-in extensibility or openness, so that specific instances of the
media type can layer additional semantics on top of the media type's
foundation. In this case, a profile is the appropriate mechanism to
signal that the original semantics and processing model of the media
type still apply, but that an additional processing model can be used
to extract additional semantics.

@ethanresnick has explored these concepts these concepts in detail and has
proposed that these be called "profile extensions", as outlined in
#1195

Ethan's proposal allows profile extensions to be associated with structural
elements in the document. However, I'm also concerned about allowing for
specification of any unreserved areas of the spec, including structural
elements like attributes, relationships, and meta, but also query params like
filter, page, etc. It also seems in keeping with the spirit of a profile to
allow the combination of additional semantics in a single profile - including
both usage and structural expectations.

For instance, let's take the page example above. Imagine developers want to
share a common usage of offset / limit pagination that uses the page
parameter (e.g. /articles?page[offset]=0&page[limit]=10). And they want to
allow servers to specify a page member in the top-level meta with the
total member. It seems beneficial that these concepts could be wrapped
together in a single "profile" or "profile extension", so that
implementations can agree on both structure and usage atomically.

Are there other places better suited for the expression of capabilities? For
instance, we have discussed the "home document" proposal, as described in
https://mnot.github.io/I-D/json-home/ Are there other options we have not yet
considered?

I'm opening this issue to discuss a number of matters:

• Do we agree on the basic classifications above?

• Should negotiation mechanisms differ for additive vs. conformant
  extensions (i.e. "profiles")?

• What are the appropriate boundaries for a profile extension? Should they
  include structure + usage?

• Are there other standards, such as home documents and schemas, that should
  be considered?

• Is consensus strong enough re: additive extensions that we should consider
  focusing on the extension mechanism before anything profile-related?

I'd like to start as simply and conservatively as possible. But we also need to
think wholistically. We should establish a path by which every choice made by a
particular implementation of the spec can be described, standardized, and
shared.

This is a great time to express your questions, concerns, and opinions about
extending the specification.