Merge pull request #920 from json-api/clarify-relationship-self

ethanresnick · ethanresnick · commit 5a1be64ff325 · 2015-11-23T18:23:38.000-08:00
Clarify relationship self link
diff --git a/_format/1.0/index.md b/_format/1.0/index.md
@@ -252,7 +252,9 @@ A "relationship object" **MUST** contain at least one of the following:
   * `self`: a link for the relationship itself (a "relationship link"). This
     link allows the client to directly manipulate the relationship. For example,
     it would allow a client to remove an `author` from an `article` without
-    deleting the `people` resource itself.
+    deleting the `people` resource itself. When fetched successfully, this link
+    returns the [linkage][resource linkage] for the related resources as its
+    primary data. (See [Fetching Relationships](#fetching-relationships).)
   * `related`: a [related resource link]
 * `data`: [resource linkage]
 * `meta`: a [meta object][meta] that contains non-standard meta-information about the
diff --git a/_format/1.1/index.md b/_format/1.1/index.md
@@ -252,7 +252,9 @@ A "relationship object" **MUST** contain at least one of the following:
   * `self`: a link for the relationship itself (a "relationship link"). This
     link allows the client to directly manipulate the relationship. For example,
     it would allow a client to remove an `author` from an `article` without
-    deleting the `people` resource itself.
+    deleting the `people` resource itself. When fetched successfully, this link
+    returns the [linkage][resource linkage] for the related resources as its
+    primary data. (See [Fetching Relationships](#fetching-relationships).)
   * `related`: a [related resource link]
 * `data`: [resource linkage]
 * `meta`: a [meta object][meta] that contains non-standard meta-information about the
