Add FAQ re: arrays vs. sets and the need for the linked object

json-api · steveklabnik · Jul 5, 2014 · Apr 27, 2014 · Jun 9, 2014 · Jun 12, 2014
commit f802141050f2b3bf7e03185efc5afc94a7deef9d
diff --git a/faq/index.md b/faq/index.md
@@ -61,4 +61,21 @@ against this schema, that does not necessarily mean it is a valid JSON API
 document. The schema is provided for a base level sanity check.
 
 You can find more information about the JSON Schema format at
-[http://json-schema.org](http://json-schema.org).
+[http://json-schema.org](http://json-schema.org).
+
+### Why are resource collections returned as arrays instead of sets keyed by ID?
+
+A JSON array is naturally ordered while sets require metadata to specify order
+among members. Therefore, arrays allow for more natural sorting by default or
+specified criteria.
+
+In addition, JSON API allows read-only resources to be returned without IDs,
+which would of course be incompatible with a set keyed by IDs.
+
+### Why are related resources nested in a `linked` object in a compound document?
+
+Primary resources should be isolated because their order and number is often
+significant. It's necessary to separate primary and related resources by more
+than type because it's possible that a primary resource may have related
+resources of the same type (e.g. the "parents" of a "person"). Nesting related
+resources in `linked` prevents this possible conflict.