Skip to content

Commit 0b08dc1

Browse files
handrewsjeremyfiel
andcommitted
Apply suggestions from code review (3.2.0 port of 3856 2/4)
Review feedback from Jeremy Fiel and typo fix from Ralf Handl. Co-authored-by: Jeremy Fiel <[email protected]>
1 parent c4e89e6 commit 0b08dc1

File tree

1 file changed

+9
-8
lines changed

1 file changed

+9
-8
lines changed

versions/3.2.0.md

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

209209
#### <a name="resolvingImplicitConnections"></a>Resolving Implicit Connections
210210

211-
Several features of this specification require resolving a non-URI-based connection to some other part of the OpenAPI Description (OAD).
211+
Several features of this specification require resolution of non-URI-based connections to some other part of the OpenAPI Description (OAD).
212212

213-
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.
213+
These connections are unambiguously resolved in single-document OADs, but the resolution process in multi-document OADs is _implementation-defined_, within the constraints described in this section.
214214
In some cases, an unambiguous URI-based alternative is available, and OAD authors are RECOMMENDED to always use the alternative:
215215

216216
Source | Target | Alternative
@@ -220,22 +220,23 @@ Source | Target | Alternative
220220
[Operation Object](#operationObject) `tags` | [Tag Object](#tagObject) `name` (in the Components Object) | _n/a_
221221
[Link Object](#linkObject) `operationId` | [Path Item Object](#pathItemObject) `operationId` | `operationRef`
222222

223-
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.
223+
A fifth implicit connection involves appending the templated URL paths of the [Paths Object](#pathsObject) to the appropriate [Server Object](#serverObject)'s `url` field.
224+
This is unambiguous because only the entry document's Paths Object contributes URLs to the described API.
224225

225226
It is RECOMMENDED to consider all Operation Objects from all parsed documents when resolving any Link Object `operationId`.
226-
This requires ensuring that all referenced documents have been parsed prior to determining an `operationId` to be unresolvable.
227+
This requires parsing all referenced documents prior to determining an `operationId` to be unresolvable.
227228

228-
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.
229+
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 appropriately typed sub-object of the Components Object.
229230
For example, the component name of the Schema Object at `#/components/schemas/Foo` is `Foo`.
230-
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.
231-
This means that resolving component names and tag names both depend on starting from the correct OpenAPI Object.
231+
The implicit connection of `tags` in the Operation Object uses the `name` field of Tag Objects, which (like the Components Object) are found under the root OpenAPI Object.
232+
This means resolving component names and tag names both depend on starting from the correct OpenAPI Object.
232233

233234
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.
234235
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.
235236

236237
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`.
237238

238-
There currently are no URI-based alternatives for the Security Requirement Object or for the Operation Object's `tags` field.
239+
There are no URI-based alternatives for the Security Requirement Object or for the Operation Object's `tags` field.
239240
These limitations are expected to be addressed in a future release.
240241

241242
Note that no aspect of implicit connection resolution changes how [URIs are resolved](#relativeReferencesURI), or restricts their possible targets.

0 commit comments

Comments
 (0)