Subject: i109: Clarify entity / representation / variant terminology

From: Mark Nottingham <[email-masked]>
Date: Fri, 9 May 2008 16:09:33 +1000

<http://www3.tools.ietf.org/wg/httpbis/trac/ticket/109>

The following three terms are defined in 2616:
> entity
>
> The information transferred as the payload of a request or response.  
> An entity consists of metainformation in the form of entity-header  
> fields and content in the form of an entity-body, as described in  
> section 7.
>
> representation
>
> An entity included with a response that is subject to content  
> negotiation, as described in section 12. There may exist multiple  
> representations associated with a particular response status.
>
> variant
>
> A resource may have one, or more than one, representation(s)  
> associated with it at any given instant. Each of these  
> representations is termed a 'varriant'. Use of the term 'variant'  
> does not necessarily imply that the resource is subject to content  
> negotiation.
>

It's been asserted that there's no real distinction between these  
terms (keeping in mind that the distinction between "a particular  
instance of an entity/representation/variant" and "the entity/ 
representation/variant that might be seen under particular  
circumstances" is a separate issue, #69).

If we can agree on that, we only need to find a way to rationalise the  
terms in the spec.

Straw-man proposal:

1) "variant" occurs 16 times in the -02 specs, and a good portion of  
those is the "requested variant" text. If we ignore those instances  
for the moment, the expedient thing to do would seem to be to change  
the remaining occurrences to either "entity" or "representation," and  
remove this term altogether.

2) "representation" occurs 47 times in the -02 specs, while "entity"  
occurs 420 times.

One option would be to switch all occurrences of "entity" over to  
"representation" or vice-versa. If we do the former, we'll end up with  
awkward things like changing the classification of "entity-header  
fields" to "representation-header fields" and "entity tags" to  
"representation tags." Doing the latter seems more straightforward,  
but it still jars some.

A more moderate approach to #2 would be to choose a preferred term,  
migrate to it where it's sensible (at editors' discretion), and  
explicitly define the terms to mean the same thing.

Thoughts?

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

---

From: Stefan Eissing <[email-masked]>
Date: Fri, 9 May 2008 10:01:57 +0200

Am 09.05.2008 um 08:09 schrieb Mark Nottingham:

> [...]
> 1) "variant" occurs 16 times in the -02 specs, and a good portion  
> of those is the "requested variant" text. If we ignore those  
> instances for the moment, the expedient thing to do would seem to  
> be to change the remaining occurrences to either "entity" or  
> "representation," and remove this term altogether.

+1 for "representation" (see below).

> 2) "representation" occurs 47 times in the -02 specs, while  
> "entity" occurs 420 times.
>
> "representation" or vice-versa. If we do the former, we'll end up  
> with awkward things like changing the classification of "entity- 
> header fields" to "representation-header fields" and "entity tags"  
> to "representation tags." Doing the latter seems more  
> straightforward, but it still jars some.
>

For me, "entity" is part of the message and "representation" is part  
of the resource. So, for my (probably soon corrected by the big guns  
here) incomplete gut-http-feeling, it makes sense to say things like:  
The representation of a resource is transferred as the entity in a  
HTTP response message.

//Stefan

--
<green/>bytes GmbH, Hafenweg 16, D-48155 Münster, Germany
Amtsgericht Münster: HRB5782

---

From: "Brian Smith" <[email-masked]>
Date: Fri, 9 May 2008 09:41:12 -0700

> remove this term altogether.

When deciding between "variant" and "representation," I think it makes sense 
to look at standards for extensions to HTTP to see how these two terms are 
being used. I looked at all the proposed standards that were obviously 
related to HTTP and WebDAV. "Variant" and "selected variant" is only used 
with the RFC2616-defined meaning. "Representation" is sometimes used to 
refer to variants, and sometimes it is used in its more general sense to 
describe other things. "Represent" and "represented" are often used in their 
more general sense as well. Details below.

Obviously, some of these proposed standards are not so relevant. However, to 
me it seems like a good idea to give "variant" a very precise meaning and 
let HTTP-related standards use "representation," "represents," 
"representing," and "represented" in their more general sense to describe 
other things. "Variant" also has an obvious relationship to the "Vary" 
header.

Defining "representation" in a way that isn't specific to content 
negotiation (without using "represent") may prove tricky as well. It seems 
to me it would be easier to remove the definition of "representation," leave 
the current definition of "variant" as is, and change all instances of 
"representation" to "variant" or "entity" as appropriate.

Regards,
Brian

RFC 3229 (Delta encoding in HTTP) uses "variant" consistently, and uses 
"representation" only in its more general sense (and to define "variant."). 
It uses "variant" consistently throughout.

RFC 4387: Uses representation once, but again it is in its more general 
sense.

RFC 3230 (Instance Digests in HTTP) uses representation and variant almost 
evenly, and tends to use "variant" when it is trying to be precise.

RFC 4918 (WebDAV): Uses "representation" once when "entity" would be more 
appropriate, and uses the interesting phrase "representation returned upon 
GET" a couple times. It never uses "variant."

RFC 2227 uses "variant" throughout, and uses "represents" in a more general 
sense.

RFC 2817 doesn't use either term.
RFC 2935 and RFC 2965 do not use either term, but it does use "represents" 
in its more general sense.

---

From: Julian Reschke <[email-masked]>
Date: Fri, 09 May 2008 16:02:16 +0200

Stefan Eissing wrote:
> For me, "entity" is part of the message and "representation" is part of 
> the resource. So, for my (probably soon corrected by the big guns here) 
> incomplete gut-http-feeling, it makes sense to say things like: The 
> representation of a resource is transferred as the entity in a HTTP 
> response message.

+1

But not every entity transferred over HTTP is a representation of a 
resource. Example: the response body sent with a 404 status.

BR, Julian

---

From: "Roy T. Fielding" <[email-masked]>
Date: Fri, 9 May 2008 15:46:02 -0700

> resource. Example: the response body sent with a 404 status.

It is a representation of a 404 response.

   <http://www.ics.uci.edu/~fielding/pubs/dissertation/ 
rest_arch_style.htm#sec_5_2_1_2>

   Depending on the message control data, a given representation may
   indicate the current state of the requested resource, the desired
   state for the requested resource, or the value of some other  
resource,
   such as a representation of the input data within a client's query
   form, or a representation of some error condition for a response.

....Roy

---

From: Julian Reschke <[email-masked]>
Date: Sat, 10 May 2008 10:30:30 +0200

Brian Smith wrote:
> ...
> RFC 4918 (WebDAV): Uses "representation" once when "entity" would be 
> more appropriate, and uses the interesting phrase "representation 
> returned upon GET" a couple times. It never uses "variant."
> ...

What's wrong with "representation returned upon GET"?

BR, Julian

---

From: "Brian Smith" <[email-masked]>
Date: Sat, 10 May 2008 07:31:08 -0700

> What's wrong with "representation returned upon GET"?

Nothing.