Ignore:
Timestamp:
02/09/12 05:22:28 (8 years ago)
Author:
fielding@…
Message:

(editorial) make header field registry consistent with others by moving considerations for new fields down to registrations

File:
1 edited

Legend:

Unmodified
Added
Removed
  • draft-ietf-httpbis/latest/p2-semantics.xml

    r1846 r1847  
    976976
    977977<section title="Payload Metadata Fields" anchor="payload.fields">
    978 </section>
    979 
    980 <section title="Considerations for Creating Header Fields" anchor="considerations.for.creating.header.fields">
    981 <t>
    982    New header fields are registered using the procedures described in
    983    <xref target="RFC3864"/>.
    984 </t>
    985 <t>
    986    The requirements for header field names are defined in
    987    <xref target="RFC3864" x:fmt="of" x:sec="4.1"/>.  Authors of specifications
    988    defining new fields are advised to keep the name as short as practical, and
    989    not to prefix them with "X-" if they are to be registered (either
    990    immediately or in the future).
    991 </t>
    992 <t>
    993    New header field values typically have their syntax defined using ABNF
    994    (<xref target="RFC5234"/>), using the extension defined in &abnf-extension;
    995    as necessary, and are usually constrained to the range of ASCII characters.
    996    Header fields needing a greater range of characters can use an encoding
    997    such as the one defined in <xref target="RFC5987"/>.
    998 </t>
    999 <t>
    1000    Because commas (",") are used as a generic delimiter between field-values,
    1001    they need to be treated with care if they are allowed in the field-value's
    1002    payload. Typically, components that might contain a comma are protected with
    1003    double-quotes using the quoted-string ABNF production (&field-components;).
    1004 </t>
    1005 <t>
    1006    For example, a textual date and a URI (either of which might contain a comma)
    1007    could be safely carried in field-values like these:
    1008 </t>
    1009 <figure><artwork type="example">
    1010   Example-URI-Field: "http://example.com/a.html,foo",
    1011                      "http://without-a-comma.example.com/"
    1012   Example-Date-Field: "Sat, 04 May 1996", "Wed, 14 Sep 2005"
    1013 </artwork></figure>
    1014 <t>
    1015    Note that double quote delimiters almost always are used with the
    1016    quoted-string production; using a different syntax inside double quotes
    1017    will likely cause unnecessary confusion.
    1018 </t>
    1019 <t>
    1020    Many header fields use a format including (case-insensitively) named
    1021    parameters (for instance, <x:ref>Content-Type</x:ref>, defined in
    1022    &header-content-type;). Allowing both unquoted (token) and quoted
    1023    (quoted-string) syntax for the parameter value enables recipients to use
    1024    existing parser components. When allowing both forms, the meaning of a
    1025    parameter value ought to be independent of the syntax used for it (for an
    1026    example, see the notes on parameter handling for media types in
    1027    &media-types;).
    1028 </t>
    1029 <t>
    1030    Authors of specifications defining new header fields are advised to consider
    1031    documenting:
    1032   <list style="symbols">
    1033     <x:lt>
    1034       <t>Whether the field is a single value, or whether it can be a list
    1035       (delimited by commas; see &header-fields;).</t>
    1036       <t>If it does not use the list syntax, document how to treat messages
    1037       where the header field occurs multiple times (a sensible default would
    1038       be to ignore the header field, but this might not always be the right
    1039       choice).</t>
    1040       <t>Note that intermediaries and software libraries might combine
    1041       multiple header field instances into a single one, despite the header
    1042       field not allowing this. A robust format enables recipients to discover
    1043       these situations (good example: "Content-Type", as the comma can only
    1044       appear inside quoted strings; bad example: "Location", as a comma can
    1045       occur inside a URI).</t>
    1046     </x:lt>
    1047     <x:lt><t>Under what conditions the header field can be used; e.g., only in
    1048     responses or requests, in all messages, only on responses to a particular
    1049     request method.</t></x:lt>
    1050     <x:lt><t>Whether it is appropriate to list the field-name in the
    1051     <x:ref>Connection</x:ref> header field (i.e., if the header field is to
    1052     be hop-by-hop, see &header-connection;).</t></x:lt>
    1053     <x:lt><t>Under what conditions intermediaries are allowed to modify the header
    1054     field's value, insert or delete it.</t></x:lt>
    1055     <x:lt><t>How the header field might interact with caching (see
    1056     <xref target="Part6"/>).</t></x:lt>
    1057     <x:lt><t>Whether the header field is useful or allowable in trailers (see
    1058     &chunked-encoding;).</t></x:lt>
    1059     <x:lt><t>Whether the header field ought to be preserved across redirects.</t></x:lt>
    1060   </list>
    1061 </t>
    1062978</section>
    1063979
     
    43114227</section>
    43124228
    4313 <section title="Header Field Registration" anchor="header.field.registration">
     4229<section title="Header Field Registry" anchor="header.field.registry">
    43144230<t>
    43154231   HTTP header fields are registered within the Message Header Field Registry
    4316    located at <eref target="http://www.iana.org/assignments/message-headers/message-header-index.html"/>
    4317    (see <xref target="RFC3864"/>).  The Message Header Field Registry
    4318    shall be updated with the permanent registrations below:
     4232   located at <eref target="http://www.iana.org/assignments/message-headers/message-header-index.html"/>,
     4233   as defined by <xref target="RFC3864"/>.
     4234</t>
     4235
     4236<section title="Considerations for New Header Fields" anchor="considerations.for.new.header.fields">
     4237<t>
     4238   The requirements for header field names are defined in
     4239   <xref target="RFC3864" x:fmt="of" x:sec="4.1"/>.  Authors of specifications
     4240   defining new fields are advised to keep the name as short as practical, and
     4241   not to prefix them with "X-" if they are to be registered (either
     4242   immediately or in the future).
     4243</t>
     4244<t>
     4245   New header field values typically have their syntax defined using ABNF
     4246   (<xref target="RFC5234"/>), using the extension defined in &abnf-extension;
     4247   as necessary, and are usually constrained to the range of ASCII characters.
     4248   Header fields needing a greater range of characters can use an encoding
     4249   such as the one defined in <xref target="RFC5987"/>.
     4250</t>
     4251<t>
     4252   Because commas (",") are used as a generic delimiter between field-values,
     4253   they need to be treated with care if they are allowed in the field-value's
     4254   payload. Typically, components that might contain a comma are protected with
     4255   double-quotes using the quoted-string ABNF production (&field-components;).
     4256</t>
     4257<t>
     4258   For example, a textual date and a URI (either of which might contain a comma)
     4259   could be safely carried in field-values like these:
     4260</t>
     4261<figure><artwork type="example">
     4262  Example-URI-Field: "http://example.com/a.html,foo",
     4263                     "http://without-a-comma.example.com/"
     4264  Example-Date-Field: "Sat, 04 May 1996", "Wed, 14 Sep 2005"
     4265</artwork></figure>
     4266<t>
     4267   Note that double-quote delimiters almost always are used with the
     4268   quoted-string production; using a different syntax inside double-quotes
     4269   will likely cause unnecessary confusion.
     4270</t>
     4271<t>
     4272   Many header fields use a format including (case-insensitively) named
     4273   parameters (for instance, <x:ref>Content-Type</x:ref>, defined in
     4274   &header-content-type;). Allowing both unquoted (token) and quoted
     4275   (quoted-string) syntax for the parameter value enables recipients to use
     4276   existing parser components. When allowing both forms, the meaning of a
     4277   parameter value ought to be independent of the syntax used for it (for an
     4278   example, see the notes on parameter handling for media types in
     4279   &media-types;).
     4280</t>
     4281<t>
     4282   Authors of specifications defining new header fields are advised to consider
     4283   documenting:
     4284  <list style="symbols">
     4285    <x:lt>
     4286      <t>Whether the field is a single value, or whether it can be a list
     4287      (delimited by commas; see &header-fields;).</t>
     4288      <t>If it does not use the list syntax, document how to treat messages
     4289      where the header field occurs multiple times (a sensible default would
     4290      be to ignore the header field, but this might not always be the right
     4291      choice).</t>
     4292      <t>Note that intermediaries and software libraries might combine
     4293      multiple header field instances into a single one, despite the header
     4294      field not allowing this. A robust format enables recipients to discover
     4295      these situations (good example: "Content-Type", as the comma can only
     4296      appear inside quoted strings; bad example: "Location", as a comma can
     4297      occur inside a URI).</t>
     4298    </x:lt>
     4299    <x:lt><t>Under what conditions the header field can be used; e.g., only in
     4300    responses or requests, in all messages, only on responses to a particular
     4301    request method.</t></x:lt>
     4302    <x:lt><t>Whether it is appropriate to list the field-name in the
     4303    <x:ref>Connection</x:ref> header field (i.e., if the header field is to
     4304    be hop-by-hop, see &header-connection;).</t></x:lt>
     4305    <x:lt><t>Under what conditions intermediaries are allowed to modify the header
     4306    field's value, insert or delete it.</t></x:lt>
     4307    <x:lt><t>How the header field might interact with caching (see
     4308    <xref target="Part6"/>).</t></x:lt>
     4309    <x:lt><t>Whether the header field is useful or allowable in trailers (see
     4310    &chunked-encoding;).</t></x:lt>
     4311    <x:lt><t>Whether the header field ought to be preserved across redirects.</t></x:lt>
     4312  </list>
     4313</t>
     4314</section>
     4315
     4316<section title="Registrations" anchor="header.field.registration">
     4317<t>
     4318   The Message Header Field Registry shall be updated with the
     4319   following permanent registrations:
    43194320</t>
    43204321<?BEGININC p2-semantics.iana-headers ?>
     
    44484449</t>
    44494450</section>
     4451</section>
    44504452
    44514453<section title="Content Coding Registry" anchor="content.coding.registry">
Note: See TracChangeset for help on using the changeset viewer.