clarify intent of links member

[jelhan]

There has been many confusion about the intent of the links member. People tried using it for links not pointing to other JSON:API documents. Such as related files, related resources represented in different formats or other representations of the same resource in other formats. This PR tries to clarify the intent of links member and pointing readers to alternative ways solving their use case.

Open questions:

• Should we backport this to v1.1?

Closes #1684 #1678

[auvipy]

looks better

[lindyhopchris]

@jelhan someone raised a good point in my Laravel JSON:API repo - can links be modified via profiles? Assuming that's not the intent, based on what's drafted in this PR.

FYI I'm in support of this clarification - I've always found it confusing as to whether you're allowed to customise the links member. So it's good to get this clarified.

[jelhan]

@jelhan someone raised a good point in my Laravel JSON:API repo - can links be modified via profiles? Assuming that's not the intent, based on what's drafted in this PR.

No. Profiles can only define document members and processing rules that are reserved for implementors. The links object is not reserved for implementors. The JSON:API specification defines an infinite set of members, which are allowed within the links object depending on the context.

An extension can define additional members for the links object and define processing rules for them. As every extension-defined member, such a member must be namespaced. This change would not limit an extension to define additional members for the links object. But it would clarify, which extension-specific members should be added to the links object and for which use cases an extension should define another document member.

[lindyhopchris]

Ah yes, sorry I think I meant profiles or extensions.

Agree with what you've written.

[auvipy]

IMHO it could be back ported in v1.1