Skip to content

Extending representations to parameters and headers #762

Closed
@darrelmiller

Description

@darrelmiller

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions