Re: Last gasp terminology issue

Jeff said:
> So I'll make one last attempt to suggest that the term "variant"
> is the wrong one.  I'd still support Koen's suggestion of "entity
> source" as the best compromise (given the extremely misleading but
> historically accepted misuse of the term "entity").  Among other
> things, it fits nicely as a directly replacement for the text
> of the definition of "variant".  I.e., this
> 
>     variant
>       Each representation of that resource that corresponds to a different
>       sequence of entities that could be returned for a requested resource
>       is termed a variant.
> 
> would become
> 
>     entity source
>       Each representation of that resource that corresponds to a different
>       sequence of entities that could be returned for a requested resource
>       is termed an entity source.

Ummm, while that is better than variant, the definition is still bogus.
I was going to correct that in 04a (I did in 03), but Jim suggested I
wait until we had a clean draft to look at.  A better one is

      entity source
        The most specific resource corresponding to a representation.
        This may be separate from the requested resource.

but I still think that the term just isn't needed.  Let's look at its
occurrences within the draft.  Oooh, it looks like some of these are
now seriously wrong.

Draft 04 says:
=============================
> 10.3.1 300 Multiple Choices
>  
> The requested resource is available in one or more variants, each with
> their own specific location, and agent-driven negotiation information
> (section 12) is being provided so that the user (or user agent) can
> select a preferred representation.

would be better worded as

  The requested resource corresponds to any one of a set of resources,
  each with its own specific location, and agent-driven negotiation
  information (section 12) is being provided so that the user (or user
  agent) can select a preferred resource and redirect its request to
  that location.

=============================
> 14.15 Content-Location
>  
> The Content-Location entity-header field may be used to supply the
> resource location for the entity enclosed in the message. In the case
> where a resource has multiple entities associated with it, and those
> entities actually have separate locations by which they might be
> individually accessed, the server should provide a Content-Location for
> the particular variant which is returned. In addition, a server SHOULD
> provide a Content-Location with any response which was internally
> redirected to a resource other than the one identified by the request.

would be better worded as

                        the server should provide a Content-Location for
  the resource corresponding to the response entity. 

> ...
> The Content-Location value is not a replacement for the original
> requested URI; it is only a statement of the location of this particular
> entity at the time of the request. Future requests MAY use the Content-
> Location URI if the desire is to identify that particular variant.

would be better worded as

  The Content-Location value is not a replacement for the original
  requested URI; it is only a statement of the location of the resource
  corresponding to this particular entity at the time of the request.
  Future requests MAY use the Content-Location URI if the desire is to
  identify the source of that particular entity.

=============================
> 14.24 If-Modified-Since
>  
> The If-Modified-Since request-header field is used with the GET method
> to make it conditional: if the requested variant has not been modified
> since the time specified in this field, an entity will not be returned  ...

The above is a protocol error.  IMS applies to the resource as a whole,
not to any single variant.  It should be

  The If-Modified-Since request-header field is used with the GET method
  to make it conditional: if the requested resource has not been modified
  since the time specified in this field, an entity will not be returned  ...

Likewise, below it

> b)If the variant has been modified ...
> c)If the variant has not been modified ...

should both be "resource" instead of "variant".

=============================
> 14.25 If-Match
> ...
Ugh. Here is a recent change that is just wrong:

>   Note: The meaning of "If-Match: *" is that the method SHOULD be
>   performed if the representation selected by the origin server (or
>   by a cache, possibly using the Vary mechanism, see section 14.43)
>   exists, and MUST NOT be performed if the representation does not
>   exist. For example,
>  
>       PUT /foo.html HTTP/1.1
>       Host: www.w3.org
>       If-Match: *
>  
>   may be performed only if /foo.html exists.

It doesn't belong in a Note, and should say:

  The meaning of "If-Match: *" is that the method MAY be performed
  if the resource already exists (i.e., if a GET on that resource would
  result in a 2xx response), and MUST NOT be performed if the resource
  does not already exist.

That particular example is no help, and missed some things required
of a PUT, so I'd rather put a better example elsewhere.  Vary and
caches really don't have anything to do with it.

>...
> An updating request (e.g., a PUT or POST) on a resource should include
> only one entity tag, the one associated with the particular variant
> whose value is being conditionally updated.

is not quite right, and isn't explanatory.

  A request intended to update a resource (e.g., a PUT) MAY include an
  If-Match header field to signal that the request method MUST NOT be
  applied if the entity corresponding to the If-Match value (a single
  entity tag) is no longer a representation of that resource.  This
  allows the user to indicate that they do not wish the request to be
  successful if the resource has been changed without their knowledge.

=============================
> 14.26 If-None-Match

Similar changes as to If-Match:

>  Note: The meaning of "If-None-Match: *" is that the method MUST NOT
>  be performed if the representation selected by the origin server
>  (or by a cache, possibly using the Vary mechanism, see section
>  14.43) exists, and SHOULD be performed if the representation does
>  not exist. For example,
> 
>      PUT /foo.html HTTP/1.1
>      Host: www.w3.org
>      If-None-Match: *
> 
>  may be performed only if /foo.html does not exist. This feature may
>  be useful in preventing races between PUT operations.

should be

  The meaning of "If-None-Match: *" is that the method MUST NOT
  be performed if the resource already exists (i.e., if any GET on that
  resource could result in a 2xx response), and MAY be performed
  if the resource does not already exist. This feature may
  be useful in preventing some races between PUT operations.

A full request example is only useful when it is at least minimally
complete and illustrates something that the field alone does not.

=============================
> 14.28 If-Unmodified-Since

Like IMS, the one occurrence of "variant" (2nd para) must be "resource"
in order for the description to be correct.

=============================
> 14.29 Last-Modified
> 
> The Last-Modified entity-header field indicates the date and time at
> which the origin server believes the variant was last modified. .

This change from draft 03 is wrong and should not have been made.
The full paragraph needs to be restored (with term updates):

  The Last-Modified entity-header field indicates the date and time at
  which the origin server believes the resource was last modified. The
  exact semantics of this field are defined in terms of how the recipient
  SHOULD interpret it: if the recipient has a cached entity from this
  resource which is older than the date given by the Last-Modified field,
  that entity SHOULD be considered stale.

We (Henrik and I) spent a long time getting people to understand and
accept that definition of the semantics of last-modified, and that
work must not be thrown out at the last minute.

The last paragraph in this section

> To preserve compatibility with HTTP/1.0 clients and caches, and because
> the Last-Modified date may be useful for purposes other than cache
> validation, HTTP/1.1 servers SHOULD send Last-Modified whenever
> feasible.

Is no longer in context, and in any case should be just

  HTTP/1.1 origin servers SHOULD send Last-Modified whenever its
  appropriate value can be determined.

=============================

> 19.6.2.1 Alternates

Just delete " (variants)" in the first paragraph.

=============================

That's it -- with those changes, we no longer need variant as a term
and we can stop confusing ourselves with it.

 ...Roy T. Fielding
    Department of Information & Computer Science    (fielding@ics.uci.edu)
    University of California, Irvine, CA 92717-3425    fax:+1(714)824-4056
    http://www.ics.uci.edu/~fielding/

Received on Tuesday, 4 June 1996 10:02:46 UTC