Fix: #110. Interoperability considerations instead of new parameter

[ioggstream]

This PR

• replaces Fix: #110. Schema Object parameter #118
• adds interoperability considerations about accepting referenced resources.

[darrelmiller]

Same comment as in the other PR. Why would we limit this?

[ioggstream]

Let bygones be bygones :)

I think that OAS 3.0 is the first specification with a standardization base,
and referencing 2.0 does not help interoperability.

Moreover, it's in an FAQ that will be removed at publication.

[handrews]

I think that OAS 3.0 is the first specification with a standardization base,

What does this mean, exactly? OAS 2.0 (which was a tiny bit different from Swagger 2.0, but mostly just small fixes to errors) was the first version released under the OpenAPI Initiative. So it's as standardized as 3.0 or 3.1.

and referencing 2.0 does not help interoperability.

Didn't we define a version media type parameter for content negotiation on this? While I hate that this is true, there are still tools out there that can't use anything after 2.0. I'd love to do anything and everything to make 2.0 go away, but I'm not sure that forbidding it here will really help that goal. And it seems to prevent people who might want to try to bridge 2.0 to 3.x from making an effort in a standardized way that is consistent with what they will do to bridge 3.0 to 3.1+, or to 4.0

Moreover, it's in an FAQ that will be removed at publication.

Does this mean that in practice, 2.0 is not excluded? I'm a bit confused.

[ioggstream]

forbidding it here will really help that goal. And it seems to prevent people who might want to try to bridge 2.0 to 3.x

This makes sense, but I think that migration should be the only reason for that.

Actually, using version: 2.0 is not "forbidden". Just "undefined" here, because:

• I did no proof-reading of the spec wrt OAS 2.0 and there are no statements such as:

dependently on the OAS version, the keyword associated with the version is different between 2.0 (swagger) and 3+ (openapi) ...

• I don't know whether the terms of "OAD", "OAd", ... are still valid for v2.0...
• 2.0 tools generally use application/vnd.swagger.whatever

Anyway, I'm not that into v2.0, but if you/ @darrelmiller think that this document suits OAS 2.0, we can extend the scope.

[handrews]

This is talking about using the version parameter in the Content-Type header of a response, or a similar usage, correct? Should this be made more clear when initially discussing the parameter usage? What happens when a version paramter is used in this way with an OpenAPI Document (with an OpenAPI Object) where the openapi field disagrees with the version parameter? "Disagrees" here needs to be handled with the same concerns over compatibility and version matching that I just brought up in #124.

[ioggstream]

using the version parameter in the Content-Type header of a response

Yes, this is stated in the document introduction: can you please check if it's clear enough here?

• https://github.com/ietf-wg-httpapi/mediatypes/blob/main/draft-ietf-httpapi-rest-api-mediatypes.md#introduction

What happens when a version paramter disagrees with the version [specified in the OpenAPI object]

I think prescribing a behavior may go beyond the scope of the media type registration,
since:

• it is responsibility of the sender to ensure the correct value of the media type;
• it is a choice of the client to decide the tolerance threshold according to its use case.

Maybe the above wording could fit the Interoperability considerations.

Agree to discuss this further in #124.