Subject: Re: PROPOSAL - i109: Clarify entity / representation / variant terminology

From: Jonathan Rees <[email-masked]>
Date: Fri, 6 Feb 2009 07:40:30 -0500

On Jul 28, 2008, at 9:49 AM, Mark Nottingham wrote:

> I saw a number of +1's to this rough plan, and only Brian offering  
> another path, which didn't seem to get much support.
>
> Let's try doing this (i.e., getting rid of variant -- remembering  
> that there's a separate issue for 'requested variant' -- and change  
> the definition of representation to be the same as that of entity,  
> giving editors discretion to adjust instances of each as  
> appropriate). We can revisit if necessary.

(I'm sorry I'm coming late to this conversation and perhaps you have  
discussed the following, but...)

Yes, I could never understand the difference between 'variant' and  
'representation'.

But I don't think making 'entity' and 'representation' synonyms makes  
much sense. There are a couple of reasons.

First, if they are synonyms, there is no reason to use both.

Second, W3C (e.g. its web architecture recommendation, but the usage  
has spread) reserves 'representation' to mean specifically an entity  
in a 200 response. Thus an entity in a 404 response, or in a PUT or  
POST request, would not be called a representation, but other entities  
wouldn't. There is no reason to redefine 'representation'  
unnecessarily introducing confusion with other specifications.

Webarch goes further and says that a 'representation' is 'of' the  
resource, meaning that there is a special relationship between the  
entity and the resource -- it carries the information associated with  
the resource's current state (in the REST sense), or something like  
that (a different story for services). This relationship doesn't hold  
for requests or non-200 responses. This sort of makes sense because in  
the English language a representation always represents something (is  
a representation of something).  I'm not saying there is a reason for  
HTTPbis to make such a commitment - that could be considered  
'application layer', and any theory of 'representation' could be left  
out of the protocol.

Fourth, the idea of 'representation' is useful because the protocol  
doesn't make really sense without a little bit of (informative?)  
explanation of the motivation for content negotiation. It is there  
because there was an intended use case, namely translations  
('representations') of a document in alternative formats and languages  
to meet user-agent preferences.

Jonathan

---

From: Mark Nottingham <[email-masked]>
Date: Sat, 7 Feb 2009 00:49:36 +1100

On 06/02/2009, at 11:40 PM, Jonathan Rees wrote:

> But I don't think making 'entity' and 'representation' synonyms  
> makes much sense. There are a couple of reasons.
>
> in a 200 response.

Where?

That document defines it as:
> A representation is data that encodes information about resource  
> state. Representations do not necessarily describe the resource, or  
> portray a likeness of the resource, or represent the resource in  
> other senses of the word "represent".
>
> Representations of a resource may be sent or received using  
> interaction protocols. These protocols in turn determine the form in  
> which representations are conveyed on the Web. HTTP, for example,  
> provides for transmission of representations as octet streams typed  
> using Internet media types [RFC2046].
>
I see nowhere where it's bound to a 200 response. In fact, my browser  
doesn't find '200' in the status code sense once in that document.

> Thus an entity in a 404 response, or in a PUT or POST request, would  
> not be called a representation, but other entities wouldn't. There  
> is no reason to redefine 'representation' unnecessarily introducing  
> confusion with other specifications.

That's a discussion that's probably worth having. My understanding of  
Roy's position (I'm sure he'll correct anything I get wrong) is that a  
PUT response (for example) is a representation of *some* resource,  
it's just not the resource identified by the request-URI (unless it  
happens to have a matching Content-Location, of course). In that  
sense, it's representing the state of an anonymous resource.

Is this confusing? Potentially, but it is a consistent view of the  
world, which is something that we currently lack.

> entity and the resource -- it carries the information associated  
> with the resource's current state (in the REST sense), or something  
> like that (a different story for services).

Reference, please?

> This relationship doesn't hold for requests or non-200 responses.  
> This sort of makes sense because in the English language a  
> representation always represents something (is a representation of  
> something).  I'm not saying there is a reason for HTTPbis to make  
> such a commitment - that could be considered 'application layer',  
> and any theory of 'representation' could be left out of the protocol.

I'm not really sure what line you're trying to draw between HTTP and  
semantics, but I'm generally wary of such divisions. Perhaps I spent  
too much time around SOAP people...

> ('representations') of a document in alternative formats and  
> languages to meet user-agent preferences.

I don't see this as a strong motivation for keeping the difference in  
terms.

