From 776ac714b6639da1c752d53f449b4fd679bd0c0c Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 14 Aug 2025 09:13:54 -0700 Subject: [PATCH 1/2] Fix Link Object subsections, improve examples There were two subsections called "Examples", one for actual Link Object examples and one for runtime expression examples. This puts the `operationRef` examples under the main Examples section, and renames the runtime expression example section. While I was at it, I clarified some of the wording. --- src/oas.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/src/oas.md b/src/oas.md index c631b0e5fb..9065a810ae 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 | | ---- | :---- | :---- | From 94b16b23e2e2aaeeca05cceab64b74b787d4713d Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Sat, 16 Aug 2025 12:28:12 -0700 Subject: [PATCH 2/2] Fix stray extra paren Co-authored-by: Ralf Handl --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 9065a810ae..f124b4c87b 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2509,7 +2509,7 @@ solely by the existence of a relationship. ###### `operationRef` Examples -As the `operationId` is an optional field in an [Operation Object](#operation-object)), references MAY instead be made through a URI-reference with `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`: