Clarify resolving implicit connections (3.1.1)

versions/3.1.1.md

@@ -182,12 +182,58 @@ 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 support one or both of the following approaches, and it is likewise RECOMMENDED that OAD authors organize their documents to work well with them.
+Note that neither approach changes how [URIs are resolved](#relativeReferencesURI), or restricts their possible targets.
+
+##### OADs Using Only Complete Documents
+
+The approach in this section is RECOMMENDED for OADs that are composed entirely of complete documents.
+Standalone JSON Schema documents can be included along with complete OpenAPI Documents as long as any Discriminator Objects within the standalone JSON Schemas only use explicit `mapping` URIs for all possible values.
+This OAD design is RECOMMENDED when sharing components among multiple OADs.
+
+In this approach, each document is self-contained and resolves component and tag names to the Components Object and Tag Objects under its own root OpenAPI Object.
+
+**Note:** Currently, Security Requirement Objects do not support a URI-based mechanism for connecting to Security Scheme Objects, and Operation Objects do not support a URI-based mechanism for connecting to Tag Objects.
+That means that in this approach, they can currently only connect to Security Scheme and Tag Objects within the same document.
+This limitation is expected to be addressed in a future version of this specification.
+
+##### OADs With Only One OpenAPI Object
+
+The approach in this section is RECOMMENDED for OADs where the entry OpenAPI document is the only document containing an OpenAPI Object.
+This approach is most suitable for splitting an otherwise self-contained single-document OAD into multiple documents for author convenience.
+
+In this approach, all component names are resolved through the entry document's Components Object, and all `operationId`s are resolved through Path Item Objects reachable through the `paths` or `webhooks` fields.
+
 ### <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).