Skip to content

v3.3: include an ABNF for contentType #5324

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 1 commit into
base: v3.3-dev
Choose a base branch
from
Open

v3.3: include an ABNF for contentType #5324

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
2 changes: 1 addition & 1 deletion src/oas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1715,7 +1715,7 @@

| Field Name | Type | Description |
| ---- | :----: | ---- |
| <a name="encoding-content-type"></a>contentType | `string` | The `Content-Type` for encoding a specific property. The value is a comma-separated list, each element of which is either a specific media type (e.g. `image/png`) or a wildcard media type (e.g. `image/*`). The default value depends on the type as shown in the table below. |
| <a name="encoding-content-type"></a>contentType | `string` | The `Content-Type` for encoding a specific property. The value is a comma-separated list, each element of which is either a specific media type (e.g. `image/png`) or a wildcard media type (e.g. `image/*`), with ABNF: `media-range *( "," OWS media-range )`. The default value depends on the type as shown in the table below. |
Copy link
Copy Markdown
Member

@handrews handrews May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK I know I just approved the other one, but it just occurred to me that we may need to say that the OWS rule comes from RFC9110? Or that the whole rule is imported from there?

I know @char0n tends to check our ABNF rules closely :-)

Copy link
Copy Markdown
Contributor

@char0n char0n May 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi,

@handrews thanks for flagging me ;]

I would possibly align this with Request Object.content field:

