Ignore:
Timestamp:
Jul 22, 2010, 10:43:26 PM (9 years ago)
Author:
fielding@…
Message:

Addresses #109: Clarify entity / representation / variant terminology

Replace more entity, entities, and entity-body, as appropriate.

Addresses #183: "requested resource" in content-encoding definition

Fixed.

Clarifies #178: Content-MD5 and partial responses

New terminology makes it easier to understand what is digested.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • draft-ietf-httpbis/latest/p4-conditional.xml

    r867 r874  
    307307</section>
    308308
    309 <section title="Entity Tags" anchor="entity.tags">
     309<section title="Entity-Tags" anchor="entity.tags">
    310310  <x:anchor-alias value="entity-tag"/>
    311311  <x:anchor-alias value="opaque-tag"/>
    312312  <x:anchor-alias value="weak"/>
    313313<t>
    314    Entity tags are used for comparing two or more entities from the same
    315    requested resource. HTTP/1.1 uses entity tags in the ETag (<xref target="header.etag"/>),
     314   Entity-tags are used for comparing two or more representations from the same
     315   requested resource. HTTP/1.1 uses entity-tags in the ETag (<xref target="header.etag"/>),
    316316   If-Match (<xref target="header.if-match"/>), If-None-Match (<xref target="header.if-none-match"/>), and
    317317   If-Range (&header-if-range;) header fields. The definition of how they
    318318   are used and compared as cache validators is in <xref target="weak.and.strong.validators"/>. An
    319    entity tag consists of an opaque quoted string, possibly prefixed by
     319   entity-tag consists of an opaque quoted string, possibly prefixed by
    320320   a weakness indicator.
    321321</t>
     
    326326</artwork></figure>
    327327<t>
    328    A "strong entity tag" &MAY; be shared by two entities of a resource
     328   A "strong entity-tag" &MAY; be shared by two representations of a resource
    329329   only if they are equivalent by octet equality.
    330330</t>
    331331<t>
    332    A "weak entity tag," indicated by the "W/" prefix, &MAY; be shared by
    333    two entities of a resource only if the entities are equivalent and
     332   A "weak entity-tag," indicated by the "W/" prefix, &MAY; be shared by
     333   two representations of a resource only if the representations are equivalent and
    334334   could be substituted for each other with no significant change in
    335    semantics. A weak entity tag can only be used for weak comparison.
    336 </t>
    337 <t>
    338    An entity tag &MUST; be unique across all versions of all entities
    339    associated with a particular resource. A given entity tag value &MAY;
    340    be used for entities obtained by requests on different URIs. The use
    341    of the same entity tag value in conjunction with entities obtained by
     335   semantics. A weak entity-tag can only be used for weak comparison.
     336</t>
     337<t>
     338   An entity-tag &MUST; be unique across all versions of all representations
     339   associated with a particular resource. A given entity-tag value &MAY;
     340   be used for representations obtained by requests on different URIs. The use
     341   of the same entity-tag value in conjunction with representations obtained by
    342342   requests on different URIs does not imply the equivalence of those
    343    entities.
    344 </t>
    345 
    346 <section title="Example: Entity Tags varying on Content-Negotiated Resources" anchor="example.entity.tag.vs.conneg">
     343   representations.
     344</t>
     345
     346<section title="Example: Entity-tags varying on Content-Negotiated Resources" anchor="example.entity.tag.vs.conneg">
    347347<t>
    348348   Consider a resource that is subject to content negotiation (&content-negotiation;),
     
    390390  <t>
    391391    <x:h>Note:</x:h> Content codings are a property of the representation,
    392     so therefore an entity tag of an encoded representation must be distinct
     392    so therefore an entity-tag of an encoded representation must be distinct
    393393    from an unencoded representation to prevent conflicts during cache updates
    394394    and range requests.  In contrast, transfer codings (&transfer-codings;)
    395     apply only during message transfer and do not require distinct entity tags.
     395    apply only during message transfer and do not require distinct entity-tags.
    396396  </t>
    397397</x:note>
     
    469469</t>
    470470<t>
    471    Entity tags are normally "strong validators," but the protocol
    472    provides a mechanism to tag an entity tag as "weak." One can think of
     471   An entity-tag is normally a strong validator, but the protocol
     472   provides a mechanism to tag an entity-tag as "weak." One can think of
    473473   a strong validator as one that changes whenever the sequence of bits
    474474   in a representation changes, while a weak value changes whenever the
     
    481481      incremented in stable storage every time a representation is changed.
    482482    </t><t>
    483       An entity's modification time, if defined with only one-second
     483      A representation's modification time, if defined with only one-second
    484484      resolution, could be a weak validator, since it is possible that
    485485      the representation might be modified twice during a single second.
     
    524524</t>
    525525<t>
    526    The example below shows the results for a set of entity tag pairs,
     526   The example below shows the results for a set of entity-tag pairs,
    527527   and both the weak and strong comparison function results:
    528528</t>
     
    554554</texttable>
    555555<t>
    556    An entity tag is strong unless it is explicitly tagged as weak.
    557    <xref target="entity.tags"/> gives the syntax for entity tags.
     556   An entity-tag is strong unless it is explicitly tagged as weak.
     557   <xref target="entity.tags"/> gives the syntax for entity-tags.
    558558</t>
    559559<t>
     
    621621</section>
    622622
    623 <section title="Rules for When to Use Entity Tags and Last-Modified Dates" anchor="rules.for.when.to.use.entity.tags.and.last-modified.dates">
     623<section title="Rules for When to Use Entity-tags and Last-Modified Dates" anchor="rules.for.when.to.use.entity.tags.and.last-modified.dates">
    624624<t>
    625625   We adopt a set of rules and recommendations for origin servers,
     
    630630   HTTP/1.1 origin servers:
    631631  <list style="symbols">
    632      <t>&SHOULD; send an entity tag validator unless it is not feasible to
     632     <t>&SHOULD; send an entity-tag validator unless it is not feasible to
    633633        generate one.</t>
    634634
    635      <t>&MAY; send a weak entity tag instead of a strong entity tag, if
    636         performance considerations support the use of weak entity tags,
    637         or if it is unfeasible to send a strong entity tag.</t>
     635     <t>&MAY; send a weak entity-tag instead of a strong entity-tag, if
     636        performance considerations support the use of weak entity-tags,
     637        or if it is unfeasible to send a strong entity-tag.</t>
    638638
    639639     <t>&SHOULD; send a Last-Modified value if it is feasible to send one,
     
    645645<t>
    646646   In other words, the preferred behavior for an HTTP/1.1 origin server
    647    is to send both a strong entity tag and a Last-Modified value.
    648 </t>
    649 <t>
    650    In order to be legal, a strong entity tag &MUST; change whenever the
    651    associated entity changes in any way. A weak entity tag &SHOULD;
    652    change whenever the associated entity changes in a semantically
     647   is to send both a strong entity-tag and a Last-Modified value.
     648</t>
     649<t>
     650   In order to be legal, a strong entity-tag &MUST; change whenever the
     651   associated representation changes in any way. A weak entity-tag &SHOULD;
     652   change whenever the associated representation changes in a semantically
    653653   significant way.
    654654</t>
     
    656656  <t>
    657657    <x:h>Note:</x:h> In order to provide semantically transparent caching, an
    658     origin server must avoid reusing a specific strong entity tag
    659     value for two different entities, or reusing a specific weak
    660     entity tag value for two semantically different entities. Cache
     658    origin server must avoid reusing a specific strong entity-tag
     659    value for two different representations, or reusing a specific weak
     660    entity-tag value for two semantically different representations. Cache
    661661    entries might persist for arbitrarily long periods, regardless of
    662662    expiration times, so it might be inappropriate to expect that a
     
    668668   HTTP/1.1 clients:
    669669  <list style="symbols">
    670      <t>&MUST; use that entity tag in any cache-conditional request (using
    671         If-Match or If-None-Match) if an entity tag has been provided by the
     670     <t>&MUST; use that entity-tag in any cache-conditional request (using
     671        If-Match or If-None-Match) if an entity-tag has been provided by the
    672672        origin server.</t>
    673673
     
    682682
    683683     <t>&SHOULD; use both validators in cache-conditional requests if both an
    684         entity tag and a Last-Modified value have been provided by the origin
     684        entity-tag and a Last-Modified value have been provided by the origin
    685685        server. This allows both HTTP/1.0 and HTTP/1.1 caches to respond
    686686        appropriately.</t>
     
    690690   An HTTP/1.1 origin server, upon receiving a conditional request that
    691691   includes both a Last-Modified date (e.g., in an If-Modified-Since or
    692    If-Unmodified-Since header field) and one or more entity tags (e.g.,
     692   If-Unmodified-Since header field) and one or more entity-tags (e.g.,
    693693   in an If-Match, If-None-Match, or If-Range header field) as cache
    694694   validators, &MUST-NOT; return a response status of 304 (Not Modified)
     
    698698<t>
    699699   An HTTP/1.1 caching proxy, upon receiving a conditional request that
    700    includes both a Last-Modified date and one or more entity tags as
     700   includes both a Last-Modified date and one or more entity-tags as
    701701   cache validators, &MUST-NOT; return a locally cached response to the
    702702   client unless that cached response is consistent with all of the
     
    709709      conservative assumptions about the validators they receive.
    710710  </t><t>
    711       HTTP/1.0 clients and caches will ignore entity tags. Generally,
     711      HTTP/1.0 clients and caches will ignore entity-tags. Generally,
    712712      last-modified values received or used by these systems will
    713713      support transparent and efficient caching, and so HTTP/1.1 origin
     
    737737<t>
    738738   The "ETag" response-header field provides the current value of the
    739    entity tag (see <xref target="entity.tags"/>) for one representation of
    740    the resource identified by the Effective Request URI.  An entity tag
     739   entity-tag (see <xref target="entity.tags"/>) for one representation of
     740   the resource identified by the Effective Request URI.  An entity-tag
    741741   is intended for use as a resource-local identifier for differentiating
    742742   between representations of the same resource that vary over time or via
     
    756756</artwork></figure>
    757757<t>
    758    An entity tag provides an "opaque" cache validator that allows for
     758   An entity-tag provides an "opaque" cache validator that allows for
    759759   more reliable validation than modification dates in situations where
    760760   it is inconvenient to store modification dates,
     
    764764</t>
    765765<t>
    766    The principle behind entity tags is that only the service author
     766   The principle behind entity-tags is that only the service author
    767767   knows the semantics of a resource well enough to select an
    768768   appropriate cache validation mechanism, and the specification of any
     
    781781<t>
    782782   The "If-Match" request-header field is used to make a request method
    783    conditional. A client that has one or more entities previously
    784    obtained from the resource can verify that one of those entities is
    785    current by including a list of their associated entity tags in the
     783   conditional. A client that has one or more representations previously
     784   obtained from the resource can verify that one of those representations is
     785   current by including a list of their associated entity-tags in the
    786786   If-Match header field.
    787787</t>
     
    790790   transaction overhead. It is also used when updating resources, to prevent
    791791   inadvertent modification of the wrong version of a resource. As a special
    792    case, the value "*" matches any current entity of the resource.
     792   case, the value "*" matches any current representation of the resource.
    793793</t>
    794794<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="If-Match"/><iref primary="true" item="Grammar" subitem="If-Match-v"/>
     
    797797</artwork></figure>
    798798<t>
    799    If any of the entity tags match the entity tag of the representation that
     799   If any of the entity-tags match the entity-tag of the representation that
    800800   would have been returned in the response to a similar GET request
    801801   (without the If-Match header) on that resource, or if "*" is given
    802    and any current entity exists for that resource, then the server &MAY;
     802   and any current representation exists for that resource, then the server &MAY;
    803803   perform the requested method as if the If-Match header field did not
    804804   exist.
    805805</t>
    806806<t>
    807    If none of the entity tags match, or if "*" is given and no current
     807   If none of the entity-tags match, or if "*" is given and no current
    808808   representation exists, the server &MUST-NOT; perform the requested method, and
    809809   &MUST; return a 412 (Precondition Failed) response. This behavior is
     
    827827   If-Match header field to signal that the request method &MUST-NOT; be
    828828   applied if the representation corresponding to the If-Match value (a single
    829    entity tag) is no longer a representation of that resource. This
     829   entity-tag) is no longer a representation of that resource. This
    830830   allows the user to indicate that they do not wish the request to be
    831831   successful if the resource has been changed without their knowledge.
     
    936936<t>
    937937   The "If-None-Match" request-header field is used to make a request method
    938    conditional. A client that has one or more entities previously
    939    obtained from the resource can verify that none of those entities is
    940    current by including a list of their associated entity tags in the
     938   conditional. A client that has one or more representations previously
     939   obtained from the resource can verify that none of those representations is
     940   current by including a list of their associated entity-tags in the
    941941   If-None-Match header field.
    942942</t>
     
    948948</t>
    949949<t>
    950    As a special case, the value "*" matches any current entity of the
     950   As a special case, the value "*" matches any current representation of the
    951951   resource.
    952952</t>
     
    956956</artwork></figure>
    957957<t>
    958    If any of the entity tags match the entity tag of the representation that
     958   If any of the entity-tags match the entity-tag of the representation that
    959959   would have been returned in the response to a similar GET request
    960960   (without the If-None-Match header) on that resource, or if "*" is
     
    970970</t>
    971971<t>
    972    If none of the entity tags match, then the server &MAY; perform the
     972   If none of the entity-tags match, then the server &MAY; perform the
    973973   requested method as if the If-None-Match header field did not exist,
    974974   but &MUST; also ignore any If-Modified-Since header field(s) in the
    975    request. That is, if no entity tags match, then the server &MUST-NOT;
     975   request. That is, if no entity-tags match, then the server &MUST-NOT;
    976976   return a 304 (Not Modified) response.
    977977</t>
     
    10751075   of the origin server and the nature of the original resource. For
    10761076   files, it may be just the file system last-modified time. For
    1077    entities with dynamically included parts, it may be the most recent
     1077   representations with dynamically included parts, it may be the most recent
    10781078   of the set of last-modify times for its component parts. For database
    10791079   gateways, it may be the last-update time stamp of the record. For
     
    10911091   as close as possible to the time that it generates the Date value of
    10921092   its response. This allows a recipient to make an accurate assessment
    1093    of the entity's modification time, especially if the representation changes
     1093   of the representation's modification time, especially if the representation changes
    10941094   near the time that the response is generated.
    10951095</t>
     
    14901490<section title="Changes from RFC 2616" anchor="changes.from.rfc.2616">
    14911491<t>
    1492   Allow weak entity tags in all requests except range requests (Sections
     1492  Allow weak entity-tags in all requests except range requests (Sections
    14931493  <xref target="weak.and.strong.validators" format="counter"/> and
    14941494  <xref target="header.if-none-match" format="counter"/>).
Note: See TracChangeset for help on using the changeset viewer.