Ignore:
Timestamp:
Jul 29, 2010, 11:11:34 PM (9 years ago)
Author:
fielding@…
Message:

Addresses #109: Clarify entity / representation / variant terminology

Removed entity-header adjective and ABNF and clarified distinction
between payload and representation.

Uncapitalize the phrase effective request URI so that it doesn't
dominate the prose, and define the term "target resource" to be
used instead of the "resource identified by the effective request URI".

File:
1 edited

Legend:

Unmodified
Added
Removed
  • draft-ietf-httpbis/latest/p3-payload.xml

    r942 r965  
    260260  </list>
    261261</t>
    262 <t>
    263   <iref item="payload"/>
    264   <x:dfn>payload</x:dfn>
    265   <list>
    266     <t>
    267       The information transferred within a given message is called the
    268       payload, consisting  of optional payload metadata and an optional
    269       payload body.  The payload in HTTP is always a partial or complete
    270       representation of some resource, though which resource is represented
    271       is dependent on the type of message (request or response), the
    272       request method, and the response status code.
    273     </t>
    274   </list>
    275 </t>
    276 <t>
    277   <iref item="representation"/>
    278   <x:dfn>representation</x:dfn>
    279   <list>
    280     <t>
    281       A representation is information in a format that can be readily
    282       communicated from one party to another.  For our purposes, a
    283       representation is binary data and its associated metadata.
    284       A representation of a resource is information that reflects the
    285       state of that resource, as observed at some point in the past
    286       or to be desired at some point in the future.
    287     </t>
    288   </list>
    289 </t>
    290262</section>
    291263
     
    705677</section>
    706678
    707 <section title="Representation" anchor="representation">
    708 <t>
    709    Request and Response messages &MAY; transfer a representation if not otherwise
    710    restricted by the request method or response status code. A representation
    711    consists of entity-header fields and a representation body, although some
    712    responses will only include the entity-headers.
    713 </t>
    714 <t>
    715    In this section, both sender and recipient refer to either the client
    716    or the server, depending on who sends and who receives the message.
    717 </t>
    718 
    719 <section title="Entity Header Fields" anchor="entity.header.fields">
    720   <x:anchor-alias value="entity-header"/>
    721   <x:anchor-alias value="extension-header"/>
    722 <t>
    723    Entity-header fields define metadata about the representation data
    724    enclosed in the message-body or, if no message-body is present, about
    725    the representation that would have been transferred in a 200 response
    726    to a simultaneous GET request on the Effective Request URI.
    727 </t>
    728 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="entity-header"/><iref primary="true" item="Grammar" subitem="extension-header"/>
    729   <x:ref>entity-header</x:ref>  = <x:ref>Content-Encoding</x:ref>         ; <xref target="header.content-encoding"/>
    730                  / <x:ref>Content-Language</x:ref>         ; <xref target="header.content-language"/>
    731                  / <x:ref>Content-Length</x:ref>           ; &header-content-length;
    732                  / <x:ref>Content-Location</x:ref>         ; <xref target="header.content-location"/>
    733                  / <x:ref>Content-MD5</x:ref>              ; <xref target="header.content-md5"/>
    734                  / <x:ref>Content-Range</x:ref>            ; &header-content-range;
    735                  / <x:ref>Content-Type</x:ref>             ; <xref target="header.content-type"/>
    736                  / <x:ref>Expires</x:ref>                  ; &header-expires;
    737                  / <x:ref>Last-Modified</x:ref>            ; &header-last-modified;
    738                  / <x:ref>extension-header</x:ref>
    739  
    740   <x:ref>extension-header</x:ref> = <x:ref>header-field</x:ref>
    741 </artwork></figure>
    742 <t>
    743    The extension-header mechanism allows additional entity-header fields
    744    to be defined without changing the protocol, but these fields cannot
    745    be assumed to be recognizable by the recipient. Unrecognized header
    746    fields &SHOULD; be ignored by the recipient and &MUST; be forwarded by
    747    transparent proxies.
    748 </t>
     679<section title="Payload" anchor="payload">
     680<t>
     681   HTTP messages &MAY; transfer a payload if not otherwise restricted by
     682   the request method or response status code.  The payload consists of
     683   metadata, in the form of header fields, and data, in the form of the
     684   sequence of octets in the message-body after any transfer-coding has
     685   been decoded.
     686</t>
     687<iref item="payload"/>
     688<t>   
     689   A "<x:dfn>payload</x:dfn>" in HTTP is always a partial or complete
     690   representation of some resource.  We use separate terms for payload
     691   and representation because some messages contain only the associated
     692   representation's header fields (e.g., responses to HEAD) or only some
     693   part(s) of the representation (e.g., the 206 status code).
     694</t>
     695<t>
     696    define metadata for the whole representation, which we refer
     697   to as "representation header fields", while others define only metadata
     698   about what is included in the message, which we
     699</t>
     700<section title="Payload Header Fields" anchor="payload.header.fields">
     701  <x:anchor-alias value="payload-header"/>
     702<t>
     703   HTTP header fields that specifically define the payload, rather than the
     704   associated representation, are referred to as "payload header fields".
     705   The following payload header fields are defined by HTTP/1.1:
     706</t>
     707<figure><artwork>
     708   <x:ref>Content-Length</x:ref>           ; &header-content-length;
     709   <x:ref>Content-MD5</x:ref>              ; <xref target="header.content-md5"/>
     710   <x:ref>Content-Range</x:ref>            ; &header-content-range;
     711</artwork></figure>
    749712</section>
    750713
    751714<section title="Payload Body" anchor="payload.body">
    752715  <x:anchor-alias value="payload-body"/>
    753 <t>
    754    The payload body (if any) sent with an HTTP request or response is in
    755    a format and encoding defined by the entity-header fields.
    756 </t>
    757716<t>
    758717   A payload body is only present in a message when a message-body is
     
    761720   have been applied to ensure safe and proper transfer of the message.
    762721</t>
    763 
    764 <section title="Type" anchor="type">
    765 <t>
    766    When a payload body is included with a message, the data type of that
    767    body is determined via the header fields Content-Type and Content-Encoding.
     722</section>
     723</section>
     724
     725<section title="Representation" anchor="representation">
     726<iref item="representation"/>
     727<t>
     728   A "<x:dfn>representation</x:dfn>" is information in a format that can be readily
     729   communicated from one party to another.  A resource representation
     730   is information that reflects the state of that resource, as observed
     731   at some point in the past (e.g., in a response to GET) or to be
     732   desired at some point in the future (e.g., in a PUT request).
     733</t>
     734<t>
     735   Most, but not all, representations transferred via HTTP are intended
     736   to be a representation of the target resource (the resource identified
     737   by the effective request URI).  The precise semantics of a representation
     738   are determined by the type of message (request or response), the request
     739   method, the response status code, and the representation metadata.
     740   For example, the above semantic is true for the representation in any
     741   200 (OK) response to GET and for the representation in any PUT request.
     742   A 200 response to PUT, in contrast, contains either a representation
     743   that describes the successful action or a representation of the target
     744   resource, with the latter indicated by a Content-Location header field
     745   with the same value as the effective request URI.  Likewise, response
     746   messages with an error status code usually contain a representation that
     747   describes the error and what next steps are suggested for resolving it.
     748</t>
     749
     750<section title="Representation Header Fields" anchor="representation.header.fields">
     751  <x:anchor-alias value="representation-header"/>
     752<t>
     753   Representation header fields define metadata about the representation data
     754   enclosed in the message-body or, if no message-body is present, about
     755   the representation that would have been transferred in a 200 response
     756   to a simultaneous GET request with the same effective request URI.
     757</t>
     758<t>
     759   The following header fields are defined as representation metadata:
     760</t>
     761<figure><artwork>
     762   <x:ref>Content-Encoding</x:ref>         ; <xref target="header.content-encoding"/>
     763   <x:ref>Content-Language</x:ref>         ; <xref target="header.content-language"/>
     764   <x:ref>Content-Location</x:ref>         ; <xref target="header.content-location"/>
     765   <x:ref>Content-Type</x:ref>             ; <xref target="header.content-type"/>
     766   <x:ref>Expires</x:ref>                  ; &header-expires;
     767   <x:ref>Last-Modified</x:ref>            ; &header-last-modified;
     768</artwork></figure>
     769</section>
     770
     771<section title="Representation Data" anchor="representation.data">
     772  <x:anchor-alias value="representation-data"/>
     773<t>
     774   The representation body associated with an HTTP message is
     775   either provided as the payload body of the message or
     776   referred to by the message semantics and the effective request
     777   URI.  The representation data is in a format and encoding defined by
     778   the representation metadata header fields.
     779</t>
     780<t>
     781   The data type of the representation data
     782   is determined via the header fields Content-Type and Content-Encoding.
    768783   These define a two-layer, ordered encoding model:
    769784</t>
    770785<figure><artwork type="example">
    771   payload-body := Content-Encoding( Content-Type( data ) )
    772 </artwork></figure>
    773 <t>
    774    Content-Type specifies the media type of the underlying data. Any HTTP/1.1
    775    message containing a payload body &SHOULD; include a Content-Type header
    776    field defining the media type of that body, unless that information is
    777    unknown.
    778 </t>
    779 <t>   
     786  representation-data := Content-Encoding( Content-Type( bits ) )
     787</artwork></figure>
     788<t>
     789   Content-Type specifies the media type of the underlying data, which
     790   defines both the data format and how that data &SHOULD; be processed
     791   by the recipient (within the scope of the request method semantics).
     792   Any HTTP/1.1 message containing a payload body &SHOULD; include a
     793   Content-Type header field defining the media type of the associated
     794   representation unless that metadata is unknown to the sender.
    780795   If the Content-Type header field is not present, it indicates that
    781    the sender does not know the media type of the data; recipients &MAY;
    782    either assume that it is "application/octet-stream" (<xref target="RFC2046" x:fmt="," x:sec="4.5.1"/>)
     796   the sender does not know the media type of the representation;
     797   recipients &MAY; either assume that the media type is
     798   "application/octet-stream" (<xref target="RFC2046" x:fmt="," x:sec="4.5.1"/>)
    783799   or examine the content to determine its type.
    784800</t>
    785801<t>
    786    In practice, currently-deployed servers sometimes provide a Content-Type
    787    header which does not correctly convey the intended interpretation of the
    788    content sent, with the result that some clients will examine the response
    789    body's content and override the specified type.
    790 </t>
    791 <t>
     802   In practice, resource owners do not always properly configure their origin
     803   server to provide the correct Content-Type for a given representation,
     804   with the result that some clients will examine a response body's content
     805   and override the specified type.
    792806   Clients that do so risk drawing incorrect conclusions, which might expose
    793    additional security risks (e.g., "privilege escalation"). Implementers are
    794    encouraged to provide a means of disabling such "content sniffing" when it
    795    is used.
     807   additional security risks (e.g., "privilege escalation").  Furthermore,
     808   it is impossible to determine the sender's intent by examining the data
     809   format: many data formats match multiple media types that differ only in
     810   processing semantics.  Implementers are encouraged to provide a means of
     811   disabling such "content sniffing" when it is used.
    796812</t>
    797813<t>
    798814   Content-Encoding is used to indicate any additional content
    799815   codings applied to the data, usually for the purpose of data
    800    compression, that are a property of the representation.  There is
    801    no default encoding.
    802 </t>
    803 </section>
    804    
     816   compression, that are a property of the representation.  If
     817   Content-Encoding is not present, then there is no additional
     818   encoding beyond that defined by the Content-Type.
     819</t>
    805820</section>
    806821</section>
     
    962977   This section defines the syntax and semantics of HTTP/1.1 header fields
    963978   related to the payload of messages.
    964 </t>
    965 <t>
    966    For entity-header fields, both sender and recipient refer to either the
    967    client or the server, depending on who sends and who receives the message.
    968979</t>
    969980
     
    13091320  <x:anchor-alias value="Content-Encoding-v"/>
    13101321<t>
    1311    The "Content-Encoding" entity-header field indicates what content-codings
     1322   The "Content-Encoding" header field indicates what content-codings
    13121323   have been applied to the representation, and thus what decoding mechanisms
    13131324   must be applied in order to obtain the media-type referenced by the
     
    13591370  <x:anchor-alias value="Content-Language-v"/>
    13601371<t>
    1361    The "Content-Language" entity-header field describes the natural
     1372   The "Content-Language" header field describes the natural
    13621373   language(s) of the intended audience for the representation. Note that this might
    13631374   not be equivalent to all the languages used within the representation.
     
    14341445<t>
    14351446   If Content-Location is included in a response message and its value
    1436    is the same as the Effective Request URI, then the response payload
     1447   is the same as the effective request URI, then the response payload
    14371448   &SHOULD; be considered the current representation of that resource.
    14381449   For a GET or HEAD request, this is the same as the default semantics
     
    14461457<t>
    14471458   If Content-Location is included in a response message and its value
    1448    differs from the Effective Request URI, then the origin server is
     1459   differs from the effective request URI, then the origin server is
    14491460   informing recipients that this representation has its own, presumably
    14501461   more specific, identifier.  For a GET or HEAD request, this is an
    1451    indication that the Effective Request URI identifies a resource that
     1462   indication that the effective request URI identifies a resource that
    14521463   is subject to content negotiation and the representation selected for
    14531464   this response can also be found at the identified URI.  For other
     
    14911502</t>
    14921503<t>
    1493    If the Content-Location value is a partial URI, it is
    1494    interpreted relative to the Effective Request URI.
     1504   If the Content-Location value is a partial URI, the partial URI is
     1505   interpreted relative to the effective request URI.
    14951506</t>
    14961507</section>
     
    15021513  <x:anchor-alias value="Content-MD5-v"/>
    15031514<t>
    1504    The "Content-MD5" entity-header field, as defined in <xref target="RFC1864"/>, is
     1515   The "Content-MD5" header field, as defined in <xref target="RFC1864"/>, is
    15051516   an MD5 digest of the payload body that provides an end-to-end message
    15061517   integrity check (MIC) of the payload body (the message-body after any
     
    15771588  <x:anchor-alias value="Content-Type-v"/>
    15781589<t>
    1579    The "Content-Type" entity-header field indicates the media type of the
     1590   The "Content-Type" header field indicates the media type of the
    15801591   representation. In the case of responses to the HEAD method, the media type is
    15811592   that which would have been sent had the request been a GET.
     
    15921603</artwork></figure>
    15931604<t>
    1594    Further discussion of methods for identifying the media type of a
    1595    representation is provided in <xref target="type"/>.
     1605   Further discussion of Content-Type is provided in <xref target="representation.data"/>.
    15961606</t>
    15971607</section>
     
    28182828<x:ref>disposition-type</x:ref> = "attachment" / disp-extension-token
    28192829
    2820 <x:ref>entity-header</x:ref> = Content-Encoding / Content-Language / Content-Length
    2821  / Content-Location / Content-MD5 / Content-Range / Content-Type /
    2822  Expires / Last-Modified / extension-header
    2823 <x:ref>extension-header</x:ref> = header-field
    2824 
    28252830<x:ref>filename-parm</x:ref> = "filename=" quoted-string
    28262831
     
    28572862; MIME-Version defined but not used
    28582863; content-disposition defined but not used
    2859 ; entity-header defined but not used
    28602864</artwork></figure></section>
    28612865<?ENDINC p3-payload.abnf-appendix ?>
Note: See TracChangeset for help on using the changeset viewer.