What we call "headers"

A little while back we made some changes in http-core regarding terminology and headers. This seems to have caused some confusion and comment, so I thought I'd summarise where I think we're at (Julian and Roy might want to chime in if they feel differently or want to add nuance). 

Note that this is _not_ a call to bikeshed the chosen terms*.

The corresponding spec text is at <https://httpwg.org/http-core/draft-ietf-httpbis-semantics-latest.html#header.fields>, although of course we're still working on it.


## Field Components

A _field line_ is a field name/value pair that maps directly to the HTTP/1 serialisation of a field. Notably, it only includes the value between the `:` and the `\n` -- subsequent values have not been folded in. This is typically used by the syntactic specifications (h1, h2, h3), and in other limited cases (e.g., Cookies).

A _field section_ is a set of field lines before or after a message body (let's ignore "midders" for now).

A _field name_ is the field's name. Hopefully, this is pretty straightforward.

A _field value_ is the field's *whole* value -- after potential combination of multiple field lines. We chose this meaning because it's by far the most common; it's rare that specs need to refer to a syntactic HTTP/1 or HTTP/2 field line value. 

When we need to refer to the individual parts of a field line, we can call them the _field line name_ and _field line value_. Again, this is pretty rare, and usually in the "infrastructure" specs. I know this isn't a "pretty" name, but it's necessary to distinguish between the different meanings in some circumstances.

A _field_ is a field name/field value pair -- notably, including the result of combining multiple instances of the header field in the section. This is typically used in a fairly abstract way.

Colloquially, when we want to refer to a specific field section, we can call it _headers_ or _trailers_, as appropriate. Likewise _header_ and _trailer_ are understood to be _header field_ and _trailer field_ when expanded (note that this means it's *not* a field line).


## Field Contexts

Historically, we've used "header" and "headers" pretty loosely; sometimes things can be trailers, but this name doesn't recognise that. So, when the semantics document talks about these things, it uses "field" or "fields" -- unless something is defined very specifically as allowed (or required) to be in headers or trailers.

That's because we've made separate changes to make the delineation between headers and trailers stronger; trailers can no longer be "folded" into headers automatically.

So, if you define something that doesn't explicitly allow itself to be sent in the trailer section, it's perfectly OK to call it a "header field." You can also just call it a "field" if you like, but that may confuse some readers as to whether you intended to allow it to be sent as a trailer field.

Cheers,



*  The timeless phrase "welcome to my killfile" comes to mind.

--
Mark Nottingham   https://www.mnot.net/

Received on Tuesday, 17 March 2020 06:39:08 UTC