Suggested change
| <a name="encoding-content-type"></a>contentType | `string` | The `Content-Type` for encoding a specific property. The value is a comma-separated list, each element of which is either a specific media type (e.g. `image/png`) or a wildcard media type (e.g. `image/*`), with ABNF: `media-range *( "," OWS media-range )`. The default value depends on the type as shown in the table below. |
| <a name="encoding-content-type"></a>contentType | `string` | The `Content-Type` for encoding a specific property. The value is a comma-separated list, each element of which is either a specific media type (e.g. `image/png`) or [media type range](https://tools.ietf.org/html/rfc9110#appendix-A) (e.g. `image/*`). The default value depends on the type as shown in the table below. |

Then If can suggest replacing the following section with:

Original section:

Determining how to handle a type value of null depends on how null values are being serialized. If null values are entirely omitted, then the contentType is irrelevant. See Appendix B for a discussion of data type conversion options.

Replaced by:

Determining how to handle a type value of null depends on how null values are being serialized. If null values are entirely omitted, then the contentType is irrelevant. See Appendix B for a discussion of data type conversion options.

The contentType field is defined by the following [ABNF] syntax:

encoding-content-type = media-range *( "," OWS media-range )

Here, media-range and OWS are taken from [RFC9110].

| <a name="encoding-headers"></a>headers | Map[`string`, [Header Object](#header-object) \| [Reference Object](#reference-object)] | A map allowing additional information to be provided as headers. `Content-Type` is described separately and SHALL be ignored in this section. This field SHALL be ignored if the media type is not a `multipart`. |
| <a name="encoding-encoding"></a>encoding | Map[`string`, [Encoding Object](#encoding-object)] | Applies nested Encoding Objects in the same manner as the [Media Type Object](#media-type-object)'s `encoding` field. |
| <a name="encoding-prefix-encoding"></a>prefixEncoding | [[Encoding Object](#encoding-object)] | Applies nested Encoding Objects in the same manner as the [Media Type Object](#media-type-object)'s `prefixEncoding` field. |
Expand Down Expand Up @@ -1868,7 +1868,7 @@
Note that as stated in [Working with Binary Data](#working-with-binary-data), if the Encoding Object's `contentType`, whether set explicitly or implicitly through its default value rules, disagrees with the `contentMediaType` in a Schema Object, the `contentMediaType` SHALL be ignored.
Because of this, and because the Encoding Object's `contentType` defaulting rules do not take the Schema Object's `contentMediaType` into account, the use of `contentMediaType` with an Encoding Object is NOT RECOMMENDED.

Note also that `Content-Transfer-Encoding` is deprecated for `multipart/form-data` ([RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.7)) where binary data is supported, as it is in HTTP.

Check failure on line 1871 in src/oas.md

View workflow job for this annotation

GitHub Actions / lint 

[Linkspector] reported by reviewdog 🐶
Cannot reach https://www.rfc-editor.org/rfc/rfc7578.html#section-4.7 Status: null Cannot read properties of null (reading 'status')

Raw Output:
message:"Cannot reach https://www.rfc-editor.org/rfc/rfc7578.html#section-4.7 Status: null Cannot read properties of null (reading 'status')"  location:{path:"src/oas.md"  range:{start:{line:1871  column:85}  end:{line:1871  column:151}}}  severity:ERROR  source:{name:"linkspector"  url:"https://github.com/UmbrellaDocs/linkspector"}

See [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a detailed examination of percent-encoding concerns for form media types.

Expand Down Expand Up @@ -4584,7 +4584,7 @@
| <a name="security-scheme-description"></a>description | `string` | Any | A description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. |
| <a name="security-scheme-name"></a>name | `string` | `apiKey` | **REQUIRED**. The name of the header, query or cookie parameter to be used. |
| <a name="security-scheme-in"></a>in | `string` | `apiKey` | **REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"`, or `"cookie"`. |
| <a name="security-scheme-scheme"></a>scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authentication scheme to be used in the [Authorization header as defined in RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#section-16.4.1). The values used SHOULD be registered in the [IANA Authentication Scheme registry](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml). The value is case-insensitive, as defined in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#section-11.1). |

Check failure on line 4587 in src/oas.md

View workflow job for this annotation

GitHub Actions / lint 

[Linkspector] reported by reviewdog 🐶
Cannot reach https://www.rfc-editor.org/rfc/rfc9110.html#section-11.1 Status: null Cannot read properties of null (reading 'status')

Raw Output:
message:"Cannot reach https://www.rfc-editor.org/rfc/rfc9110.html#section-11.1 Status: null Cannot read properties of null (reading 'status')"  location:{path:"src/oas.md"  range:{start:{line:4587  column:452}  end:{line:4587  column:519}}}  severity:ERROR  source:{name:"linkspector"  url:"https://github.com/UmbrellaDocs/linkspector"}
| <a name="security-scheme-bearer-format"></a>bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. |
| <a name="security-scheme-flows"></a>flows | [OAuth Flows Object](#oauth-flows-object) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported. |
| <a name="security-scheme-open-id-connect-url"></a>openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. [Well-known URL](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig) to discover the [[OpenID-Connect-Discovery]] [provider metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata). |
Expand Down Expand Up @@ -5125,7 +5125,7 @@
## Appendix D: Serializing Headers and Cookies

HTTP headers have inconsistent rules regarding what characters are allowed, and how some or all disallowed characters can be escaped and included.
While the `quoted-string` ABNF rule given in [[RFC9110]] [Section 5.4.6](https://www.rfc-editor.org/rfc/rfc9110.html#section-5.6.4) is the most common escaping solution, it is not sufficiently universal to apply automatically.

Check failure on line 5128 in src/oas.md

View workflow job for this annotation

GitHub Actions / lint 

[Linkspector] reported by reviewdog 🐶
Cannot reach https://www.rfc-editor.org/rfc/rfc9110.html#section-5.6.4 Status: null Cannot read properties of null (reading 'status')

Raw Output:
message:"Cannot reach https://www.rfc-editor.org/rfc/rfc9110.html#section-5.6.4 Status: null Cannot read properties of null (reading 'status')"  location:{path:"src/oas.md"  range:{start:{line:5128  column:58}  end:{line:5128  column:132}}}  severity:ERROR  source:{name:"linkspector"  url:"https://github.com/UmbrellaDocs/linkspector"}
For example, a strong `ETag` looks like `"foo"` (with quotes, regardless of the contents), and a weak `ETag` looks like `W/"foo"` (note that only part of the value is quoted); the contents of the quotes for this header are also not escaped in the way `quoted-string` contents are.

For this reason, any data being passed to a header by way of a [Parameter](#parameter-object) or [Header](#header-object) Object needs to be quoted and escaped prior to passing it to the OAS implementation, and the parsed header values are expected to contain the quotes and escapes.
Expand Down
Loading