chore: refactor relationships guide (#9071)

guides/index.md

@@ -0,0 +1,4 @@
+# Guides
+
+- [Relationships](./relationships/index.md)
+- [Terminology](./terminology.md)

guides/relationships/configuration/0-one-to-none.md

@@ -1,7 +1,7 @@
 # One To None Relationships
 
 - Next → [One To One Relationships](./1-one-to-one.md)
-- ⮐ Go Back [Relationships Guide](../../relationships.md)
+- ⮐ Go Back [Relationships Guide](../index.md)
 
 ---
 
@@ -169,4 +169,4 @@ export default class TrailRunner {
 ---
 
 - Next → [One To One Relationships](./1-one-to-one.md)
-- ⮐ [Relationships Guide](../../relationships.md)
+- ⮐ [Relationships Guide](../index.md)

guides/relationships/configuration/1-one-to-one.md

@@ -2,7 +2,7 @@
 
 - Previous ← [One To None Relationships](./0-one-to-none.md)
 - Next → [One To Many Relationships](./2-one-to-many.md)
-- ⮐ [Relationships Guide](../../relationships.md)
+- ⮐ [Relationships Guide](../index.md)
 
 ---
 
@@ -240,4 +240,4 @@ export class TrailRunner {
 
 - Previous ← [One To None Relationships](./0-one-to-none.md)
 - Next → [One To Many Relationships](./2-one-to-many.md)
-- ⮐ [Relationships Guide](../../relationships.md)
+- ⮐ [Relationships Guide](../index.md)

guides/relationships/configuration/2-one-to-many.md

@@ -2,7 +2,7 @@
 
 - Previous ← [One To One Relationships](./1-one-to-one.md)
 - Next → [Many To None Relationships](./3-many-to-none.md)
-- ⮐ [Relationships Guide](../../relationships.md)
+- ⮐ [Relationships Guide](../index.md)
 
 ---
 
@@ -243,4 +243,4 @@ export class TrailRunner {
 
 - Previous ← [One To One Relationships](./1-one-to-one.md)
 - Next → [Many To None Relationships](./3-many-to-none.md)
-- ⮐ [Relationships Guide](../../relationships.md)
+- ⮐ [Relationships Guide](../index.md)

guides/relationships/configuration/3-many-to-none.md

@@ -2,7 +2,7 @@
 
 - Previous ← [One To Many Relationships](./2-one-to-many.md)
 - Next → [Many To One Relationships](./4-many-to-one.md)
-- ⮐ [Relationships Guide](../../relationships.md)
+- ⮐ [Relationships Guide](../index.md)
 
 ---
 
@@ -168,4 +168,4 @@ export class ActivityData extends Model {
 
 - Previous ← [One To Many Relationships](./2-one-to-many.md)
 - Next → [Many To One Relationships](./4-many-to-one.md)
-- ⮐ [Relationships Guide](../../relationships.md)
+- ⮐ [Relationships Guide](../index.md)

guides/relationships/configuration/4-many-to-one.md

@@ -2,7 +2,7 @@
 
 - Previous ← [Many To None Relationships](./3-many-to-none.md)
 - Next → [Many To Many Relationships](./5-many-to-many.md)
-- ⮐ [Relationships Guide](../../relationships.md)
+- ⮐ [Relationships Guide](../index.md)
 
 ---
 

guides/relationships/configuration/5-many-to-many.md

@@ -1,7 +1,7 @@
 # Many To Many Relationships
 
 - Previous ← [Many To One Relationships](./4-one-to-many.md)
-- ⮐ [Relationships Guide](../../relationships.md)
+- ⮐ [Relationships Guide](../index.md)
 
 ---
 
@@ -221,4 +221,4 @@ export class TrailRunner {
 ---
 
 - Previous ← [Many To One Relationships](./4-one-to-many.md)
-- ⮐ [Relationships Guide](../../relationships.md)
+- ⮐ [Relationships Guide](../index.md)

guides/relationships/features/inverses.md

@@ -1,6 +1,6 @@
 # Relationship Inverses
 
-- ⮐ [Relationships Guide](../../relationships.md)
+- ⮐ [Relationships Guide](../index.md)
 
 ---
 

guides/relationships/index.md

@@ -0,0 +1,38 @@
+# Relationships Guide
+
+## Feature Overview
+- [Inverses](./features/inverses.md)
+<!--
+- [Resource Relationships]()
+- [Collection Relationships]()
+- [Polymorphism]()
+- [Links vs Identifiers]()
+- [Sync vs Async]()
+-->
+
+## Configuration
+- [1:none](./configuration/0-one-to-none.md) (One To None)
+- [1:1](./configuration/1-one-to-one.md) (One To One)
+- [1:Many](./configuration/2-one-to-many.md) (One To Many)
+- [Many:None](./configuration/3-many-to-none.md) (Many To None)
+- [Many:1](./configuration/4-many-to-one.md) (Many To One)
+- [Many:Many](./configuration/5-many-to-many.md) (Many To Many)
+
+<!--
+## Mutating Relationships
+- [Adding/Removing]()
+- [Saving]()
+- [Saving Multiple Related Records At Once]()
+- [Sorting & Filtering]()
+
+## Advanced
+- [Understanding "the Graph"]()
+- [Pagination]()
+- [Directionality]()
+- [Compound Foreign Keys]()
+- [Joins]()
+-->
+
+# Misc
+
+- [Terminology](./terminology.md#relationships)

guides/terminology.md

@@ -0,0 +1,140 @@
+# Terminology
+
+- ⮐ [Main Guide](./index.md)
+
+**Sections**
+
+- [Data](#data)
+  - [Resource](#resource)
+  - [Collection](#collection)
+  - [Identifier](#identifier)
+  - [Document](#document)
+  - [RelationshipDocument](#relationshipdocument)
+- [Relationships](#relationships)
+  - [Inverse](#inverse)
+  - [Self Referential](#self-referential)
+  - [Reflexive](#reflexive)
+  - [Circular](#circular)
+  - [Polymorphic](#polymorphic)
+
+---
+
+## Data
+
+EmberData treats data "opaquely" meaning that any data format will work so long as you are able to describe to the library
+how that data fits into various concepts (usually this is done by implementing a [Cache](https://api.emberjs.com/ember-data/release/classes/%3CInterface%3E%20Cache)).
+
+Below, we describe the semantic meaning of these more opaque concepts.
+
+### Resource
+
+A resource is a unit of discretely identifiable data.
+
+Usually resources map to things like rows in a database
+with their "type" being derived from the table name.
+
+Discretely identifiable means that given some data, your
+app would consistently be able to identify the source of
+that data and meaningfully distinguish it from other data.
+
+For instance, in the following JSON we have two distinct
+resources:
+
+```jsonc
+{
+  "users": [
+    { "id": 1, "name": "Chris" }, // => resource 1
+    { "id": 2, "name": "Rey" } // => resource 2
+  ]
+}
+```
+
+#### Resource Types
+
+Every resource has a string "type". All resources with the same
+type are assumed to have the same [schema](#scema).
+
+Types can represent polymorphic traits.
+
+For instance, imagine your API has the notion of an `automobile` resource. Automobiles have an id, a number of wheels, and a name.
+
+```jsonc
+{
+  "automobiles": [
+    { "id": 1, "wheels": 4, "name": "Rivian R1T" }
+  ]
+}
+```
+
+However, every specific automobile belongs to a more specialized type. For instance "pickup" which has the additional [fields](#field) of `length` and `4wd` and "racecar" which has the additional field of `topspeed`.
+
+```jsonc
+{
+  "pickups": [
+    {
+      "id": 1,
+      "wheels": 4,
+      "name": "Rivian R1T",
+      "length": "12ft",
+      "4wd": true
+    }
+  ],
+  "racecars": [
+    {
+      "id": 2,
+      "wheels": 4,
+      "name": "Mazda 787B",
+      "topspeed": { "value": 258, "unit": "mph" }
+    }
+  ]
+}
+```
+
+In this case, we can refer to both type `pickup` and type `racecar` as satisfying type `automobile`. We refer to `pickup` and `racecar` as "concrete types" and to `automobile` as an `abstract type`. For more, read about [polymorphism in depth](./relationships/features/polymorphism.md).
+
+### Field
+
+### Schema
+
+### Collection
+
+### Identifier
+
+### Document
+
+### RelationshipDocument
+
+---
+
+## Relationships
+
+### Inverse
+
+The "inverse" of a relationship is the compound key generated by considering both the [type](#resource-types) and the `name` of the matching [field](#field) on the related [resource](#resource) .
+
+E.g. if Users have Pets and Pets have Owners, then the
+inverse of the field `user.pets` is `pet.owners`, and the inverse of `pet.owners` is similarly `user.pets`.
+
+> **Note** `to-none` relationships have no inverse. We often refer to this as a `null inverse`.
+
+### Self Referential
+
+Self referential relationships are relationships that point back at the same resource type.
+
+E.g. if a Person has parents and children, the link between `person.parents` and `person.children` is self-referential because both sides belong to the `person` resource type.
+
+### Reflexive
+
+Reflexive relationships are self-referential relationships that point back at the same property in addition to the same type.
+
+For instance, if a User has friends, where `user.friends` is its own inverse.
+
+### Circular
+
+A circular relationship is a self-referential or reflexive relationship for which the *value* is the same on both sides.
+
+For instance, if Ego is his own best friend, then `ego.bestFriend === ego`
+
+### Polymorphic
+
+Polymorphic relationsips can be satisfied by multiple resource types. For instance, a user may have many vehicles, and each vehicle might be of type `car` or `boat` or `airplane` etc.