Skip to content

Commit 0c72000

Browse files
committed
Improve wording from review feedback
Also fix an incorrect section anchor.
1 parent a1305d4 commit 0c72000

File tree

1 file changed

+5
-3
lines changed

1 file changed

+5
-3
lines changed

versions/3.1.1.md

Lines changed: 5 additions & 3 deletions
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="resolvingIndirectLinkages"></a>Resolving Indirect Connections
191+
#### <a name="resolvingIndirectConnections"></a>Resolving Indirect 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

@@ -204,13 +204,15 @@ Source | Target | Alternative
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

206206
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.
207+
Note that neither approach changes how [URIs are resolved](##relativeReferencesURI), or restricts their possible targets.
207208

208209
##### OADs Using Only Complete Documents
209210

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+
The approach in this section is RECOMMENDED for OADs that are composed entirely of complete documents.
212+
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.
211213
This OAD design is RECOMMENDED when sharing components among multiple OADs.
212214

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

0 commit comments

Comments
 (0)