Specification (and extension) design guidelines

[arno-di-loreto]

Just like API guidelines can facilitate the job of people creating API, having specification design guidelines could help people design OpenAPI v4, its extensions, its evolution, and future versions.
Creating guidelines is also an excellent way to find explanations for the rules we may (inadvertently) invent and especially evaluate the consequences for humans and machines reading/creating OpenAPI documents.

Here are some questions that should be answered in "OpenAPI Specification guidelines":

• How to point/reference another element? (A reference to something should always be a JSON pointer and not a name (security scheme example) #26)
• Choosing between map and list (Consideration for moving from objects to arrays. #32 and Map vs list in responses (and in general) #25 )
• Naming conventions (responses vs apiResponses vs pathResponses #34)

These are practical questions, guidelines can also describe more "meta" concerns like:

• Which perspectives/considerations should be evaluated when making a design decision?
• What is considered a breaking change?

[handrews]

The referencing discussion should keep the analogous discussion at AsyncAPI in mind.