Skip to content

Commit 776ac71

Browse files
committed
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.
1 parent b1bb5d4 commit 776ac71

File tree

1 file changed

+10
-7
lines changed

1 file changed

+10
-7
lines changed

src/oas.md

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2507,10 +2507,12 @@ Clients follow all links at their discretion.
25072507
Neither permissions nor the capability to make a successful call to that link is guaranteed
25082508
solely by the existence of a relationship.
25092509
2510-
##### `operationRef` Examples
2510+
###### `operationRef` Examples
25112511

2512-
As references to `operationId` MAY NOT be possible (the `operationId` is an optional
2513-
field in an [Operation Object](#operation-object)), references MAY also be made through a relative `operationRef`:
2512+
As the `operationId` is an optional field in an [Operation Object](#operation-object)), references MAY instead be made through a URI-reference with `operationRef`.
2513+
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.
2514+
2515+
A relative URI-reference `operationRef`:
25142516

25152517
```yaml
25162518
links:
@@ -2520,7 +2522,7 @@ links:
25202522
username: $response.body#/username
25212523
```
25222524

2523-
or a URI `operationRef`:
2525+
A non-relative URI `operationRef`:
25242526

25252527
```yaml
25262528
links:
@@ -2530,8 +2532,9 @@ links:
25302532
username: $response.body#/username
25312533
```
25322534

2533-
Note that in the use of `operationRef` the _escaped forward-slash_ is necessary when
2534-
using JSON Pointer, and it is necessary to URL-encode `{` and `}` as `%7B` and `%7D`, respectively, when using JSON Pointer as URI fragments.
2535+
Note that in the use of `operationRef` the _escaped forward-slash_ (`~1`) is necessary when
2536+
using JSON Pointer in URI fragments, and it is necessary to URL-encode `{` and `}` as `%7B` and `%7D`, respectively.
2537+
The unescaped, percent-decoded path template in the above examples would be `/2.0/repositories/{username}`.
25352538

25362539
##### Runtime Expressions
25372540

@@ -2565,7 +2568,7 @@ The `name` identifier is case-sensitive, whereas `token` is not.
25652568

25662569
The table below provides examples of runtime expressions and examples of their use in a value:
25672570

2568-
##### Examples
2571+
###### Example Expressions
25692572

25702573
| Source Location | example expression | notes |
25712574
| ---- | :---- | :---- |

0 commit comments

Comments
 (0)