Introduce extensions for v1.1 (json-api#1457)

dgeb · gabesullice · web-flow · commit a20e262cef1b · 2020-02-12T08:35:18.000-07:00
* Amend the client and server content negotiation responsibilities to include the `ext` parameter

* Clarify server responsibilities

* Introduce extension namespacing

* Add namespace example

Co-authored-by: Gabe Sullice &lt;gabriel@sullice.com&gt;
diff --git a/_format/1.1/index.md b/_format/1.1/index.md
@@ -36,10 +36,12 @@ Clients and servers **MUST** send all JSON:API data using this media type in the
 `Content-Type` header.
 
 Further, the JSON:API media type **MUST** always be specified with either no
-media type parameters or with only the `profile` parameter. This applies to both
-the `Content-Type` and `Accept` headers whenever they are present.
+media type parameters, the `ext` parameter, the `profile` parameter or both the
+`ext` and `profile` parameters. This applies to both the `Content-Type` and
+`Accept` headers.
 
-The `profile` parameter is used to support [profiles].
+The `ext` parameter is used to support [extensions] and the `profile` parameter
+is used to support [profiles].
 
 > Note: A media type parameter is an extra piece of information that can
 accompany a media type. For example, in the header
@@ -53,17 +55,24 @@ negotiation and versioning.
 ### <a href="#content-negotiation-clients" id="content-negotiation-clients" class="headerlink"></a> Client Responsibilities
 
 When processing a JSON:API response document, clients **MUST** ignore any
-parameters other than `profile` in the server's `Content-Type` header.
+parameters other than `ext` and `profile` parameters in the server's
+`Content-Type` header.
 
 ### <a href="#content-negotiation-servers" id="content-negotiation-servers" class="headerlink"></a> Server Responsibilities
 
-Servers **MUST** respond with a `415 Unsupported Media Type` status code if
-a request specifies the header `Content-Type: application/vnd.api+json` with
-any media type parameters other than `profile`.
+If a request specifies the `Content-Type` header with the JSON:API media type,
+servers **MUST** respond with a `415 Unsupported Media Type` status code if that
+media type contains any media type parameters other than `ext` or `profile`.
+
+If a request's `Accept` header contains an instance of the JSON:API media type,
+servers **MUST** respond with a `406 Not Acceptable` status code if all
+instances of that media type are modified with a media type parameter other
+than `ext` or `profile`.
 
-Servers **MUST** respond with a `406 Not Acceptable` status code if a request's
-`Accept` header contains the JSON:API media type and all instances of that
-media type are modified with a media type parameter other than `profile`.
+If a request's `Accept` header contains an instance of the JSON:API media type,
+servers **MUST** respond with a `406 Not Acceptable` status code if every
+instance of that media type is modified by the `ext` parameter and each
+contains at least one unsupported extension URI.
 
 ## <a href="#document-structure" id="document-structure" class="headerlink"></a> Document Structure
 
@@ -1900,6 +1909,43 @@ parameter from this specification, it **MUST** return `400 Bad Request`.
 > \[a-z\], JSON:API is reserving the ability to standardize additional query
 > parameters later without conflicting with existing implementations.
 
+## <a href="#extensions" id="extensions" class="headerlink"></a> Extensions
+
+JSON:API supports the use of "extensions" as a way to indicate additional
+semantics that extend the basic semantics described in this specification.
+
+An extension is a separate specification defining these extended semantics.
+
+An exenstion **MAY** impose additional processing rules or further restrictions
+and it **MAY** define new object members as described below.
+
+An extension **MUST NOT** lessen or remove any processing rules, restrictions or
+object member requirements defined in this specification or other extensions.
+
+### <a href="#extension-members" id="extension-members" class="headerlink"></a> Extending Document Structure
+
+An extension **MAY** define new members within the document structure defined by
+this specification. The name of every new member introduced by an extension
+**MUST** be prefixed with an extension namespace followed by a colon (`:`). The
+namespace **MUST** be identical for every member introduced by a particular
+extension.
+
+Namespaces guarantee that extensions will never conflict with the current or
+future versions of this specification.
+
+In the following example, an extension requiring that each request document
+contains a unique request ID has been applied. It uses the namespace `request`
+and adds a top-level object member named `request:id`: 
+
+```
+{
+  "request:id": "some-long-uuid",
+  "data": {
+    "type": "comments",
+  }
+}
+```
+
 ## <a href="#profiles" id="profiles" class="headerlink"></a> Profiles
 
 JSON:API supports the use of "profiles" as a way to indicate additional
@@ -2386,6 +2432,7 @@ request as equivalent to one in which the square brackets were percent-encoded.
 [link object]: #document-links-link-object
 [link relation type]: #document-links-link-relation-type
 [link parameters]: #document-links-link-parameters
+[extensions]: #extensions
 [profiles]: #profiles
 [timestamps profile]: #profiles-timestamp-profile
 [profile keywords]: #profile-keywords
