Subject: Clarifying Content-Location (Issue 136)

From: Julian Reschke <[email-masked]>
Date: Sun, 27 Sep 2009 14:08:17 +0200

Hi,

we've got an old issue pending resolution with respect to totally 
confusing language in the introduction of Content-Location (see old mail 
quoted at the end and 
<http://trac.tools.ietf.org/wg/httpbis/trac/ticket/136>).

The RFC2616 text was:

-- snip --
14.14 Content-Location

    The Content-Location entity-header field MAY be used to supply the
    resource location for the entity enclosed in the message when that
    entity is accessible from a location separate from the requested
    resource's URI. A server SHOULD provide a Content-Location for the
    variant corresponding to the response entity; especially 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.
-- snip --

Note the double SHOULD in the second half, one overlapping the other in 
scope; more discussion about this is in the old mailing list thread 
starting at 
<http://lists.w3.org/Archives/Public/ietf-http-wg/2008JulSep/0259.html>.

We recently rephrased the header field introductions, and Part 3 now states:

-- snip --
5.7.  Content-Location

    The "Content-Location" entity-header field is used to supply a URI
    for the entity in the message when it is accessible from a location
    separate from the requested resource's URI.

    A server SHOULD provide a Content-Location for the variant
    corresponding to the response entity, especially 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.
-- snip --

(Note the first sentence was rewritten, and a paragraph break was inserted)

We'd like to reduce this to:

-- snip --
5.7.  Content-Location

    The "Content-Location" entity-header field is used to supply a URI
    for the entity in the message when it is accessible from a location
    separate from the requested resource's URI.

    A server SHOULD provide a Content-Location for the variant
    corresponding to the response entity, especially 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.
-- snip --

...which essentially removes the SHOULD for the case where there's only 
one entity - I think that reflects common sense.

(see also 
<http://trac.tools.ietf.org/wg/httpbis/trac/attachment/ticket/136/136.diff>)

Best regards, Julian

Julian Reschke wrote:
> 
> Hi,
> 
> I was staring at the definition of Content-Language, and trying to 
> figure out how to rephrase it avoiding the term "variant" (as discussued 
> in <http://wiki.tools.ietf.org/wg/httpbis/trac/ticket/109>):
> 
> RFC 2616 says:
> 
>    The Content-Location entity-header field MAY be used to supply the
>    resource location for the entity enclosed in the message when that
>    entity is accessible from a location separate from the requested
>    resource's URI. A server SHOULD provide a Content-Location for the
>    variant corresponding to the response entity; especially 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. -- 
> <http://tools.ietf.org/html/rfc2616#section-14.14>
> 
> Comments:
> 
> - the first "MAY" seems to be useless and actually distracting ("may be 
> used", "can be used" or "is used" would be just fine)
> 
> - "...when that entity is accessible from a location separate from the 
> requested resource's URI" -- can this be simplified to "when that entity 
> is accessible from a location separate from the request-URI"? Or am I 
> missing something here?
> 
> - then it goes on saying server "SHOULD" return the header, but then 
> "SHOULD return especially" in some special cases -- but there was 
> already an unconditional SHOULD without that condition.
> 
> Part of this confusion seems to be the result of trying to BCP14fy what 
> RFC2068 said (which had the first "SHOULD" in lower case).
> 
> So, looking at RFC 2068:
> 
>    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 for the resource corresponding to
>    the response entity. -- 
> <http://tools.ietf.org/html/rfc2068#section-14.15>
> 
> This looks a bit better, except for the last sentence:
> 
> "In addition, a server SHOULD provide a Content-Location for the 
> resource corresponding to the response entity."
> 
> ...which I frankly do not understand -- what does it say what hasn't 
> been said before?
> 
> So if I had to rewrite this I would make it just:
> 
>    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.
> 
> (BCP14fying the should, dropping the last sentence)
> 
> Feedback appreciated,
> 
> Julian
> 
> 
> 
> 
>

---

From: "Robert Brewer" <[email-masked]>
Date: Sun, 27 Sep 2009 08:44:28 -0700

> one entity - I think that reflects common sense.
<http://trac.tools.ietf.org/wg/httpbis/trac/attachment/ticket/136/136.d
> iff>)

Yes, although I don't think that quite "removes the SHOULD for the case
where there's only one entity". Also, must we continue the tradition of
adding adverbs ad infinitum to create long, passive, run-on sentences?
;)

  The "Content-Location" entity-header field supplies a URI for the
  entity in the message when it is different than the requested
  resource's URI. When a resource has multiple entities accessible
  at separate locations, a server SHOULD provide a Content-Location
  for the variant.

Robert Brewer
[email-masked]

---

From: Julian Reschke <[email-masked]>
Date: Sun, 27 Sep 2009 18:51:37 +0200

> where there's only one entity". Also, must we continue the tradition of

It doesn't?

>   at separate locations, a server SHOULD provide a Content-Location

Yes, that's better. How about changing the end to

   ...SHOULD provide a Content-Location for the returned entity.

?

BR, Julian

---

From: "Robert Brewer" <[email-masked]>
Date: Sun, 27 Sep 2009 12:36:30 -0700

Julian Reschke wrote:
> Robert Brewer wrote:
> > Yes, although I don't think that quite "removes the SHOULD
> > for the case where there's only one entity".
> 
> It doesn't?

I actually read the proposed text before reading your rationale, and I
read it as SHOULD for only one entity. The word "especially" wasn't a
strong enough modifier, I think.

> > Also, must we continue the tradition of adding adverbs ad
> > infinitum to create long, passive, run-on sentences?
> > ;)
> >

Even better. I actually considered that but wasn't confident enough in
my knowledge of the distinction between "entity" and "variant" to
propose that change.

Robert Brewer
[email-masked]

---

From: Adrien de Croy <[email-masked]>
Date: Mon, 28 Sep 2009 16:39:01 +1300

One thing relating to this header and caching.

If a response contains a Content-Location header, do the other (e.g.
cache control) headers relate to the original requested URI, or to the
new URI specified in the Content-Location or both?

in other words, should the cache maintain 2 indices for this entity -
one from the original URI and one from the Content-Location?

Or do something else?

Regards

Adrien

Robert Brewer wrote:

Julian Reschke wrote:

Robert Brewer wrote:

It doesn't?

Robert Brewer
[email-masked]

--
Adrien de Croy - WinGate Proxy Server - http://www.wingate.com

---

From: "Brian Smith" <[email-masked]>
Date: Sun, 27 Sep 2009 22:54:48 -0500

>    ...SHOULD provide a Content-Location for the returned entity.

First, "when it is different than the request resource's URI" is unnecessary
and wrong. Having a Content-Location that is the same as the request URI is
valid and is actually the only safe use of Content-Location.

Since the use of Content-Location for cache invalidation was recently
removed, there are now NO interoperable uses for Content-Location. So, why
SHOULD the server provide a Content-Location? I would say that the server
really, really SHOULD NOT provide a Content-Location unless it knows that
there are no relative URLs in the resource or in any headers in the
response. Also, other protocols (e.g. AtomPub) overload Content-Location for
other purposes which further reduces the cases where Content-Location is
appropriate.

It would be better for interoperability to say "Servers SHOULD NOT use the
Content-Location header." At the very least, the specification must not say
that servers "SHOULD" use the Content-Location header.

Regards,
Brian

---

From: Julian Reschke <[email-masked]>
Date: Mon, 28 Sep 2009 08:29:33 +0200

> valid and is actually the only safe use of Content-Location.

What use would that be? (assuming we're talking about GET)

> other purposes which further reduces the cases where Content-Location is

The use is to identify a specific variant.

The base-URI question has a separate issue 
(<http://trac.tools.ietf.org/wg/httpbis/trac/ticket/154>).

> ...

I think that's a separate discussion (and I happen to disagree).

BR, Julian

---

From: "Brian Smith" <[email-masked]>
Date: Mon, 28 Sep 2009 01:59:06 -0500

Julian Reschke wrote:
> Brian Smith wrote:
> > First, "when it is different than the request resource's URI" is
> > unnecessary and wrong. Having a Content-Location that is the
> > same as the request URI is valid and is actually the only safe
> > use of Content-Location.
> 

Exactly. Content-Location doesn't have any interoperable uses in HTTP. My
point is that Content-Location is generally safe only when Content-Location
= Request-URI, but then it is useless, except for its misuse in AtomPub (See
RFC 5023 to see how Content-Location is used in AtomPub).

> The use is to identify a specific variant.

It doesn't identify a specific variant, because the resource at the
Content-Location may also be subject to content negotiation (especially
Vary: Content-Encoding). 

Secondly, why SHOULD servers identify every variant with a URL? I agree that
they MAY do so, but why SHOULD? Especially, if a resource varies only on
Content-Encoding, why SHOULD a server provide three URLs for it? Besides the
base URI issue, it reduces cache efficiency if anybody actually requests the
resource through the Content-Location URLs. It also complicates the
management of the URL space on the server. Yet, there's no benefit to be
gained from the added costs.

Regards,
Brian

---

From: "Roy T. Fielding" <[email-masked]>
Date: Mon, 28 Sep 2009 00:18:30 -0700

> RFC 5023 to see how Content-Location is used in AtomPub).

It is being used correctly by AtomPub.  The purpose of the field is to
support MIME encapsulation, not HTTP, so the fact that it has only
one remaining usage in HTTP (due to browser bugs) should be no big
surprise.

The section should not say "when it is different than the request
resource's URI" because it is useful for a response to a non-GET
method that wants to indicate that this body is what you would
have received in a 200 response if the request had been a GET on
the content-location URI.  In other words, it saves the client
from having to make a subsequent request for the current state if
the client can trust the server's response, which is almost always
true for non-GET methods and especially when the Content-Location
does match the requested URI.

....Roy

---

From: Julian Reschke <[email-masked]>
Date: Mon, 28 Sep 2009 09:26:43 +0200

> RFC 5023 to see how Content-Location is used in AtomPub).

Actually, we just recently clarified the spec, supporting what AtomPub 
does. See <http://tools.ietf.org/wg/httpbis/trac/ticket/110>. The 
description of Content-Location probably should mention that other section.

> Content-Location may also be subject to content negotiation (especially

OK, it defines a resource which may or may not have a one-to-one 
relation to a variant.

> gained from the added costs.

That's a good point, in particular because of Content-Encoding. I 
propose that we discuss this as a separate issue (Mark, are you ok with 
opening a separate one for this?)

BR, Julian