Consider unifying the URL template syntax of callbacks and links

[ePaul]

Both the Link object (in a response) and the Callback object (in an operation) have a way of deriving a URL from some kind of pattern.

But those patterns are differently:

• For the href in the link object, we have a template string, which can contain {$...} expressions inside it. The full thing looks like /users/{$request.body#/user/uuid}.
• For the keys in the Callback object, we just have a single expression. So we have e.g. $request.body#/failedUrl.

Could we use the same syntax for both? This might also make the documentation less redundant.

[darrelmiller]

I would argue they are the same syntax. The only difference is in the href case the expression is embedded inside a parameter template and for callback it is not because the expression is supposed to evaluate to a complete URL and that URL is in the customer's ___domain so it isn't describable.

Having said this, I would argue that we should drop the first case completely. So instead of having,

components:
  links:
    UserRepositories:
      # returns array of '#/components/schemas/repository'
      href: '/2.0/repositories/{$response.body#/username}'

we do this.

components:
  links:
    UserRepositories:
      # returns array of '#/components/schemas/repository'
      href: '/2.0/repositories/{name}'
      parameters:
        name: $response.body#/username

I don't like the idea of requiring tooling to match the href with expression to an existing operation.

/cc @OAI/tdc

[RobDolinMS]

TDC: @fehguy is good with what is done in the bottom example.
TDC: @darrelmiller will make this change.

[webron]

Resolved by #1103!