Skip to content
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

Limit interoperable parsing expectations (avoid type conflicts) #3732

Merged
merged 4 commits into from
Apr 25, 2024

Conversation

handrews
Copy link
Member

@handrews handrews commented Apr 21, 2024

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:

  • 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 for these scenarios
  • Linters can write a rule to match these expectations
  • Everyone is guided towards straightforward best practices

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.

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 handrews added clarification requests to clarify, but not change, part of the spec re-use: ref/id resolution how $ref, operationId, or anything else is resolved labels Apr 21, 2024
@handrews handrews added this to the v3.1.1 milestone Apr 21, 2024
@handrews handrews requested a review from a team April 21, 2024 16:49
The Structural Interoperability section should be a subsection
of the OpenAPI Description Structure section.
versions/3.1.1.md Outdated Show resolved Hide resolved
Co-authored-by: Ralf Handl <ralf.handl@sap.com>
Copy link
Contributor

@lornajane lornajane left a comment

Choose a reason for hiding this comment

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

Thanks for this!

@lornajane lornajane merged commit 6d1ca8e into OAI:v3.1.1-dev Apr 25, 2024
1 check passed
@handrews handrews deleted the multi-parse branch May 1, 2024 19:51
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
Labels
clarification requests to clarify, but not change, part of the spec re-use: ref/id resolution how $ref, operationId, or anything else is resolved
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants