v3.2: Reorganize sections #4908
Open
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
This moves many sections but does not make any changes to titles or contents. Not even obvious trivial ones. The indentation levels are a little strange to make it easier to merge outstanding PRs and see moved sections, and will be fixed in the next commit.
ralfhandl
approved these changes
Aug 27, 2025
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.
This is the first step in addressing #4831 (with slight differences from the re-org last posted in that issue). It only moves sections and adjusts indents, without any other changes to contents or to section names. All of the more complex changes, including renaming, combining, or splitting sections, will be in subsequent PR(s).
GitHub does not use git's feature to detect moved code in diffs, so I do not recommend looking at the normal diff. I have provided multiple other ways to look at this.
To prove that all non-heading lines were only moved, you can see screenshots of
git diff --color-moved=dimmed-zebrahere. These are not intended for detailed review, they just show by color what is a move vs a change.Even in those diffs it's still hard to see what was moved, so I made alternate views of the two commits, one of which does the move and the other of which adjusts heading levels. I recommend looking at the headings-only diffs in particular:
Finally, here is the rendered outcome: OAS 3.2
Two sections, "Object" and "Schema" (both under "Definitions", not the big "Schema" section obviously) have been entirely removed, as the new section names (renamed in a future PR) and organization makes them unnecessary.
Several additional section headings have been removed because they only had subsections (no other content) and the subsections no longer need the grouping: "Specification", "Definitions", "Working With Data".
The resulting top-level sections are: