Skip to content

v3.3: use extra markup to clarify intent #5331

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
+2 −2
Open

v3.3: use extra markup to clarify intent #5331

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
4 changes: 2 additions & 2 deletions src/oas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1379,10 +1379,10 @@
For all other value types for both top-level non-array properties and for values, including array values, within a top-level array, the Encoding Object MUST be applied to the entire value.
The order of these name-value pairs in the target media type is implementation-defined.

For `application/x-www-form-urlencoded`, the encoding keys MUST map to parameter names, with the values produced according to the rules of the [Encoding Object](#encoding-object).
For `application/x-www-form-urlencoded`, the `encoding` keys MUST map to parameter names, with the values produced according to the rules of the [Encoding Object](#encoding-object).
See [Encoding the `x-www-form-urlencoded` Media Type](#encoding-the-x-www-form-urlencoded-media-type) for guidance and examples, both with and without the `encoding` field.

For `multipart`, the encoding keys MUST map to the [`name` parameter](https://www.rfc-editor.org/rfc/rfc7578#section-4.2) of the `Content-Disposition: form-data` header of each part, as is defined for `multipart/form-data` in [[!RFC7578]].
For `multipart/form-data`, the `encoding` keys MUST map to the [`name` parameter](https://www.rfc-editor.org/rfc/rfc7578#section-4.2) of the `Content-Disposition: form-data` header of each part, as is defined for `multipart/form-data` in [[!RFC7578]].
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.

@karenetheridge I agree with you in general here, but there's a bit of history.

The reason this does not say /form-data is because of the paragraph further down along the lines of "MAY use a name parameter with other multipart but most multipart implementations probably won't support it."

I'm unsure what to do here. That part was added as a possible workaround for lack of proper sequential multipart support, and I somewhat regret it as now it's this weird thing that makes it harder to make clear statements like this.

We could say "For multipart/form-data (or any multipart format making use of a name paraameter)..."?

Copy link
Copy Markdown
Member Author

@karenetheridge karenetheridge May 13, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

How about "For multipart types that decode to an object... such as multipart/form-data in RFC7578" ?

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.

I think that works. In theory there could be some other multipart that encodes to an object by some other mechanism, but... I have never heard of such a thing and I've looked, so this should be fine.

See [[!RFC7578]] [Section 5](https://www.rfc-editor.org/rfc/rfc7578.html#section-5) for guidance regarding non-ASCII part names.

See [Encoding `multipart` Media Types](#encoding-multipart-media-types) for further guidance and examples, both with and without the `encoding` field.
Expand Down Expand Up @@ -3879,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
Loading