v3.2: Provide parsing and serialization guidance #4793
Conversation
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
This creates a "Working with Data" section that incorporates the existing "Data Types" section (with some section level adjustments) along with new guidance on mapping different kinds of data between serialized, data, and application forms. This terminology matches the terminology currently being considered for examples. The application form is largely out of scope for the OAS, and is mainly included to clarify this scope while acknowledging that the OAS may influence such things. Most of the new material is on parsing and serializing, briefly addressing JSON as the common case before going into detail on non-JSON data, with examples. This is where the requirements for schema and/or instance inspection/searching are listed. The only additional change is no longer mentioning the property schema in the Encoding Object, in part because with the new `multipart/mixed` support Encoding Objects can be used with arrays as well as objects.
handrews
added
the
media and encoding
ralfhandl
requested changes
Jul 18, 2025
baywet
approved these changes
Jul 18, 2025
Co-authored-by: Ralf Handl <ralf.handl@sap.com>
Provide examples of narrowing multiple types, and make it clear that every schema without a `type` keyword allows all types. Also note that implementations MAY go beyond these requirements, but set boundaries on what they can do.
|
@ralfhandl I have made the other updates, and in the process expanded the example and guidance somewhat. I also restored the MAY allowing further inspection, and put some boundaries on it. Yesterday I had not been able to figure out a good way to bound that but today it seems more tractable. @baywet this might interest you in particular as it does place some restrictions on inferences that can be made about type. |
handrews
changed the title
ralfhandl
approved these changes
Jul 19, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
NOTE: This PR is a replacement for #4743. @whitlockjc and @baywet it is largely inspired by your questions of how far we need to go to explain how to build on schemas and other parts of the OAS, and how that fits with tools that do not work with runtime data (e.g. code gen). This is now substantially less ambitious and I think much better for it.
This creates a "Working with Data" section that incorporates the existing "Data Types" section (with some section level adjustments) along with new guidance on mapping different kinds of data between serialized, data, and application forms. This terminology matches the terminology currently being considered for examples. Note that "Working with Binary Data" is just moved, but the diff got confused and sort-of makes it look like the heading got deleted.
The application form is largely out of scope for the OAS, and is mainly included to clarify this scope while acknowledging that the OAS may influence such things.
Most of the new material is on parsing and serializing, briefly addressing JSON as the common case before going into detail on non-JSON data, with examples. This is where the requirements for schema and/or instance inspection/searching are listed.
The only additional change is no longer mentioning the property schema in the Encoding Object, in part because with the new
multipart/mixedsupport Encoding Objects can be used with arrays as well as objects.