RE: Review of FPWD Conneg-by-AP

Dear Andrea,

On Tuesday, November 13, 2018 12:19 PM, andrea.perego@ec.europa.eu [mailto:andrea.perego@ec.europa.eu] wrote:

> Following Antoine's mail, I include below my comments concerning the Content
> Negotiation by Profile spec (https://w3c.github.io/dxwg/conneg-by-ap/). As the
> ones I contributed for the PROF spec [1], they are mainly editorial.

Thank you for your review. As with Antoine's comments, those are very helpful!

> I give my +1 to the publication of this spec,

:-)

> although I would recommend fixing at
> least those editorial issues concerning lack of compliance with the W3C ReSpec
> template. I'll create PRs for at least some of them.

That's your comments 0, 2, 6 and 8, right?

> Meanwhile, I have 2 main non-editorial comments (that can be addressed in the
> next version of the spec):
> 
> 1. In different sections, HTTP is mentioned as one example of protocols supporting
> content negotiation, which may lead to the (wrong?) assumption that the PROF-
> CONNEG spec is protocol-independent. Is this the case? Otherwise, it should be
> made explicit that we are talking about HTTP only. I think this is something that
> needs to be clarified throughout the document.

Good point. That's something that requires deeper discussion and is probably for 2PWD. I _think_ that the abstract model could work over other protocols, too.

> 2. I'm missing the context about the notion of profile "token": why they are needed,
> in addition to URIs? Cannot we have just URIs?

I _think_ (Nick may correct me here) that tokens are primarily for use with QSA and are preferred over URIs simply because they are shorter.

> ----
> [1] http://lists.w3.org/Archives/Public/public-dxwg-wg/2018Nov/0338.html

> 
> ----
> 
> 0. The document on GH is said to be a "W3C First Public Working Draft". This needs
> to be changed: all documents on GH are of type "W3C Editor's Draft" (see, e.g.,
> https://w3c.github.io/dxwg/dcat/). The change of type into FPWD will be done
> when the document is moved to TR space.

That was PR #565

> 1. Abstract:
> 
> 1.1. I wonder whether "Internet clients" should be replaced with "HTTP clients": are
> we not talking about HTTP conneg?

Perhaps "clients" would do just as well (since that's what we have in the definitions).

> 1.2. "For details about what a profile is, see the [PROF-GUIDE] recommendation
> published by the producers of this document.". PROF-GUIDE is not (yet) a
> Recommendation. I suggest replacing the sentence with "For details about what a
> profile is, see [PROF-GUIDE]."

+1

> 1.3. "For the formal ontology describing profiles, their parts and relations to other
> profiles and specifications, see the [PROF-ONT] recommendation, also published by
> this document's publisher." Same as above: I suggest replacing it with "For the
> formal ontology describing profiles, their parts and relations to other profiles and
> specifications, see [PROF-ONT]."

+1

> 2. Sections 1.1 & 1.2 does not comply with the W3C ReSpec template: they should
> be merged into a specific section (Section 2), about conformance, where the
> conformance boilerplate will be automatically added (whereas now it is hard-coded)
> - see: https://github.com/w3c/respec/wiki/conformance

I've done that change in PR #561 (yet to be merged)

> 3. Section 3: "When using non-HTTP content negotiation, other methods, such as
> URIs with Query String Arguments, no universal or standardized method for doing
> this has been established although there are multiple specific ways this has been
> implemented previously, such as the OAI-PMH protocol [OAI-PMH]." I suggest
> adding also OGC CSW catalogue services as an example (which is explicitly
> mentioned in our use cases exactly wrt this point).
> 
> 4. Section 4: "IETF": expand acronym at its first occurrence. It may be also worth
> encapsulating the first occurrence within an ABBR tag, so that the acronym
> expansion will be shown as a tooltip throughout the document - see:
> https://github.com/w3c/respec/wiki/ReSpec-Editor's-Guide#abbreviations--
> acronyms . BTW, the same approach could be used for frequently occurring
> acronyms, as QSA

3 and 4 are merged through your PR #566

> 5. Section 5.2:
> 
> [[
> 1. list profiles
> a server responds to a client with the list of profile URIs for the profiles it is able to
> deliver resource representations conforming to
> ]]
> 
> I wonder whether there's something missing at the end of the sentence
> ("conforming to" what?)

The sentence is correct but admittedly hard to read. "conforming to" refers to the profiles in the list of profile URIs. It's hard to come up with a catchy definition. My best attempt would be:
[[
A server responds to a client with a list of profile URIs. For each URI in that list, the server can deliver at least one resource representation conforming to the profile identified by that URI."
]]

Does that make sense?

> 6. Section 7: The link to the test suite must be included in config.js
> (https://github.com/w3c/respec/wiki/testSuiteURI), which will take care of including
> it into the "Status of this document" section.
> 
> 7. Section 8: The link to the implementation must be included in config.js
> (https://github.com/w3c/respec/wiki/implementationReportURI), which will take
> care of including it into the "Status of this document" section. Also, I think the
> implementation report should be placed in the DXWG wiki space.

Ah, thanks, I wasn't aware of those... Can/should we still have separate sections for test suite and implementations or does ReSpec take care of that as soon as we include them in config.js?

I've created PR #567 to add the links to config.js. I'm not sure where to keep the implementation report(s) and that's probably something we need to address in a plenary meeting.

Best,

Lars

Received on Tuesday, 13 November 2018 15:06:52 UTC