Merge pull request OAI#1199 from DavidBiesack/semver

Semantic Versioning

Author: Ron

versions/3.0.md

@@ -20,10 +20,12 @@ Additional utilities, such as testing tools, can also use the files.
 <!-- TOC depthFrom:1 depthTo:3 withLinks:1 updateOnSave:1 orderedList:0 -->
 
 - [Definitions](#definitions)
+	- [OpenAPI Definition File](#oasDefinitionFile)
 	- [Path Templating](#pathTemplating)
 	- [Media Types](#mediaTypes)
 	- [HTTP Status Codes](#httpCodes)
 - [Specification](#specification)
+	- [Versions](#versions)
 	- [Format](#format)
 	- [File Structure](#fileStructure)
 	- [Data Types](#dataTypes)
@@ -68,6 +70,9 @@ Additional utilities, such as testing tools, can also use the files.
 
 ## Definitions
 
+##### <a name="oasDefinitionFile"></a>OpenAPI Definition File
+A file or set of files which defines an API. The OpenAPI definition file uses and conforms to the OpenAPI Specification.
+
 ##### <a name="pathTemplating"></a>Path Templating
 Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters.
 
@@ -94,6 +99,16 @@ The available status codes are defined by [RFC7231](http://tools.ietf.org/html/r
 
 ## Specification
 
+### Versions
+
+The OpenAPI Specification is versioned using [Semantic Versioning 2.0.0](http://semver.org/spec/v2.0.0.html) (semver) and follows the semver specification.
+
+The `major`.`minor` portion of the semver (for example `3.0`) SHALL designate the OAS feature set. Typically, *`.patch`* versions address errors in this document, not the feature set. Tooling which supports OAS 3.0 SHOULD be compatible with all OAS 3.0.\* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between `3.0.0` and `3.0.1` for example.
+
+Subsequent minor version releases of the OpenAPI Specification (incrementing the `minor` version number) SHOULD NOT interfere with tooling developed to a lower minor version and same major version.  Thus a hypothetical `3.1.0` specification SHOULD be usable with tooling designed for `3.0.0`.
+
+An OpenAPI definition file compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 definition document contain a top-level version field named [`swagger`](http://swagger.io/specification/#swaggerObject) and value `"2.0"`.)
+
 ### Format
 
 An API description that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
@@ -120,7 +135,7 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA
 
 ### <a name="fileStructure"></a>File Structure
 
-The OAS representation of the API is made of a single file.
+An OpenAPI definition file 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.
 
@@ -141,7 +156,6 @@ Types that are not accompanied by a `format` property follow the type definition
 
 The formats defined by the OAS are:
 
-
 Common Name | [`type`](#dataTypes) | [`format`](#dataTypeFormat) | Comments
 ----------- | ------ | -------- | --------
 integer | `integer` | `int32` | signed 32 bits
@@ -173,13 +187,13 @@ In the following description, if a field is not explicitly **REQUIRED** or descr
 
 #### <a name="oasObject"></a>OpenAPI Object
 
-This is the root document object for the API specification.
+This is the root document object of the [OpenAPI definition file](#oasDefinitionFile).
 
 ##### Fixed Fields
 
 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**. This string MUST be the [semantic version number](http://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI definition file uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI definition file. This is *not* related to the API [`info.version`](#infoVersion) string.
 <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="oasPaths"></a>paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API.
@@ -190,15 +204,6 @@ Field Name | Type | Description
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
 
-#### <a name="oasVersionString"></a>OpenAPI Version String
-
-The version string signifies which OpenAPI Specification version the document complies to.  The format for this string MUST be `major`.`minor`.`patch`.  The `patch` MAY be suffixed by a hyphen and extra alphanumeric characters.
-
-A `major`.`minor` SHALL be used to designate the OpenAPI Specification version, and will be considered compatible with the OpenAPI Specification specified by that `major`.`minor` version.  The patch version will not be considered by tooling, making no distinction between `3.0.0` and `3.0.1`.
-
-In subsequent versions of the OpenAPI Specification, care will be given such that increments of the `minor` version SHOULD NOT interfere with operations of tooling developed to a lower minor version.  Thus a hypothetical `3.1.0` specification SHOULD be usable with tooling designed for `3.0.0`.
-
-
 #### <a name="infoObject"></a>Info Object
 
 The object provides metadata about the API.
@@ -213,7 +218,7 @@ Field Name | Type | Description
 <a name="infoTermsOfService"></a>termsOfService | `string` | A URL to the Terms of Service for the API. MUST be in the format of a URL.
 <a name="infoContact"></a>contact | [Contact Object](#contactObject) | The contact information for the exposed API.
 <a name="infoLicense"></a>license | [License Object](#licenseObject) | The license information for the exposed API.
-<a name="infoVersion"></a>version | `string` | **REQUIRED**. The version of the API definition (which is distinct from the OpenAPI Specification version or the API implementation version).
+<a name="infoVersion"></a>version | `string` | **REQUIRED**. The version of the API definition (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version).
 
 
 This object can be extended with [Specification Extensions](#specificationExtensions).