You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
Copy file name to clipboardExpand all lines: src/oas.md
+3-7Lines changed: 3 additions & 7 deletions
Original file line number
Diff line number
Diff line change
@@ -968,8 +968,8 @@ See [Appendix B](#appendix-b-data-type-conversion) for a discussion of convertin
968
968
###### Common Fixed Fields
969
969
970
970
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.
973
973
974
974
| Field Name | Type | Description |
975
975
| ---- | :----: | ---- |
@@ -2423,8 +2423,7 @@ The Header Object follows the structure of the [Parameter Object](#parameter-obj
2423
2423
2424
2424
These fields MAY be used with either `content` or `schema`.
2425
2425
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.
2428
2427
2429
2428
| Field Name | Type | Description |
2430
2429
| ---- | :----: | ---- |
@@ -2439,7 +2438,6 @@ This object MAY be extended with [Specification Extensions](#specification-exten
2439
2438
###### Fixed Fields for use with `schema`
2440
2439
2441
2440
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.
2443
2441
2444
2442
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.
2445
2443
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
2451
2449
| <aname="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`. |
2452
2450
| <aname="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`. |
2453
2451
| <aname="header-schema"></a>schema |[Schema Object](#schema-object)| The schema defining the type used for the header. |
2454
-
| <aname="header-example"></a>example | Any | Example of the header's potential value; see [Working With Examples](#working-with-examples). |
2455
-
| <aname="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). |
2456
2452
2457
2453
See also [Appendix C: Using RFC6570-Based Serialization](#appendix-c-using-rfc6570-based-serialization) for additional guidance.
0 commit comments