adds documentation on the openapi attribute and versioning strategy

Author: fehguy

versions/3.0.md

@@ -125,7 +125,7 @@ It combines what previously was the Resource Listing and API Declaration (versio
 
 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 | [OpenAPI Version String](#oasVersion) | **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="oasHosts"></a>hosts | [Hosts Object](#hostsObject) | An array of Host objects which provide `scheme`, `host`, `port`, and `basePath` in an associative manner.
 <a name="oasPaths"></a>paths | [Paths Object](#pathsObject) | **Required.** The available paths and operations for the API.
@@ -140,6 +140,15 @@ Field Pattern | Type | Description
 ---|:---:|---
 <a name="oasExtensions"></a>^x- | Any | Allows extensions to the OAS Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
 
+#### <a name="oasVersion"></a>OpenAPI Version String
+
+The version string signifies the version of the OpenAPI Specification that 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.