- From: Svensson, Lars <L.Svensson@dnb.de>
- Date: Tue, 13 Nov 2018 15:06:27 +0000
- To: "andrea.perego@ec.europa.eu" <andrea.perego@ec.europa.eu>
- CC: "public-dxwg-wg@w3.org" <public-dxwg-wg@w3.org>
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