Verbose Header Object documentation (3.0.4)

versions/3.0.4.md

@@ -2232,7 +2232,7 @@ Expressions can be embedded into string values by surrounding the expression wit
 
 #### <a name="headerObject"></a>Header Object
 
-The Header Object is used to describe headers for [HTTP responses](#responseHeaders) and for [individual parts in `multipart` representations](#encodingHeaders); see the relevant [Header Object](#headerObject) and [Encoding Object](#encodingObject) documentation for restrictions on which headers can be described.
+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:
 
@@ -2248,7 +2248,7 @@ 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 a parameter is deprecated and SHOULD be transitioned out of usage. 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`
 
@@ -2260,7 +2260,7 @@ Serializing with `schema` is NOT RECOMMENDED for headers with parameters (name=v
 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 separate header values 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`.
+<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](https://github.com/OAI/OpenAPI-Specification/blob/v3.0.4-dev/versions/3.0.4.md#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.