Clarify how to model binary data in 3.1#3727
Merged
miqui merged 3 commits intoOAI:v3.1.1-devfrom Apr 28, 2024
Merged
Conversation
This reorganizes binary data-related guidance into a "Working With Binary Data" section, as has already been done in 3.0.4. This includes more detailed guidance on when various approaches to binary data make sense (e.g. you cannot stuff raw binary into JSON no matter what you put in your Schema Object, and while you can base64-encode entire message bodies, it takes up a lot more space for no clear benefit). Also note that only `multipart` media types with named parts are supported, as they are modeled as an object.
handrews
added
schema-object
media and encoding
Member
Author
|
Paging @karenetheridge as it won't let me add you as a requested reviewer. |
This was
linked to
issues
Apr 20, 2024
This was referenced Apr 20, 2024
ralfhandl
approved these changes
Apr 22, 2024
Also, remove the example that goes against the advice in the updated binary-handling section.
Member
Author
|
@ralfhandl after your approval I removed an example that contradicts the guidance in the revised section, and clarified that there is no HTTP header that can indicate base64-encoding of an entire message body (which was the problem with the removed example- it ended up senging a PNG as text with no in-message explanation of the encoding). [EDIT: And also fixed a stray |
miqui
approved these changes
Apr 28, 2024
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Content-EncodingHTTP header field andcontentEncoding#2476Note: I wrote most of this quite some time ago and just tidied it up now... please review it carefully as I might have missed some unfinished aspect.
This reorganizes binary data-related guidance into a "Working With Binary Data" section, as has already been done in 3.0.4.
This includes more detailed guidance on when various approaches to binary data make sense (e.g. you cannot stuff raw binary into JSON no matter what you put in your Schema Object, and while you can base64-encode entire message bodies, it takes up a lot more space for no clear benefit).
Also noted that only
multipartmedia types with named parts are supported, as they are modeled as an object.