Organize the specification into tiers

[rafalkrupinski]

There seem to be contradicting expectations towards OpenAPI:

On one hand it tries to be able to describe all possible, or at least actually used ways of accessing Web APIs.
On the other hand it tries to encourage certain best practices.

Both approaches make some sense - best practices are great for interoperability and tooling, while the open approach allows more adoption.

Other technologies have different compatibility layers or tiers: CSS levels or HTML strict vs relaxed.

How about creating different compatibility tiers for OpenAPI?

Example design of tiers:

1. Strict tier: would describe only the best practices.

   When using the strict tier, you should be able to do anything, but not necessarily in every way possible (authenticate, but only with a subset of available methods, not with OAuth1).
   Server-side tools implementers could follow it to write simple and compatible frameworks
   Authors of client-side tools would have choice to simplify the implementations by accepting only this tier, or just offer the highest level of support for it.

   No backward compatibility between major OAS versions, since the best practices evolve.

2. Acceptable tier: would relax the strict tier with other widely accepted solutions. Compatible with at least one previous OAS version.

3. Open tier: allow for more ways of doing stuff. Describe APIs designed long time ago, or designed without OpenAPI in mind.
   Mostly with client-side in mind.

I think it should help developing OAS, since it would allow breaking backward compatibility in specific cases, and allow to focus on the tiers separately.

It would definitely help with tooling, since it would allow to focus the efforts on a smaller specification (strict tier) and support other tiers at later stage, with more generic code or via extensions.

One may raise an issue of fragmentation, but I think there's already plenty of tools that support OAI partially or even badly. Having a guide to the best practices should actually decrease fragmentation.