v3.2: Refactor and streamline OpenAPI Description Structure sections (take 2) #4927
Conversation
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
* 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.
handrews
changed the title
Co-authored-by: Ralf Handl <ralf.handl@sap.com>
|
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
lornajane
approved these changes
Sep 9, 2025
3 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.