Aug 28, 2011, 7:56:24 AM (8 years ago)

add considerations for new header fields (see #231)

1 edited


  • draft-ietf-httpbis/latest/p2-semantics.xml

    r1416 r1417  
    3131  <!ENTITY effective-request-uri      "<xref target='Part1' x:rel='#effective.request.uri' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    3232  <!ENTITY intermediaries             "<xref target='Part1' x:rel='#intermediaries' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
     33  <!ENTITY chunked-encoding           "<xref target='Part1' x:rel='#chunked.encoding' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    3334  <!ENTITY full-date                  "<xref target='Part1' x:rel='#date.time.formats.full.date' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    3435  <!ENTITY http-url                   "<xref target='Part1' x:rel='#http-url' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    4546  <!ENTITY header-authorization       "<xref target='Part7' x:rel='#header.authorization' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    4647  <!ENTITY header-cache-control       "<xref target='Part6' x:rel='#header.cache-control' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
     48  <!ENTITY header-connection          "<xref target='Part1' x:rel='#header.connection' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    4749  <!ENTITY header-content-location    "<xref target='Part3' x:rel='#header.content-location' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    4850  <!ENTITY header-content-range       "<xref target='Part5' x:rel='#header.content-range' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    481483<section title="Header Fields" anchor="header.fields">
     485   Header fields are key value pairs that can be used to communicate data about
     486   the message, its payload, the target resource, or about the connection
     487   itself (i.e., control data).  See &header-fields; for a general definition
     488   of their syntax.
     491<section title="Considerations for Creating Header Fields" anchor="considerations.for.creating.header.fields">
     493   New header fields are registered using the procedures described in
     494   <xref target="RFC3864"/>.
     497   The requirements for header field names are defined in
     498   <xref target="RFC3864" x:fmt="of" x:sec="4.1"/>.  Authors of specifications
     499   defining new fields are advised to keep the name as short as practical, and
     500   not to prefix them with "X-" if they are to be registered (either
     501   immediately or in the future).
     504   New header field values typically have their syntax defined using ABNF
     505   (<xref target="RFC5234"/>), using the extensions defined in &notation-abnf;
     506   as necessary, and are usually constrained to the range of ASCII characters.
     507   Header fields needing a greater range of characters can use an encoding
     508   such as the one defined in <xref target="RFC5987"/>.
     511   Because commas (",") are used as a generic delimiter between field-values,
     512   they need to be treated with care if they are allowed in the field-value's
     513   payload. Typically, components that might contain a comma are protected with
     514   double-quotes using the quoted-string ABNF production (&field-rules;).
     517   For example, a textual date and a URI (either of which might contain a comma)
     518   could be safely carried in field-values like these:
     520<figure><artwork type="example">
     521  Example-URI-Field: "http://example.com/a.html,foo",
     522                     "http://without-a-comma.example.com/"
     523  Example-Date-Field: "Sat, 04 May 1996", "Wed, 14 Sep 2005"
     526   Authors of specifications defining new header fields are advised to consider
     527   documenting:
     528  <list style="symbols">
     529    <t>Whether the field is a single value, or whether it can be a list
     530    (delimited by commas; see &header-fields;).</t>
     531    <t>Under what conditions the header field can be used; e.g., only i
     532    responses or requests, in all messages, only on responses to a particular
     533    request method.</t>
     534    <t>Whether it is appropriate to list the field-name in the Connection header
     535    (i.e., if the header is to be hop-by-hop, see &header-connection;).</t>
     536    <t>Under what conditions intermediaries are allowed to modify the header
     537    field's value, insert or delete it.</t>
     538    <t>How the header might interact with caching (see <xref target="Part6"/>).</t>
     539    <t>Whether the header field is useful or allowable in trailers (see
     540    &chunked-encoding;).</t>
     541    <t>Whether the header field should be preserved across redirects.</t>
     542  </list>
    483546<section title="Request Header Fields" anchor="request.header.fields">
     3570<reference anchor="RFC5987">
     3571        <front>
     3572    <title>Character Set and Language Encoding for Hypertext Transfer Protocol (HTTP) Header Field Parameters</title>
     3573    <author initials="J. F." surname="Reschke" fullname="Julian F. Reschke">
     3574      <organization abbrev="greenbytes">greenbytes GmbH</organization>
     3575      <address>
     3576        <postal>
     3577          <street>Hafenweg 16</street>
     3578          <city>Muenster</city><region>NW</region><code>48155</code>
     3579          <country>Germany</country>
     3580        </postal>
     3581        <email>julian.reschke@greenbytes.de</email>     
     3582        <uri>http://greenbytes.de/tech/webdav/</uri>   
     3583      </address>
     3584    </author>
     3585    <date month="August" year="2010"/>
     3586  </front>
     3587  <seriesInfo name="RFC" value="5987"/>
    41844267<section title="Since draft-ietf-httpbis-p2-semantics-16" anchor="changes.since.16">
    4186   None yet.
     4269  Work-in-progress:
     4270  <list style="symbols">
     4271    <t>
     4272      <eref target="http://tools.ietf.org/wg/httpbis/trac/ticket/231"/>:
     4273      "Considerations for new headers"
     4274    </t>
     4275  </list>
Note: See TracChangeset for help on using the changeset viewer.