diff --git a/src/oas.md b/src/oas.md index c631b0e5fb..f124b4c87b 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2507,10 +2507,12 @@ Clients follow all links at their discretion. Neither permissions nor the capability to make a successful call to that link is guaranteed solely by the existence of a relationship. -##### `operationRef` Examples +###### `operationRef` Examples -As references to `operationId` MAY NOT be possible (the `operationId` is an optional -field in an [Operation Object](#operation-object)), references MAY also be made through a relative `operationRef`: +As the `operationId` is an optional field in an [Operation Object](#operation-object), references MAY instead be made through a URI-reference with `operationRef`. +Note that both of these examples reference operations that can be identified via the [Paths Object](#paths-object) to ensure that the operation's path template is unambiguous. + +A relative URI-reference `operationRef`: ```yaml links: @@ -2520,7 +2522,7 @@ links: username: $response.body#/username ``` -or a URI `operationRef`: +A non-relative URI `operationRef`: ```yaml links: @@ -2530,8 +2532,9 @@ links: username: $response.body#/username ``` -Note that in the use of `operationRef` the _escaped forward-slash_ is necessary when -using JSON Pointer, and it is necessary to URL-encode `{` and `}` as `%7B` and `%7D`, respectively, when using JSON Pointer as URI fragments. +Note that in the use of `operationRef` the _escaped forward-slash_ (`~1`) is necessary when +using JSON Pointer in URI fragments, and it is necessary to URL-encode `{` and `}` as `%7B` and `%7D`, respectively. +The unescaped, percent-decoded path template in the above examples would be `/2.0/repositories/{username}`. ##### Runtime Expressions @@ -2565,7 +2568,7 @@ The `name` identifier is case-sensitive, whereas `token` is not. The table below provides examples of runtime expressions and examples of their use in a value: -##### Examples +###### Example Expressions | Source Location | example expression | notes | | ---- | :---- | :---- |