OpenAPI vocabulary or dialect for code generation

Code generation tools often have special requirements or restrictions on the structure of an OpenAPI definition (document?) that improve the generated code. Here are some examples of restrictions from the IBM OpenAPI SDK generator:

• Parameters must be unique by name only, irrespective of "in".

  Rationale: Operation parameters are often rendered as the parameters on a function or method in the target language of the code generator. Since most languages require parameters to have unique names, the code generator would need to incorporate the in of a parameter into its name to prevent name collisions. This is undesirable, since it exposes the mechanics of the API without adding any value.

• There should be at most one success response with a response body. A 204 and other 2XX is okay, but no other combination of two or more 2XX responses.

  Rationale: In statically-typed languages like Java, the return value of a method must have a single static type. This makes it difficult to represent an operation with two different response schemas as a single method returning a single response type.

• Property names and parameter names must be "case-insensitive" unique

  Rationale: Code generators often reformat the names of parameters, properties, and schemas to use idomatic case formatting for the target language: lower_snake_case for Python, lowerCamelCase for Java, etc. But this reformatting could introduce naming conflicts if two parameters, e.g. "foo_bar" and "fooBar" are not "case-insensitive" unique.

• Arrays must contain items of a single type

  Rationale: Many languages require an array to contain only values of a single type.

• Schema type must specify a single type -- no type arrays

  Rationale: Some widely-used statically-typed languages, e.g. Java and Go) have no provision for "union" types, making it impossible to define a type: [ integer, string ] typed property or parameter.

• Don't use "nullable"

  Rationale: it's deprecated, and is just an alternate way of expressing type arrays

• Don't use JSON schema "not"

  Rationale There's no obvious way to represent this in many widely used programming languages.

• No "if-then-else" in JSON schema

  Rationale There's no obvious way to represent this in many widely used programming languages.

• The API document should be "self contained" (no external "$refs")

  Rationale: External refs can easily create multiple namespaces for schemas, parameters, security schemes, etc. These are unnecessary complications for code generators.

• All "$refs" must be to elements in the "components" section of the document

  Rationale: "$ref" targets outside of "components" are unnecessary complications for code generators.

It would be nice to have a common set of rules like this that could be codified into a "Code generation" vocabulary or dialect for OpenAPI.

Start with issue #2542 and review the listed code-generation restrictions and their rationales. Determine whether the project wants a shared OpenAPI vocabulary or dialect, then define an agreed set of rules and how it should be codified. Done means the scope and representation are resolved rather than remaining a proposal.