updates for identification of spec, schema #631
Conversation
|
Also fixes #496 |
| @@ -71,7 +71,7 @@ The schema exposes two types of fields. Fixed fields, which have a declared name | |||
|
|
|||
| The OAS representation of the API is made of a single file. However, parts of the definitions can be split into separate files, at the discretion of the user. This is applicable for `$ref` fields in the specification as follows from the [JSON Schema](http://json-schema.org) definitions. | |||
|
|
|||
| By convention, the OpenAPI Specification (OAS) file is named `swagger.json`. | |||
| By convention, the OpenAPI Specification (OAS) file is named `oas.json`. | |||
There was a problem hiding this comment.
or openapi.yaml and openapi.json
There was a problem hiding this comment.
openapi.json works for me :)
There was a problem hiding this comment.
I prefer openapi.* if we must suggest something, although I prefer if we didn't express a preference for a filename.
|
Schema version + spec version will not necessarily be the same. @OAI/tdc to review by Weds and provide comments? |
| @@ -106,7 +106,8 @@ This is the root document object for the API specification. It combines what pre | |||
|
|
|||
| Field Name | Type | Description | |||
| ---|:---:|--- | |||
| <a name="oasSwagger"></a>swagger | `string` | **Required.** Specifies the OpenAPI Specification version being used. It can be used by the Swagger UI and other clients to interpret the API listing. The value MUST be `"2.0"`. | |||
| <a name="oasSwagger"></a>swagger | `string` | **Required.** Specifies the OpenAPI Specification version being used. It can be used by tooling vendors 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="oasSchema"></a>schema | `string` | An optional URL to a formal OAS schema. If present, tooling _may_ choose to use this for validating the document, and the location _must_ be a formally approved OAS schema produced by the OpenAPI working group. | |||
There was a problem hiding this comment.
Kill this, will cause more harm than good @OAI/tdc
Will publish a formal location of the schema (https://openapis.org/schemas/3.0-latest.json)
|
Regarding the version - reiterating what we discussed (for documentation sake) - the benefits of a patch-level version granularity are clear, but we're also not going to be update the spec (normally) for every minor change. We'll do our best to collect changes and not have a too-frequent release cycle. |
|
Other than that, 👍 from me for the PR (assuming suggested file name and removal of |
|
I have removed the schema reference and |
|
@OAI/tdc please approve or reject |
|
👍 |
2 similar comments
|
👍 |
|
👍 |
updates for identification of spec, schema [Manually ported merge commit] Co-authored-by: Tony Tam <tony@eatbacon.org>
Fixes #561