Merge pull request OAI#948 from OAI/dm/final-review

Various minor corrections

Author: darrelmiller

versions/3.0.md

@@ -180,7 +180,7 @@ It combines what previously was the Resource Listing and API Declaration (versio
 
 Field Name | Type | Description
 ---|:---:|---
-<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="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 optional array of Server Objects which provide connectivity information to a target server.
 <a name="oasPaths"></a>paths | [Paths Object](#pathsObject) | **Required.** The available paths and operations for the API.
@@ -191,7 +191,7 @@ Field Name | Type | Description
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
 
-#### <a name="oasVersion"></a>OpenAPI Version String
+#### <a name="oasVersionString"></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.
 
@@ -383,7 +383,7 @@ An object representing a Server Variable for server URL template substituion.
 
 Field Name | Type | Description
 ---|:---:|---
-<a name="serverVariableEnum"></a>enum | [ `primitive` ] | An enumeration of primitive type values to be used if the substitution options are from a limited set.
+<a name="serverVariableEnum"></a>enum | [`primitive`] | An enumeration of primitive type values to be used if the substitution options are from a limited set.
 <a name="serverVariableDefault"></a>default | `primitive` |  **Required.** The default value to use for substitution if an alternate value is not specified, and will be sent if an alternative value is _not_ supplied. Unlike the [Schema Object's](#schemaObject) `default`, this value MUST be provided by the consumer.
 <a name="serverVariableDescription"></a>description | `string` | An optional description for the server variable.
 
@@ -409,6 +409,8 @@ Field Pattern | Type | Description
 <a name="componentsLinks"></a> links | Map[`string`, [Link Object](#linkObject)] | An object to hold reusable [Link Objects](#linkObject).
 <a name="componentsCallbacks"></a> callbacks | Map[`string`, [Callback Object](#callbackObject)] | An object to hold reusable [Callback Objects](#callbackObject).
 
+This object can be extended with [Specification Extensions](#specificationExtensions). 
+
 All the fixed fields declared above are objects that MUST use keys that match the regular expression: `[a-zA-Z0-9.\-_]+`.
 
 Field Name Examples:
@@ -1075,20 +1077,23 @@ A free-form query parameter, allowing undefined parameters of a specific type:
 {
   "in": "query",
   "name": "freeForm",
-  "type": "object",
-  "additionalProperties": {
-    "type": "integer"
-  },
+  "schema": {
+    "type": "object",
+    "additionalProperties": {
+      "type": "integer"
+    },
+  }
   "style": "form"
 }
 ```
 
 ```yaml
 in: query
 name: freeForm
-type: object
-additionalProperties:
-  type: integer
+schema:
+  type: object
+  additionalProperties:
+    type: integer
 style: form
 ```
 
@@ -1258,16 +1263,12 @@ Each Media Type Object provides schema and examples for a the media type identif
 ##### Fixed Fields
 Field Name | Type | Description
 ---|:---:|---
-
 <a name="mediaTypeSchema"></a>schema | [Schema Object](#schemaObject) <span>&#124;</span> [Reference Object](#referenceObject)] | The schema defining the type used for the request body.
 <a name="mediaTypeExamples"></a>examples | [[Example Object](#exampleObject) <span>&#124;</span> [Reference Object](#referenceObject)] | Examples of the media type.  Each example in the Examples array SHOULD be in the correct format as specified in the media type.  The `examples` object is mutually exclusive to the `example` object.  Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema.
 <a name="mediaTypeExample"></a>example | [Example Object](#exampleObject) <span>&#124;</span> [Reference Object](#referenceObject) | Example of the media type.  The example object SHOULD be in the correct format as specified in the media type.  The `example` object is mutually exclusive to the `examples` object.  Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the the example provided by the schema.
 <a name="mediaTypeEncoding"></a>encoding | [Encoding Object](#encodingObject) | Encoding of the media type.  The encoding object SHOULD only apply to `requestBody` objects when the content type is `multipart`.
 
-##### Patterned Fields
-Field Pattern | Type | Description
----|:---:|---
-<a name="parameterExtensions"></a>^x- | Any | Allows extensions to the OpenAPI 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.
+This object can be extended with [Specification Extensions](#specificationExtensions). 
 
 ##### Media Type Examples