-
Notifications
You must be signed in to change notification settings - Fork 9.1k
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
Appendix on converting data types to strings (3.0.4) #3840
Merged
Merged
Conversation
This file contains 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
handrews
added
clarification
requests to clarify, but not change, part of the spec
param serialization
Issues related to parameter and/or header serialization
media and encoding
Issues regarding media type support and how to encode data (outside of query/path params)
labels
May 22, 2024
This was referenced May 23, 2024
ralfhandl
reviewed
May 23, 2024
ralfhandl
reviewed
May 23, 2024
ralfhandl
reviewed
May 23, 2024
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
+1, two minor nits
ralfhandl
previously approved these changes
May 23, 2024
ralfhandl
previously approved these changes
May 24, 2024
This was referenced May 27, 2024
ralfhandl
previously approved these changes
May 28, 2024
miqui
previously approved these changes
May 29, 2024
It's very unclear how numbers, booleans, and other non-UTF-8-string values are converted to strings, particularly for the form media types. This adds a brief appendix that acknowledges the lack of standardization, and points to resources for the few cases that do have specifications. It highlights concerns with relying on certain JSON Schema keywords or values for serialization, and suggests defining schemas of type string and requiring applications to perform the conversion prior to schema validation as a way to control the results. This also clarifies that schema validation occurs before serialization.
Co-authored-by: Ralf Handl <[email protected]>
Co-authored-by: Ralf Handl <[email protected]>
JSON Schema was accidentally the draft for 3.1, while this spec uses the older 7159 for JSON instead of 8259, so I have matched that rather than change it or cite both.
The spec doesn't address it, but implementations often have their own rules.
The most recent force-push was just to resolve merge conflicts. There were previously two TSC approvals, so this should get merged ASAP and only needs one re-approval. |
miqui
approved these changes
Jun 10, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Labels
clarification
requests to clarify, but not change, part of the spec
media and encoding
Issues regarding media type support and how to encode data (outside of query/path params)
param serialization
Issues related to parameter and/or header serialization
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.
Rendering with all currently open 3.0.4 changes (as of the timestamp of this edit - use the dropdown on the word "edited" in the bar for this comment) can be found here.
Fixes:
explode
which are 3.1-specific and will be addressed separately)This is an appendix because it's pretty much just advice for things that otherwise feel like an erroneous gap in the spec - but as with PR #3818, this is stuff where it's hard to know where to look or what to ask, so having it in the spec is important.
It's very unclear how numbers, booleans, and other non-UTF-8-string values are converted to strings, particularly for the form media types. This adds a brief appendix that acknowledges the lack of standardization, and points to resources for the few cases that do have specifications.
It highlights concerns with relying on certain JSON Schema keywords or values for serialization, and suggests defining schemas of type string and requiring applications to perform the conversion prior to schema validation as a way to control the results.
This also clarifies that schema validation occurs before serialization.
QUESTION: I was pretty casual about where I put the "See Appendix C" notes - are there better places?