Skip to content

allow extension defined member as only member in links object of relationship object #1658

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

Jump to bottom
Merged
merged 1 commit into from
Aug 22, 2022
Merged

allow extension defined member as only member in links object of relationship object #1658

merged 1 commit into from
Aug 22, 2022

Conversation

jelhan
Copy link
Contributor

@jelhan jelhan commented Aug 22, 2022

This allows an extension defined member as the only member in a links object of a relationship object.

This is not a breaking change compared. Extensions are not part of v1.0. So there could not be an applied extension if implementing v1.0.

Similar changes have been landed in #1642 and #1644 for other cases.

@jelhan jelhan requested a review from dgeb August 22, 2022 12:23
@VGirol
Copy link
Contributor

VGirol commented Aug 22, 2022

Perhaps one should also allow a member defined by an extension as the only member in:

  • the top level links object
  • the links object of a resource object.

@jelhan
Copy link
Contributor Author

jelhan commented Aug 22, 2022 •
edited
Loading

Perhaps one should also allow a member defined by an extension as the only member in:

* the top level links object

* the links object of a resource object.

We assume that it is not needed in this cases. In both cases it only lists allowed members. But does not forbid any other members:

The top-level links object MAY contain the following members:

If present, this links object MAY contain a self link that identifies the resource represented by the resource object.

Extensions are allowed to define new members anywhere in the document:

An extension MAY define new members within the document structure defined by this specification.

The only problematic case is if current wording requires another member of a fixed list to be present as well. I have included more details in #1642.

@jelhan
Copy link
Contributor Author

jelhan commented Aug 22, 2022

Maybe the wording used for the links object in the different contexts should be aligned:

json-api/_format/1.1/index.md

Lines 313 to 323 in f9e4e0e

The top-level [links object][links] **MAY** contain the following members:
* `self`: the [link][links] that generated the current response document. If a
document has extensions or profiles applied to it, this link **SHOULD** be
represented by a [link object] with the `type` target attribute specifying the
JSON:API media type with all applicable parameters.
* `related`: a [related resource link] when the primary data represents a
resource relationship.
* `describedby`: a [link] to a description document (e.g. OpenAPI or JSON
Schema) for the current document.
* [pagination] links for the primary data.

json-api/_format/1.1/index.md

Lines 489 to 497 in f9e4e0e

* `links`: a [links object][links] containing 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,
removing an `author` through an `article`'s relationship URL would disconnect
the person from the `article` without 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]

json-api/_format/1.1/index.md

Lines 578 to 579 in f9e4e0e

If present, this links object **MAY** contain a `self` [link][links] that
identifies the resource represented by the resource object.

I don't see good reasons for having a different wording in this three cases. In all cases a list of potential members is specified. Using a different wording may only cause confusion.

There is one important difference: a links object in context of a relationship object must have at least one member. The others are allowed to be empty as well. I don't think that these difference is by intend.

@VGirol
Copy link
Contributor

VGirol commented Aug 22, 2022

I had in mind that :

json-api/_format/1.1/index.md

Lines 281 to 283 in f9e4e0e

Unless otherwise noted, objects defined by this specification or any applied
extensions **MUST NOT** contain any additional members. Client and server
implementations **MUST** ignore non-compliant members.

So, i thought that, because of this, extension defined members could not be the only member of a links object in the others contexts (top-level and resource).
But i forgot this :

json-api/_format/1.1/index.md

Lines 96 to 98 in f9e4e0e

An extension **MAY** define new members within the document structure defined by
this specification. The rules for extension member names are covered
[below](#extension-members).

So, you're right.

The only problematic case is if current wording requires another member of a fixed list to be present as well.

Sorry for the inconvenience...

@jelhan
Copy link
Contributor Author

jelhan commented Aug 22, 2022

Sorry for the inconvenience...

Not at all! I'm happy to see other people having a close look at the details at well. It will help us to not miss anything important before releasing v1.1.

@dgeb
Copy link
Member

dgeb commented Aug 22, 2022

Thanks for the discussion @jelhan and @VGirol.

Maybe the wording used for the links object in the different contexts should be aligned

Sounds good. As we discussed separately, it's fine with me to handle this in a subsequent PR.

@dgeb dgeb merged commit 07645e5 into gh-pages Aug 22, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@dgeb dgeb dgeb approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@jelhan @VGirol @dgeb
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