Description
There seems to be confusion about the intent of the links member. Readers of the specification assume that it is meant to hold any links. Even many some implementations have followed that misunderstanding. See #1019 and #1656 as examples. Allowing implementation-specific members in the links objects has been requested at many places. See #1678 and https://discuss.jsonapi.org/t/links-with-custom-relations/1942, https://discuss.jsonapi.org/t/links-object-clarification-needed/130 and as examples.
The main reason for both the misunderstandings as well as the requests to allow implementation-specific members are based on the assumption that all URLs should go into links member. In my understanding of the spec the links is only for discovering related JSON:API documents. Other URLs should be an attribute of a resource (e.g. for referencing a file attached to a resource), should go into meta or extension-specific members (e.g. for alternative representations of the same resource).
I feel we should communicate that intent more clearly (assuming that my understanding of the specification is correct). Especially the following introduction sentence in Links chapter may be misleading:
Where specified, a
linksmember can be used to represent links.
I feel we should clarify that it is only about representing links to related JSON:API documents. Additionally we may want to give a hint how to handle other URLs / links in a note.