Header terminology

[mnot]

From #59:

There's some fuzziness about terminology around the differences between:

• a header's complete value
• a header line
• an individual value in a list-based header field

This could do with some improvement.

[mnot]

Another thing to consider is whether we should condone/use "header" instead of / in addition to "header field"; the former is extremely common use.

[reschke]

I agree that we should define common terminology here. We've had similar questions about WG drafts such as expect-ct and client-hints.

Proposal:

• a header's complete value: "coalesced field value" (or maybe "aggregated field value"?)
  • a header line: "raw field value"
  • an individual value in a list-based header field: "list element"

[mnot]

What if we made an explicit split between the syntactic concept of header fields, and the abstract, post-aggregation concept of the headers that most people are used to working with?

That way, we'd have a clean split; these would be syntactic:

• header field - one line
• header field-name - one line's name
• header field-value - one line's value

... and these would refer to the synthetic value after coalescence:

• header - coalesced header
• header name - coalesced header name
• header value - coalesced header value

Ideally, we'd adjust "header section" to "header field section" to reinforce that it's syntactic.

[reschke]

+1 in general, but I don't believe that calling one thing "header field" and the other "header" is going to work - right now people use it interchangeably. Better find a new attribute, such as "aggregated", "coalesced" or "combined":

[mnot]

I suspect that we call it a "header field" and everyone else calls it a "header."

Perhaps if we use only "field" to denote the syntax, and "header" to denote the post-processed thing?

[reschke]

That again would change an existing definition and would be IMHO confusing. I still prefer to be more clear by adding an attribute.

[mnot]

I agree we need to be clear. However, something like "coalesced header field value" is too verbose for common usage. Ideally, we'd be using two words, not four.

Let's look at it from a slightly different perspective. For practitioners and other specifications, the most common term by far is going to be a term to refer to:

• For headers that don't use the #list convention, its value - while still being able to talk about "extra values that were appended due to additional headers being present"
• For headers that do use the #list convention, a member of the list

If we can come up with a brief, descriptive term for that -- e.g., "header item" -- we can build other things around it, I think.

[annevk]

FWIW, Fetch has this as "combined value".

[royfielding]

I agree we need to clean this up. I would prefer not to paint that shed in a meeting. Can we just point people to this issue and not spend any time on it? Painting it here is fine.

[mcmanus]

in bkk: really discussed header-field vs header nomenclature. Sense of room favored loosening to allow just header but it wasn't unanimous particular wrt email consistency.

[mnot]

Discussed by the editors. Proposal:

In semantics:

• [ ] "List-based field" refers to a field that uses the #-rule or similar
• [ ] "Singleton field" refers to a field that does not use the #-rule or similar (will need to define how singleton fields should be handled when they don't conform to ABNF)
• [ ] "Field item" refers to a single value in a list-based field
• [ ] "Combined [field] value" makes sense to refer to all instances of a list-based header after combining with commas

Note that "field value" could refer to a field item, a combined field value, or a field instance value.

In messaging:

• [ ] "Field instance" refers to the received-on-the-wire field name/value pair (with "field instance value" being used for the latter

[mcmanus]

ietf104: general happiness with the above comment. Also discussion of the need to include "colloquial glue" so that other documents may refer to headers without using the field or other such annotations although httpbis documents would likely use the terminology that results from this issue

[mnot]

I notice that we use "field value" and "field-value" inconsistently; it would be good to settle on one. I think that we probably want to omit the hyphen when we're referring to the combined value (as per below).

Also, based upon our current usage (and that elsewhere), I'd propose we use "field value" to mean what's defined as "combined field value" above, to avoid unnecessary changes; it's very rare to refer to a single-line instance of a value.

Furthermore, I'd propose that "header value" be acceptable for field values that are only defined to appear in headers (depending on the outcome of the trailer-related issues, but that seems like a logical direction at this point). We need not use it to define our headers.

I think we can act on this by:

• [ ] Renaming Semantics - Header Field Order to something like "Header and Trailer Field Order and Combination"
• [ ] Defining "list-based" and "singleton" terminology there. This would also entail noting that generic processors don't need to know the difference between them.
• [ ] Using "list-based" or "singleton" appropriately in the definition of all headers we specify throughout all three specs.
• [ ] Finding any instance where field[-]value does not mean "combined" (probably in messaging) and craft language to avoid it (probably using "instance"). The one obvious place this occurs is in messaging when describing the ABNF of H1 headers. I think we can just clarify that field-value is the uncombined form, and desist from using it.
• [ ] Figure out if we actually need to use "field item".

Make sense?

[mnot]

@royfielding @reschke ping on above. I'd like to get this moving.

[reschke]

FWIW; we use "field-value" when talking about the ABNF rule. If there are deviations from that, we should fix those first.