Skip to content

Commit def8f41

Browse files
committed
Explain lack of HTTP header for base64 encoding
Also, remove the example that goes against the advice in the updated binary-handling section.
1 parent e62f218 commit def8f41

File tree

1 file changed

+1
-14
lines changed

1 file changed

+1
-14
lines changed

versions/3.1.1.md

Lines changed: 1 addition & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -174,7 +174,7 @@ Keyword | Raw | Encoded | Comments
174174
`contentMediaType` | `image/png` | `image/png` | can sometimes be omitted if redundant (see below)
175175
`contentEncoding` | _omit_ | `base64` or `base64url` | other encodings are [allowed](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#section-8.3)
176176

177-
Note that the encoding indicated by `contentEncoding`, which inflates the size of data in order to represent it as 7-bit ASCII text, is unrelated to HTTP's `Content-Encoding` header, which indicates whether and how a message body has been compressed and is applied after all content serialization described in this section has occurred.
177+
Note that the encoding indicated by `contentEncoding`, which inflates the size of data in order to represent it as 7-bit ASCII text, is unrelated to HTTP's `Content-Encoding` header, which indicates whether and how a message body has been compressed and is applied after all content serialization described in this section has occurred. Since HTTP allows unencoded binary message bodies, there is no standardized HTTP header for indicating base64 or similar encoding of an entire message body.
178178

179179
Using a `contentEncoding` of `base64url` ensures that URL encoding (as required in the query string and in message bodies of type `application/x-www-form-urlencoded`) does not need to further encode any part of the already-encoded binary data.
180180

@@ -1499,19 +1499,6 @@ content:
14991499
application/octet-stream: {}
15001500
```
15011501

1502-
Binary content transferred with base64 encoding:
1503-
1504-
```yaml
1505-
content:
1506-
image/png:
1507-
schema:
1508-
type: string
1509-
contentMediaType: image/png
1510-
contentEncoding: base64
1511-
```
1512-
1513-
Note that the `Content-Type` remains `image/png`, describing the semantics of the payload. The JSON Schema `type` and `contentEncoding` fields explain that the payload is transferred as text. The JSON Schema `contentMediaType` is technically redundant, but can be used by JSON Schema tools that may not be aware of the OpenAPI context.
1514-
15151502
These examples apply to either input payloads of file uploads or response payloads.
15161503

15171504
A `requestBody` for submitting a file in a `POST` operation may look like the following example:

0 commit comments

Comments
 (0)