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).