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
Copy file name to clipboardExpand all lines: versions/3.1.1.md
+9-4
Original file line number
Diff line number
Diff line change
@@ -199,16 +199,20 @@ Source | Target | Alternative
199
199
------ | ------ | -----------
200
200
[Security Requirement Object](#securityRequirementObject)`{name}` | [Security Scheme Object](#securitySchemeObject) name under the [Components Object](#componentsObject) | _n/a_
201
201
[Discriminator Object](#discriminatorObject)`mapping`_(implicit, or explicit name syntax)_ | [Schema Object](#schemaObject) name under the Components Object | `mapping`_(explicit URI syntax)_
202
+
[Operation Object](#operationObject)`tags` | [Tag Object](#tagObject)`name` (in the Components Object) | _n/a_
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.
205
+
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.
205
206
206
207
It is RECOMMENDED to consider all Operation Objects from all parsed documents when resolving any Link Object `operationId`.
207
208
This requires ensuring that all referenced documents have been parsed prior to determining an `operationId` to be unresolvable.
208
209
209
210
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
211
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.
212
+
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.
213
+
This means that resolving component names and tag names both depend on starting from the correct OpenAPI Object.
214
+
215
+
For resolving component and tag 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.
212
216
Note that neither approach changes how [URIs are resolved](#relativeReferencesURI), or restricts their possible targets.
213
217
214
218
##### OADs Using Only Complete Documents
@@ -217,9 +221,10 @@ The approach in this section is RECOMMENDED for OADs that are composed entirely
217
221
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.
218
222
This OAD design is RECOMMENDED when sharing components among multiple OADs.
219
223
220
-
In this approach, each document is self-contained and resolves component names to its own Components Object.
224
+
In this approach, each document is self-contained and resolves component and tag names to the Components Object and Tag Objects under its own root OpenAPI Object.
221
225
222
-
**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.
226
+
**Note:** Currently, Security Requirement Objects do not support a URI-based mechanism for connecting to Security Scheme Objects, and Operation Objects do not support a URI-based mechanism for connecting to Tag Objects.
227
+
That means that in this approach, they can currently only connect to Security Scheme and Tag Objects within the same document.
223
228
This limitation is expected to be addressed in a future version of this specification.
0 commit comments