@evert, afaict, we could integrate that RFC w/ JSON:API fairly easily. They're not mutually exclusive. To do that, we would add hints as an allowed member of a link objects both as a sibling of—and similar to—the params member.

If you're saying that we could have added describedby under hints, I don't think that works because that RFC is about providing hints related to HTTP headers, statuses, etc. I suppose it would be a proxy for the Link header, but for better or for worse the JSON:API spec, talks about links exclusively about links represented in the JSON response body.

Perhaps you're referring to the links hint from that RFC since we could have done something like:

links: {
  self: {
    href: /articles/1,
    hints: {
      links: {
        describedby: /schemas/article.json
      }
    }
}

Instead of what we chose:

links: {
  self: {
    href: /articles/1,
    describedby: {
      href: /schemas/article.json
    }
}

We considered something like that (i.e. adding a links target attribute to link objects themselves) but decided against it to keep nesting/complexity to a minimum.

PS. It's funny you mentioned that RFC, I just mentioned it in a post within 30 minutes of your reply 😺