Introduce Local IDs, or lids, to v1.1

dgeb · dgeb · commit c7c70427c807 · 2020-04-02T10:28:51.000-04:00
A client may include a "local ID" as a `lid` member in a resource object to
uniquely identify the resource within the request document. Every representation
of that resource, whether as a resource object or resource identifier object,
must then include the matching `lid` member and value.

This addition paves the way for requests of all kinds that may need to establish
linkage between resources that have not yet been assigned a server-generated ID.
diff --git a/_format/1.1/index.md b/_format/1.1/index.md
@@ -191,8 +191,10 @@ A resource object **MUST** contain at least the following top-level members:
 * `id`
 * `type`
 
-Exception: The `id` member is not required when the resource object originates at
-the client and represents a new resource to be created on the server.
+Exception: The `id` member is not required when the resource object originates
+at the client and represents a new resource to be created on the server. In that
+case, a client **MAY** include a `lid` member to uniquely identify each resource
+within the document.
 
 In addition, a resource object **MAY** contain any of these top-level members:
 
@@ -228,8 +230,17 @@ Here's how an article (i.e. a resource of type "articles") might appear in a doc
 
 #### <a href="#document-resource-object-identification" id="document-resource-object-identification" class="headerlink"></a> Identification
 
-Every [resource object][resource objects] **MUST** contain an `id` member and a `type` member.
-The values of the `id` and `type` members **MUST** be strings.
+As noted above, every [resource object][resource objects] **MUST** contain a
+`type` member. Every resource object **MUST** also contain an `id` member,
+except when the resource object originates at the client and represents a new
+resource to be created on the server. If `id` is omitted due to this exception,
+a `lid` member **MAY** be included that uniquely identifies the resource
+_locally_ within the document. The value of the `lid` member **MUST** be
+identical for every representation of the resource in the document, including
+other resource objects and [resource identifier objects][resource identifier
+object]. The values of `lid` members **MUST** be unique across resource types.
+
+The values of the `id`, `type`, and `lid` members **MUST** be strings.
 
 Within a given API, each resource object's `type` and `id` pair **MUST**
 identify a single, unique resource. (The set of URIs controlled by a server,
@@ -400,7 +411,13 @@ response that includes the resource as the primary data.
 A "resource identifier object" is an object that identifies an individual
 resource.
 
-A "resource identifier object" **MUST** contain `type` and `id` members.
+A "resource identifier object" **MUST** contain `type` and `id` members, except
+when it represents a new resource to be created on the server. In this case, a
+`lid` member **MUST** be included and `type` **MAY** be included. As discussed
+above, the value of the `lid` member **MUST** be identical for every
+representation of the resource in the document.
+
+The values of the `id`, `type`, and `lid` members **MUST** be strings.
 
 A "resource identifier object" **MAY** also include a `meta` member, whose value is a [meta] object that
 contains non-standard meta-information.
@@ -510,6 +527,10 @@ each `type` and `id` pair.
 composite key that uniquely references [resource objects] in another part of
 the document.
 
+> Note: For resources that do not contain an `id` member but do contain a `lid`,
+the `lid` is sufficient to establish resource identity and thus linkage between
+resource objects and resource identifier objects throughout the document.
+
 > Note: This approach ensures that a single canonical [resource object][resource objects] is
 returned with each response, even when the same resource is referenced
 multiple times.
