Skip to content

v3.2: sync fixes from 3.3 #5299

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
karenetheridge wants to merge 12 commits into
base: v3.2-dev
Choose a base branch
from
+26 −25
Open

v3.2: sync fixes from 3.3 #5299

Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
c3bbe4e
fix typo
valerii15298 Feb 23, 2026
3c0288d
Fix incorrect xml closing tags
valerii15298 Feb 23, 2026
1c31595
Fix unclosed html `li` tags
valerii15298 Feb 23, 2026
d7701af
simplify broken json in SetCookie example
valerii15298 Feb 23, 2026
106b699
Fix missing name for `responses` component in example
valerii15298 Feb 23, 2026
68bb088
Fix `const` value in example to match requestBody data
valerii15298 Feb 23, 2026
aed0141
Fix broken $ref in example
valerii15298 Feb 23, 2026
322abd1
Fixed correct level of encoding object
valerii15298 Feb 23, 2026
aba7e99
Fix malformed json
valerii15298 Feb 23, 2026
edfe850
Fix http QUERY method link text to match its url
valerii15298 Feb 23, 2026
d7a573a
Update http QUERY draft link to the latest
valerii15298 Feb 24, 2026
a3d48f3
Add externalValue to example
valerii15298 Feb 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 26 additions & 25 deletions src/oas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -607,7 +607,7 @@
| <a name="path-item-head"></a>head | [Operation Object](#operation-object) | A definition of a HEAD operation on this path. |
| <a name="path-item-patch"></a>patch | [Operation Object](#operation-object) | A definition of a PATCH operation on this path. |
| <a name="path-item-trace"></a>trace | [Operation Object](#operation-object) | A definition of a TRACE operation on this path. |
| <a name="path-item-query"></a>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. |
| <a name="path-item-query"></a>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. |
| <a name="path-item-additional-operations"></a>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). |
| <a name="path-item-servers"></a>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. |
| <a name="path-item-parameters"></a>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). |
Expand Down Expand Up @@ -788,7 +788,7 @@

| Field Name | Type | Description |
| ---- | :----: | ---- |
| <a name="parameter-name"></a>name | `string` | **REQUIRED**. The name of the parameter. Parameter names are _case-sensitive_. <ul><li>If [`in`](#parameter-in) is `"path"`, the `name` field MUST correspond to a single template expression occurring within the [path](#paths-path) field in the [Paths Object](#paths-object). See [Path Templating](#path-templating) for further information.<li>If [`in`](#parameter-in) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.<li>If `in` is `"querystring"`, or for [certain combinations](#style-examples) of [`style`](#parameter-style) and [`explode`](#parameter-explode), the value of `name` is not used in the parameter serialization.<li>For all other cases, the `name` corresponds to the parameter name used by the [`in`](#parameter-in) field.</ul> |
| <a name="parameter-name"></a>name | `string` | **REQUIRED**. The name of the parameter. Parameter names are _case-sensitive_. <ul><li>If [`in`](#parameter-in) is `"path"`, the `name` field MUST correspond to a single template expression occurring within the [path](#paths-path) field in the [Paths Object](#paths-object). See [Path Templating](#path-templating) for further information.</li><li>If [`in`](#parameter-in) is `"header"` and the `name` field is `"Accept"`, `"Content-Type"` or `"Authorization"`, the parameter definition SHALL be ignored.</li><li>If `in` is `"querystring"`, or for [certain combinations](#style-examples) of [`style`](#parameter-style) and [`explode`](#parameter-explode), the value of `name` is not used in the parameter serialization.</li><li>For all other cases, the `name` corresponds to the parameter name used by the [`in`](#parameter-in) field.</li></ul> |
| <a name="parameter-in"></a>in | `string` | **REQUIRED**. The location of the parameter. Possible values are `"query"`, `"querystring"`, `"header"`, `"path"` or `"cookie"`. |
| <a name="parameter-description"></a>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. |
| <a name="parameter-required"></a>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`. |
Expand Down Expand Up @@ -1605,7 +1605,7 @@
format: int64
- properties:
event:
const: addJson
const: addJSON
data:
$comment: |
These content fields indicate
Expand Down Expand Up @@ -1831,9 +1831,9 @@
# 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
Expand All @@ -1851,7 +1851,7 @@

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

Expand Down Expand Up @@ -2771,7 +2771,7 @@
content:
application/linkset+json:
schema:
$ref: '#/components/mediaTypes/CollectionLinks'
$ref: '#/components/schemas/CollectionLinks'
```

#### Representing the `Set-Cookie` Header
Expand Down Expand Up @@ -2849,11 +2849,10 @@
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
Expand Down Expand Up @@ -3160,7 +3159,7 @@
```json
{
"code": "1234",
"count": 42
"count": 42,
"extra": {
"info": "abc"
}
Expand Down Expand Up @@ -3880,7 +3879,7 @@

#### Namespace Limitations

The `namespace` field is intended to match the syntax of [XML namespaces](https://www.w3.org/TR/xml-names11/), although there are a few caveats:

Check failure on line 3882 in src/oas.md

View workflow job for this annotation

GitHub Actions / lint 

[Linkspector] reported by reviewdog 🐶
Cannot reach https://www.w3.org/TR/xml-names11/ Status: 403

Raw Output:
message:"Cannot reach https://www.w3.org/TR/xml-names11/ Status: 403"  location:{path:"src/oas.md"  range:{start:{line:3882  column:58}  end:{line:3882  column:110}}}  severity:ERROR  source:{name:"linkspector"  url:"https://github.com/UmbrellaDocs/linkspector"}

* Versions 3.1.0, 3.0.3, and earlier of this specification erroneously used the term "absolute URI" instead of "non-relative URI" ("non-relative IRI" as of OAS v3.2.0), so authors using namespaces that include a fragment should check tooling support carefully.
* XML allows but discourages relative IRI-references, while this specification outright forbids them.
Expand Down Expand Up @@ -4293,14 +4292,15 @@
name: Fluffy
- kind: Dog
name: Fido
externalValue: ./examples/pets.xml
```

Where `./examples/pets.xml` would be:

```xml
<animals>
<animal kind="Cat">Fluffy</animals>
<animal kind="Dog">Fido</animals>
<animal kind="Cat">Fluffy</animal>
<animal kind="Dog">Fido</animal>
<animals>
```

Expand All @@ -4321,15 +4321,16 @@
xml:
nodeType: cdata
responses:
content:
application/xml:
schema:
$ref: "#/components/schemas/Documentation"
examples:
docs:
dataValue:
content: <html><head><title>Awesome Docs</title></head><body></body><html>
externalValue: ./examples/docs.xml
AwesomeDocs:
content:
application/xml:
schema:
$ref: "#/components/schemas/Documentation"
examples:
docs:
dataValue:
content: <html><head><title>Awesome Docs</title></head><body></body><html>
externalValue: ./examples/docs.xml
```

Where `./examples/docs.xml` would be:
Expand Down
Loading