Standardize maps and extensions

[webron]

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.

[ePaul]

Having maps in general sounds nice.
We should possibly have a paragraph about this in the beginning?

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.

Hmm, we could declare the x- prefix reserved, though I guess for parsing/typing purposes it is better to have just one type of value in the map.

We just should look through all the existing maps and consider where the extensions which could possibly be added there could sensibly go instead. (Likely into the containing object, or into the value.)

[webron]

I'd rather we didn't add those exceptions. We had a similar issue with the Encoding Object where you need to mention the name of a Schema property as a key. It doesn't make sense to disallow properties with the x- prefix as a name, so we ended up not supporting extensions there at all. Extensions are great, but when it comes to containers (i.e. maps), it can be done in the actual values or at an upper level.

[webron]

Another example of a construct that already doesn't support it - the Headers Object. Can you imagine not allowing x- for header names? :)

[ePaul]

Yeah, I guess you are right. That was just me trying to play devil's advocate to have the arguments laid down.

[webron]

@ePaul - I appreciate that. That's normally my job ;)

[raymondfeng]

+1 to use Map, but with the generics syntax, such as Map<string, Schema Object>.

[whitlockjc]

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

Couldn't we use an allOf for this?

[RobDolinMS]

TDC: @webron wants this one. He will try to summarize cases that need to be discussed for TDC ConCall on Fri, 5/12; and will try to write the PR after that.

[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.

[darrelmiller]

Not sure about removing Security Requirements Object