added clarification for examples
MODIFY
versions/3.0.md
versions/3.0.md
@@ -765,7 +765,7 @@ Field Name | Type | Description
<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.
-For more complex scenarios a `content` object can be used to define the media-type and schema of the parameter.
+For more complex scenarios a `content` object can be used to define the media-type and schema of the parameter. Note that because the `content` object provides the appropriate serialization between examples and content serialization strategies, the `example` is not allowed in the simple `schema` scenario.
Field Name | Type | Description
---|:---:|---
@@ -1068,8 +1068,8 @@ Each content type object provides schema and examples for a the media type ident
Field Name | Type | Description
---|:---:|---
<a name="contentTypeSchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body.
-<a name="contentTypeExamples"></a>examples | [Examples Array](#examplesArray) | Examples of the content type.
-<a name="contentTypeExample"></a>example | [Example Object](#exampleObject) | Example of the content type.
+<a name="contentTypeExamples"></a>examples | [Examples Array](#examplesArray) | Examples of the content type. Each example in the Examples Array must be in the correct format as specified in the _content_ type
+<a name="contentTypeExample"></a>example | [Example Object](#exampleObject) | Example of the content type. The example object _must_ be in the correct format as specified in the _content_ type.
##### Patterned Fields
Field Pattern | Type | Description
@@ -1102,10 +1102,10 @@ application/json:
schema:
$ref: "#/definitions/Pet"
examples:
+ # converted directly from YAML to JSON
- name: Fluffy
petType: Cat
- - name: Rover
- petType: Frog
+ - {"name": "Rover", "petType": "Frog"}
```
@@ -2153,13 +2153,15 @@ description: Pets operations
#### <a name="examplesObject"></a>Examples Object
-Anywhere an `example` may be given, allow a $ref object.
-This does mean that `example`, structurally, can be either a string primitive or an object, like `additionalProperties`.
+Anywhere an `example` may be given, a JSON Reference may be used, with the
+explicit restriction that examples having a JSON format with object named
+`$ref` are not allowed. This does mean that `example`, structurally, can be
+either a string primitive or an object, similar to `additionalProperties`.
-In locations where the field being provided an `example` is a scalar value _or_ has it's content-type definition determined by a higher-level construct (a response payload, for example, uses the `produces` attribute to select the correct message format), the plural `examples` shall be used, and the payload format be specified as a key to the example.
-
-In all cases, the payload is expected to be compatible with the type schema for the value that it is accompanying.
-Tooling Specifications may choose to validate compatibility automatically, and reject the example value(s) if they are not compatible.
+In all cases, the payload is expected to be compatible with the type schema
+for the value that it is accompanying. Tooling implementations may choose to
+validate compatibility automatically, and reject the example value(s) if they
+are not compatible.
```yaml
# in a model
@@ -2181,20 +2183,18 @@ definitions:
- {"bar": "baz"}
'application/xml':
examples:
- -
- $ref: 'http://foo.bar#/examples/address-example.xml'
+ - $ref: 'http://foo.bar#/examples/address-example.xml'
'text/plain':
examples:
- -
- $ref: 'http://foo.bar#/examples/address-example.txt'
+ - $ref: 'http://foo.bar#/examples/address-example.txt'
# in a parameter
parameters:
- - name: 'zip'
+ - name: 'zipCode'
in: 'query'
type: 'string'
- format: 'zip'
+ format: 'zip-code'
example:
$ref: 'http://foo.bar#/examples/zip-example'
# in a response, note the plural `examples`:

added clarification for examples