From 3f7e8996654333eb541335287c2d6e26fa278344 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/16] fix typo --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index d9a40430de..3ab3d60f81 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 28df72dbf912a4ee225920095fddee8e23ecafbd 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/16] 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 3ab3d60f81..69e79c0b27 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 16a1366074ef08322b102dd8bf7806262d50bf6c 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/16] 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 69e79c0b27..f401168690 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 68938612766b5125e4f68bb23d03eac612adb90f 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/16] 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 f401168690..81f1943cb3 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 a3c6c34c527689de145142abba6ffbae967bff91 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/16] 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 81f1943cb3..2bf40c55b7 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 d367db65c0f1b1ae98498e61bb0ce004303f0ce6 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/16] 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 2bf40c55b7..ec0fd7b683 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 6841a2eff7876e5e5477fc96a809007ff2ac6e21 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/16] 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 ec0fd7b683..649d16c8f6 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 692d1712a32c6f4b79ea0e43999861c4ae00e811 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/16] 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 649d16c8f6..503a207b90 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 a4d6f8d092a05cbc3d19ab5f746c32d778328ec8 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/16] 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 503a207b90..459fdc0082 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 d3be6ac8e064419535f721d7e7f5941f7d3a2881 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/16] 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 459fdc0082..b1c6c9dfaf 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 1471f14847706d58e83f33c878f7ae30062b51c4 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/16] 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 b1c6c9dfaf..581c465c13 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 b5851a5e5e6ac0051b5121dda43adc0e87f88202 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 22 Jan 2026 12:26:11 -0800 Subject: [PATCH 12/16] Explain that schemas are for mandatory requirements We do not host linting schemas here. --- CONTRIBUTING.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 724639da17..9eea8dfeea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -259,6 +259,11 @@ As part of the publishing process, the YAML source files are converted to JSON, #### Schemas and OAS Requirements +Not all uses of OAS Objects and fields are necessarily useful. +However, the OAS does not forbid various questionable combinations, for +reasons ranging from preserving possible future use with new features to +maintaining compatibility with past versions that neglected to forbid something. + The schemas published by the OpenAPI Initiative _only_ validate mandatory OAS requirements. This means that a field value or combination with another field is only forbidden in a schema if there is a corresponding MUST / MUST NOT / From 25e99388a483b70e764c590f7f2f95b3af8caef0 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Sun, 25 Jan 2026 16:49:57 -0800 Subject: [PATCH 13/16] Remove 1st paragraph (review feedback) --- CONTRIBUTING.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9eea8dfeea..724639da17 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -259,11 +259,6 @@ As part of the publishing process, the YAML source files are converted to JSON, #### Schemas and OAS Requirements -Not all uses of OAS Objects and fields are necessarily useful. -However, the OAS does not forbid various questionable combinations, for -reasons ranging from preserving possible future use with new features to -maintaining compatibility with past versions that neglected to forbid something. - The schemas published by the OpenAPI Initiative _only_ validate mandatory OAS requirements. This means that a field value or combination with another field is only forbidden in a schema if there is a corresponding MUST / MUST NOT / From a9d2f3a3067c1dfbdfb57bf6c88961fb7d2f35f6 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 14/16] Add externalValue to example --- src/oas.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/oas.md b/src/oas.md index 581c465c13..4f2d0bd1cf 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 33911d83e59794d4e54e8d76299437e7b7ed5c74 Mon Sep 17 00:00:00 2001 From: Ethan Date: Tue, 14 Apr 2026 11:06:10 -0700 Subject: [PATCH 15/16] 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 4f2d0bd1cf..fcc90a8327 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). From 7320cfe52219512fb1b3d57e6352fbd640ea06d8 Mon Sep 17 00:00:00 2001 From: Ethan Date: Mon, 16 Mar 2026 16:36:27 -0700 Subject: [PATCH 16/16] fix OAS.md Appedix F URI inconsistencies --- src/oas.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/oas.md b/src/oas.md index fcc90a8327..8cc0ca8ace 100644 --- a/src/oas.md +++ b/src/oas.md @@ -5336,7 +5336,7 @@ components: content: application/json: schema: - $ref: "#/components/api/schemas/Foo" + $ref: "#/components/schemas/Foo" schemas: Foo: properties: @@ -5457,7 +5457,7 @@ components: ``` In this example, all of the `$self` and `$id` values are relative URI references consisting of an absolute path. -This allows the retrieval URI to set the host (and scheme), in this case `https://staging.example.com`, resulting in the first document's `$self` being `https://staging.example.com/openapi`, and the second document's `$self` being `https://staging.example.com/api/shared/foo`, with `$id` values of `https://staging.example.com/api/schemas/foo` and `https://staging.example.com/api/schemas/bar`. +This allows the retrieval URI to set the host (and scheme), in this case `https://staging.example.com`, resulting in the first document's `$self` being `https://staging.example.com/api/openapi`, and the second document's `$self` being `https://staging.example.com/api/shared/foo`, with `$id` values of `https://staging.example.com/api/schemas/foo` and `https://staging.example.com/api/schemas/bar`. Relative `$self` and `$id` values of this sort allow the same set of documents to work when deployed to other hosts, e.g. `https://example.com` (production) or `https://localhost:8080` (local development). ## Appendix G: Parsing and Resolution Guidance