Introduce describedby link relation

[dgeb]

The describedby link relation can be used to identify a description document, which may be an OpenAPI definition, a JSON Schema document, or another description format.

It's proposed that the describedby member can appear in two places:

• A) in the top-level links object, in which case it provides a description for the current document.
• B) inside any link object, in which case it provides a description for the target of the link.

We could optionally allow this member inside any links object that can also contain a self link - namely, resource links and relationship links. This would be consistent with (A) but also somewhat redundant with (B). I'd like to make a decision about this explicitly prior to merging.

Another question is whether there should be a central definition of a "description document" within the JSON:API spec, or whether using parenthetical examples (e.g. OpenAPI or JSON Schema) is sufficient.

related: #1281

/cc @philsturgeon @gabesullice

[philsturgeon]

🚢 👍

[jugaadi]

Thanks @dgeb @philsturgeon @gabesullice for initiating this effort.

I'd vote for adopting a central default description format to avoid any confusion between API providers and consumers. Any other format can be handled through profiles.

In this case, I would prefer OpenAPI because:

1. Large community
2. Industry wide support
3. Tooling
4. Alignment with JSON Schema

PS: We are already using OpenAPI for describing JSON:API resources. This spec is used by both the client and server to handle requests and responses.

[dgeb]

@jugaadi Thanks for your feedback! I agree that OpenAPI is a solid choice and a good starting point.

While we don't want to restrict the content type of the description documents pointed to by describedby, we definitely want to provide some recommendations in the non-normative section of the site that will cover best practices. We can include example usage of OpenAPI and JSON Schema to start, and would appreciate your contributions to the recommendations based on your experience.

[dgeb]

@gabesullice I think this is ready to review. Please let me know what you think about my question from the PR description:

We could optionally allow this member inside any links object that can also contain a self link - namely, resource links and relationship links. This would be consistent with (A) but also somewhat redundant with (B). I'd like to make a decision about this explicitly prior to merging.

[gabesullice]

@dgeb and I discussed this today. WRT to the question in the description, we decided against allowing describedby links in resource or relationship objects because it may cause confusion about whether the description document is intended to describe the object as it appears in the current response or the description document of the document you expect to receive by following its self link. The describedby target attribute is a link hint that clearly indicates that the description document it targets describes the target URL.

I think this PR is ready to merge.

[gabesullice]

This looks good to me.

[evert]

There is also this format: https://tools.ietf.org/html/draft-nottingham-link-hint

bit different from how this was done, but does the same thing nonetheless

[gabesullice]

@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 😺

[evert]

Yea just for context, I do believe that your use-case is one of the things link-hints hopes to solve, but it would indeed be a deeper nested structure.

I believe the equivalent syntax would actually be:

links: {
  self: {
    href: /articles/1,
    hints: {
      formats: {
        'application/vnd+api.json': {
           links: {
             describedby: {
               href: "/schemas/article.json",
               type: "application/schema+json"
           }
        }
      }
    }
}

This makes the most sense for links that are explicitly not self links. For a self link, I would just take the format information and lift it to its own link:

links: {
  self: {
    href: /articles/1,
  },
  describedby: {
    href: "/schemas/article.json",
    type: "application/schema+json"
  }
}

[gabesullice]

Whoaaa, I had not grokked that bit of the RFC. That's a very thought provoking idea... It's interesting how the format is specialized by a schema/profile.

For a self link, I would just take the format information and lift it to its own link:

This PR does exactly that, but only for top-level links.

[MikeRalphson]

Probably not worth opening a new issue, but just thought I'd note that link describedBy is generally about describing a resource (so JSON Schema fits well here), but an OpenAPI document generally describes the surface area of a whole or partial API.

The link rel service-desc might be more appropriate for OpenAPI?

[gabesullice]

I expect implementors to link to the HTML representations of their OpenAPI spec where they can add a fragment to the URL. For example, https://petstore.swagger.io/#/user

[claudenirmf]

Hello, all! I am facing an interesting situation (not unlike the previous comment from @gabesullice) that could provide some insight.

In our implementation, we want to enhance the experience of developers, mainly because they may have to communicate to similar servers implementing different sets of features (e.g., only some implement a certain filter). So, we have decided to respond to errors with an error object, where we wish to use the link describedby to point to a resource where the developer may learn the specifics of that server's implementation.

Here are the catches: (i) this is intended to be human-readable; (ii) this usually is not even about resource itself, but the parameters sent in the request.

We still want to use describedby in successful responses such that a software can retrieve the JSON Schema for those resources, for instance. But I am unsure about how to differentiate these distinct usages describedby.