Limit interoperable parsing expectations (avoid type conflicts) #3732
Conversation
This file contains 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
As discovered through the OASComply project, certain referencing scenarios are ambiguous, with different authorities holding contradictory interpretations regarding whether and how they are to be supported. As a result, it is impossible to define compliance, as all of the interpretations can be argued to be "correct" in some sense. This change excludes some particularly challenging scenarios from compliance testing by making their behavior explicitly implementation-defined. This has several benefits: * No current implementation is rendered non-compliant * No currently usable OAD is rendered invalid * New implementers need not put effort into handling these scenarios * User expectations are set to _not_ expect consistent behavior * Linters can write a rule to match these expectations * Everyone is guided towards straightforwad best practices
handrews
added
clarification
The Structural Interoperability section should be a subsection of the OpenAPI Description Structure section.
ralfhandl
reviewed
Apr 25, 2024
Co-authored-by: Ralf Handl <ralf.handl@sap.com>
ralfhandl
approved these changes
Apr 25, 2024
handrews
added a commit
that referenced
this pull request
May 22, 2024
Clarify interoperable parsing expectations (3.0.4 port of #3732)
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 of several changes to un-block the OASComply project.
As discovered through the OASComply project, certain referencing scenarios are ambiguous, with different authorities holding contradictory interpretations regarding whether and how they are to be supported. As a result, it is impossible to define compliance, as all of the interpretations can be argued to be "correct" in some sense.
This change excludes some particularly challenging scenarios from compliance testing by making their behavior explicitly implementation-defined. This has several benefits:
Note that the scenarios being deemed "implementation-defined" here are rarely if ever done on purpose.
If you are unclear as to why there is ambiguity in these parsing rules, please read at least the summary report on this topic, before objecting. While the scenarios excluded here were arguably well-specified in 2.0, the relevant language was removed in 3.0, with the requirements becoming even more ambiguous in 3.1.
If accepted, I will forward-port this to 3.2.0. I believe this can also be backported to 3.0.4, but the requirements are slightly different there so I wanted to start with the easiest case, which is 3.1.1.