Modeling HTTP fields (headers/trailers) as a starting point for modeling all the things

[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. 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.