Variables/Parameters in Links

The OpenAPI v3 links feature allows specifying related operations. To me, however, the spec was not clear on whether it’s possible and if, how to define links that require an additional variable for the call.

To give a practical example, assume there’s a GET /users operation to list all users and a GET /users/{id} operation to get details about an individual user. I could add the latter as a link to the former but this link requires an additional piece of information, specifically which user from the list I want to receive details for.

{
 "links" : {
  "details" : {
   "operationId" : "getUserDetails",
    "parameters": {
     "id" : "$response.body#/*/id"
    }
   }
  }
}

Is that possible or even desired to express with the links feature? If yes, is * the right syntax for a placeholder in JSON pointer? If not, is there another way?

[LukasRos]

Ok, thanks for your quick reply and the clarification, so I’ve understood links are always 1:1 pointers to other operations, never 1:n. I think that 1:n links with variables are a really interesting feature and would love to see them in a future version of the OAS.

[xorcus]

I guess the use of hypermedia is not in line with OAS design-time Link Object as it requires link information in the runtime response. What I had in mind is something similar to JSON Hyper-Schema and relative JSON pointers, as described by @handrews in his comment on Jan 5, 2018, but without needing separate hyper-schema resources. Ideally, all links would be included in the OAS API spec.

As explained in Relative JSON Pointer, section 6, the fragment identifiers do not apply to relative pointers.

Would it be possible to have links in OAS Schema Object, allowing for the <non-negative-integer> prefix of JSON pointers (i.e. using Relative JSON pointers) as part of the standard OAS spec?

As far as I am aware, the only changes needed in the OAS are: a) Add links as a regular property of Schema Object (same as in Response Object) b) In Runtime Expressions, redefine the fragment:

fragment = a JSON Pointer [RFC 6901](https://tools.ietf.org/html/rfc6901)  

by allowing for the optional non-negative-integer prefix, having semantics explained in Relative JSON Pointer:

fragment = [ <non-negative-integer> ] <a JSON Pointer [RFC 6901](https://tools.ietf.org/html/rfc6901)>

This is a backward-compatible change.

If <non-negative-integer> is not there, JSON Pointer is absolute. If present, JSON pointer is relative. In majority of use cases, the evaluation of links does not depend on context in which a Schema Object is found, but rather on a Schema Object property (e.g. the unique id). Therefore, in a simplified client implementation, it should be sufficient to support evaluating only relative JSON pointers starting with zero, i.e. having the <non-negative-integer> set to zero.