v3.2: Should the `example` field be deprecated (Parameter, Header, and Media Type Objects)

[handrews]

The Parameter, Header, and Media Type Objects all support both an example field (singular) and an examples field (plural) that uses Example Objects. The example field is equivalent to the value field in an Example Object.

Due to PR #4647 introducing new Example Object fields with more well-defined behavior, we are considering deprecateding value and externalValue in favor of the new fields (see Issue #4660).

Should we also deprecate example? It pretty much exists as a more convenient alternative to value for people who don't want to name their examples.

Alternatives and variations:

• @mikekistler is in favor of keeping it
• @karenetheridge suggested just discouraging its use rather than formally deprecating it
• @handrews notes that the empty string is a valid JSON/YAML key and could be a good convention for people who just want one unnamed example. Such an unnamed example could also be a signal to tools that if they only show one, show the unnamed one. (However, writing of himself in the third person, @handrews suspects most people will find this too cryptic and weird)

[karenetheridge]

@karenetheridge suggested just discouraging its use rather than formally deprecating it

Given the policy in 3.2 that states that deprecation means "we discourage its use, and may remove it in the next major release", I change my opinion to "let's deprecate it". ;)