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

Appendix on converting data types to strings (3.0.4) #3840

Merged
merged 5 commits into from
Jun 10, 2024

Conversation

handrews
Copy link
Member

@handrews handrews commented May 22, 2024

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:

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?

@handrews 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
@handrews handrews added this to the v3.0.4 milestone May 22, 2024
@handrews handrews requested a review from a team May 22, 2024 23:59
versions/3.0.4.md Outdated Show resolved Hide resolved
versions/3.0.4.md Outdated Show resolved Hide resolved
Copy link
Contributor

@ralfhandl ralfhandl left a 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
ralfhandl previously approved these changes May 23, 2024
ralfhandl
ralfhandl previously approved these changes May 24, 2024
ralfhandl
ralfhandl previously approved these changes May 28, 2024
miqui
miqui previously approved these changes May 29, 2024
handrews and others added 5 commits June 10, 2024 15:51
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 <ralf.handl@sap.com>
Co-authored-by: Ralf Handl <ralf.handl@sap.com>
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.
@handrews
Copy link
Member Author

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 miqui merged commit 061dcbd into OAI:v3.0.4-dev Jun 10, 2024
1 check passed
@handrews handrews deleted the ser-types-304 branch June 11, 2024 00:21
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
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants