Modeling HTTP fields (headers/trailers)

[handrews]

In last week's call we reached a tentative decision that "maybe we should focus on creating a well defined model for an HTTP request/response with sufficient semantics for APIs."

I'd like to suggest starting with HTTP fields (headers and trailers). This is a big pain point in OAS 3, and the modeling abilities there are minimal. It would be a huge win to back-port header modeling to 3.2 (or assuming we try to push a 3.2 out quickly, more likely this backport would go into 3.3). Here are some relevant issues, all of which center around more complex and detailed representations of headers:

• Make it easier to define link headers OpenAPI-Specification#667
• Multiple 'Set-Cookie' headers in one response OpenAPI-Specification#1237
• Multiple specifications for the header with the same name in components OpenAPI-Specification#1572
• Support for structured-headers de/serialization OpenAPI-Specification#1980
• Question: Create Links from "complex" headers OpenAPI-Specification#2402
• Use wildcard or regex in cookie name in Cookie Authentication OpenAPI-Specification#2296
• Parameters for Media Types OpenAPI-Specification#2342
• How to state parameter requirements in HTTP headers? OpenAPI-Specification#2458
• Enhance Response cache-control header OpenAPI-Specification#2784

I've started working up an overall JSON Schema-representable model of RFC 9110 §5.6 "Common Rules for Defining Field Values" and RFC 8941 "Structured Field Values for HTTP", which would cover a fair number of cases. [EDIT: I don't think I got far with this and don't remember what I did with it.] We would want to keep these sets of rules distinct even though they have some overlap. There would also need to be some special-cases because of the long history of HTTP fields, and we'd probably want a registry to allow defining additional custom models as needed.

But mostly, we should be able to handle a lot of existing headers through 9110 plus a few custom models, and most new headers through 8941.

[handrews]

There are two "normal" patterns:  RFC9110 §5.6's Common Rules for Defining Field Values and RFC8941 Structured Field Values for HTTP  Everything else is a special case to a greater or lesser degree.

Header data models would go in a registry, just like we already do for media type data models. The registry would indicate that, for each header, the model is one of:

• RFC9110§5.6
• RFC8941
• Something from another RFC (e.g. the Link header already has a data model from RFC9264, as there is a media type that maps to its contents)
• Something entirely custom

At this point it is not clear to me if we will sometimes want to provide a custom model for certain fields that could be expressed in RFC9110§5.6 or RFC8941 terms. That probably will have to do with how elegant the generic data models for those rules can be.

[handrews]

Another open question is how to hook the data models into the existing system. Media Type Objects expect a media type key, which works for some headers (e.g. Link which maps to the application/linkset media type), but not for most.

One option would be to overload the content key to allow either a media type range (the current value) or a registered value from the header registry, which would be required to not look like a media type range. An alternative would be to add a new field that is only used for Header Objects and in: header Parameter Objects that is similar to content but works with the header registry. There may be other better options as well, these are just the first two that come to mind.

[karenetheridge]

I don't like the idea of overloading .../content/* to mean something else other than a media-type decoding.

I've been toying with something like style: automatic which will simply indicate "do what the header registry says to do for this header name".

[handrews]

@karenetheridge yeah that's a very valid objection on content. I'm not entirely sold on further complicating style by adding a very different sort of behavior to it, but on the other hand it is a better extension point than content.