From 555d5097c09866d87bcfc9d4edaabd9676380ef6 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/12] fix typo --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 82a8885fa8..8b966ce5de 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 bb6c47621a88497d7ea2d0d68b25f76477f80366 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/12] 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 8b966ce5de..25998aeb5c 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 f8d96a31375c96f79ad29fc54d8fb72b5a0629c5 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/12] 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 25998aeb5c..b4f85c5478 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 aebf573341d85b36091f031915249b6406e760be 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/12] 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 b4f85c5478..86864949e9 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 b9a99fa24ce30ecda062fc040f5b66a7c16805ab 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/12] 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 86864949e9..72bcf142ef 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 442bf72d732b8cbc97736a26e8b9405e0acd08cd 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/12] 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 72bcf142ef..f508497413 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 72f529f4b56273a40c4bc06195f3521f902740e1 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/12] 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 f508497413..82bffba705 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 e1f73fbdda2ac060a34450688b522b198f1e1dae 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/12] 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 82bffba705..25c39af0d5 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 5fa0dd4b677ce584851fbb11079d9528496741a2 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/12] 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 25c39af0d5..701e32b6ff 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 958501f33cb19c2a5dc4d311b4e15a61f9de5872 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/12] 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 701e32b6ff..6f4f7ff0fb 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 f4784fa743a4ee7b7c31dcdaff9cb0688d6c3f95 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/12] 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 6f4f7ff0fb..eab3f35184 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 6ebe8efce5bc9c0d3b1f5bbb2076817e333667ac 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/12] Add externalValue to example --- src/oas.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/oas.md b/src/oas.md index eab3f35184..3c38f05e72 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: