What we call "headers"

Mark Nottingham <mnot@mnot.net> Tue, 17 March 2020 06:43 UTC

Return-Path: <ietf-http-wg-request+bounce-httpbisa-archive-bis2juki=lists.ie@listhub.w3.org>
X-Original-To: ietfarch-httpbisa-archive-bis2Juki@ietfa.amsl.com
Delivered-To: ietfarch-httpbisa-archive-bis2Juki@ietfa.amsl.com
Received: from localhost (localhost []) by ietfa.amsl.com (Postfix) with ESMTP id 8A4463A1930 for <ietfarch-httpbisa-archive-bis2Juki@ietfa.amsl.com>; Mon, 16 Mar 2020 23:43:36 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2.751
X-Spam-Status: No, score=-2.751 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, HEADER_FROM_DIFFERENT_DOMAINS=0.249, MAILING_LIST_MULTI=-1, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (2048-bit key) header.d=mnot.net header.b=C0VJiGJP; dkim=pass (2048-bit key) header.d=messagingengine.com header.b=1uuwU4Sr
Received: from mail.ietf.org ([]) by localhost (ietfa.amsl.com []) (amavisd-new, port 10024) with ESMTP id f9ddGn9M5lHZ for <ietfarch-httpbisa-archive-bis2Juki@ietfa.amsl.com>; Mon, 16 Mar 2020 23:43:34 -0700 (PDT)
Received: from lyra.w3.org (lyra.w3.org []) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id AEAD03A192F for <httpbisa-archive-bis2Juki@lists.ietf.org>; Mon, 16 Mar 2020 23:43:33 -0700 (PDT)
Received: from lists by lyra.w3.org with local (Exim 4.92) (envelope-from <ietf-http-wg-request@listhub.w3.org>) id 1jE5sc-0003oR-2y for ietf-http-wg-dist@listhub.w3.org; Tue, 17 Mar 2020 06:39:10 +0000
Resent-Date: Tue, 17 Mar 2020 06:39:10 +0000
Resent-Message-Id: <E1jE5sc-0003oR-2y@lyra.w3.org>
Received: from titan.w3.org ([]) by lyra.w3.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from <mnot@mnot.net>) id 1jE5sa-0003ng-67 for ietf-http-wg@listhub.w3.org; Tue, 17 Mar 2020 06:39:08 +0000
Received: from out1-smtp.messagingengine.com ([]) by titan.w3.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from <mnot@mnot.net>) id 1jE5sY-0005lP-4S for ietf-http-wg@w3.org; Tue, 17 Mar 2020 06:39:07 +0000
Received: from compute4.internal (compute4.nyi.internal []) by mailout.nyi.internal (Postfix) with ESMTP id A288A5C01E3; Tue, 17 Mar 2020 02:38:52 -0400 (EDT)
Received: from mailfrontend1 ([]) by compute4.internal (MEProxy); Tue, 17 Mar 2020 02:38:52 -0400
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=mnot.net; h=from :content-type:content-transfer-encoding:mime-version:subject :message-id:date:cc:to; s=fm2; bh=8ixnENbywX/vcsAfXHFjE2aBW7ML27 /NiBsHFqwXFzE=; b=C0VJiGJPo8vCWPE+TbDEoCJyt31GuvqSTxpe+m9fwMKZtf UNXpeWY+wLgPc9JrIveXWW1KuK7ONIOYzYW5by0ECfa+oqgCaSjAPfeS9bEhRCR+ zAs7J8XZcL5UYwJcOocAdlT/lSCi7FpgNdfJKdMr7vHALI+f9AakpKSAfWA9CqH5 HwVZmGWQZKLILdETB+JfYQgJG/OssMKHll6H4p/zimLQcz+/DpWlbmKdtVxErzHF 8YsxTIyiIxGaEO+1LzffEo+U2agdKOwEY3lXsWu9flVCH8nDKvhXmtgrxeiKv+4E WX58MCVwicD215NG3AlPbhRwmU6rFFU6tsqT3QsA==
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:content-type :date:from:message-id:mime-version:subject:to:x-me-proxy :x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s=fm2; bh=8ixnEN bywX/vcsAfXHFjE2aBW7ML27/NiBsHFqwXFzE=; b=1uuwU4SrncvSQ6FgF3nAkB PZfrcqEidbInssfJmMbcOSWdmqZltaX4DVW+YhWWY0A2BJBP2SKQVhkc89hCqlfy A96xJ7MY48jmjWxMr1WxK/6m/+4whp23OKgDkRBfCmsj2IaJMnWvLiaeR5kSHm7O dZ6INAwmLYmRB4znd0xo1jswNjaIIDNGIfUdToRRprUT9vbbYWdcfWNk7uzEigIM y2Qs4JQIUSiSQ5zuP/meEqiDAkxhZk8siKhsio849PXk94YijJpkojpXAqmghT4q xdUJ7e/14mi1Fskde/oJSzlCHo4cBSB+gzpHMgkfygsvkBJhuyt+rxU+OTl+DyGg ==
X-ME-Sender: <xms:e3BwXnok8YA8RzXC61MA9BvfpZuzTEPlrnYK6N70j-UyUDDo_PHqJQ>
X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedugedrudefgedgleeiucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurhephfgtgfgguffkfffvofesthhqmhdthhdtvdenucfhrhhomhepofgrrhhkucfp ohhtthhinhhghhgrmhcuoehmnhhothesmhhnohhtrdhnvghtqeenucffohhmrghinhephh htthhpfihgrdhorhhgpdhmnhhothdrnhgvthenucfkphepudduledrudejrdduheekrddv hedunecuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrghilhhfrhhomhepmh hnohhtsehmnhhothdrnhgvth
X-ME-Proxy: <xmx:e3BwXl4ZD5vdX0EJlMpmQJ2G2Hf1yc8_whhI6CWvg3payyiP0VTDAA> <xmx:e3BwXvMtiz79a7eDlmSX_NWrHyY16fkVs_mvKTFHrYSePUCsgPoXlg> <xmx:e3BwXvPrjdE3C6Qy0RvUgvebGa43Bp60FrO3RSIkaBzc0EtcqU4aBA> <xmx:fHBwXo7Pi9Ed-uYuM0Ojo_zTWA03CsjSeEyB78Nc6---2nVmNjom9g>
Received: from macbook-pro.mnot.net (unknown []) by mail.messagingengine.com (Postfix) with ESMTPA id 640053280060; Tue, 17 Mar 2020 02:38:50 -0400 (EDT)
From: Mark Nottingham <mnot@mnot.net>
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
Mime-Version: 1.0 (Mac OS X Mail 13.0 \(3608.\))
Message-Id: <CF788613-EEE1-4321-BE98-780E7C77F607@mnot.net>
Date: Tue, 17 Mar 2020 17:38:47 +1100
Cc: "Julian F. Reschke" <julian.reschke@greenbytes.de>, Roy Fielding <fielding@gbiv.com>
To: HTTP Working Group <ietf-http-wg@w3.org>
X-Mailer: Apple Mail (2.3608.
Received-SPF: pass client-ip=; envelope-from=mnot@mnot.net; helo=out1-smtp.messagingengine.com
X-W3C-Hub-Spam-Status: No, score=-9.8
X-W3C-Hub-Spam-Report: BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001, W3C_AA=-1, W3C_DB=-1, W3C_IRA=-1, W3C_IRR=-3, W3C_WL=-1
X-W3C-Scan-Sig: titan.w3.org 1jE5sY-0005lP-4S f4daed3d013573c5ddb73a6c4c84aea3
X-Original-To: ietf-http-wg@w3.org
Subject: What we call "headers"
Archived-At: <https://www.w3.org/mid/CF788613-EEE1-4321-BE98-780E7C77F607@mnot.net>
Resent-From: ietf-http-wg@w3.org
X-Mailing-List: <ietf-http-wg@w3.org> archive/latest/37451
X-Loop: ietf-http-wg@w3.org
Resent-Sender: ietf-http-wg-request@w3.org
Precedence: list
List-Id: <ietf-http-wg.w3.org>
List-Help: <https://www.w3.org/Mail/>
List-Post: <mailto:ietf-http-wg@w3.org>
List-Unsubscribe: <mailto:ietf-http-wg-request@w3.org?subject=unsubscribe>

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.


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

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