Separate related resources in a top-level linked object.

dgeb · dgeb · commit 5a7b7a2e0e3d · 2013-11-01T12:47:26.000-04:00
It's important to separate the primary resource from related resources because: * It allows the client to easily identify the primary resource among related resources of the same type. This is especially important when creating a resource without prior knowledge of its server-assigned id. * It clarifies issues like pagination that are specific to the primary resource. This can be achieved by nesting related resources in a `linked` object. For instance: ```javascript { "posts": [{ "id": "1", "name": "Rails is Omakase", "links": { "author": "9", "related": ["2"] } }], "linked": { "posts": [{ "id": "2", "name": "The Parley Letter", "links": { "author": "9", "related": ["1"] } }], "people": [{ "id": "9", "name": "DHH" }] } } ``` It's easy to imagine a scenario in which resources that are members of the primary array are secondary resources for other members of the primary array (e.g. people + friends). In those scenarios, primary resources should not be duplicated as secondary resources in `linked`. In other words, a single canonical representation of a resource should continue to be returned with each response. [Closes #74]
diff --git a/format/index.md b/format/index.md
@@ -24,7 +24,8 @@ attributes section and should not be used as attribute names.
 The top-level of a JSON API document **MAY** have the following keys:
 
 * `meta`: meta-information about a resource, such as pagination
-* Other resource names (`posts`, `comments`, `people`, etc.)
+* `linked`: a collection of documents, grouped by type, that are related to the
+   primary document and/or each other
 
 ### Reserved Attributes
 
@@ -197,7 +198,8 @@ The top-level of a JSON API document **MAY** have the following keys:
 
 * `meta`: meta-information about a resource, such as pagination
 * `links`: URL templates to be used for expanding resources' relationships URLs
-* Other resource names (`posts`, `comments`, `people`, etc.)
+* `linked`: a collection of documents, grouped by type, that are related to the
+   primary document and/or each other
 
 ### Singular Resources
 
@@ -397,7 +399,10 @@ Top-level URL templates allow you to specify relationships as IDs, but without r
 
 To save HTTP requests, it may be convenient to send related documents along with the requested documents.
 
-In this case, a bit of extra metadata for each relationship can link together the documents.
+Related documents **MUST** be included in a top level `"linked"` object, in which they are grouped together in arrays according to their type.
+
+The type of each relationship **MAY** be specified in the `"links"` object with
+the `"type"` key. This facilitates lookups of related documents by the client.
 
 ```javascript
 {
@@ -431,35 +436,42 @@ In this case, a bit of extra metadata for each relationship can link together th
       "comments": [ "6" ]
     }
   }],
-  "author": [{
-    "id": "9",
-    "name": "@d2h"
-  }],
-  "comments": [{
-    "id": "1",
-    "body": "Mmmmmakase"
-  }, {
-    "id": "2",
-    "body": "I prefer unagi"
-  }, {
-    "id": "3",
-    "body": "What's Omakase?"
-  }, {
-    "id": "4",
-    "body": "Parley is a discussion, especially one between enemies"
-  }, {
-    "id": "5",
-    "body": "The parsley letter"
-  }, {
-    "id": "6",
-    "body": "Dependency Injection is Not a Vice"
-  }]
+  "linked": {
+    "people": [{
+      "id": "9",
+      "name": "@d2h"
+    }],
+    "comments": [{
+      "id": "1",
+      "body": "Mmmmmakase"
+    }, {
+      "id": "2",
+      "body": "I prefer unagi"
+    }, {
+      "id": "3",
+      "body": "What's Omakase?"
+    }, {
+      "id": "4",
+      "body": "Parley is a discussion, especially one between enemies"
+    }, {
+      "id": "5",
+      "body": "The parsley letter"
+    }, {
+      "id": "6",
+      "body": "Dependency Injection is Not a Vice"
+    }]
+  }
 }
 ```
 
-The benefit of this approach is that when the same document is referenced multiple times (in this example, the author of the three posts), it only needs to be presented a single time in the document.
+This approach ensures that a single canonical representation of each document
+is returned with each response, even when the same document is referenced
+multiple times (in this example, the author of the three posts). Along these
+lines, if a primary document is linked to another primary or related document,
+it should not be duplicated within the `"linked"` object.
 
-By always combining documents in this way, a client can consistently extract and wire up references.
+By always combining documents in this way, a client can consistently extract and
+wire up references.
 
 JSON API documents **MAY** specify the URL for a document in a compound
 response by specifying a `"href"` key:
