Extending representations to parameters and headers

Assuming the recent PR for representations becomes part of OpenAPI 3.0, I propose that we reuse the concept to allow defining complex types for both parameter values and header values.

However, the additional complexity of ‘representations’ should only be required for complex types and not primitive types. This means that both header and parameter objects should be defined as having [type | representations] for describing the value.

This proposal rolls back, the previous change in 3.0, that a schema property is required in parameters to describe primitive types.

By using representations to define complex types, we are able to identify the media type that is used for the purpose of serialization. This would help with issues like #401 #69 #222 and address #665.

Because representation objects have schemas we address #717 #652 #667

So a parameter can be a primitive value like this,

{
  "name": "token",
  "in": "header",
  "description": "token to be passed as a header",
  "required": true,
  "type": "string"
  }

Or a complex value,

{
  "name": "token",
  "in": "header",
  "description": "token to be passed as a header",
  "required": true,
  "representations" : {
      "text/csv" : {
         "schema": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "int64"
            }
      }
   }
}
}

For response headers we can also optionally use representations object to describe JSON based headers.

"headers" : {
  "bb-telemetry-data": {
          "description": "Client statistics ",
          "representations": {
               "application/json" : {
                        "schema": { ... },
                         "examples": [ ...] 
                     }
           }
   }
}

From an tooling implementers perspective, one implementation of the representations structure can now be reused for describing complex structures in request bodies, response bodies, parameters and headers. There are certain escaping rules that are different and so tooling will need to know where the complex type is being serialized to ensure that only valid characters are used in URLs and headers.

One challenge for implementers is that if an OpenAPI definition defines two potential representations for a URL parameter or Header value, then it would be necessary to “sniff” a HTTP message to determine which representation is being used. This might be simple when it comes to differentiating between JSON and XML but becomes more difficult when media types like text/plain and text/csv are used.

[jharmn]

IMO the inclusion of a mongrel JSON Schema has been a long standing problem (which I’m glad we are fixing). The reason is that, practically speaking, tooling providers want to use existing schema parser/validators. That wasn’t fully possible before (due to a hacked JSON Schema), but tooling providers did it anyways. The notion that anyone is going to write a XML parser/validator (or any other format) based on JSON Schema is hard for me to believe, especially in the historical context. If we supported XSD, for instance, we could simply required that $ref be utilized (or some other linking syntax, maybe $schemaRef), so we don’t have to have XSD/protobuf-schema/etc quoted into JSON Schema (which could get pretty gross). P.S. This probably belongs in #764 as a revival comment.

[DavidBiesack]

“representational” got boiled down to just “RE” in “REST” so we could just use “re” : { … } and to save the most keystrokes 😏

I prefer "content"alaContent-Type`. I think that is more accurate than “bodies” and “payloads” (which feel wrong to me for headers and parameters) and concise enough.