Skip to content
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.

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

Clarify how to model binary data in 3.1 #3727

Merged
merged 3 commits into from
Apr 28, 2024
Merged

Conversation

handrews
Copy link
Member

@handrews handrews commented Apr 20, 2024

Note: 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 multipart media types with named parts are supported, as they are modeled as an object.

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 handrews added schema-object media and encoding Issues regarding media type support and how to encode data (outside of query/path params) labels Apr 20, 2024
@handrews handrews added this to the v3.1.1 milestone Apr 20, 2024
@handrews handrews requested a review from a team April 20, 2024 19:53
@handrews
Copy link
Member Author

Paging @karenetheridge as it won't let me add you as a requested reviewer.

Also, remove the example that goes against the advice in the
updated binary-handling section.
@handrews
Copy link
Member Author

handrews commented Apr 27, 2024

@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 format: byte]

@miqui miqui merged commit 5e48c67 into OAI:v3.1.1-dev Apr 28, 2024
1 check passed
@handrews handrews deleted the encodings branch May 9, 2024 19:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
media and encoding Issues regarding media type support and how to encode data (outside of query/path params) schema-object
Projects
None yet
3 participants