v3.2: Refactor and streamline OpenAPI Description Structure sections #4918

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Open

handrews wants to merge 2 commits into OAI:v3.2-dev

from handrews:oad

Open

v3.2: Refactor and streamline OpenAPI Description Structure sections #4918

handrews wants to merge 2 commits into OAI:v3.2-dev from handrews:oad

+184 −173

Conversation

handrews

Copy link

Member

@handrews handrews commented Sep 1, 2025

Please review carefully, as there's more going on here than in the other reorg PRs.

These sections had gotten rather bloated, plus moving them under the OpenAPI Object changes how it all reads. These two commits first move things (with as few changes as possible) and then make significant edits to the results for conciseness and readability. None of the changes are intended to change any actual requirements.

While there are a lot of changes, there are also a lot of unchanged blocks, including the former Appendixes F and G which are now in reversed order and (in one case) a subsection of the new appendix. Here are git diff --color-moved=dimmed-zebra diffs which make that a lot more clear (but are not good for detailed reviewing).

Rendered result.

1st commit message:

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.

2nd commit message:

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.

schema changes are included in this pull request
schema changes are needed for this pull request but not done yet
no schema changes are needed for this pull request

handrews added 2 commits

August 31, 2025 16:11

@handrews


 Refactor OpenAPI Description Structure sections

ae6b05f

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

@handrews


 Streamline OpenAPI Description Structure post-moves

39af966

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.

@handrews handrews added this to the v3.2.0 milestone

Sep 1, 2025

@handrews handrews requested review from a team as code owners

September 1, 2025 00:01

@handrews handrews added the editorial label

Sep 1, 2025

@handrews

Copy link

Member Author

handrews commented Sep 1, 2025

Note that despite my care to not overlap any changes, git can't understand changes to adjacent lines and wants this to conflict with PR #4915. Please approve and merge that first, and let me fix the conflict because there will not be any changes to these commits.

ralfhandl

ralfhandl reviewed

Sep 1, 2025

View reviewed changes

Copy link

Contributor

@ralfhandl ralfhandl left a comment

Choose a reason for hiding this comment

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

This is definitely easier to read!

src/oas.md

* Detecting JSON Schema documents through detecting keywords or otherwise successfully parsing the document in accordance with the JSON Schema specification

* Detecting a document containing a referenceable Object at its root based on the expected type of the reference

* Allowing users to configure the type of documents that might be loaded due to a reference to a non-root Object

Implementations MUST NOT treat a reference as unresolvable before completely parsing all Documents provided to the implementation as possible parts of the OAD.

Copy link

Contributor

@ralfhandl ralfhandl Sep 1, 2025

Choose a reason for hiding this comment

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

Suggested change

Implementations MUST NOT treat a reference as unresolvable before completely parsing all Documents provided to the implementation as possible parts of the OAD.

Implementations MUST NOT treat a reference as unresolvable before completely parsing all documents provided to the implementation as possible parts of the OAD.

Lowercase "document" seems more in line with the surrounding text which only capitalizes OpenAPI Documents.

Copy link

Member Author

@handrews handrews Sep 1, 2025

Choose a reason for hiding this comment

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

@ralfhandl It should be "OpenAPI Documents." Lower-case "document" is not correct (I would prefer not to address non-OpenAPI/JSON Schema Document "documents" at all as I thin it would be less confusing at this point, but I think I already lost that debate),

src/oas.md

While it is possible to structure certain OpenAPI Descriptions to ensure that they will behave correctly when references are parsed as isolated fragments, depending on this is NOT RECOMMENDED.

This specification does not explicitly enumerate the conditions under which such behavior is safe and provides no guarantee for continued safety in any future versions of the OAS.

