You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Some servers/discriminator text that should have been removed
in the previous commit was accidentally left in. Several
non-essential recommendations have been removed.
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).
194
194
195
195
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.
196
196
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
210
210
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.
211
211
This OAD design is RECOMMENDED when sharing components among multiple OADs.
212
212
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.
214
216
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.
220
219
221
220
##### OADs With Only One OpenAPI Object
222
221
223
222
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.
227
224
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.
0 commit comments