Conversation
| <a name="oasVersion"></a>openapi | `string` | **REQUIRED**. Specifies the OpenAPI Specification version being used. It can be used by tooling specifications and clients to interpret the version. The structure SHALL be `major`.`minor`.`patch`, where `patch` versions MUST be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling SHOULD typically be compatible with the corresponding `major`.`minor` (3.0.\*). Patch versions will correspond to patches of this document. | ||
| <a name="oasInfo"></a>info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata can be used by the clients if needed. | ||
| <a name="oasServers"></a>servers | [[Server Object](#serverObject)] | An array of Server Objects which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`. | ||
| <a name="oasServers"></a>servers | [[Server Object](#serverObject)] | An array of Server Objects that provides connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`. |
There was a problem hiding this comment.
It is the server objectS which provide the connectivity, not the array, so I think 'which provide' is correct.
There was a problem hiding this comment.
ok, tks. Corrected PR to make the verb match Server Objects and added a comma before which to clarify things.
| Field Name | Type | Description | ||
| ---|:---:|--- | ||
| <a name="oasVersion"></a>openapi | `string` | **REQUIRED**. Specifies the OpenAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version. The structure SHALL be `major`.`minor`.`patch`, where `patch` versions MUST be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling SHOULD typically be compatible with the corresponding `major`.`minor` (3.0.\*). Patch versions will correspond to patches of this document. | ||
| <a name="oasVersion"></a>openapi | `string` | **REQUIRED**. Specifies the OpenAPI Specification version being used. It can be used by tooling specifications and clients to interpret the version. The structure SHALL be `major`.`minor`.`patch`, where `patch` versions MUST be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling SHOULD typically be compatible with the corresponding `major`.`minor` (3.0.\*). Patch versions will correspond to patches of this document. |
There was a problem hiding this comment.
Should we specify that the OpenAPI Specification version is a Semantic Version 2.0.0 version number?
| Field Name | Type | Description | ||
| ---|:---:|--- | ||
| <a name="oasVersion"></a>openapi | `string` | **REQUIRED**. Specifies the OpenAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version. The structure SHALL be `major`.`minor`.`patch`, where `patch` versions MUST be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling SHOULD typically be compatible with the corresponding `major`.`minor` (3.0.\*). Patch versions will correspond to patches of this document. | ||
| <a name="oasVersion"></a>openapi | `string` | **REQUIRED**. Specifies the OpenAPI Specification version being used. It can be used by tooling specifications and clients to interpret the version. The structure SHALL be `major`.`minor`.`patch`, where `patch` versions MUST be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling SHOULD typically be compatible with the corresponding `major`.`minor` (3.0.\*). Patch versions will correspond to patches of this document. |
There was a problem hiding this comment.
This is inconsistent with #1164 for "OpenAPI Version String" which adds, "The patch MAY be suffixed by a hyphen and extra alphanumeric characters." Remove redundancy; I think it is sufficient here to here note that this string is the [OpenAPI Version String](#oasVersionString) without repeating the major.minor.patch syntax (i.e. link to the immediately following section).
I think the information here about compatibility and tooling belongs in the OpenAPI Version String section below, or better in a higher level section which discusses OAS versioning (not just the version of the OpenAP definition file). The last two paragraphs are also more about the OAS versioning and not really the OpenAPI Version String in the Info Object.
Also, if we do not say that OAS uses semver, then we should be more specific here and should say that major, minor and patch are non-negative integers and patch may have a suffix consisting of a hyphen - and additional alphanumeric characters. (But I suggest we instead say we use semver so we don't have to define all that.)
Note the current 3.0.0-rc2 is a prerelease version which does not conform to this syntax here (unless we diverge from semver and claim that patch == 0.rc2 but I do not think we should do that.
|
Approved by @OAI/tdc. |
4 participants
No description provided.