Structured Headers for HTTP

Document Type Active Internet-Draft (httpbis WG)
Last updated 2017-11-27 (latest revision 2017-11-26)
Replaces draft-ietf-httpbis-jfv
Stream IETF
Intended RFC status (None)
Formats plain text xml pdf html bibtex
Stream WG state WG Document
Document shepherd Patrick McManus
IESG IESG state I-D Exists
Consensus Boilerplate Unknown
Telechat date
Responsible AD (None)
Send notices to Patrick McManus <>
HTTP Working Group                                         M. Nottingham
Internet-Draft                                                    Fastly
Intended status: Standards Track                               P-H. Kamp
Expires: May 31, 2018                          The Varnish Cache Project
                                                       November 27, 2017

                      Structured Headers for HTTP


   This document describes Structured Headers, a way of simplifying HTTP
   header field definition and parsing.  It is intended for use by new
   specifications of HTTP header fields.  This includes revisions of
   existing specifications when doing so does not cause interoperability

Note to Readers

   Discussion of this draft takes place on the HTTP working group
   mailing list (, which is archived at [1].

   _RFC EDITOR: please remove this section before publication_

   Working Group information can be found at
   [2]; source code and issues list for this draft can be found at

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on May 31, 2018.

Nottingham & Kamp         Expires May 31, 2018                  [Page 1]
Internet-Draft         Structured Headers for HTTP         November 2017

Copyright Notice

   Copyright (c) 2017 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   ( in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

1.  Introduction

   Specifying the syntax of new HTTP header fields is an onerous task;
   even with the guidance in [RFC7231], Section 8.3.1, there are many
   decisions - and pitfalls - for a prospective HTTP header field

   Likewise, bespoke parsers often need to be written for specific HTTP
   headers, because each has slightly different handling of what looks
   like common syntax.

   This document introduces structured HTTP header field values
   (hereafter, Structured Headers) to address these problems.
   Structured Headers define a generic, abstract model for data, along
   with a concrete serialisation for expressing that model in textual
   HTTP headers, as used by HTTP/1 [RFC7230] and HTTP/2 [RFC7540].

   HTTP headers that are defined as Structured Headers use the types
   defined in this specification to define their syntax and basic
   handling rules, thereby simplifying both their definition and

   Additionally, future versions of HTTP can define alternative
   serialisations of the abstract model of Structured Headers, allowing
   headers that use it to be transmitted more efficiently without being

   Note that it is not a goal of this document to redefine the syntax of
   existing HTTP headers; the mechanisms described herein are only
   intended to be used with headers that explicitly opt into them.

   To specify a header field that uses Structured Headers, see
   Section 2.

Nottingham & Kamp         Expires May 31, 2018                  [Page 2]
Internet-Draft         Structured Headers for HTTP         November 2017

   Section 4 defines a number of abstract data types that can be used in
   Structured Headers, of which only three are allowed at the "top"
   level: lists, dictionaries, or items.

   Those abstract types can be serialised into textual headers - such as
   those used in HTTP/1 and HTTP/2 - using the algorithms described in
   Section 3.

1.1.  Notational Conventions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "OPTIONAL" in this document are to be interpreted as described in BCP
Show full document text