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 @@ -1375,14 +1375,14 @@
The behavior of the `encoding` field is designed to support web forms, and is therefore only defined for media types structured as name-value pairs that allow repeat values, most notably `application/x-www-form-urlencoded` and `multipart/form-data`.

To use the `encoding` field, each key under the field MUST exist as a property; `encoding` entries with no corresponding property SHALL be ignored.
Array properties MUST be handled by applying the given Encoding Object to produce one encoded value per array item, each with the same `name`, as is recommended by [[!RFC7578]] [Section 4.3](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.3) for supplying multiple values per form field.

Check failure on line 1378 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.3 Status: null Cannot read properties of null (reading 'status')

Raw Output:
message:"Cannot reach https://www.rfc-editor.org/rfc/rfc7578.html#section-4.3 Status: null Cannot read properties of null (reading 'status')"  location:{path:"src/oas.md"  range:{start:{line:1378  column:178}  end:{line:1378  column:248}}}  severity:ERROR  source:{name:"linkspector"  url:"https://github.com/UmbrellaDocs/linkspector"}
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]].
Comment thread
karenetheridge marked this conversation as resolved.
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 @@ -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 `multipart/form-data` in particular ([RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.8)).

Check failure on line 1854 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.8 Status: null Cannot read properties of null (reading 'status')

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

##### Handling Multiple `contentType` Values

Expand All @@ -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 @@ -1947,7 +1947,7 @@

##### Example: Multipart Form with Multiple Files

In accordance with [RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.3), multiple files for a single form field are uploaded using the same name (`file` in this example) for each file's part:

Check failure on line 1950 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.3 Status: null Cannot read properties of null (reading 'status')

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

```yaml
requestBody:
Expand Down Expand Up @@ -2641,7 +2641,7 @@
/ "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
```

Here, `json-pointer` is taken from [RFC6901](https://tools.ietf.org/html/rfc6901), `char` from [RFC8259](https://tools.ietf.org/html/rfc8259#section-7) and `token` from [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#section-5.6.2).

Check failure on line 2644 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.2 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.2 Status: null Cannot read properties of null (reading 'status')"  location:{path:"src/oas.md"  range:{start:{line:2644  column:170}  end:{line:2644  column:238}}}  severity:ERROR  source:{name:"linkspector"  url:"https://github.com/UmbrellaDocs/linkspector"}

The `name` identifier is case-sensitive, whereas `token` is not.

Expand Down Expand Up @@ -2776,7 +2776,7 @@

#### Representing the `Set-Cookie` Header

The `Set-Cookie` header is noted in [[!RFC9110]] [Section 5.3](https://www.rfc-editor.org/rfc/rfc9110.html#section-5.3) as an exception to the normal rules of headers with multiple values.

Check failure on line 2779 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.3 Status: null Cannot read properties of null (reading 'status')

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

For most headers using the general syntax defined in RFC9110, the multiple-line and comma-separated single-line forms are interchangeable, meaning that this:

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-16.4.1 Status: null Cannot read properties of null (reading 'status')

Raw Output:
message:"Cannot reach https://www.rfc-editor.org/rfc/rfc9110.html#section-16.4.1 Status: null Cannot read properties of null (reading 'status')"  location:{path:"src/oas.md"  range:{start:{line:4587  column:144}  end:{line:4587  column:248}}}  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
Loading