diff --git a/guides/index.md b/guides/index.md new file mode 100644 index 00000000000..2020d407db3 --- /dev/null +++ b/guides/index.md @@ -0,0 +1,4 @@ +# Guides + +- [Relationships](./relationships/index.md) +- [Terminology](./terminology.md) diff --git a/guides/relationships.md b/guides/relationships.md deleted file mode 100644 index 066a8aeebc2..00000000000 --- a/guides/relationships.md +++ /dev/null @@ -1,38 +0,0 @@ -# Relationships Guide - -## Feature Overview -- [Inverses](./relationships/features/inverses.md) - - -## Configuration -- [1:none](./relationships/configuration/0-one-to-none.md) (One To None) -- [1:1](./relationships/configuration/1-one-to-one.md) (One To One) -- [1:Many](./relationships/configuration/2-one-to-many.md) (One To Many) -- [Many:None](./relationships/configuration/3-many-to-none.md) (Many To None) -- [Many:1](./relationships/configuration/4-many-to-one.md) (Many To One) -- [Many:Many](./relationships/configuration/5-many-to-many.md) (Many To Many) - - - -# Misc - -- [Terminology](./relationships/terminology.md) diff --git a/guides/relationships/configuration/0-one-to-none.md b/guides/relationships/configuration/0-one-to-none.md index 335269bab3c..84cb1afd663 100644 --- a/guides/relationships/configuration/0-one-to-none.md +++ b/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) diff --git a/guides/relationships/configuration/1-one-to-one.md b/guides/relationships/configuration/1-one-to-one.md index a296c7114a9..71e1819fbf5 100644 --- a/guides/relationships/configuration/1-one-to-one.md +++ b/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) diff --git a/guides/relationships/configuration/2-one-to-many.md b/guides/relationships/configuration/2-one-to-many.md index 41aa5782ac9..ed5f99c18f5 100644 --- a/guides/relationships/configuration/2-one-to-many.md +++ b/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) diff --git a/guides/relationships/configuration/3-many-to-none.md b/guides/relationships/configuration/3-many-to-none.md index b6297e19571..58e913948d6 100644 --- a/guides/relationships/configuration/3-many-to-none.md +++ b/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) diff --git a/guides/relationships/configuration/4-many-to-one.md b/guides/relationships/configuration/4-many-to-one.md index 93582f60800..a712fafc28f 100644 --- a/guides/relationships/configuration/4-many-to-one.md +++ b/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) --- diff --git a/guides/relationships/configuration/5-many-to-many.md b/guides/relationships/configuration/5-many-to-many.md index 9c67a2d048f..78be6fd31bc 100644 --- a/guides/relationships/configuration/5-many-to-many.md +++ b/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) diff --git a/guides/relationships/features/inverses.md b/guides/relationships/features/inverses.md index 557c5c3d691..9a9cb80b20f 100644 --- a/guides/relationships/features/inverses.md +++ b/guides/relationships/features/inverses.md @@ -1,6 +1,6 @@ # Relationship Inverses -- ⮐ [Relationships Guide](../../relationships.md) +- ⮐ [Relationships Guide](../index.md) --- diff --git a/guides/relationships/index.md b/guides/relationships/index.md new file mode 100644 index 00000000000..f7f75d3676f --- /dev/null +++ b/guides/relationships/index.md @@ -0,0 +1,38 @@ +# Relationships Guide + +## Feature Overview +- [Inverses](./features/inverses.md) + + +## 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) + + + +# Misc + +- [Terminology](./terminology.md#relationships) diff --git a/guides/relationships/terminology.md b/guides/relationships/terminology.md deleted file mode 100644 index 663d2860855..00000000000 --- a/guides/relationships/terminology.md +++ /dev/null @@ -1,36 +0,0 @@ -# Relationship Terminology - -- ⮐ [Relationships Guide](../relationships.md) - ---- - -## Inverse - -The "inverse" of a relationship is the compound key generated by considering both the related `resource` `type` and the `name` of the matching field on the related `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`. - -`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. diff --git a/guides/terminology.md b/guides/terminology.md new file mode 100644 index 00000000000..c1c8ffdc706 --- /dev/null +++ b/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.