Merge branch 'v3.0.4-dev' into v3.0.4-dev

Author: handrews

versions/3.0.4.md

@@ -171,6 +171,8 @@ Two formats, `binary` and `byte`, describe different ways to work with binary da
 * `binary` is used where unencoded binary data is allowed, such as when sending a binary payload as an HTTP message body, or as part of a `multipart/*` payload that allows binary parts
 * `byte` is used where binary data is embedded in a text-only format such as `application/json` or `application/x-www-form-urlencoded`
 
+The `maxLength` keyword MAY be used to set an expected upper bound on the length of a streaming payload.  The keyword can be applied to either string data, including encoded binary data, or to unencoded binary data.  For unencoded binary, the length is the number of octets.
+
 Note that the encoding indicated by `byte`, which inflates the size of data in order to represent it as 7-bit ASCII text, is unrelated to HTTP's `Content-Encoding` header, which indicates whether and how a message body has been compressed.
 
 ### <a name="richText"></a>Rich Text Formatting
@@ -1048,16 +1050,17 @@ Field Name | Type | Description
 
 In order to support common ways of serializing simple parameters, a set of `style` values are defined.
 
-`style` | [`type`](#dataTypes) |  `in` | Comments
+`style` | [`type`](#dataTypes) | `in` | Comments
 ----------- | ------ | -------- | --------
-matrix |  `primitive`, `array`, `object` |  `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7) 
-label | `primitive`, `array`, `object` |  `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5)
-form |  `primitive`, `array`, `object` |  `query`, `cookie` | Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` (when `explode` is false) or `multi` (when `explode` is true) value from OpenAPI 2.0.
-simple | `primitive`, `array`, `object` | `path`, `header` | Simple style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.2).  This option replaces `collectionFormat` with a `csv` value from OpenAPI 2.0.
+matrix | `primitive`, `array`, `object` | `path` | Path-style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.7)
+label | `primitive`, `array`, `object` | `path` | Label style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.5)
+simple | `primitive`, `array`, `object` | `path`, `header` | Simple style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.2). This option replaces `collectionFormat` with a `csv` value from OpenAPI 2.0.
+form | `primitive`, `array`, `object` | `query`, `cookie` | Form style parameters defined by [RFC6570](https://tools.ietf.org/html/rfc6570#section-3.2.8). This option replaces `collectionFormat` with a `csv` (when `explode` is false) or `multi` (when `explode` is true) value from OpenAPI 2.0.
 spaceDelimited | `array`, `object` | `query` | Space separated array values or object properties and values. This option replaces `collectionFormat` equal to `ssv` from OpenAPI 2.0.
 pipeDelimited | `array`, `object` | `query` | Pipe separated array values or object properties and values. This option replaces `collectionFormat` equal to `pipes` from OpenAPI 2.0.
 deepObject | `object` | `query` | Provides a simple way of rendering nested objects using form parameters.
 
+The behavior of applying a style that uses a delimiter to data containing that delimiter is not defined, and is therefore NOT RECOMMENDED.  To ensure interoperability, any such delimiter characters need to be escaped prior to serializing with the style, and unescaped after parsing.  In the case of `spaceDelimited`, care must be taken to avoid confusing interactions with URL parameter encoding of spaces.
 
 ##### Style Examples
 
@@ -1074,12 +1077,12 @@ The following table shows examples of rendering differences for each value.
 ----------- | ------ | -------- | -------- | -------- | -------
 matrix | false | ;color | ;color=blue | ;color=blue,black,brown | ;color=R,100,G,200,B,150
 matrix | true | ;color | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150
-label | false | .  | .blue |  .blue,black,brown | .R,100,G,200,B,150
-label | true | . | .blue |  .blue.black.brown | .R=100.G=200.B=150
-form | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150
-form | true | color= | color=blue | color=blue&color=black&color=brown | R=100&G=200&B=150
+label | false | . | .blue | .blue,black,brown | .R,100,G,200,B,150
+label | true | . | .blue | .blue.black.brown | .R=100.G=200.B=150
 simple | false | n/a | blue | blue,black,brown | R,100,G,200,B,150
 simple | true | n/a | blue | blue,black,brown | R=100,G=200,B=150
+form | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150
+form | true | color= | color=blue | color=blue&color=black&color=brown | R=100&G=200&B=150
 spaceDelimited | false | n/a | n/a | color=blue%20black%20brown | color=R%20100%20G%20200%20B%20150
 pipeDelimited | false | n/a | n/a | color=blue\|black\|brown | color=R\|100\|G\|200\|B\|150
 deepObject | true | n/a | n/a | n/a | color[R]=100&color[G]=200&color[B]=150
@@ -1373,7 +1376,7 @@ Field Name | Type | Description
 <a name="mediaTypeSchema"></a>schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the content of the request, response, or parameter.
 <a name="mediaTypeExample"></a>example | Any | Example of the media type.  The example object SHOULD be in the correct format as specified by the media type.  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.
 <a name="mediaTypeExamples"></a>examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type.  Each example object SHOULD  match the media type and specified schema if present.  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="mediaTypeEncoding"></a>encoding | Map[`string`, [Encoding Object](#encodingObject)] | A map between a property name and its encoding information. The key, being the property name, MUST exist in the schema as a property. The encoding object SHALL only apply to `requestBody` objects when the media type is `multipart` or `application/x-www-form-urlencoded`.
+<a name="mediaTypeEncoding"></a>encoding | Map[`string`, [Encoding Object](#encodingObject)] | A map between a property name and its encoding information. The key, being the property name, MUST exist in the schema as a property. The encoding attribute SHALL only apply to [Request Body Objects](#requestBodyObject), and only when the media type is `multipart` or `application/x-www-form-urlencoded`.  If no Encoding Object is provided for a property, the behavior is determined by the default values documented for the Encoding Object.
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
@@ -1567,7 +1570,7 @@ requestBody:
               $ref: '#/components/schemas/Address'
 ```
 
-An `encoding` attribute is introduced to give you control over the serialization of parts of `multipart` request bodies.  This attribute is _only_ applicable to `multipart` and `application/x-www-form-urlencoded` request bodies.
+An `encoding` attribute is introduced to give you control over the serialization of parts of `multipart` request bodies.  This attribute is _only_ applicable to request bodies, and _only_ for `multipart` and `application/x-www-form-urlencoded` media types.
 
 #### <a name="encodingObject"></a>Encoding Object
 
@@ -2124,7 +2127,7 @@ field in an [Operation Object](#operationObject)), references MAY also be made t
 links:
   UserRepositories:
     # returns array of '#/components/schemas/repository'
-    operationRef: '#/paths/~12.0~1repositories~1{username}/get'
+    operationRef: '#/paths/~12.0~1repositories~1%7Busername%7D/get'
     parameters:
       username: $response.body#/username
 ```
@@ -2135,13 +2138,14 @@ or an absolute `operationRef`:
 links:
   UserRepositories:
     # returns array of '#/components/schemas/repository'
-    operationRef: https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get
+    operationRef: https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1%7Busername%7D/get
     parameters:
       username: $response.body#/username
 ```
 
 Note that in the use of `operationRef`, the _escaped forward-slash_ is necessary when 
-using JSON references.
+using JSON Pointers, and it is necessary to URL-encode `{` and `}` as `%7B` and `%7D`, respectively when
+using JSON Pointers as URI fragments.
 
 
 ##### <a name="runtimeExpression"></a>Runtime Expressions
@@ -2718,7 +2722,7 @@ Field Name | Type | Description
 <a name="propertyName"></a>propertyName | `string` | **REQUIRED**. The name of the property in the payload that will hold the discriminator value.
 <a name="discriminatorMapping"></a> mapping | Map[`string`, `string`] | An object to hold mappings between payload values and schema names or references.
 
-The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`.
+The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`.  Note that because the discriminating property's value is used as a component name and/or as the key in the `mapping` object, the behavior of any value that is not a string is undefined.
 
 In OAS 3.0, a response payload MAY be described to be exactly one of any number of types: