Skip to content

Commit a7c9c0c

Browse files
committed
Review feedback and maintainability
Let's only explain the validation requirements in one place. Also, header example fields were supposed to be moved rather than duplicatd but I missed the removal of the old ones.
1 parent 042e708 commit a7c9c0c

File tree

1 file changed

+3
-7
lines changed

1 file changed

+3
-7
lines changed

src/oas.md

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -968,8 +968,8 @@ See [Appendix B](#appendix-b-data-type-conversion) for a discussion of convertin
968968
###### Common Fixed Fields
969969

970970
These fields MAY be used with either `content` or `schema`.
971-
When `example` or `examples` are provided in conjunction with the `schema` field, the example SHOULD match the specified schema and follow the prescribed serialization strategy for the parameter.
972-
The `example` and `examples` fields are mutually exclusive.
971+
972+
The `example` and `examples` fields are mutually exclusive; see [Working with Examples](#working-with-examples) for guidance on validation requirements.
973973

974974
| Field Name | Type | Description |
975975
| ---- | :----: | ---- |
@@ -2423,8 +2423,7 @@ The Header Object follows the structure of the [Parameter Object](#parameter-obj
24232423

24242424
These fields MAY be used with either `content` or `schema`.
24252425

2426-
When `example` or `examples` are provided in conjunction with the `schema` field, the example SHOULD match the specified schema and follow the prescribed serialization strategy for the header.
2427-
The `example` and `examples` fields are mutually exclusive.
2426+
The `example` and `examples` fields are mutually exclusive; see [Working with Examples](#working-with-examples) for guidance on validation requirements.
24282427

24292428
| Field Name | Type | Description |
24302429
| ---- | :----: | ---- |
@@ -2439,7 +2438,6 @@ This object MAY be extended with [Specification Extensions](#specification-exten
24392438
###### Fixed Fields for use with `schema`
24402439

24412440
For simpler scenarios, a [`schema`](#header-schema) and [`style`](#header-style) can describe the structure and syntax of the header.
2442-
When `example` or `examples` are provided in conjunction with the `schema` field, the example MUST follow the prescribed serialization strategy for the header.
24432441

24442442
Serializing headers with `schema` can be problematic due to the URI percent-encoding that is automatically applied, which would percent-encode characters such as `;` that are used to separate primary header values from their parameters.
24452443
The `allowReserved` field can disable most but not all of this behavior.
@@ -2451,8 +2449,6 @@ See [Appendix D](#appendix-d-serializing-headers-and-cookies) for details and fu
24512449
| <a name="header-explode"></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 field has no effect. The default value is `false`. |
24522450
| <a name="header-allow-reserved"></a>allowReserved | `boolean` | When this is true, header values are serialized using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2), as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of percent-encoded triples). See [Appendix D: Serializing Headers and Cookies](#appendix-d-serializing-headers-and-cookies) for guidance on header encoding and escaping. The default value is `false`. |
24532451
| <a name="header-schema"></a>schema | [Schema Object](#schema-object) | The schema defining the type used for the header. |
2454-
| <a name="header-example"></a>example | Any | Example of the header's potential value; see [Working With Examples](#working-with-examples). |
2455-
| <a name="header-examples"></a>examples | Map[ `string`, [Example Object](#example-object) \| [Reference Object](#reference-object)] | Examples of the header's potential value; see [Working With Examples](#working-with-examples). |
24562452

24572453
See also [Appendix C: Using RFC6570-Based Serialization](#appendix-c-using-rfc6570-based-serialization) for additional guidance.
24582454

0 commit comments

Comments
 (0)