Standardize maps and extensions

Before releasing 3.0.0-RC0 we introduced a new type construct to the spec in the Components Object. For examples, schemas has the type of Map[string, Schema Object].

This was done to avoid creating a Schemas Object, Responses Object and so on, which would simply be those maps. I’d recommend we drop existing map objects and use the same construct for those, including Server Variables Object, Scopes Object and so on.

The exception would be the Paths Object as it imposes a pattern to the named field.

Following that, suggest we drop support for extensions in maps (except Paths Object) - there’s no way to tell the difference between a name in the map and an extension. If someone wants to name a server variable x-y-z, it would be unclear whether it’s an extension or a name of a variable.

[webron]

The following is a list of potential objects to be converted to maps. There are three types - recommended, unknown, not-recommended. Each object also specifies whether extensions are allowed or not. In some cases (will try to note), the decision to allow extensions was flipped because it doesn’t make sense otherwise.

Recommended to be dropped:

• Server Variables Object Map[{name}, Server Variable Object] No extensions
• Encoding Object Map[{property}, Encoding Property Object] No extensions Change Encoding Property Object to Encoding Object *
• Callbacks Object Map[string, Callback Object | Reference Object] No extensions *
• Headers Object Map[string, Header Object | Reference Object] No extensions
• Links Object Map[string, Link Object | Reference Object] No extensions
• Link Parameters Object Map[string, Any | {expression}] No extensions
• Scopes Object Map[string, string] No extensions *
• Security Requirement Object Map[string, [string]] No extensions

Unknown:

• Paths Object Map[/{path}, Path Item Object] Extensions allowed Reasoning: this is a special object in terms of interpretation.
• Content Object Map[{mediaType}, Media Type Object] No extensions Reasoning: we just introduces this object…

Recommended to keep as-is:

• Responses Object Map[‘default’|1-5, Response Object | Reference Object] Extensions allowed Reasoning: this one is a bit complicated, with the allowed keys, and the requirement that one key at least must be provided.
• Callback Object Map[{expression}, Path Item Object] Extensions allowed Reasoning: the key is too complex to describe in a property, and it might take away too much of the impact of callbacks.

Some of these may prove challenging to remove because they offer additional text to explain the general concept (for example: Links, Callbacks). In such case, we might create top-level topics to explain those better, and reference to the topics from the relevant properties.

Once we’re in agreement on the changes, I’ll write up the PR - it’s going to be a big one.

[webron]

Resolved by #1115.