Review of FPWD Conneg-by-AP

Dears,

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.

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.

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.

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?

Cheers,

Andrea

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

1. Abstract: 

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

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

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


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

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

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.


----
Andrea Perego, Ph.D.
Scientific / Technical Project Officer
European Commission DG JRC
Directorate B - Growth and Innovation
Unit B6 - Digital Economy
Via E. Fermi, 2749 - TP 262
21027 Ispra VA, Italy

https://ec.europa.eu/jrc/


----
The views expressed are purely those of the writer and may
not in any circumstances be regarded as stating an official
position of the European Commission.

Received on Tuesday, 13 November 2018 11:19:22 UTC