Subject: WGLC review of p2 -- Editorial Issues

From: Mark Nottingham <[email-masked]>
Date: Mon, 26 Nov 2012 16:58:44 +1100

I think all of this feedback can be dealt with editorially; if anyone (including the editors) feels otherwise or objects to the proposed resolutions, please say so.

Much of it is regarding the use of SHOULD-level requirements in the specification.

* Several of the section headers should be pluralised; e.g., "2. Resource" -> "2. Resources"; "3. Representation" -> "3. Representations"; "3.1.1 Data Type" -> "3.1.1 Data Types"  (most sections are pluralised, and having a few that aren't is jarring)

* 2. Resource - "Resource owners SHOULD NOT include request semantics within a URI..."  This is a new requirement; I personally think it's justified for interop, but wanted to make sure everyone was aware.

* 3.1.1.1 Media Types - references to RFC4288 needs to be updated to draft-ietf-appsawg-media-type-regs.

* 3.1.x - we seem to have a variety of language about respecting the registries; use of non-registered media types is "discouraged", while "Applications SHOULD limit their use of character encodings to those defined within the IANA registry." No such advice is given about Content-Types, while content-codings "SHOULD be registered." Finally, we only note that language tags have a name space "administered by IANA." 

I'm not suggesting we have consistency for its own sake here, but it does seem like these are pretty wildly divergent, and I can't see why.

* 3.1.1.3 Canonicalization and Text Defaults -- "... a bare CR or LF MUST NOT be substituted for CRLF within any of the HTTP control structures (such as header fields and multipart boundaries)." At least for header fields, this seems to contradict common practice and the advice for Message Parsing Robustness in p1. This text was also in 2616.

* 3.1.1.4 Multipart Types -- "In all other respects, an HTTP user agent SHOULD follow the same or similar behaviour as a MIME user agent would upon receipt of a multipart type."  This is a meaningless SHOULD; suggest "ought to."

* 3.1.1.5 Content Type -- "... defines both the data format and how that data SHOULD be processed by the recipient..."  Is this really a conformance requirement? Suggest "ought to."

* 3.1.1.5 Content Type -- "A server SHOULD include a Content-Type header field in a message containing a payload body... unless the intended media type is unknown to the sender."   Have we settled on "SHOULD... unless" or "MUST... unless" for this type of construct? I don't want to provoke a religious war, just want a consistent spec. 

* 3.1.2.2 Content-Encoding -- The second-to-last paragraph illustrates a situation where content negotiation is taking place; it would be good to mention the need to use Vary as well.

* 3.1.2.2 Content-Encoding -- last paragraph: "The server SHOULD respond with a status code of 415 (Unsupported Media Type)." Here and many other places, we use SHOULD to denote that in normal processing, that status code gets used, but that another status code might pre-empt it (e.g., 401).  It would be nice if this were spelled out somewhere and referred to throughout, to make the conditions on the SHOULD unambiguous. 

* 3.4.1 Proactive Negotiation -- this revision brings new terms, "proactive negotiation" and "reactive negotiation." This hasn't been discussed on-list, so I wanted to make sure people were aware. Also, it would be nice to refer to the old names (server-driven and client-driven) to help people map from the old spec.

* 3.4.1 Proactive Negotiation -- The note about User-Agent based negotiation implies that it's fragile because new clients might not be recognised. This is only part of the story; it's also fragile because the mapping of capabilities to the UA string is inexact at best. Finally, "clients" should be "user-agents", as other clients don't insert UA.

* 3.4.2 Reactive Negotiation -- The sentence beginning with "In addition, this specification does not define any mechanism..." would read better if it were moved to the end of the last paragraph and adjusted accordingly.

* 4. Product Tokens -- This section is quite awkward here. What about moving it as a subsection of the introduction? Or, moving it to the first place it's used (as has been done with several other constructs)?

* 5.1 Request Methods overview -- Same problem as in 3.1.2.2 WRT status codes and SHOULD (two occurrences)

* 5.2.1 Safe Methods -- "The GET, HEAD, OPTIONS and TRACE request methods are defined to be safe."  --> "Of the request methods in this specification, the GET, HEAD, OPTIONS and TRACE methods are defined to be safe."

* 5.2.1 Safe Methods -- "A user agent SHOULD distinguish between safe and unsafe methods when presenting potential actions to a user..."   This is a requirement on user interaction -- is it really a conformance requirement?

* 5.3.1 GET -- "... it is the produced data which shall be returned..." -- avoid RFC2119 language; suggest "will"

* 5.3.3 POST -- the list of functions could be read as exclusive; suggest clarifying that these are just examples.

* 5.3.3 POST -- "If a resource has been created on the origin server..." -> "If a resource (or more than one resources) has been created on the origin server..."

* 5.3.4 PUT -- "Unrecognized header fields SHOULD be ignored..." --> "... SHOULD be ignored by the server..."

* 5.3.5 DELETE -- The first paragraph is awkward; it seems like a collection of random statements.

* 5.3.6 CONNECT -- The first paragraph is awkward; it should come out and say that it's intended for proxies, not origin servers.

* 6.5 Context -- the title is quite curt; suggest "Request Context"

* 6.5.1 From -- "The 'From' header field, if given, SHOULD contain an Internet e-mail address..." Why just SHOULD?

* 6.5.1 From -- "In particular, robot agents SHOUDL include this header field..."  AIUI this isn't widely adhered to; should we downgrade to prose?

* 6.5.1 From -- "The client SHOULD NOT send the From header field without the user's approval..."  Does this need to be a requirement?

* 6.5.3 User-Agent -- "User agents SHOULD include this field with requests."  Is this really a conformance requirement?

* 7 Response Status Codes -- "In such cases, user agents SHOULD present to the user the representation enclosed with the response..."  Again, a UI requirement; downgrade to prose?

* 7.2.1 100 Continue -- "The client SHOULD continue with its request."  SHOULD -> ought to.

* 7.2.1 100 Continue -- "The client SHOULD continue by sending the remainder of the request" --> prose

* 7.2.2 101 Switching Protocols -- "The protocol SHOULD be switched only when it is advantageous to do so." --> prose

* 7.3.2 201 Created -- "If the action cannot be carried out immediately, the server SHOULD respond with 202 (Accepted) response instead."  --> prose

* 7.4.1 - 7.6.6 -- Many many SHOULDs that ought to be reformulated as prose.

* 7.5.6 406 Not Acceptable -- "If the response could be unacceptable, a user agent SHOULD temporarily stop receipt of more data and query the user for a decision on further actions." This is a UI constraint, and even without that consideration, making it a requirement seems quite strong.

8.1.1.2 Date -- "Clients can use the Date header field as well; in order..." --> "Clients can use the Date header field in requests as well; in order..."

* 8.1.2 Location -- "For 3xx (Redirection) responses, the location SHOULD indicate the server's preferred URI for automatic redirection to the resource."  --> prose

* 8.1.2 Location -- Should mention that new status codes MAY define semantics for Location.

* 8.1.2 Retry-After -- Should mention that new status codes MAY nominate the use of Retry-After.

* 8.2.1 Vary -- would benefit greatly from an example of two responses that a resource uses negotiation on (showing with and without gzip, for example).

* 8.2.1 Vary -- "The field-names given are not limited..." "given" is ambiguous; suggest "listed".

* 8.4 Informative -- The section title is quite terse; suggest "Informative Header Fields"

* 9.1.2 Considerations for new methods -- add: "If it is possible to make a request using a new method conditional [ref to p4], this ought to be documented by that method. Likewise, if partial request semantics [ref to p5] are meaningful for a new method, it ought to document this too."

* 10.1 Transfer of Sensitive Information -- "Therefore, applications SHOULD supply as much control over this information as possible..."  Is this really a conformance requirement?

* 10.1 Transfer of Sensitive Information -- "Four header fields are worth special mention in this context..." User-Agent needs to be included here.

* 10.2 Encoding Sensitive Information in URIs -- "...it is strongly recommended that the user be able to select..."  Recommended is an RFC2119 keyword; suggest "advised."

* 10.2 Encoding Sensitive Information in URIs -- "Clients SHOULD NOT include a referer header field in a (non-secure) HTTP request if the referring page was transferred with a secure protocol."  This is an odd place to bury this; the section title isn't applicable. Suggest moving it to the section defining the Referer header.

* 10.2 Encoding Sensitive Information in URIs -- "Clients SHOULD NOT include a referer header field in a (non-secure) HTTP request if the referring page was transferred with a secure protocol."  Why SHOULD NOT? I.e., what are the cases where they SHOULD? Ought it be a MUST?

* 10.2 Encoding Sensitive Information in URIs -- "Authors of services SHOULD NOT use GET-based forms for the submission of sensitive data..." Is this really a conformance requirement?

* 10.5 Privacy Issues Connect to Accept Header Fields -- "General purpose user agents which provide a high degree of header field configurability SHOULD warn users..."  Is this really a conformance requirement?

* Appendix A. Differences between HTTP and MIME -- contains several SHOULDs that don't describe conditions when it's OK to violate, and either aren't really conformance requirements, or seem quite important for interop (thereby arguing for MUST).

* Appendix C. Changes from RFC2616 -- These notes are quite terse, sometimes becoming difficult to read. Suggest rewriting to normalise tense and point of view.

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