From 89e151233b8adb041dd673ec9c9cf601ff827ca7 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 2 May 2024 11:34:58 -0700 Subject: [PATCH 01/10] Clarify resolving implicit connections (3.1.1) This clarifies how to handle resolving implicit (non-URI-based) connections in multi-document OpenAPI Descriptions. While the behavior is implementation-defined overall, two approaches are RECOMMENDED for tool developers and OAD authors: one that is best suited for sharing components among OADs, and one that is compatible with pre-3.1 parsing approaches and is convenient for breaking a monolithic document up purely for author convenience. Note that the term "complete OpenAPI document" has been defined in another change pending approval on the 3.0.4 branch. --- versions/3.1.1.md | 45 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 00f035fbfe..15a1055e35 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -182,12 +182,55 @@ It is the responsibility of an embedding format to define how to parse embedded When parsing an OAD, JSON or YAML objects are parsed into specific Objects (such as [Operation Objects](#operationObject), [Response Objects](#responseObject), [Reference Objects](#referenceObject), etc.) based on the parsing context. Depending on how references are arranged, a given JSON or YAML object can be parsed in multiple different contexts: -* As a full OpenAPI Description document (an [OpenAPI Object](#oasObject) taking up an entire document) +* As a complete OpenAPI Description document * As the Object type implied by its parent Object within the document * As a reference target, with the Object type matching the reference source's context 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. +#### Resolving Indirect Connections + +Several features of this specification require resolving a non-URI-based connection to some other part of the OpenAPI Description (OAD). Most connections 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. + +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. In some cases, an unambiguous alternative is available, and OAD authors are RECOMMENDED to always use the alternative: + +Source Object | Source | Target Object | Target | Alternative +------------- | ------ | ------------- | ------ | ----------- +[Security Requirement Object](#securityRequirementObject) | `{name}` | [Components Object](#componentsObject) | [Security Scheme Object](#securitySchemeObject) component name | _n/a_ +[Discriminator Object](#discriminatorObject) | `mapping` _(implicit or by name)_ | Components Object | [Schema Object](#schemaObject) component name | `mapping` _(explicit URI for all instance values)_ +[Link Object](#linkObject) | `operationId` | [Path Item Object](#pathItemObject) | `operationId` | `operationRef` +[Paths Object](#pathsObject) | _prefix to_ `/{path}` | [Server Object](#serverObject) _at top level_ | `url` | _n/a_ + +Note that since this version of the OAS requires parsing all documents completely, there is no need to search for Schema Objects using `allOf` to participate in a [Discriminator Object](#discriminatorObject)'s hierarchy. +When using `mapping` to provide explicit Schema Object URIs, some relative URI-references consisting of a single path segment are also valid component names. +In such cases OAD authors SHOULD use the `.` path segment (e.g. "`./foo`" instead of "`foo`") to ensure that the `mapping` values are processed as URIs rather than names. + +Note also that Server Objects local to Path Item Objects or Operation Objects are always unambiguous. + +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. + +##### OADs Using Only Complete Documents + +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. +This OAD design is RECOMMENDED when sharing components among multiple OADs. + +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. + +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`. +Other Path Item Objects can still be connected via `operationRef`. + +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. +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). + +##### OADs With Only One OpenAPI Object + +The approach in this section is RECOMMENDED for OADs where the entry OpenAPI document is the only document containing an OpenAPI Object. +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. + +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. + +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. + ### Data Types Data types in the OAS are based on the types supported by the [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.2.1). From 1a2971015e97dfebc0975ed808a3cd2e27771bc9 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 20 May 2024 17:01:21 -0700 Subject: [PATCH 02/10] Better table, remove some discriminator info Some of what this said about the Discriminator Object is better handled in that Object's section, which is being revised in another PR. --- versions/3.1.1.md | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 15a1055e35..aee2bfe76c 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -190,22 +190,18 @@ If the same JSON/YAML object is parsed multiple times and the respective context #### Resolving Indirect Connections -Several features of this specification require resolving a non-URI-based connection to some other part of the OpenAPI Description (OAD). Most connections 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. +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. -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. In some cases, an unambiguous alternative is available, and OAD authors are RECOMMENDED to always use the alternative: +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. +In some cases, an unambiguous URI-based alternative is available, and OAD authors are RECOMMENDED to always use the alternative: -Source Object | Source | Target Object | Target | Alternative -------------- | ------ | ------------- | ------ | ----------- -[Security Requirement Object](#securityRequirementObject) | `{name}` | [Components Object](#componentsObject) | [Security Scheme Object](#securitySchemeObject) component name | _n/a_ -[Discriminator Object](#discriminatorObject) | `mapping` _(implicit or by name)_ | Components Object | [Schema Object](#schemaObject) component name | `mapping` _(explicit URI for all instance values)_ -[Link Object](#linkObject) | `operationId` | [Path Item Object](#pathItemObject) | `operationId` | `operationRef` -[Paths Object](#pathsObject) | _prefix to_ `/{path}` | [Server Object](#serverObject) _at top level_ | `url` | _n/a_ +Source | Target | Alternative +------ | ------ | ----------- +[Security Requirement Object](#securityRequirementObject) `{name}` | [Security Scheme Object](#securitySchemeObject) name under the [Components Object](#componentsObject) | _n/a_ +[Discriminator Object](#discriminatorObject) `mapping` _(implicit, or explicit name syntax)_ | [Schema Object](#schemaObject) name under the Components Object | `mapping` _(explicit URI syntax)_ +[Link Object](#linkObject) `operationId` | [Path Item Object](#pathItemObject) `operationId` | `operationRef` -Note that since this version of the OAS requires parsing all documents completely, there is no need to search for Schema Objects using `allOf` to participate in a [Discriminator Object](#discriminatorObject)'s hierarchy. -When using `mapping` to provide explicit Schema Object URIs, some relative URI-references consisting of a single path segment are also valid component names. -In such cases OAD authors SHOULD use the `.` path segment (e.g. "`./foo`" instead of "`foo`") to ensure that the `mapping` values are processed as URIs rather than names. - -Note also that Server Objects local to Path Item Objects or Operation Objects are always unambiguous. +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. 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. From b23b9458eeb8b6cb1afdb84258eb4ebd76c08437 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 20 May 2024 20:57:21 -0700 Subject: [PATCH 03/10] Trim down implict resolution text further. Some servers/discriminator text that should have been removed in the previous commit was accidentally left in. Several non-essential recommendations have been removed. --- versions/3.1.1.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index aee2bfe76c..0a60425846 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -190,7 +190,7 @@ If the same JSON/YAML object is parsed multiple times and the respective context #### Resolving Indirect Connections -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. +Several features of this specification require resolving a non-URI-based connection to some other part of the OpenAPI Description (OAD). 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. 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 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. This OAD design is RECOMMENDED when sharing components among multiple OADs. -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. +In this approach, each document is self-contained and resolves components to its own Components Object. +When resolving an `operationId`, all Path Item Objects from all parsed documents are considered. +This requires ensuring that all referenced documents have been parsed prior to determining an `operationId` to be unresolvable. -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`. -Other Path Item Objects can still be connected via `operationRef`. - -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. -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). +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. +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. ##### OADs With Only One OpenAPI Object The approach in this section is RECOMMENDED for OADs where the entry OpenAPI document is the only document containing an OpenAPI Object. -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. - -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. +This approach is most suitable for splitting an otherwise self-contained single-document OAD into multiple documents for author convenience. -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. +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. ### Data Types From a1305d4747f087b3e4ca7ed86ab3c24f8e0923e1 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Tue, 21 May 2024 11:53:28 -0700 Subject: [PATCH 04/10] Remove the "from future "compatibility idea If we want to do this sort of thing it is probably best discussed separately. --- versions/3.1.1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 0a60425846..c21fc570d0 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -214,8 +214,8 @@ In this approach, each document is self-contained and resolves components to its When resolving an `operationId`, all Path Item Objects from all parsed documents are considered. This requires ensuring that all referenced documents have been parsed prior to determining an `operationId` to be unresolvable. -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. -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. +**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. +This limitation is expected to be addressed in the next minor version of this specification. ##### OADs With Only One OpenAPI Object From 0c72000f1504e30dd6f69f34e0c25f1f0c75bb34 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Wed, 22 May 2024 10:31:19 -0700 Subject: [PATCH 05/10] Improve wording from review feedback Also fix an incorrect section anchor. --- versions/3.1.1.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index c21fc570d0..c60e974fd0 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -188,7 +188,7 @@ When parsing an OAD, JSON or YAML objects are parsed into specific Objects (such 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. -#### Resolving Indirect Connections +#### Resolving Indirect Connections Several features of this specification require resolving a non-URI-based connection to some other part of the OpenAPI Description (OAD). @@ -204,13 +204,15 @@ Source | Target | Alternative 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. 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. +Note that neither approach changes how [URIs are resolved](##relativeReferencesURI), or restricts their possible targets. ##### OADs Using Only Complete Documents -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. +The approach in this section is RECOMMENDED for OADs that are composed entirely of complete documents. +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. This OAD design is RECOMMENDED when sharing components among multiple OADs. -In this approach, each document is self-contained and resolves components to its own Components Object. +In this approach, each document is self-contained and resolves component names to its own Components Object. When resolving an `operationId`, all Path Item Objects from all parsed documents are considered. This requires ensuring that all referenced documents have been parsed prior to determining an `operationId` to be unresolvable. From 1db3d6e12bdc9090cc4f2af2b264ed19da9f566e Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 22 May 2024 13:13:46 -0700 Subject: [PATCH 06/10] Be cautious about future features Co-authored-by: Ralf Handl --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index c60e974fd0..76ca3a6724 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -217,7 +217,7 @@ When resolving an `operationId`, all Path Item Objects from all parsed documents This requires ensuring that all referenced documents have been parsed prior to determining an `operationId` to be unresolvable. **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. -This limitation is expected to be addressed in the next minor version of this specification. +This limitation is expected to be addressed in a future version of this specification. ##### OADs With Only One OpenAPI Object From 5958e6fb7d3324fef5da59a11256558a7331c2ad Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Wed, 22 May 2024 20:06:41 -0700 Subject: [PATCH 07/10] fix broken markdown link --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 76ca3a6724..d0adc55678 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -204,7 +204,7 @@ Source | Target | Alternative 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. 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. -Note that neither approach changes how [URIs are resolved](##relativeReferencesURI), or restricts their possible targets. +Note that neither approach changes how [URIs are resolved](#relativeReferencesURI), or restricts their possible targets. ##### OADs Using Only Complete Documents From 25a962942e42ce80be31b528541e03a41fa1c538 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 23 May 2024 11:11:32 -0700 Subject: [PATCH 08/10] 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. --- versions/3.1.1.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index d0adc55678..e0f466d976 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -188,7 +188,7 @@ When parsing an OAD, JSON or YAML objects are parsed into specific Objects (such 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. -#### Resolving Indirect Connections +#### Resolving Implicit Connections Several features of this specification require resolving a non-URI-based connection to some other part of the OpenAPI Description (OAD). @@ -203,7 +203,12 @@ Source | Target | Alternative 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. -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. +It is RECOMMENDED to consider all Operation Objects from all parsed documents When resolving any Link Object `operationId`. +This requires ensuring that all referenced documents have been parsed prior to determining an `operationId` to be unresolvable. + +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. +For example, the component name of the Schema Object at `#/components/schemas/Foo` is `Foo`. +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. Note that neither approach changes how [URIs are resolved](#relativeReferencesURI), or restricts their possible targets. ##### OADs Using Only Complete Documents @@ -213,8 +218,6 @@ Standalone JSON Schema documents can be included along with complete OpenAPI Doc This OAD design is RECOMMENDED when sharing components among multiple OADs. In this approach, each document is self-contained and resolves component names to its own Components Object. -When resolving an `operationId`, all Path Item Objects from all parsed documents are considered. -This requires ensuring that all referenced documents have been parsed prior to determining an `operationId` to be unresolvable. **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. This limitation is expected to be addressed in a future version of this specification. From bddfb07925f831cec8abd4b3eef64fcf09375add Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 23 May 2024 12:37:16 -0700 Subject: [PATCH 09/10] Fix typo (review feedback) Co-authored-by: Ralf Handl --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index e0f466d976..599660f458 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -203,7 +203,7 @@ Source | Target | Alternative 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. -It is RECOMMENDED to consider all Operation Objects from all parsed documents When resolving any Link Object `operationId`. +It is RECOMMENDED to consider all Operation Objects from all parsed documents when resolving any Link Object `operationId`. This requires ensuring that all referenced documents have been parsed prior to determining an `operationId` to be unresolvable. 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. From b71e80b0ec7c6cc9f0fa5bf5ce756c88c6d45e44 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Fri, 24 May 2024 11:20:32 -0700 Subject: [PATCH 10/10] Add implicit tag connections These were left out but have the same problems as Security Requirements. --- versions/3.1.1.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 599660f458..5b1ec60e81 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -199,16 +199,20 @@ Source | Target | Alternative ------ | ------ | ----------- [Security Requirement Object](#securityRequirementObject) `{name}` | [Security Scheme Object](#securitySchemeObject) name under the [Components Object](#componentsObject) | _n/a_ [Discriminator Object](#discriminatorObject) `mapping` _(implicit, or explicit name syntax)_ | [Schema Object](#schemaObject) name under the Components Object | `mapping` _(explicit URI syntax)_ +[Operation Object](#operationObject) `tags` | [Tag Object](#tagObject) `name` (in the Components Object) | _n/a_ [Link Object](#linkObject) `operationId` | [Path Item Object](#pathItemObject) `operationId` | `operationRef` -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. +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. It is RECOMMENDED to consider all Operation Objects from all parsed documents when resolving any Link Object `operationId`. This requires ensuring that all referenced documents have been parsed prior to determining an `operationId` to be unresolvable. 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. For example, the component name of the Schema Object at `#/components/schemas/Foo` is `Foo`. -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. +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. +This means that resolving component names and tag names both depend on starting from the correct OpenAPI Object. + +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. Note that neither approach changes how [URIs are resolved](#relativeReferencesURI), or restricts their possible targets. ##### OADs Using Only Complete Documents @@ -217,9 +221,10 @@ The approach in this section is RECOMMENDED for OADs that are composed entirely 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. This OAD design is RECOMMENDED when sharing components among multiple OADs. -In this approach, each document is self-contained and resolves component names to its own Components Object. +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. -**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. +**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. +That means that in this approach, they can currently only connect to Security Scheme and Tag Objects within the same document. This limitation is expected to be addressed in a future version of this specification. ##### OADs With Only One OpenAPI Object