How to handle response headers?

[darrelmiller]

Do we just keep that as a distinct property on the response object? Is it just a simple dictionary? What would it mean to make it a JSON Schema?
What do people do with those headers?

[handrews]

In Hyper-Schema, it was a schema and referenced the I-D that became RFC 8941 for how to map various header syntaxes into the JSON Schema data model.

[darrelmiller]

Yes, I was thinking we need to make sure we account for mapping to structured fields.

[handrews]

It occurs to me that since RFC 9112 §10 defines an application/http media type, we could map as much or as little of that media type into the JSON data model to apply schemas to it. I'm not sure that's ideal and haven't tried to do any such thing to see if it even makes sense, but it might be worth some thought.

[arno-di-loreto]

Whatever the solution: headers (and trailers?) should be handled the same way in request (+path+api) and response.

Reminder about how request and response headers are handled in V3:

• Request headers are defined with a parameter object in the parameters list. A request header has a name property.
• Responses headers are defined with a header object in the headers map. The response header object is a subset of the parameter object without a name property (the header's name is the map's key).

That leads to the following issues:

• While completely reusable headers (including their name) can be defined, it's impossible for the response ones (because their name is the key in the map).
• Also, it's impossible to share headers between request (components.parameters) and response (components.headers). They can share a common schema though.

Based on the current form of v4, having a dedicated property everywhere where headers (or trailers?) are needed looks fine (it's content would be similar to parameter schema? or using a standard as mentioned above).

I've noticed in some samples the idea of using a specific property in the parameters schema for headers (along with the better idea of having a dedicated property!).

        parameterSchema:
          type: object
          properties:
            header:      ## We can either use this specially named property or create a first class headerSchema property on the Request Object
              type: object
              properties:
                path:
                  const: service.createFoo  ## path Header field used to convey the RPC method

That specific property inside the parameter schema (which is completely "free") would lead to problems: what if I need a "header" query parameter? Unless all different non-body parameters are stored in a high-level "parameters" schema with property matching the existing parameter type and maybe new ones? (path, query, anchor, headers, trailers, and cookies for instance), but then why not have a fixed OpenAPI structure defining explicitly the different non-body parameters? Also that "parameter schema with some fixed properties" would possibly not be reusable in responses? (are "trailers" and "headers" response's parameters?)

PS: And we shouldn't forget there's also the question of cookies (are they parameters? Or specific headers?).