Clarify entity / representation / variant terminology

[mnot@…]

From RFC2616;

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.

These terms have caused confusion, perhaps because they imply server implementation details more than on-the-wire behaviours. E.g., from the client's perspective, is there any difference between the three terms?

[mnot@…]

Proposal:

1) Remove definition and instances of 'variant' from the spec (except for 'requested variant'; see #69).

2) Change definition of 'representation' to be that of 'entity'

3) Give editors license to change 'representation' to 'variant' and vice versa as appropriate.

[julian.reschke@…]

Replying to mnot@pobox.com:

3) Give editors license to change 'representation' to 'variant' and vice versa as appropriate.

That should be "entity", not "variant", right?

[mnot@…]

"requested resource" also comes up often, and may confuse people (because some will read this as "the response / representation I requested").

[mnot@…]

Plan of action:

1. make 'entity' and 'representation' definitions equivalent, use as appropriate throughout specs
2. replace 'variant' with 'representation' throughout specs (except where used as 'requested variant'; see #69)
3. for 'requested resource', propose appropriate sentence changes to reflect interface definitions
4. eventually, align with 'selected response' terminology in p6

[mnot@…]

Discussed at Stockholm meeting; no disagreement with plan as outlined above.

[fielding@…]

From [852]:

Changed message-body ABNF to be *OCTET. Specifying the actual number of octets will have to be done in prose.

Moved mistitled "Message Length" section into the Message Body section, since it only explains how many octets are in the body. Deleted useless "Entity Length" section and transfer-length term.

Addresses #28: Connection closing

Removed redundant mention of terminating by connection close and rewrote explanation so that it doesn't self-contradict.

Addresses #90: Delimiting messages with multipart/byteranges

Removed message-delimiting paragraphs of multipart/byteranges from p1 and p3.

Addresses #95: Handling multiple Content-Length headers

Added requirements for what to do if multiple or invalid Content-Length is received.

Rephrased requirements for Transfer-Encoding to only apply when a transfer-coding is present. Clarify that Transfer-Encoding overrides Content-Length and treat receiving both as an error. Clarify that only the chunked transfer-coding can delimit a message (the original design allowed other self-descriptive encodings, but that was abandoned in 2616).

Addresses #109: Clarify entity / representation / variant terminology

Entity-body terminology changed to payload in order to clarify that it is what gets packaged (as a message-body) into a message, allowing us to (eventually) distinguish between messages containing whole representations and messages containing only partial representations. Reduce use of the same terms for other things (e.g., in explanation of dates).

[fielding@…]

From [856]:

Addresses #69: Clarify "Requested Variant" Addresses #109: Clarify entity / representation / variant terminology

Replaced entity with payload and variant with representation. Cleaned up description of 204 status code (related to ticket #22) Rewrote section on Content-Location and refer to def in RFC2557.

Addresses #110: Clarify rules for determining what entities a response carries

Detail the rules for Content-Location and remove the cross-ref.

Addresses #167: Content-Location on 304 responses

Removed sentence in C-Loc that refers to using C-Loc to select a

variant from cache (an already removed "feature")

Addresses #136: confusing req. language for Content-Location

Removed the confusing paragraph because HTTP does not know anything about variants behind the resource interface and thus cannot make this an interop requirement. In any case, it only existed to support the already removed cache feature that nobody implemented.

Addresses #80: Content-Location isn't special

Clarifies that C-Loc is representation metadata and what (not) to do with it if received on a request.

[julian.reschke@…]

From [859]:

Remove paragraphs in "changes from 2068" about message length handling that do not apply anymore after recent changes; update the remaining to not point to the other parts (see #90)(see #95)(see #109)

[fielding@…]

From [860]:

Addresses #69: Clarify "Requested Variant"

Eliminated that phrase.

Addresses #109: Clarify entity / representation / variant terminology

Replaced variant with representation. Cleaned up p4 description of 304 and 206 status code

[fielding@…]

From [866]:

Addresses #109: Clarify entity / representation / variant terminology

Replaced entity with representation.

[fielding@…]

From [874]:

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.

[fielding@…]

From [965]:

Addresses #109: Clarify entity / representation / variant terminology

Removed entity-header adjective and ABNF and clarified distinction between payload and representation.

Uncapitalize the phrase effective request URI so that it doesn't dominate the prose, and define the term "target resource" to be used instead of the "resource identified by the effective request URI".

[fielding@…]

This should now be complete.