Skip to content

Commit 5c60e5b

Browse files
committed
Further clarify link operation ambiguity
There are even more ways this can go wrong!
1 parent 11c5cac commit 5c60e5b

File tree

1 file changed

+4
-3
lines changed

1 file changed

+4
-3
lines changed

versions/3.1.1.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2385,9 +2385,10 @@ For computing links and providing instructions to execute them, a [runtime expre
23852385
This object MAY be extended with [Specification Extensions](#specification-extensions).
23862386

23872387
A linked operation MUST be identified using either an `operationRef` or `operationId`.
2388-
In the case of an `operationId`, it MUST be unique and resolved in the scope of the OpenAPI description.
2389-
Because of the potential for name clashes, the `operationRef` syntax is preferred
2390-
for multi-document OpenAPI descriptions.
2388+
The identified or reference operation MUST be unique, and in the case of an `operationId`, it MUST be resolved within the scope of the OpenAPI Description (OAD).
2389+
Because of the potential for name clashes, the `operationRef` syntax is preferred for multi-document OADs.
2390+
However, because use of an operation depends on its URL path template in the [Paths Object](#paths-object), operations from any [Path Item Object](#path-item-object) that is referenced multiple times within the OAD cannot be resolved unambiguously.
2391+
In such ambiguous cases, the resulting behavior is implementation-defined and MAY result in an error.
23912392

23922393
Note that it is not possible to provide a constant value to `parameters` that matches the syntax of a runtime expression.
23932394
It is possible to have ambiguous parameter names, e.g. `name: "id", in: "path"` and `name: "path.id", in: "query"`; this is NOT RECOMMENDED and the behavior is implementation-defined, however implementations SHOULD prefer the qualified interpretation (`path.id` as a path parameter), as the names can always be qualified to disambiguate them (e.g. using `query.path.id` for the query parameter).

0 commit comments

Comments
 (0)