Align terminology with RFC7231. See #2476

[ioggstream]

This PR

• replaces Content-Type with Content-Encoding HTTP header field.
• Content-Encoding header field value is an ordered list of content-codings: they might be used not only to compress, but to apply other transformation to the content-type bits (eg. see MICE), so instead of using "encoding" the PR uses "content-codings" to disambiguate;

See: #2476

Note

I have not been able to find a definition of multipart metadata in any RFC so I refer to Content-Transfer-Encoding because not all of its uses are deprecated: see https://tools.ietf.org/html/rfc7578#section-4.5).
As I'm not sure of this point feel free to correct me.

cc: @handrews (PS thanks for your hard work and sorry for the late review)

[handrews]

I am only endorsing the replacement of Content-Type with Content-Encoding in the two places seen here. Also, "an encoding" is a typo, it should have been "any encoding." The rest of it I will leave to @MikeRalphson / the TSC.

I wouldn't mention Content-Transfer-Encoding - leaving some wiggle room for how people use that if they choose to use it seems like a better option as this is new and I'd recommend not nailing things down until we get some feedback from the field. It's an obscure case because of the deprecation. Although really I'd have to go re-read the entire OAS sections on the Encoding object and form data which I do not have time to do right now.

I don't know what a "content-coding" is or why that would be a more desirable term. And I wouldn't say "eventual content-[en]coding" because they're just different things. The only reason an order is mentioned is that the part that JSON Schema describes is done when serializing the media type, and the Content-Encoding HTTP header is part of HTTP. So by definition, when encoding/sending, application-level actions happen first, then protocol. And when receiving/decoding, it's the other way around.

[ioggstream]

I wouldn't mention Content-Transfer-Encoding

That's ok.

I don't know what a "content-coding" is or why that would be a more desirable term

In HTTP, the Content-Encoding header conveys a list of "content-coding"s, just like Content-Type conveys the media-type. The difference is that Content-Encoding contains an ordered list of content-codings to be applied.
For example:

• gzip is a content-coding,
• br is another content-coding.

This means that when you use the http lexicon you don't actually have a "content-encoding" but either:

• no content-codings => no Content-Encoding header field (see "identity" is not a valid field value for "Content-Encoding" httpwg/http-extensions#1223 and Make it clearer that "identity" really is only for "Accept-Encoding" (restores normative language from 2616) (#388) httpwg/http-core#389) thus the reason for eventual content-coding(s)
• one or more content-codings => Content-Encoding: gzip, br

Aligning with the HTTP lexicon makes it easier not confusing the HTTP layer with the applicative one, especially when the wording choice is constrained.

My 2¢, R.

[handrews]

@ioggstream thanks for the content-coding explanation, somehow that had never registered despite how many times I've read the RFC! I definitely agree that using HTTP terminology with HTTP headers/concepts is ideal. For the rest of this, I will still leave it to the TSC as I'm not as involved with either JSON Schema or OAS as I was a year ago.

paging @webron @philsturgeon @Relequestual (and do feel free to tag me again if there's something you need my help on).

[ioggstream]

thanks for the content-coding explanation .. had never registered

that's normal: I'm reading daily HTTP spec since 2018 and I'm still learning ;)
In case you need to check HTTP stuff, I suggest to use the last HTTP Semantics I-D. The wg worked hard to write a readable document and clean up the terminology.

[ioggstream]

hi @webron, should I move the PR to v3.1.1 ?

[webron]

Please do, thanks!