Clarify resolving implicit connections (3.1.1)

This clarifies how to handle resolving implicit (non-URI-based)
connections in multi-document OpenAPI Descriptions.

While the behavior is implementation-defined overall, this
RECOMMENDS a single approach based on how things behaved going
back to the 2.0 referencing model.  This allows Security Schemes
and Tags to (like the top-level Server Objects) define
a deployment-specific interface for referenced documents to access.

This entry document interface approach makes less sense for the
Discriminator Object, but it can use the URI syntax of `mapping`
to keep things within the local document.

This also aligns the search for matching `operationId`s with
3.1's full-document parsing requirements.

Note that the term "complete OpenAPI document" has been defined
in another change pending approval on the 3.0.4 branch.

Author: handrews

versions/3.1.1.md

@@ -185,12 +185,46 @@ It is the responsibility of an embedding format to define how to parse embedded
 
 When parsing an OAD, JSON or YAML objects are parsed into specific Objects (such as [Operation Objects](#operationObject), [Response Objects](#responseObject), [Reference Objects](#referenceObject), etc.) based on the parsing context.  Depending on how references are arranged, a given JSON or YAML object can be parsed in multiple different contexts:
 
-* As a full OpenAPI Description document (an [OpenAPI Object](#oasObject) taking up an entire document)
+* As a complete OpenAPI Description document
 * As the Object type implied by its parent Object within the document
 * As a reference target, with the Object type matching the reference source's context
 
 If the same JSON/YAML object is parsed multiple times and the respective contexts require it to be parsed as _different_ Object types, the resulting behavior is _implementation defined_, and MAY be treated as an error if detected.  An example would be referencing an empty Schema Object under `#/components/schemas` where a Path Item Object is expected, as an empty object is valid for both types.  For maximum interoperability, it is RECOMMENDED that OpenAPI Description authors avoid such scenarios.
 
+#### <a name="resolvingImplicitConnections"></a>Resolving Implicit Connections
+
+Several features of this specification require resolving a non-URI-based connection to some other part of the OpenAPI Description (OAD).
+
+These connections are easily resolved in single-document OADs, but the resolution process in multi-document OADs has never been spelled out, and is therefore _implementation-defined_, within the constraints described in this section.
+In some cases, an unambiguous URI-based alternative is available, and OAD authors are RECOMMENDED to always use the alternative:
+
+Source | Target | Alternative
+------ | ------ | -----------
+[Security Requirement Object](#securityRequirementObject) `{name}` |  [Security Scheme Object](#securitySchemeObject) name under the [Components Object](#componentsObject) | _n/a_
+[Discriminator Object](#discriminatorObject) `mapping` _(implicit, or explicit name syntax)_ | [Schema Object](#schemaObject) name under the Components Object | `mapping` _(explicit URI syntax)_
+[Operation Object](#operationObject) `tags` | [Tag Object](#tagObject) `name` (in the Components Object) | _n/a_
+[Link Object](#linkObject) `operationId` | [Path Item Object](#pathItemObject) `operationId` | `operationRef`
+
+A fifth implicit connection, which involves appending the templated URL paths of the [Paths Object](#pathsObject) to the appropriate [Server Object](#serverObject)'s `url` field, is unambiguous because only the entry document's Paths Object contributes URLs to the described API.
+
+It is RECOMMENDED to consider all Operation Objects from all parsed documents when resolving any Link Object `operationId`.
+This requires ensuring that all referenced documents have been parsed prior to determining an `operationId` to be unresolvable.
+
+The implicit connections in the Security Requirement Object and Discriminator Object rely on the _component name_, which is the property name holding the component in the appropriate typed sub-object of the Components Object.
+For example, the component name of the Schema Object at `#/components/schemas/Foo` is `Foo`.
+The implicit connection of tags in the Operation Object use the `name` field of Tag Objects, which (like the Components Object) are found under the root OpenAPI Object.
+This means that resolving component names and tag names both depend on starting from the correct OpenAPI Object.
+
+For resolving component and tag name connections from a referenced (non-entry) document, it is RECOMMENDED that tools resolve from the entry document, rather than the current document.
+This allows Security Scheme Objects and Tag Objects to be defined with the API's deployment information (the top-level Server Objects), and treated as an interface for referenced documents to access.
+
+The interface approach can also work for Discriminator Objects and Schema Objects, but it is also possible to keep the Discriminator Object's behavior within a single document using the relative URI-reference syntax of `mapping`.
+
+There are not currently URI-based alternatives for the Security Requirement Object or for the Operation Object's `tags` field.
+These limitations are expected to be addressed in a future release.
+
+Note that no aspect of implicit connection resolution changes how [URIs are resolved](#relativeReferencesURI), or restricts their possible targets.
+
 ### <a name="dataTypes"></a>Data Types
 
 Data types in the OAS are based on the types supported by the [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.2.1).