Cheers,

--
Mark Nottingham     http://www.mnot.net/

---

From: "Roy T. Fielding" <[email-masked]>
Date: Fri, 6 Feb 2009 11:03:34 -0800

On Feb 6, 2009, at 4:40 AM, Jonathan Rees wrote:
>> that there's a separate issue for 'requested variant' -- and  
>> change the definition of representation to be the same as that of  
>> entity, giving editors discretion to adjust instances of each as  
> (I'm sorry I'm coming late to this conversation and perhaps you  
> have discussed the following, but...)
>
> Second, W3C (e.g. its web architecture recommendation, but the  
> usage has spread) reserves 'representation' to mean specifically an  
> entity in a 200 response. Thus an entity in a 404 response, or in a  
> PUT or POST request, would not be called a representation, but  
> other entities wouldn't. There is no reason to redefine  
> 'representation' unnecessarily introducing confusion with other  
> specifications.

Sorry, that is not true.  There are many resources involved in HTTP,  
only
one of which is identified by the requested URI.  Each of those  
resources
may have representations, and the meaning of the payload in a  
response message
is defined by the status code.  A 404 response is going to contain a
representation of a resource on the server that describes that error.
A 200 response is going to contain a representation of the resource that
was identified as the request target.

> like that (a different story for services). This relationship  
> doesn't hold for requests or non-200 responses. This sort of makes  
> sense because in the English language a representation always  
> represents something (is a representation of something).  I'm not  
> saying there is a reason for HTTPbis to make such a commitment -  
> that could be considered 'application layer', and any theory of  
> 'representation' could be left out of the protocol.

I am not aware of any such conclusions in webarch, at least in the  
one that
I approved for publication.

....Roy

---

From: "Robert Brewer" <[email-masked]>
Date: Fri, 6 Feb 2009 11:15:14 -0800

> sense, it's representing the state of an anonymous resource.

I've also heard him say that "the response body sent with a 404 status
is a representation of a 404 response." [1]

Robert Brewer
[email-masked]

[1] http://markmail.org/message/54jr3v2s5uy7jjzx

---

From: Jonathan Rees <[email-masked]>
Date: Fri, 6 Feb 2009 15:56:36 -0500

> I approved for publication.

Cool!  I guess I did make a logical leap there, assuming that  
'representation' was shorthand for 'representation of the resource  
named by the request-URI'. Never occurred to me it could mean anything  
else.

I always forget that you can CN a 404 entity.

I prefer 'entity', though, as it is more neutral and doesn't lead to  
this confusion. Am I an outlier, or could anyone else make the same  
mistake? Maybe there should be an explanation "representation of what"?

Sorry for adding to the muddle!

Jonathan

---

From: "Brian Smith" <[email-masked]>
Date: Fri, 6 Feb 2009 16:05:47 -0600

> mistake? Maybe there should be an explanation "representation of what"?

I don't see how it makes sense to replace "entity" with "representation"
given that important terms like "ETag" (entity tag) and "entity-header
field" are already well-defined in RFC 2616, and they well understood by
everybody implementing HTTP.

Is HTTPbis actually ever going to get published? Is there a new schedule? It
looks like it is going to be at least a year late and there is very little
progress being made. Perhaps the issue list should be cut down to the bare
minimum needed to resolve known interoperable issues. If that is done then I
think issues like i109 are should be first on the chopping block, since its
resolution will not improve interoperability.

- Brian

---

From: Mark Nottingham <[email-masked]>
Date: Sat, 7 Feb 2009 10:07:52 +1100

On 07/02/2009, at 9:05 AM, Brian Smith wrote:
> progress being made.

We have been going in spurts. I expressed concern about the schedule  
last year, but the feedback from both the ADs and people in the room  
(IIRC this was in Dublin) was that we're still making good progress,  
and the work justifies the wait.

Personally, I'm OK with this answer, as long as we are still moving  
forward; RFC2616 has served us for quite some time, and it can hold on  
a bit longer.

The editors have made some progress recently on proposals for a  
variety of issues, but we're waiting for the IPR contributions  
situation to be resolved (hopefully in the next week or so) before  
publsihing.

> Perhaps the issue list should be cut down to the bare

I'd be surprised if we resolved every issue on the list, but I think  
we shouldn't throw them away either.

I will be concerned if we lose editorial resources, or don't have good  
feedback and review. So far it doesn't look like that's the situation.

Cheers,