If some referenced (non-entry) documents have an Object other than an OpenAPI Object as its root, or containes additional non-OpenAPI content, or if only the referenced part of the document is parsed, the resulting behavior can be implementation-defined or undefined; see [Appendix G: Parsing and Resolution Guidance](#appendix-g-parsing-and-resolution-guidance) for details.

Copy link

Contributor

@ralfhandl ralfhandl Sep 1, 2025

Choose a reason for hiding this comment

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

Suggested change

If some referenced (non-entry) documents have an Object other than an OpenAPI Object as its root, or contain additional non-OpenAPI content, or if only the referenced part of the document is parsed, the resulting behavior can be implementation-defined or undefined; see [Appendix G: Parsing and Resolution Guidance](#appendix-g-parsing-and-resolution-guidance) for details.

@ralfhandl ralfhandl requested a review from a team

September 1, 2025 08:04

mikekistler

mikekistler approved these changes

Sep 1, 2025

View reviewed changes

Copy link

Contributor

@mikekistler mikekistler left a comment

Choose a reason for hiding this comment

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

Looks good. 👍

I left a few minor suggestions which are hopefully uncontroversial but happy to discuss if there is any concern.

src/oas.md

An OpenAPI Document is a single JSON or YAML document that conforms to the OpenAPI Specification. An OpenAPI Document compatible with OAS 3.\*.\* contains a required [`openapi`](#oas-version) field which designates the version of the OAS that it uses.

An **OpenAPI Document** is a single JSON or YAML document that conforms to the OpenAPI Specification by having an OpenAPI Object with its required [`openapi`](#oas-version) field which designates the version of the OAS that it uses.

Copy link

Contributor

@mikekistler mikekistler Sep 1, 2025

Choose a reason for hiding this comment

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

The "by having" wording here makes it sound (to me anyway) like this is all that is needed to conform to the OpenAPI spec. How about:

Suggested change

An **OpenAPI Document** is a single JSON or YAML document that conforms to the OpenAPI Specification. The required [`openapi`](#oas-version) field of its OpenAPI Object designates which version of the OAS that it uses.

Copy link

Member Author

@handrews handrews Sep 1, 2025

Choose a reason for hiding this comment

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

@mikekistler I'm not sure I agree with this rewording, I'll think on it.

src/oas.md

An OpenAPI Description (OAD) MAY be made up of a single JSON or YAML document or be divided into multiple, connected parts at the discretion of the author. In the latter case, [Reference Object](#reference-object), [Path Item Object](#path-item-object) and [Schema Object](#schema-object) `$ref` fields, as well as the [Link Object](#link-object) `operationRef` field, and the URI form of the [Discriminator Object](#discriminator-object) `mapping` field, are used to identify the referenced elements.

An OpenAPI Description MAY be made up of a single JSON or YAML OpenAPI Document or be divided into multiple, connected parts at the discretion of the author.

Copy link

Contributor

@mikekistler mikekistler Sep 1, 2025

Choose a reason for hiding this comment

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

Squeeze out extra space.

Suggested change

An OpenAPI Description MAY be made up of a single JSON or YAML OpenAPI Document or be divided into multiple, connected parts at the discretion of the author.

src/oas.md

##### Parsing Documents

In order to properly handle [Schema Objects](#schema-object), OAS 3.1 inherits the parsing requirements of [JSON Schema Specification Draft 2020-12](https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html#section-9), with appropriate modifications regarding base URIs as specified in [Relative References In URIs](#relative-references-in-api-description-uris).

Each OpenAPI Document in an OAD MUST be fully parsed in order to locate possible reference targets, including the OpenAPI Object's [`$self`](#oas-self) field and the [Schema Object's](#schema-object) `$id`, `$anchor`, and `$dynamicAnchor` keyword.

Copy link

Contributor

@mikekistler mikekistler Sep 1, 2025

Choose a reason for hiding this comment

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

I have two concerns with this new text:

I think an OAD may include documents that are not OpenAPI Documents (e.g. JSON Schema documents), and these also need to be parsed in the manner described, so "OpenAPI Document" should just be "document".
The beginning of this sentence talks about reference targets, but then says "including ..." things that are not reference targets but instead are keywords that affect how reference targets are identified.

Here's a suggested change to address these concerns:

Suggested change

Each document in an OAD MUST be fully parsed in order to locate possible reference targets for references in the OAD, taking into account the OpenAPI Object's [`$self`](#oas-self) field and the [Schema Object's](#schema-object) `$id`, `$anchor`, and `$dynamicAnchor` keyword.

Copy link

Member Author

@handrews handrews Sep 1, 2025

Choose a reason for hiding this comment

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

@mikekistler

I'll add "JSON Schema Documents" or similar. Lower-case "document" is too permissive as it allows thing that are neither OpenAPI Documents nor JSON Schema Documents.
Yeah that line got munged, I'll either accept this suggestion later or (after reading the context) reword it in some other way. I'd like to get away from having too many lists of keywords that we need to keep up-to-date scattered all over.

@handrews

Copy link

Member Author

handrews commented Sep 1, 2025

@mikekistler @ralfhandl I'll wait to act on suggestions until after PR #4913 is merged so I can resolve conflicts.

@ralfhandl ralfhandl requested a review from a team

September 2, 2025 07:53

Labels

editorial

3 participants

@handrews @ralfhandl @mikekistler

v3.2: Refactor and streamline OpenAPI Description Structure sections #4918

Are you sure you want to change the base?

v3.2: Refactor and streamline OpenAPI Description Structure sections #4918

Conversation

@handrews handrews commented Sep 1, 2025

Uh oh!

handrews commented Sep 1, 2025

Uh oh!

@ralfhandl ralfhandl left a comment

Choose a reason for hiding this comment

Uh oh!

@ralfhandl ralfhandl Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

@handrews handrews Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

@ralfhandl ralfhandl Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

@mikekistler mikekistler left a comment

Choose a reason for hiding this comment

Uh oh!

@mikekistler mikekistler Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

@handrews handrews Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

@mikekistler mikekistler Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

@mikekistler mikekistler Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

@handrews handrews Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

handrews commented Sep 1, 2025

Uh oh!

Uh oh!