The examples keyword is not supported inside schema (OAI#2042)

* examples not supported inside schema

* figured it out

* a tiny little edit

Signed-off-by: Mike Ralphson <[email protected]>

Author: Phil Sturgeon

versions/3.1.0.md

@@ -1031,11 +1031,11 @@ For simpler scenarios, a [`schema`](#parameterSchema) and [`style`](#parameterSt
 Field Name | Type | Description
 ---|:---:|---
 <a name="parameterStyle"></a>style | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `query` - `form`; for `path` - `simple`; for `header` - `simple`; for `cookie` - `form`.
-<a name="parameterExplode"></a>explode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map.  For other types of parameters this property has no effect. When [`style`](#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.
+<a name="parameterExplode"></a>explode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When [`style`](#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.
 <a name="parameterAllowReserved"></a>allowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`.
 <a name="parameterSchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the parameter.
-<a name="parameterExample"></a>example | Any | Example of the media type.  The example SHOULD match the specified schema and encoding properties if present.  The `example` field is mutually exclusive of the `examples` field.  Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.
-<a name="parameterExamples"></a>examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type.  Each example SHOULD contain a value in the correct format as specified in the parameter encoding.  The `examples` field is mutually exclusive of the `example` field.  Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema.
+<a name="parameterExample"></a>example | Any | Example of the parameter's potential value. The example SHOULD match the specified schema and encoding properties if present. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` that contains an example, the `example` value SHALL _override_ the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.
+<a name="parameterExamples"></a>examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the parameter's potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` that contains an example, the `examples` value SHALL _override_ the example provided by the schema.
 
 For more complex scenarios, the [`content`](#parameterContent) property can define the media type and schema of the parameter.
 A parameter MUST contain either a `schema` property, or a `content` property, but not both.
@@ -1044,7 +1044,7 @@ When `example` or `examples` are provided in conjunction with the `schema` objec
 
 Field Name | Type | Description
 ---|:---:|---
-<a name="parameterContent"></a>content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing the representations for the parameter. The key is the media type and the value describes it.  The map MUST only contain one entry.
+<a name="parameterContent"></a>content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.
 
 ##### Style Values
 
@@ -1955,18 +1955,6 @@ validate compatibility automatically, and reject the example value(s) if incompa
 
 ##### Example Object Examples
 
-In a model:
-
-```yaml
-schemas:
-  properties:
-    name:
-      type: string
-      examples:
-        name:
-          $ref: https://example.org/petapi-examples/openapi.json#/components/examples/name-example
-```
-
 In a request body:
 
 ```yaml
@@ -2003,9 +1991,9 @@ parameters:
     schema:
       type: 'string'
       format: 'zip-code'
-      examples:
-        zip-example: 
-          $ref: '#/components/examples/zip-example'
+    examples:
+      zip-example: 
+        $ref: '#/components/examples/zip-example'
 ```
 
 In a response: