From 372f396df9d141cb3b660fbd582dc0a5adf7be1e Mon Sep 17 00:00:00 2001 From: Valerii Petryniak <44531564+valerii15298@users.noreply.github.com> Date: Mon, 23 Feb 2026 22:58:18 +0200 Subject: [PATCH 01/13] fix typo --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index efd8e22103..4097508b84 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1851,7 +1851,7 @@ However, this is not guaranteed, so it may be more interoperable to keep the pad See [Encoding Usage and Restrictions](#encoding-usage-and-restrictions) for guidance on correlating schema properties with parts. -Note that there are significant restrictions on what headers can be used with `multipart` media types in general ([RFC2046](https://www.rfc-editor.org/rfc/rfc2046.html#section-5.1)) and `multi-part/form-data` in particular ([RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.8)). +Note that there are significant restrictions on what headers can be used with `multipart` media types in general ([RFC2046](https://www.rfc-editor.org/rfc/rfc2046.html#section-5.1)) and `multipart/form-data` in particular ([RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.8)). ##### Handling Multiple `contentType` Values From 1575fb58b4279eba9f94ccbac9f255bbbf794962 Mon Sep 17 00:00:00 2001 From: Valerii Petryniak <44531564+valerii15298@users.noreply.github.com> Date: Mon, 23 Feb 2026 22:26:17 +0200 Subject: [PATCH 02/13] Fix incorrect xml closing tags --- src/oas.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/oas.md b/src/oas.md index 4097508b84..e4d4f862df 100644 --- a/src/oas.md +++ b/src/oas.md @@ -4299,8 +4299,8 @@ Where `./examples/pets.xml` would be: ```xml - Fluffy - Fido + Fluffy + Fido ``` From 8998ef443a44c451dd1897e37c7e4ac3cfa91951 Mon Sep 17 00:00:00 2001 From: Valerii Petryniak <44531564+valerii15298@users.noreply.github.com> Date: Mon, 23 Feb 2026 22:07:16 +0200 Subject: [PATCH 03/13] Fix unclosed html `li` tags --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index e4d4f862df..d106f8eaee 100644 --- a/src/oas.md +++ b/src/oas.md @@ -788,7 +788,7 @@ The `example` and `examples` fields are mutually exclusive; see [Working with Ex | Field Name | Type | Description | | ---- | :----: | ---- | -| name | `string` | **REQUIRED**. The name of the parameter. Parameter names are _case-sensitive_. | +| name | `string` | **REQUIRED**. The name of the parameter. Parameter names are _case-sensitive_. | | in | `string` | **REQUIRED**. The location of the parameter. Possible values are `"query"`, `"querystring"`, `"header"`, `"path"` or `"cookie"`. | | description | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | | required | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](#parameter-in) is `"path"`, this field is **REQUIRED** and its value MUST be `true`. Otherwise, the field MAY be included and its default value is `false`. | From 6453e5422ebe06c3ba63cbf6db7c2c522ba2f77e Mon Sep 17 00:00:00 2001 From: Valerii Petryniak <44531564+valerii15298@users.noreply.github.com> Date: Mon, 23 Feb 2026 23:25:23 +0200 Subject: [PATCH 04/13] simplify broken json in SetCookie example --- src/oas.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/src/oas.md b/src/oas.md index d106f8eaee..c93910cba2 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2849,11 +2849,10 @@ components: explode: true examples: SetCookies: - dataValue: { - "lang": "en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT" - "foo": "bar; Expires=Wed, 09 Jun 2021 10:18:14 GMT" - "urlSafeData": "Hello%2C%20world%21" - } + dataValue: + lang: "en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT" + foo: "bar; Expires=Wed, 09 Jun 2021 10:18:14 GMT" + urlSafeData: "Hello%2C%20world%21" serializedValue: | lang=en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT foo=bar; Expires=Wed, 09 Jun 2021 10:18:14 GMT From dc6f48edccd1a35bca41a30a0dcf33d25153b790 Mon Sep 17 00:00:00 2001 From: Valerii Petryniak <44531564+valerii15298@users.noreply.github.com> Date: Mon, 23 Feb 2026 23:09:55 +0200 Subject: [PATCH 05/13] Fix missing name for `responses` component in example --- src/oas.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/src/oas.md b/src/oas.md index c93910cba2..2029111389 100644 --- a/src/oas.md +++ b/src/oas.md @@ -4320,15 +4320,16 @@ components: xml: nodeType: cdata responses: - content: - application/xml: - schema: - $ref: "#/components/schemas/Documentation" - examples: - docs: - dataValue: - content: Awesome Docs - externalValue: ./examples/docs.xml + AwesomeDocs: + content: + application/xml: + schema: + $ref: "#/components/schemas/Documentation" + examples: + docs: + dataValue: + content: Awesome Docs + externalValue: ./examples/docs.xml ``` Where `./examples/docs.xml` would be: From c16c369fa8083467967355698852aca1a72d226e Mon Sep 17 00:00:00 2001 From: Valerii Petryniak <44531564+valerii15298@users.noreply.github.com> Date: Mon, 23 Feb 2026 22:51:30 +0200 Subject: [PATCH 06/13] Fix `const` value in example to match requestBody data --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 2029111389..9783d3fe69 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1605,7 +1605,7 @@ content: format: int64 - properties: event: - const: addJson + const: addJSON data: $comment: | These content fields indicate From c76efd503ccaccf9732d765f69bc0ccb02ff68a1 Mon Sep 17 00:00:00 2001 From: Valerii Petryniak <44531564+valerii15298@users.noreply.github.com> Date: Mon, 23 Feb 2026 22:45:35 +0200 Subject: [PATCH 07/13] Fix broken $ref in example --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 9783d3fe69..a872e15b33 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2771,7 +2771,7 @@ components: content: application/linkset+json: schema: - $ref: '#/components/mediaTypes/CollectionLinks' + $ref: '#/components/schemas/CollectionLinks' ``` #### Representing the `Set-Cookie` Header From 859834562fd84651a930fac7e0e096bf5aa01125 Mon Sep 17 00:00:00 2001 From: Valerii Petryniak <44531564+valerii15298@users.noreply.github.com> Date: Mon, 23 Feb 2026 22:41:00 +0200 Subject: [PATCH 08/13] Fixed correct level of encoding object --- src/oas.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/oas.md b/src/oas.md index a872e15b33..6ebbf8c87c 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1831,9 +1831,9 @@ requestBody: # image media type(s) in the Encoding Object. type: string contentEncoding: base64url - encoding: - icon: - contentType: image/png, image/jpeg + encoding: + icon: + contentType: image/png, image/jpeg ``` Given a name of `example` and a solid red 2x2-pixel PNG for `icon`, this From 64b4563a50dd68784133057c1ab85d5744e5f3e5 Mon Sep 17 00:00:00 2001 From: Valerii Petryniak <44531564+valerii15298@users.noreply.github.com> Date: Mon, 23 Feb 2026 22:28:16 +0200 Subject: [PATCH 09/13] Fix malformed json --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 6ebbf8c87c..a2c31d1e97 100644 --- a/src/oas.md +++ b/src/oas.md @@ -3159,7 +3159,7 @@ This means that the data form of this serialization is equivalent to the followi ```json { "code": "1234", - "count": 42 + "count": 42, "extra": { "info": "abc" } From e46c8944436a59fd4eb286c216a5fb7a1e64065b Mon Sep 17 00:00:00 2001 From: Valerii Petryniak <44531564+valerii15298@users.noreply.github.com> Date: Mon, 23 Feb 2026 22:22:25 +0200 Subject: [PATCH 10/13] Fix http QUERY method link text to match its url --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index a2c31d1e97..d73420a203 100644 --- a/src/oas.md +++ b/src/oas.md @@ -607,7 +607,7 @@ The path itself is still exposed to the documentation viewer but they will not k | head | [Operation Object](#operation-object) | A definition of a HEAD operation on this path. | | patch | [Operation Object](#operation-object) | A definition of a PATCH operation on this path. | | trace | [Operation Object](#operation-object) | A definition of a TRACE operation on this path. | -| query | [Operation Object](#operation-object) | A definition of a QUERY operation, as defined in the most recent IETF draft ([draft-ietf-httpbis-safe-method-w-body-08](https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-11.html) as of this writing) or its RFC successor, on this path. | +| query | [Operation Object](#operation-object) | A definition of a QUERY operation, as defined in the most recent IETF draft ([draft-ietf-httpbis-safe-method-w-body-11](https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-11.html) as of this writing) or its RFC successor, on this path. | | additionalOperations | Map[`string`, [Operation Object](#operation-object)] | A map of additional operations on this path. The map key is the HTTP method with the same capitalization that is to be sent in the request. This map MUST NOT contain any entry for the methods that can be defined by other fixed fields with Operation Object values (e.g. no `POST` entry, as the `post` field is used for this method). | | servers | [[Server Object](#server-object)] | An alternative `servers` array to service all operations in this path. If a `servers` array is specified at the [OpenAPI Object](#oas-servers) level, it will be overridden by this value. | | parameters | [[Parameter Object](#parameter-object) \| [Reference Object](#reference-object)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameter-name) and [location](#parameter-in). The list can use the [Reference Object](#reference-object) to link to parameters that are defined in the [OpenAPI Object's `components.parameters`](#components-parameters). | From b07a65707f6522e3bc46a08d810d74d186e4b251 Mon Sep 17 00:00:00 2001 From: Valerii Petryniak <44531564+valerii15298@users.noreply.github.com> Date: Tue, 24 Feb 2026 17:56:29 +0200 Subject: [PATCH 11/13] Update http QUERY draft link to the latest --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index d73420a203..748d3d8def 100644 --- a/src/oas.md +++ b/src/oas.md @@ -607,7 +607,7 @@ The path itself is still exposed to the documentation viewer but they will not k | head | [Operation Object](#operation-object) | A definition of a HEAD operation on this path. | | patch | [Operation Object](#operation-object) | A definition of a PATCH operation on this path. | | trace | [Operation Object](#operation-object) | A definition of a TRACE operation on this path. | -| query | [Operation Object](#operation-object) | A definition of a QUERY operation, as defined in the most recent IETF draft ([draft-ietf-httpbis-safe-method-w-body-11](https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-11.html) as of this writing) or its RFC successor, on this path. | +| query | [Operation Object](#operation-object) | A definition of a QUERY operation, as defined in the most recent IETF draft ([draft-ietf-httpbis-safe-method-w-body-14](https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-14.html) as of this writing) or its RFC successor, on this path. | | additionalOperations | Map[`string`, [Operation Object](#operation-object)] | A map of additional operations on this path. The map key is the HTTP method with the same capitalization that is to be sent in the request. This map MUST NOT contain any entry for the methods that can be defined by other fixed fields with Operation Object values (e.g. no `POST` entry, as the `post` field is used for this method). | | servers | [[Server Object](#server-object)] | An alternative `servers` array to service all operations in this path. If a `servers` array is specified at the [OpenAPI Object](#oas-servers) level, it will be overridden by this value. | | parameters | [[Parameter Object](#parameter-object) \| [Reference Object](#reference-object)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameter-name) and [location](#parameter-in). The list can use the [Reference Object](#reference-object) to link to parameters that are defined in the [OpenAPI Object's `components.parameters`](#components-parameters). | From 90bd0fbb39dced881bf0ecd5e2d06916c2920db1 Mon Sep 17 00:00:00 2001 From: Valerii Petryniak <44531564+valerii15298@users.noreply.github.com> Date: Mon, 23 Feb 2026 23:32:29 +0200 Subject: [PATCH 12/13] Add externalValue to example --- src/oas.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/oas.md b/src/oas.md index 748d3d8def..e23e5ca8b0 100644 --- a/src/oas.md +++ b/src/oas.md @@ -4292,6 +4292,7 @@ application/xml: name: Fluffy - kind: Dog name: Fido + externalValue: ./examples/pets.xml ``` Where `./examples/pets.xml` would be: From bb752178aef397237bb3f2d81bbed1b762b53b7d Mon Sep 17 00:00:00 2001 From: Ethan Date: Tue, 14 Apr 2026 11:06:10 -0700 Subject: [PATCH 13/13] Example object externalValue: URI identifies serialized data, does not contain it --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index e23e5ca8b0..8cc0ca8ace 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2340,7 +2340,7 @@ The various fields and types of examples are explained in more detail under [Wor | description | `string` | Long description for the example. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | | dataValue | Any | An example of the data structure that MUST be valid according to the relevant [Schema Object](#schema-object). If this field is present, `value` MUST be absent. | | serializedValue | `string` | An example of the serialized form of the value, including encoding and escaping as described under [Validating Examples](#validating-examples). If `dataValue` is present, then this field SHOULD contain the serialization of the given data. Otherwise, it SHOULD be the valid serialization of a data value that itself MUST be valid as described for `dataValue`. This field SHOULD NOT be used if the serialization format is JSON, as the data form is easier to work with. If this field is present, `value`, and `externalValue` MUST be absent. | -| externalValue | `string` | A URI that identifies the serialized example in a separate document, allowing for values not easily or readably expressed as a Unicode string. If `dataValue` is present, then this field SHOULD identify a serialization of the given data. Otherwise, the value SHOULD be the valid serialization of a data value that itself MUST be valid as described for `dataValue`. If this field is present, `serializedValue` and `value` MUST be absent. See also the rules for resolving [Relative References](#relative-references-in-api-description-uris). | +| externalValue | `string` | A URI that identifies the serialized example in a separate document, allowing for values not easily or readably expressed as a Unicode string. If `dataValue` is present, then this field SHOULD identify a serialization of the given data. Otherwise, the value SHOULD identify the valid serialization of a data value that itself MUST be valid as described for `dataValue`. If this field is present, `serializedValue` and `value` MUST be absent. See also the rules for resolving [Relative References](#relative-references-in-api-description-uris). | | value | Any | Embedded literal example. The `value` field and `externalValue` field are mutually exclusive. To represent examples of media types that cannot naturally be represented in JSON or YAML, use a string value to contain the example, escaping where necessary.

**Deprecated for non-JSON serialization targets:** Use `dataValue` and/or `serializedValue`, which both have unambiguous syntax and semantics, instead. | This object MAY be extended with [Specification Extensions](#specification-extensions).