Uh oh!
There was an error while loading. Please reload this page.
v3.2: Refactor and streamline OpenAPI Description Structure sections (take 2) - #4927
Merged
Conversation
* Remove "OpenAPI Description" and "OpenAPI Document" section headings and reorder those paragraphs and the intro "OpenAPI Description Structure" paragraph to define the terms inline * Switch Appendixes F and G * F->G stays as-is, with base URI examples * G->F is expanded to a more general "Parsing and Resolution Guidance" section * Move several pieces of "Parsing Documents" to Appendix G * How to parse complete documents as the intro section * A "Warnings Regarding Fragmentary Parsing" section * Move "Structural Interoperability" under Appendix G and rename it to "Conflicts Between Field Types and Reference Contexts" * Move most of "Resolving Implicit Connections to Appendix G and rename it "Guidance Regarding Implicit Connections" * Put the original Section F implicit connection examples as a "Implicit Connection Resolution Examples" subsection Minimal adjustments were made to links to keep the build functional.
A lot of what was here is no longer needed, and other things can be said better either because of the new arrangement or because I thought of better wording since I first wrote things. In particular, get rid of the awkward Document vs document distinction by banishing discussion of small-d documents to the appendix.
Uh oh!
There was an error while loading. Please reload this page.
mikekistler
previously approved these changes
Sep 8, 2025
Uh oh!
There was an error while loading. Please reload this page.
Co-authored-by: Ralf Handl <ralf.handl@sap.com>
handrews
commented
Sep 8, 2025
MemberAuthor
Also added a commit to fix the inaccurate statement about |
ralfhandl
previously approved these changes
Sep 8, 2025
ralfhandl
approved these changes
Sep 8, 2025
This was referenced Sep 8, 2025
Uh oh!
There was an error while loading. Please reload this page.
1 task
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 freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
4 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.
Replacement for PR #4918 – please review carefully, I've rewritten this too many times across too many widely separated days which is getting a bit confusing for me.
This further streamlines things and gets rid of "Document" vs "document" by banishing discussion of what had been "documents" to Appendix G, and saying that unless otherwise specified, "document" (regardless of capitalization) refers to documents having either an OpenAPI Object or Schema Object at the root.
I have updated the rendered page on my personal github pages.
This has two commits (one for moves, one for changes, more or less) as with #4918.
Please let me know if you want other ways of looking at diffs that I did for that other PR.