Update "format" and "content*" for new JSON Schema

This removes OAS formats and examples that are now superfluous
as they are part of the 2019-09 JSON Schema draft.

Similarly it deprecates the "byte" and "binary" formats in favor
of JSON Schema's "contentEncoding" and "contentMediaType" keywords,
and updates various related exapmles and other guidance.

It also removes confusingly blank rows in the OAS format table.

Author: handrews

versions/3.1.0.md

@@ -147,10 +147,10 @@ Primitive data types in the OAS are based on the types supported by the [JSON Sc
 Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. 
 Models are defined using the [Schema Object](#schemaObject), which is a superset of JSON Schema Specification Draft 2019-09.
 
-<a name="dataTypeFormat"></a>Primitives have an optional modifier property: `format`.
-OAS uses several known formats to define in fine detail the data type being used.
+<a name="dataTypeFormat"></a>Primitives have an optional modifier property: `format`, which is defined by JSON Schema.
+OAS uses several known additional formats to define in fine detail the data type being used.
 However, to support documentation needs, the `format` property is an open `string`-valued property, and can have any value.
-Formats such as `"email"`, `"uuid"`, and so on, MAY be used even though undefined by this specification.
+Additional formats MAY be used even though undefined by either JSON Schema or this specification.
 Types that are not accompanied by a `format` property follow the type definition in the JSON Schema. Tools that do not recognize a specific `format` MAY default back to the `type` alone, as if the `format` is not specified.
 
 The formats defined by the OAS are:
@@ -161,14 +161,14 @@ The formats defined by the OAS are:
 `integer` | `int64` | signed 64 bits (a.k.a long)
 `number` | `float` | |
 `number` | `double` | |
-`string` | | |
-`string` | `byte` | base64 encoded characters
-`string` | `binary` | any sequence of octets
-`boolean` | | |
-`string` | `date` | As defined by `full-date` - [RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)
-`string` | `date-time` | As defined by `date-time` - [RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)
 `string` | `password` | A hint to UIs to obscure input.
+`string` | `byte` | base64 encoded characters **Deprecated**
+`string` | `binary` | any sequence of octets **Deprecated**
 
+Use of `byte` or `binary` is discouraged, and later versions of this specification may remove them from this list.  They SHOULD be replaced with the JSON Schema keywords `contentEncoding` or `contentMediaType` as follows:
+
+* replace `"format": "byte"` with `"contentEncoding": "base64"` or `"contentEncoding": "base64url"`
+* replace `"format": "binary"` with  `"contentMediaType": "application/octet-stream"` or an appropriate specific media type
 
 ### <a name="richText"></a>Rich Text Formatting
 Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting.
@@ -1453,14 +1453,14 @@ In contrast with the 2.0 specification, `file` input/output content in OpenAPI i
 # content transferred with base64 encoding
 schema:
   type: string
-  format: base64
+  contentEncoding: base64
 ```
 
 ```yaml
 # content transferred in binary (octet-stream):
 schema:
   type: string
-  format: binary
+  contentMediaType: application/octet-stream
 ```
 
 These examples apply to either input payloads of file uploads or response payloads.
@@ -1474,7 +1474,7 @@ requestBody:
       schema:
         # a binary file of any type
         type: string
-        format: binary
+        contentMediaType: application/octet-stream
 ```
 
 In addition, specific media types MAY be specified:
@@ -1487,11 +1487,11 @@ requestBody:
     'image/jpeg':
       schema:
         type: string
-        format: binary
+        contentMediaType: image/jpeg
     'image/png':
       schema:
         type: string
-        format: binary        
+        contentMediaType: image/png
 ```
 
 To upload multiple files, a `multipart` media type MUST be used:
@@ -1507,7 +1507,7 @@ requestBody:
             type: array
             items:
               type: string
-              format: binary
+              contentMediaType: application/octet-stream
 
 ```
 
@@ -1546,7 +1546,9 @@ When passing in `multipart` types, boundaries MAY be used to separate sections o
 
 * If the property is a primitive, or an array of primitive values, the default Content-Type is `text/plain`
 * If the property is complex, or an array of complex values, the default Content-Type is `application/json`
-* If the property is a `type: string` with `format: binary` or `format: base64` (aka a file object), the default Content-Type is `application/octet-stream`
+* If the property is a `type: string` with a `contentMediaType`, the Content-Type is the value from `contentMediaType`
+* If the property is a `type: string` with a `contentEncoding` of `base64` or `base64url`, but does _not_ have a `contentMediaType`, the default Content-Type is `application/octet-stream`
+* **Deprecated:** If the property is a `type: string` with `format: binary` or `format: base64` (aka a file object), the default Content-Type is `application/octet-stream`
 
 
 Examples:
@@ -1566,9 +1568,9 @@ requestBody:
             type: object
             properties: {}
           profileImage:
-            # default Content-Type for string/binary is `application/octet-stream`
+            # Content-Type for string/contentMediaType is the contentMediaType (image/png here)
             type: string
-            format: binary
+            contentMediaType: image/png
           children:
             # default Content-Type for arrays is based on the `inner` type (text/plain here)
             type: array
@@ -1590,7 +1592,13 @@ A single encoding definition applied to a single schema property.
 ##### Fixed Fields
 Field Name | Type | Description
 ---|:---:|---
-<a name="encodingContentType"></a>contentType | `string` | The Content-Type for encoding a specific property. Default value depends on the property type: for `string` with `format` being `binary` – `application/octet-stream`; for other primitive types – `text/plain`; for `object` - `application/json`; for `array` – the default is defined based on the inner type. The value can be a specific media type (e.g. `application/json`), a wildcard media type (e.g. `image/*`), or a comma-separated list of the two types.
+<a name="encodingContentType"></a>contentType | `string` | The Content-Type for encoding a specific property. Default value depends on the property type:
+
+* for `type` with a `contentMediaType`, the default value is the value from `contentMediaType`
+* for other primitive types – `text/plain`; for `object` - `application/json`
+* for `array` – the default is defined based on the inner type. The value can be a specific media type (e.g. `application/json`), a wildcard media type (e.g. `image/*`), or a comma-separated list of the two types
+* **Deprecated:** for `string` with `format` being `binary` – `application/octet-stream`
+
 <a name="encodingHeaders"></a>headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | A map allowing additional information to be provided as headers, for example `Content-Disposition`.  `Content-Type` is described separately and SHALL be ignored in this section. This property SHALL be ignored if the request body media type is not a `multipart`.
 <a name="encodingStyle"></a>style | `string` | Describes how a specific property value will be serialized depending on its type.  See [Parameter Object](#parameterObject) for details on the [`style`](#parameterStyle) property. The behavior follows the same values as `query` parameters, including default values. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encodingContentType) (implicit or explicit) SHALL be ignored.
 <a name="encodingExplode"></a>explode | `boolean` | When this is true, property 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 properties this property has no effect. When [`style`](#encodingStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encodingContentType) (implicit or explicit) SHALL be ignored.
@@ -1621,9 +1629,8 @@ requestBody:
             type: object
             properties: {}
           profileImage:
-            # default is application/octet-stream, need to declare an image type only!
             type: string
-            format: binary
+            contentMediaType: image/jpeg
       encoding:
         historyMetadata:
           # require XML Content-Type in utf-8 encoding