How to define Header parameter values?

[jeremyfiel]

I've not found any sufficient way to define header parameter values such as below:

• rel in a link header
• q in an accept header
• name in content-disposition header
• cache directives
  etc...

Can someone share an example of that?

[handrews]

@jeremyfiel modeling headers is a major weakness in 3.x. The schema/style-based approach is rarely suitable because it implies RFC6570 percent-encoding, which is rarely appropriate for headers. The content approach pretty much boils down to defining a text/plain representation and doing all of the work yourself (the pattern keyword won't get you very far).

We're looking at modeling HTTP interactions more holistically, including headers, in Moonwalk, and I'm hopeful that we could backport the header chunk to a 3.3 (if we can get approval for a 3.3, which would depend on a small, successful 3.2).

A few thoughts on your specific questions:

• rel in a link header: Make it easier to define link headers #667
• q in an accept header: in theory, the key under content is a media range, which can include the q parameter (Accept takes a media range)- would that help? I figure the set of media ranges under content defines the valid Accept options although that's certainly not stated anywhere
• name in content-disposition header: do you need to do that outside of multipart/form-data? Are you using it with multipart/mixed?
• cache directives: Enhance Response cache-control header #2784

See also (which I somehow forgot but @jeremyfiel noticed):

• How to state parameter requirements in HTTP headers? #2458

[jeremyfiel]

I'll pat myself on the back for this one.. I did indeed find and read all of your links prior to posting. 😃

regarding the media-range usage, i'm not interested in the media-range value, but rather the weight value which is the q. How would the media-range in content include the q parameter?

compenents:
  parameters:
    accept:
      name: accept
      in: header
      content:
        'application/json; q=0.9': // like this??? This doesn't allow any definition of the `q` value though. Where would a user manually input a `q` value in a UI, specifically to test different `q` values and the response they may receive. 
          schema:
            type: string
        'application/vnd.app+json; q=0.8':
          schema:
            type: string
        'application/vnd.another_app+json; q=0.6':
          schema:
            type: string

Imagine you have multiple mediatypes available and you want to rank their preference, that doesn't work to define the value of q or charset or any other parameter value after the media-range.

A good example from RFC9110 shows the behavior we are unable to define in OAS3.x.x.

Accept: audio/*; q=0.2, audio/basic
is interpreted as "I prefer audio/basic, but send me any audio type if it is the best available after an 80% markdown in quality".

setting these parameters for something like accept might seem unnecessary, but i'm more interested in some other headers and their parameters like content-disposition(name, filename) and link (rel). We use many different rel values in a link header and would like to define those for our consumers.

Yes, we are using content-disposition in multipart/mixed and would like to define some of those parameter values.

[handrews]

It occurs to me that if we implement #3771, we could define our own extension media type for different header syntaxes and how to model them in JSON Schema, and then they could be described with the existing in: header, content: {application/x-oas-rfc9110-header: {schema: {...}}} approach. Some headers and alternate syntaxes would need their own media types and mappings.

[jeremyfiel]

the issue with name in content-disposition is the RFC doesn't stipulate the use of it in the same way as multipart/form-data because there are no identifying "parts" available without a form or UI tied to the request. The name parameter has an implied correlation to the field identifiers in a form, such as the html selector id. So it's a bit out of bounds on the usage vs the spec. I will add some context there.

I believe RFC2046 was never amended or a new RFC was never filed to include the named body parts similar to RFC7578 for form-data, even if the usage is not tied to the form identifiers, but as plain string identifiers using the name parameter when using /mixed media type.

[handrews]

@jeremyfiel it gets a bit more complex as Content-Displosition for MIME types is defined in RFC 2183, where it does allow for additional as-yet-undefined parameters:

It is desirable to keep the set of possible disposition types small
and well defined, to avoid needless complexity. Even so, evolving
usage will likely require the definition of additional disposition
types or parameters, so the set of disposition values is extensible;
see below.

So if Content-Displosition is independently defined to allow additional parameters, once those parameters are defined somewhere, are they automatically usable in other places that use a MIME-derived Content-Disposition? (Note that for whole HTTP message bodies, Content-Disposition is instead defined by RFC6266).

[jeremyfiel]

Note: This document does not apply to Content-Disposition header
fields appearing in payload bodies transmitted over HTTP, such as
when using the media type "multipart/form-data" ([RFC2388]).

src: RFC6266

This note renders reference to RFC6266 almost irrelevant for the usage we are discussing here, for OAS.

[handrews]

@jeremyfiel that's correct. RFC6266 defines Content-Disposition for HTTP messages, while RFC 2183 defines Content-Disposition for media types including all multipart/* types. That's why I quoted RFC 2183 - I only mentioned 6266 to prevent someone from thinking it obsoletes 2183 as it took me a while to figure out that it did not do so, even indirectly.

[jeremyfiel]

I also found this issue is related #2458

[handrews]

🤦 how did I miss that one? I'll add it to the earlier list for future reaaders, thanks!

[jeremyfiel]

are they automatically usable in other places that use a MIME-derived Content-Disposition?

Where is something like this defined? I'm not familiar with where to find such information

[handrews]

@jeremyfiel I don't know why I did not answer that myself, as do I know that the likely place is an IANA registry, which would be documented in RFC2183... which it is: §9: Registration of New Content-Disposition Values and Parameters. (It turns out there are IANA registries for way more things than most people would guess)

However, the registry sadly makes it clear that parameters (in a column confusingly named "Allowed Values") are scoped to specific values (in the logically named "Value" column).

So the name parameter is specifically for form field names and is restricted to the form-data disposition, while the filename parameter is allowed for both form-data and attachment dispositions.

Of course, people ignore this sort of thing in practice all the time, and the ABNF in RFC2183 allows for arbitrary additional parameters. But in terms of normative requirements we can put in the OAS, we can't contradict other specifications. Or at least we can't do that and expect interoperability with other tools that work with multipart media types.