From 5d93c5469c8a7fcf62324b5b63eb3e4b465ca629 Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Mon, 20 Feb 2017 15:56:23 -0800 Subject: [PATCH 1/4] added clarification for examples --- versions/3.0.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index fb5e32c04b..f8889fee8b 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -765,7 +765,7 @@ Field Name | Type | Description 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`. 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 ---|:---:|--- schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body. -examples | [Examples Array](#examplesArray) | Examples of the content type. -example | [Example Object](#exampleObject) | Example of the content type. +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 +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 #### 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`: From 3ec85a2521f9d4404a881356c66fb8e63962854f Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Mon, 20 Feb 2017 16:39:36 -0800 Subject: [PATCH 2/4] fixed zip example --- versions/3.0.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index f8889fee8b..23bebf5ddb 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -2193,10 +2193,11 @@ definitions: parameters: - name: 'zipCode' in: 'query' - type: 'string' - format: 'zip-code' - example: - $ref: 'http://foo.bar#/examples/zip-example' + schema: + type: 'string' + format: 'zip-code' + example: + $ref: 'http://foo.bar#/examples/zip-example' # in a response, note the plural `examples`: responses: 200: From d16249768e64d6fd8f58419994f341e9156fc201 Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Tue, 21 Feb 2017 11:32:12 -0800 Subject: [PATCH 3/4] fixes per @OAI/TDC discussion --- versions/3.0.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 23bebf5ddb..330442c4ed 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -764,8 +764,13 @@ Field Name | Type | Description explode | `boolean` | When this is true, parameter values of type `array` or `object` generate seperate parameters for each value of the array, or key-value-pair of the map. For other types of parameters this property has no effect. The default value is false. 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`. schema | [Schema Object](#schemaObject) | The schema defining the type used for the parameter. +examples | [Examples Array](#examplesArray) | Examples of the content type. Each example in the Examples Array must be in the correct format as specified parameter encoding. The `examples` object is mutually exclusive to the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value will _override_ the example provided by the schema. +example | [Example Object](#exampleObject) | Example of the content type. The example object _must_ be in the correct format as specified in the parameter encoding. The `example` object is mutually exclusive to the `examples` object. Furthermore, if referencing a `schema` which contains an example, the `example` value will _override_ the example provided by the the schema. -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. +For more complex scenarios a `content` object can be used to define the media-type +and schema of the parameter. This option is mutually exclusive with the simple scenario +above. When `example` or `examples` are provided in conjunction with the `schema` object, +the example must follow the prescribed serialization strategy for the parameter. Field Name | Type | Description ---|:---:|--- @@ -1068,8 +1073,8 @@ Each content type object provides schema and examples for a the media type ident Field Name | Type | Description ---|:---:|--- schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body. -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 -example | [Example Object](#exampleObject) | Example of the content type. The example object _must_ be in the correct format as specified in the _content_ type. +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. The `examples` object is mutually exclusive to the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value will _override_ the example provided by the schema. +example | [Example Object](#exampleObject) | Example of the content type. The example object _must_ be in the correct format as specified in the _content_ type. The `example` object is mutually exclusive to the `examples` object. Furthermore, if referencing a `schema` which contains an example, the `example` value will _override_ the the example provided by the schema. ##### Patterned Fields Field Pattern | Type | Description From 283006cce3b817c6c9d98c9f8b8d5f7647152d5c Mon Sep 17 00:00:00 2001 From: Tony Tam Date: Wed, 22 Feb 2017 09:27:27 -0800 Subject: [PATCH 4/4] updated must ~~> should per @OAI/tdc --- versions/3.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index 330442c4ed..57823f81cf 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -1074,7 +1074,7 @@ Field Name | Type | Description ---|:---:|--- schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body. 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. The `examples` object is mutually exclusive to the `example` object. Furthermore, if referencing a `schema` which contains an example, the `examples` value will _override_ the example provided by the schema. -example | [Example Object](#exampleObject) | Example of the content type. The example object _must_ be in the correct format as specified in the _content_ type. The `example` object is mutually exclusive to the `examples` object. Furthermore, if referencing a `schema` which contains an example, the `example` value will _override_ the the example provided by the schema. +example | [Example Object](#exampleObject) | Example of the content type. The example object _should_ be in the correct format as specified in the _content_ type. The `example` object is mutually exclusive to the `examples` object. Furthermore, if referencing a `schema` which contains an example, the `example` value will _override_ the the example provided by the schema. ##### Patterned Fields Field Pattern | Type | Description