v3.2: warn that multiple document logic may change

[karenetheridge]

tags, servers and securitySchemes really ought to resolve to the referring document, not the entry document, for consistency when creating different combinations of documents in an OAD; we may clarify or fix this in 3.3

• no schema changes are needed for this pull request

[handrews]

I don't think this is getting revisited until a major release, and there's no need to make a note of that as everything can be revisited in a major release.

It's the way it is now because resolve-to-referring-document can be done with the URI-based alternatives (except for tags, but @lornajane did not want a URI alternative for tags), but there is no other way to do the resolve-to-entry behavior which a lot of things depend on right now.

Since I don't think this is getting revisited in a minor release, I'm against adding this. It just makes people feel like the spec will be unstable, and that's what we're trying to get away from.

[karenetheridge]

@handrews I absolutely intend to submit a proposal for more robust multiple-document OAD support, and you yourself encouraged me to do so. Would I be wasting my time?

[handrews]

@karenetheridge

@handrews I absolutely intend to submit a proposal for more robust multiple-document OAD support, and you yourself encouraged me to do so. Would I be wasting my time?

No, and I'm unclear on why you would be. Please don't take my response to this very specific yet rather cryptic change for 3.2 to imply that I'm against a 3.3 proposal I haven't even seen yet. I read this as a generic "let's give ourselves an out" precaution, and I don't see a reason to put that in at this stage.

Perhaps if you could explain what of your proposal would require this, that would help us evaluated the tradeoffs? My understanding was that the goal was to use Pathes Objects from multiple documents, not a rewrite of resolution rules in general.

But it all comes back to stability and compatibility limiting what we can do in a minor release. While we technically have wiggle-room with SHOULDs, they are still very strong (you are supposed to have a clear and good reason for disregarding a SHOULD), and replacing one SHOULD with a new SHOULD that contradicts it means that anyone who followed the past SHOULD suddenly needs to justify why they're not following the new one. It sets up contradictory expectations on the part of users.

Think of it this way: If a 3.2 OAD is written assuming entry resolution for component names because that is what 3.2 says SHOULD be done, but 3.3 says that current resolution SHOULD be done, then changing openapi: 3.2.9 to openapi: 3.3.0 produces different behavior. That's not how our compatibility is supposed to work. You're supposed to be able to take a 3.2 OAD that doesn't use any extensions or depend on non-compliant tool behavior and make it a 3.3 OAD without any behavioral changes. That is currently true of 3.1 to 3.2, particularly if your 3.1 OAD is compatible with the SHOULDs we itroduced in 3.1.1. Which were mostly chosen to ratify the most common behavior that already existed.

[handrews]

@karenetheridge there might be a way to get what you need for the consistency issues you mention without causing compatibility problems, though... that's why I say that if you can share a bit more details we might be able to figure out how to do that.

[miqui]

hi @handrews

Think of it this way: If a 3.2 OAD is written assuming entry resolution for component names because that is what 3.2 says SHOULD be done, but 3.3 says that current resolution SHOULD be done, then changing openapi: 3.2.9 to openapi: 3.3.0 produces different behavior.

Sorry, I don't get this point.

@handrews I absolutely intend to submit a proposal for more robust multiple-document OAD support, and you yourself encouraged me to do so. Would I be wasting my time?

Was I wrong to assume here?

[karenetheridge]

a rewrite of resolution rules in general

I am not looking at rewriting URI resolution rules. The section this PR edits is solely concerned with implicit connections, and this section already states: "the resolution process in multi-document OADs is implementation-defined", which I am interpreting as meaning that stricter behaviour can be subsequently defined without altering any existing requirements.

If however the belief is that even a recommendation cannot be changed in a minor release, then I will withhold my proposal until we are closer to a 4.0 release.

[handrews]

@karenetheridge

"resolution rules in general" was intended to refer to implicit resolution, not URI resolution, my apologies for the imprecision.

If however the belief is that even a recommendation cannot be changed in a minor release, then I will withhold my proposal until we are closer to a 4.0 release.

The key parts are:

the resolution process in multi-document OADs is implementation-defined, within the constraints described in this section.

and

it is RECOMMENDED that tools resolve from the entry document, rather than the current document.

Per RFC2119:

3. SHOULD This word, or the adjective "RECOMMENDED", mean that there
may exist valid reasons in particular circumstances to ignore a
particular item, but the full implications must be understood and
carefully weighed before choosing a different course.

So changing a SHOULD or RECOMMENDED means that implementors have to re-evaluate those "full implications" and decide what to do. I think we ought to be cautious about that, as switching the recommendation changes the behavior substantially in this case.

But I am just one person here. My opinion alone shouldn't block consideration.

[karenetheridge]

The proposal would include a change of default behaviour where implicit connections to global elements like tags, servers, and security would be scoped to individual files, rather than referring to the entry document (along with optional keywords that might modify this behaviour, but that's not relevant here).

That is: a secondary file in the OAD that had a tags keyword in an operation would use the top-level tags definitions in that file, rather than in the entry document. Since that means the tag definition for that operation will never change, no matter how or where that document is included in an OAD (or used separately as a single-document OAD), this improves behaviour consistency and makes it easier for a user to mix and match individual files in various combinations as different OADs.

However, if none of this is possible to be changed in the 3.x line, then there is no point in proceeding further.