Merge pull request #3867 from handrews/header-obj-304

Verbose Header Object documentation (3.0.4)

Author: handrews

Diff for: versions/3.0.4.md

@@ -2336,18 +2336,56 @@ Expressions can be embedded into string values by surrounding the expression wit
 
 #### <a name="headerObject"></a>Header Object
 
-The Header Object follows the structure of the [Parameter Object](#parameterObject) with the following changes:
+Describes a single header for [HTTP responses](#responseHeaders) and for [individual parts in `multipart` representations](#encodingHeaders); see the relevant [Response Object](#responseObject) and [Encoding Object](#encodingObject) documentation for restrictions on which headers can be described.
+
+The Header Object follows the structure of the [Parameter Object](#parameterObject), including determining its serialization strategy based on whether `schema` or `content` is present,  with the following changes:
 
 1. `name` MUST NOT be specified, it is given in the corresponding `headers` map.
 1. `in` MUST NOT be specified, it is implicitly in `header`.
-1. All traits that are affected by the location MUST be applicable to a location of `header` (for example, [`style`](#parameterStyle)).
+1. All traits that are affected by the location MUST be applicable to a location of `header` (for example, [`style`](#parameterStyle)).  This means that `allowEmptyValue` and `allowReserved` MUST NOT be used, and `style`, if used, MUST be limited to `simple`.
+
+###### Common Fixed Fields
+
+These fields MAY be used with either `content` or `schema`.
+
+Field Name | Type | Description
+---|:---:|---
+<a name="headerDescription"></a>description | `string` | A brief description of the header. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+<a name="headerRequired"></a>required | `boolean` | Determines whether this header is mandatory. The default value is `false`.
+<a name="headerDeprecated"></a> deprecated | `boolean` | Specifies that the header is deprecated and SHOULD be transitioned out of usage. Default value is `false`.
+
+###### Fixed Fields for use with `schema`
+
+For simpler scenarios, a [`schema`](#headerSchema) and [`style`](#headerStyle) can describe the structure and syntax of the header.
+When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the header.
+
+Serializing with `schema` is NOT RECOMMENDED for headers with parameters (name=value pairs following a `;`) in their values, or where values might have non-URL-safe characters; see [Appendix D](#serializingHeadersAndCookies) for details.
+
+Field Name | Type | Description
+---|:---:|---
+<a name="headerStyle"></a>style | `string` | Describes how the header value will be serialized.  The default (and only legal value for headers) is `simple`.
+<a name="headerExplode"></a>explode | `boolean` | When this is true, header values of type `array` or `object` generate a single header whose value is a comma-separated list of the array items or key-value pairs of the map, see [Style Examples](#style-examples). For other data types this property has no effect. The default value is `false`.
+<a name="headerSchema"></a>schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the header.
+<a name="headerExample"></a>example | Any | Example of the header'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="headerExamples"></a>examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the header's potential value. Each example SHOULD contain a value in the correct format as specified in the header 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.
+
+See also [Appendix C: Using RFC6570 Implementations](#usingRFC6570Implementations) for additional guidance.
+
+###### Fixed Fields for use with `content`
+
+For more complex scenarios, the [`content`](#headerContent) property can define the media type and schema of the header, as well as give examples of its use.
+Using `content` with a `text/plain` media type is RECOMMENDED for headers where the `schema` strategy is not appropriate.
+
+Field Name | Type | Description
+---|:---:|---
+<a name="headerContent"></a>content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing the representations for the header. The key is the media type and the value describes it. The map MUST only contain one entry.
 
 ##### Header Object Example
 
 A simple header of type `integer`:
 
 ```json
-{
+"X-Rate-Limit-Limit": {
   "description": "The number of allowed requests in the current period",
   "schema": {
     "type": "integer"
@@ -2356,9 +2394,36 @@ A simple header of type `integer`:
 ```
 
 ```yaml
-description: The number of allowed requests in the current period
-schema:
-  type: integer
+X-Rate-Limit-Limit:
+  description: The number of allowed requests in the current period
+  schema:
+    type: integer
+```
+
+Requiring that a strong `ETag` header (with a value starting with `"` rather than `W/`) is present.  Note the use of `content`, because using `schema` and `style` would require the `"` to be percent-encoded as `%22`:
+
+```json
+"ETag": {
+  "required": true,
+  "content": {
+    "text/plain": {
+      "schema": {
+        "type": "string",
+        "pattern": "^\""
+      }
+    }
+  }
+}
+```
+
+```yaml
+ETag:
+  required: true
+  content:
+    text/plain:
+      schema:
+        type: string
+        pattern: ^" 
 ```
 
 #### <a name="tagObject"></a>Tag Object
@@ -3631,3 +3696,7 @@ Version   | Date       | Notes
 1.2       | 2014-03-14 | Initial release of the formal document.
 1.1       | 2012-08-22 | Release of Swagger 1.1
 1.0       | 2011-08-10 | First release of the Swagger Specification
+
+## <a name="usingRFC6570Implementations"></a>Appendix C: Using RFC6570 Implementations
+
+## <a name="serializingHeadersAndCookies"></a>Appendix D: Serializing Headers and Cookies