Skip to content

Commit 25a9629

Browse files
committed
Indirect->Implicit, unify operationId, more tweaks
Every time I try to reference this section in another PR I type "implicit" instead of "indirect" so let's just go with that. Let's also treat `operationId` uniformly, because it fits better with how we parse documents, and the only thing this changes is in the only-the-entry-document-has-an-OpenAPI-object case, where it incorporates Path Item Objects in the entry document that are otherwise un-referenced. It seems likely that one would only include Path Item Objects in the entry document's components if one expected them to be used.
1 parent 5958e6f commit 25a9629

File tree

1 file changed

+7
-4
lines changed

1 file changed

+7
-4
lines changed

versions/3.1.1.md

+7-4
Original file line numberDiff line numberDiff line change
@@ -188,7 +188,7 @@ When parsing an OAD, JSON or YAML objects are parsed into specific Objects (such
188188

189189
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.
190190

191-
#### <a name="resolvingIndirectConnections"></a>Resolving Indirect Connections
191+
#### <a name="resolvingImplicitConnections"></a>Resolving Implicit Connections
192192

193193
Several features of this specification require resolving a non-URI-based connection to some other part of the OpenAPI Description (OAD).
194194

@@ -203,7 +203,12 @@ Source | Target | Alternative
203203

204204
A fourth 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.
205205

206-
For resolving indirect 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.
206+
It is RECOMMENDED to consider all Operation Objects from all parsed documents When resolving any Link Object `operationId`.
207+
This requires ensuring that all referenced documents have been parsed prior to determining an `operationId` to be unresolvable.
208+
209+
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.
210+
For example, the component name of the Schema Object at `#/components/schemas/Foo` is `Foo`.
211+
For resolving component 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.
207212
Note that neither approach changes how [URIs are resolved](#relativeReferencesURI), or restricts their possible targets.
208213

209214
##### OADs Using Only Complete Documents
@@ -213,8 +218,6 @@ Standalone JSON Schema documents can be included along with complete OpenAPI Doc
213218
This OAD design is RECOMMENDED when sharing components among multiple OADs.
214219

215220
In this approach, each document is self-contained and resolves component names to its own Components Object.
216-
When resolving an `operationId`, all Path Item Objects from all parsed documents are considered.
217-
This requires ensuring that all referenced documents have been parsed prior to determining an `operationId` to be unresolvable.
218221

219222
**Note:** Currently, 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.
220223
This limitation is expected to be addressed in a future version of this specification.

0 commit comments

Comments
 (0)