Skip to content

Associate "relationship object" with everything else #946

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Associate "relationship object" with everything else #946

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions _format/1.0/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -240,13 +240,14 @@ alongside other information to be represented in a resource object, these keys
#### <a href="#document-resource-object-relationships" id="document-resource-object-relationships" class="headerlink"></a> Relationships

The value of the `relationships` key **MUST** be an object (a "relationships
object"). Members of the relationships object ("relationships") represent
references from the [resource object][resource objects] in which it's defined to other resource
objects.
object"). Members of the relationships object represent "relationships", i.e.,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While we're here:
...references from the resource objects in which they are defined...

Also, this needs to be updated here too:
https://github.com/json-api/json-api/blob/gh-pages/_format/1.1/index.md

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wondered about that too. The "it" refers to the relationships object, which is singular. But yes, I agree that it would sound more correct if we referred to the relationships themselves.

references from the [resource object][resource objects] in which they are defined
to other resource objects.

Relationships may be to-one or to-many.

A "relationship object" **MUST** contain at least one of the following:
Each relationship **MUST** be represented by an object (a "relationship object")
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This needs to be updated in a few more places:
https://github.com/json-api/json-api/blob/gh-pages/_format/1.0/normative-statements.json:
https://github.com/json-api/json-api/blob/gh-pages/_format/1.1/index.md
https://github.com/json-api/json-api/blob/gh-pages/_format/1.1/normative-statements.json:

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, if we're being nitpicky/precise, my mental model has always been that each relationship has two parts: its name and its contents (the linkage, not the related). So maybe we should say "Each relationship's contents....", or use the prior wording, or make the name + contents division more explicit?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, "each relationship's contents" would seem to make sense.

The prior wording didn't associate relationship objects with any of the other definitions, which prompted the patch in the first place.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One potential problem with "each relationship's contents" is that the relationship object also includes links, and I'm not sure if those are part of the contents???

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One way to sidestep the entire issue is to specify that each member of a relationships object must be a relationship object.

It's already mentioned that members of a relationships object represent relationships, so a relationship object's purpose could be defined in terms of either.

containing at least one of the following:

* `links`: a [links object][links] containing at least one of the following:
* `self`: a link for the relationship itself (a "relationship link"). This
Expand All @@ -268,7 +269,7 @@ A relationship object that represents a to-many relationship **MAY** also contai

#### <a href="#document-resource-object-related-resource-links" id="document-resource-object-related-resource-links" class="headerlink"></a> Related Resource Links

A "related resource link" provides access to [resource objects] [linked][links]
A "related resource link" provides access to [resource objects][] [linked][links]
in a [relationship][relationships]. When fetched, the related resource object(s)
are returned as the response's primary data.

Expand Down
2 changes: 1 addition & 1 deletion _format/1.0/normative-statements.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -643,7 +643,7 @@ layout: null
"type": "normative-statements",
"attributes": {
"level": "MUST",
"description": "A \"relationship object\" **MUST** contain at least one of the following:]\\n\\n- `links`: a links object containing at least one of the following:\\n - `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.\\n - `related`: a related resource link\\n- `data`: resource linkage\\n- `meta`: a meta object that contains non-standard meta-information about the relationship."
"description": "Each relationship **MUST** be represented by an object (a \"relationship object\") containing at least one of the following:\\n\\n- `links`: a links object containing at least one of the following:\\n - `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.\\n - `related`: a related resource link\\n- `data`: resource linkage\\n- `meta`: a meta object that contains non-standard meta-information about the relationship."
},
"relationships": {
"section": {
Expand Down
11 changes: 6 additions & 5 deletions _format/1.1/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -240,13 +240,14 @@ alongside other information to be represented in a resource object, these keys
#### <a href="#document-resource-object-relationships" id="document-resource-object-relationships" class="headerlink"></a> Relationships

The value of the `relationships` key **MUST** be an object (a "relationships
object"). Members of the relationships object ("relationships") represent
references from the [resource object][resource objects] in which it's defined to other resource
objects.
object"). Members of the relationships object represent "relationships", i.e.,
references from the [resource object][resource objects] in which they are defined
to other resource objects.

Relationships may be to-one or to-many.

A "relationship object" **MUST** contain at least one of the following:
Each relationship **MUST** be represented by an object (a "relationship object")
containing at least one of the following:

* `links`: a [links object][links] containing at least one of the following:
* `self`: a link for the relationship itself (a "relationship link"). This
Expand All @@ -268,7 +269,7 @@ A relationship object that represents a to-many relationship **MAY** also contai

#### <a href="#document-resource-object-related-resource-links" id="document-resource-object-related-resource-links" class="headerlink"></a> Related Resource Links

A "related resource link" provides access to [resource objects] [linked][links]
A "related resource link" provides access to [resource objects][] [linked][links]
in a [relationship][relationships]. When fetched, the related resource object(s)
are returned as the response's primary data.

Expand Down
2 changes: 1 addition & 1 deletion _format/1.1/normative-statements.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -643,7 +643,7 @@ layout: null
"type": "normative-statements",
"attributes": {
"level": "MUST",
"description": "A \"relationship object\" **MUST** contain at least one of the following:]\\n\\n- `links`: a links object containing at least one of the following:\\n - `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.\\n - `related`: a related resource link\\n- `data`: resource linkage\\n- `meta`: a meta object that contains non-standard meta-information about the relationship."
"description": "Each relationship **MUST** be represented by an object (a \"relationship object\") containing at least one of the following:\\n\\n- `links`: a links object containing at least one of the following:\\n - `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.\\n - `related`: a related resource link\\n- `data`: resource linkage\\n- `meta`: a meta object that contains non-standard meta-information about the relationship."
},
"relationships": {
"section": {
Expand Down
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy