* WGs marked with an * asterisk has had at least one new draft made available during the last 5 days

Ticket #109 (closed design: fixed)

Opened 6 years ago

Last modified 4 years ago

Clarify entity / representation / variant terminology

Reported by: mnot@pobox.com Owned by: fielding@gbiv.com
Priority: urgent Milestone: 11
Component: non-specific Severity: Active WG Document
Keywords: Cc:
Origin: #69

Description

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?

Change History

comment:1 follow-up: ↓ 2 Changed 6 years ago by mnot@pobox.com

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.

comment:2 in reply to: ↑ 1 Changed 6 years ago by julian.reschke@gmx.de

  • Owner set to julian.reschke@gmx.de
  • Milestone changed from unassigned to 04

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?

comment:3 Changed 6 years ago by julian.reschke@gmx.de

  • Milestone changed from 04 to unassigned

comment:4 Changed 6 years ago by mnot@pobox.com

  • Milestone changed from unassigned to 06

comment:5 Changed 5 years ago by julian.reschke@gmx.de

  • Milestone changed from 06 to unassigned

comment:6 Changed 5 years ago by mnot@pobox.com

  • Priority set to urgent

comment:7 Changed 5 years ago by mnot@pobox.com

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

comment:8 Changed 5 years ago by mnot@pobox.com

  • Owner changed from julian.reschke@gmx.de to fielding@gbiv.com

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

comment:9 Changed 5 years ago by mnot@pobox.com

  • Severity set to Active WG Document

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

comment:10 Changed 4 years ago by fielding@gbiv.com

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).

comment:11 Changed 4 years ago by fielding@gbiv.com

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.

comment:12 Changed 4 years ago by julian.reschke@gmx.de

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)

comment:13 Changed 4 years ago by fielding@gbiv.com

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

comment:14 Changed 4 years ago by fielding@gbiv.com

From [866]:

Addresses #109: Clarify entity / representation / variant terminology

Replaced entity with representation.

comment:15 Changed 4 years ago by fielding@gbiv.com

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.

comment:16 Changed 4 years ago by fielding@gbiv.com

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".

comment:17 Changed 4 years ago by fielding@gbiv.com

  • Status changed from new to closed
  • Resolution set to incorporated
  • Milestone changed from unassigned to 11

This should now be complete.

comment:18 Changed 4 years ago by mnot@pobox.com

  • Status changed from closed to reopened
  • Resolution incorporated deleted

comment:19 Changed 4 years ago by mnot@pobox.com

  • Status changed from reopened to closed
  • Resolution set to fixed
Note: See TracTickets for help on using tickets.