From e79968952e7bb531b863ff201f12dabf4c520303 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 9 Sep 2024 13:46:18 -0700 Subject: [PATCH] Further clarify link operation ambiguity There are even more ways this can go wrong! --- versions/3.0.4.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 46005e9eb7..e61c2b1937 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -2310,9 +2310,10 @@ For computing links and providing instructions to execute them, a [runtime expre This object MAY be extended with [Specification Extensions](#specification-extensions). A linked operation MUST be identified using either an `operationRef` or `operationId`. -In the case of an `operationId`, it MUST be unique and resolved in the scope of the OpenAPI description. -Because of the potential for name clashes, the `operationRef` syntax is preferred -for multi-document OpenAPI descriptions. +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). +Because of the potential for name clashes, the `operationRef` syntax is preferred for multi-document OADs. +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. +In such ambiguous cases, the resulting behavior is implementation-defined and MAY result in an error. Note that it is not possible to provide a constant value to `parameters` that matches the syntax of a runtime expression. 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).