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

handrews · 2025-09-01T00:01:58Z

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.

no schema changes are needed for this pull request

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

handrews · 2025-09-01T00:05:46Z

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

This is definitely easier to read!

ralfhandl · 2025-09-01T07:58:12Z

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.


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.

@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),

This then confuses me. Suppose my OAD consists of one OpenAPI Document (uppercase D) and one or more JSON Schema documents (lowercase d in all four occurrences of this term). Then "parsing all Documents" would mean it is sufficient to only parse the single OpenAPI Document and not parse the referenced JSON Schema documents.

Next confusion: suppose another OAD consists of two OpenAPI Documents with references between them: which of them is the entry document?

ralfhandl · 2025-09-01T07:59:37Z

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.


Suggested change

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.

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.

mikekistler

Looks good. 👍

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

mikekistler · 2025-09-01T11:36:00Z

src/oas.md

+An **OpenAPI Description** (**OAD**) formally describes the surface of an API and its semantics.

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


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 by having an OpenAPI Object with its 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. The required [`openapi`](#oas-version) field of its OpenAPI Object designates which version of the OAS that it uses.

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

mikekistler · 2025-09-01T11:37:39Z

src/oas.md

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

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


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.

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.

mikekistler · 2025-09-01T12:03:41Z

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.


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

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.

@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 · 2025-09-01T17:54:29Z

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

handrews · 2025-09-05T22:04:05Z

I'm reworking this rather substantially and will just post the new thing as its own new PR.

handrews added 2 commits August 31, 2025 16:11

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 added this to the v3.2.0 milestone Sep 1, 2025

handrews requested review from a team as code owners September 1, 2025 00:01

handrews added the editorial Wording and stylistic issues label Sep 1, 2025

ralfhandl reviewed Sep 1, 2025

View reviewed changes

ralfhandl requested a review from a team September 1, 2025 08:04

mikekistler approved these changes Sep 1, 2025

View reviewed changes

ralfhandl requested a review from a team September 2, 2025 07:53

handrews closed this Sep 5, 2025

handrews mentioned this pull request Sep 8, 2025

v3.2: Refactor and streamline OpenAPI Description Structure sections (take 2) #4927

Merged

1 task

	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.

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

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

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

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

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

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

Uh oh!

Conversation

handrews commented Sep 1, 2025 • edited by karenetheridge Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

handrews commented Sep 1, 2025

Uh oh!

ralfhandl left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ralfhandl Sep 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mikekistler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

handrews commented Sep 1, 2025

Uh oh!

handrews commented Sep 5, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

handrews commented Sep 1, 2025 •

edited by karenetheridge

Loading

ralfhandl Sep 5, 2025 •

edited

Loading