Skip to content

v3.2: Provide parsing and serialization guidance - #4793

Merged
handrews merged 5 commits into
OAI:v3.2-devfrom
handrews:schema-inspect
Jul 24, 2025
Merged

v3.2: Provide parsing and serialization guidance#4793
handrews merged 5 commits into
OAI:v3.2-devfrom
handrews:schema-inspect

Conversation

@handrews

@handrewshandrews commented Jul 18, 2025•
edited by karenetheridge
Loading

Copy link
Copy Markdown
Member

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/mixed support Encoding Objects can be used with arrays as well as objects.

  • no schema changes are needed for this pull request

@handrews
Provide parsing and serialization guidance
62d67f3
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.
@handrewshandrews added this to the v3.2.0 milestone Jul 18, 2025
@handrews
handrews requested review from a team as code ownersJuly 18, 2025 02:29
@handrewshandrews added the media and encoding Issues regarding media type support and how to encode data (outside of query/path params) label Jul 18, 2025
ralfhandl
ralfhandl requested changes Jul 18, 2025
View reviewed changes

@ralfhandlralfhandl left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1, some nits and questions

Comment threadsrc/oas.md
Comment threadsrc/oas.md Outdated
Comment threadsrc/oas.md Outdated
Comment threadsrc/oas.md
Comment threadsrc/oas.md Outdated
Comment threadsrc/oas.md Outdated
Comment threadsrc/oas.md Outdated
Comment threadsrc/oas.md Outdated
@ralfhandl
ralfhandl requested a review from a teamJuly 18, 2025 08:32
baywet
baywet approved these changes Jul 18, 2025
View reviewed changes

@baywetbaywet left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks it's much clearer!

handrewsand others added 2 commits July 18, 2025 10:16
@handrews@ralfhandl
Apply suggestions from code review
9fb9893
Co-authored-by: Ralf Handl <ralf.handl@sap.com>
@handrews
Expand type guidance and optional further inspection
5661d71
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.
@handrews

handrews commented Jul 18, 2025

Copy link
Copy Markdown
MemberAuthor

@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.

@handrewshandrews changed the title Provide parsing and serialization guidancev3.2: Provide parsing and serialization guidanceJul 18, 2025
ralfhandl
ralfhandl previously approved these changes Jul 19, 2025
View reviewed changes
@ralfhandl
ralfhandl requested a review from a teamJuly 19, 2025 15:01
@handrewshandrews mentioned this pull request Jul 24, 2025
Closed
whitlockjc
whitlockjc previously approved these changes Jul 24, 2025
View reviewed changes

@whitlockjcwhitlockjc left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

handrews
handrews commented Jul 24, 2025
View reviewed changes
Comment threadsrc/oas.md Outdated
Comment threadsrc/oas.md Outdated
@handrews
handrews dismissed stale reviews from whitlockjc and ralfhandl via 2600500July 24, 2025 16:41
whitlockjc
whitlockjc approved these changes Jul 24, 2025
View reviewed changes

@whitlockjcwhitlockjc left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

lornajane
lornajane approved these changes Jul 24, 2025
View reviewed changes

@lornajanelornajane left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Repeat approval since we just dismissed the others' on minor changes. Thanks!

@handrews
handrews merged commit 79ec626 into OAI:v3.2-devJul 24, 2025
2 checks passed
@handrews
handrews deleted the schema-inspect branch August 4, 2025 18:49
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@whitlockjcwhitlockjcwhitlockjc approved these changes
@lornajanelornajanelornajane approved these changes
@ralfhandlralfhandlralfhandl left review comments
+1 more reviewer
@baywetbaywetbaywet approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

media and encodingIssues regarding media type support and how to encode data (outside of query/path params)

Projects

None yet

Milestone

v3.2.0

Development

Successfully merging this pull request may close these issues.

5 participants

@handrews@whitlockjc@lornajane@ralfhandl@baywet