Gather data modeling sections into a "Modeling Data" top-level section#4472
Closed
handrews wants to merge 7 commits intoOAI:v3.2-devfrom
Closed
Gather data modeling sections into a "Modeling Data" top-level section#4472handrews wants to merge 7 commits intoOAI:v3.2-devfrom
handrews wants to merge 7 commits intoOAI:v3.2-devfrom
Conversation
handrews
added
schema-object
discriminator
xml
param serialization
ralfhandl
reviewed
Mar 21, 2025
ralfhandl
previously approved these changes
Mar 21, 2025
ralfhandl
reviewed
Mar 21, 2025
ralfhandl
previously approved these changes
Mar 21, 2025
Create a new top-level section called "Modeling Data" that collects various data modeling and serialization sections that go well beyond explaining the Object fields. This just moves sections with no changes except to adjust the heading level to build properly. Subsequent changes will move examples into the new section and streamline the resulting content.
This just brings each of the examples corresponding to subsections under "Data Modeling Techniques" into the appropriate subsection.
This does a few section name and indentation level changes to improve the organization of the new section. It also adds links from the old locations to the new.
This only addresses the refactored Modeling Data sections, the rest will be handled separately.
Member
Author
|
@ralfhandl I've done a bit more work and incorporated your changes that were still relevant, including picking a preferred JSON Schema URL which we can change further elsewhere (since this is still just a "get feedback on direction" PR) |
Contributor
|
I like the direction of keeping the Objects sections simple & straightforward and collecting the nitty gritty special cases further down. |
Contributor
|
Just wanted to add a note after seeing this in the meeting, we discussed whether using some of this content on the learn site might make for more maintainable/navigable content and a shorter/more readable specification. |
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
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.
I went to add streaming JSON support to 3.2 and was struck again at how scattered various bits of guidance on data modeling are.
This mostly just moves sections (big sections in the first commit, then some examples in the second) and then does a tiny bit of renaming, re-indenting, and linking to make it flow. It is a draft because (assuming we go this route), it is not clear where to draw the line, particularly with examples.
There is significant overlap between the examples moved from the Schema Object and the examples still in the Discriminator Object section. I also left the XML Object Examples where they were, which makes the Modeling XML section rather perfunctory.
If folks like this general idea, we can work out how to balance what goes where.
Note that I also slightly moved "Rich Text Formatting" as taking the data modeling sections out of the introduction left it sandwiched awkwardly between the Document Structure section and the Resolving URIs/URLs sections, which really ought to be next to each other anyway. (Please do not discuss re-organizing other sections. In particular, @karenetheridge and I are already planning to reorganize Document Structure and the Resolving sections, so please wait for that effort to open that topic).