Skip to content

Commit b23b945

Browse files
committed
Trim down implict resolution text further.
Some servers/discriminator text that should have been removed in the previous commit was accidentally left in. Several non-essential recommendations have been removed.
1 parent 1a29710 commit b23b945

File tree

1 file changed

+8
-11
lines changed

1 file changed

+8
-11
lines changed

versions/3.1.1.md

Lines changed: 8 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -190,7 +190,7 @@ If the same JSON/YAML object is parsed multiple times and the respective context
190190

191191
#### <a name="resolvingIndirectLinkages"></a>Resolving Indirect Connections
192192

193-
Several features of this specification require resolving a non-URI-based connection to some other part of the OpenAPI Description (OAD). Most connections resolve to Objects directly under the [OpenAPI Object](#oasObject)'s `components` or `servers` fields, while the Link Object's `operationId` connects to the identically-named field in a Path Item Object.
193+
Several features of this specification require resolving a non-URI-based connection to some other part of the OpenAPI Description (OAD).
194194

195195
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.
196196
In some cases, an unambiguous URI-based alternative is available, and OAD authors are RECOMMENDED to always use the alternative:
@@ -210,22 +210,19 @@ For resolving indirect connections from a referenced (non-entry) document, it is
210210
The approach in this section is RECOMMENDED for OADs that are composed entirely of complete OpenAPI documents, optionally including standalone JSON Schema documents as long as any Discriminator Objects within them only use explicit `mapping` URIs for all possible values.
211211
This OAD design is RECOMMENDED when sharing components among multiple OADs.
212212

213-
In this approach, each document is self-contained when resolving components (to that document's `#/components/{type}/{name}`) and global servers (likewise to `#/servers`). When resolving `operationId`, all Path Item Objects from all parsed documents are considered.
213+
In this approach, each document is self-contained and resolves components to its own Components Object.
214+
When resolving an `operationId`, all Path Item Objects from all parsed documents are considered.
215+
This requires ensuring that all referenced documents have been parsed prior to determining an `operationId` to be unresolvable.
214216

215-
When sharing components among multiple OADs, it is RECOMMENDED to place all shared components, including Path Item Objects, in documents that do _not_ contain `paths`, `webhooks`, or `servers`.
216-
Other Path Item Objects can still be connected via `operationRef`.
217-
218-
One drawback of this approach is that Security Schemes have to be defined in each document where they are used, as there is no URI-based alternative for resolving them.
219-
For forward-compatibility with the OAS version 3.2, implementations MAY provide an _opt-in_ configuration setting to support treating [Security Requirement Object](#securityRequirementObject) property names that do not match the syntax for a component name under the Components Object as URIs for the required [Security Scheme Object](#securitySchemeObject).
217+
Security Requirement Objects do not support a URI-based mechanism for connecting to Security Scheme Objects, which means that in this approach, they can only connect to Security Schemes within the same document.
218+
For forward-compatibility with the OAS version 3.2, implementations MAY provide an _opt-in_ configuration setting to support treating Security Requirement Object property names that do not match the component name syntax as URIs for the required Security Scheme Objects.
220219

221220
##### OADs With Only One OpenAPI Object
222221

223222
The approach in this section is RECOMMENDED for OADs where the entry OpenAPI document is the only document containing an OpenAPI Object.
224-
This approach is most suitable for splitting an otherwise self-contained single-document OAD into multiple documents for author convenience, in which case it is RECOMMENDED to arrange the documents in a directory structure mirroring the structure of a single-document OAD.
225-
226-
In this approach, all component names and global servers are resolved through the entry document, and all `operationId`s are resolved through Path Item Objects reachable through the `paths` or `webhooks` fields.
223+
This approach is most suitable for splitting an otherwise self-contained single-document OAD into multiple documents for author convenience.
227224

228-
Since this version of the OAS specification requires complete parsing of all documents, Schema Objects that use `allOf` to participate in another Schema Object's use of `discriminator` SHOULD be recognized and considered to be part of the OAD, even if they are not otherwise directly referenced.
225+
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.
229226

230227
### <a name="dataTypes"></a>Data Types
231228

0 commit comments

Comments
 (0)