- From: Rob Atkinson <rob@metalinkage.com.au>
- Date: Tue, 13 Nov 2018 11:21:43 +1100
- To: Antoine Isaac <aisaac@few.vu.nl>
- Cc: Dataset Exchange Working Group <public-dxwg-wg@w3.org>
- Message-ID: <CACfF9LwRzEZuu06SD+g1MW649RiJtdetZ32a1p4d_NXPpMr9oA@mail.gmail.com>
Thanks Antoine this is great feedback - I dont see any fundamental disagreements but a lot of very constructive suggestions for improving text. I'll wait for plenary decisions tomorrow but FWIW I am willing to do an editorial job to try to incorporate as much as I feel confident i can improve and make sure issues are in place where something more substantive is needed. Or let someone else do this :-) Rob On Tue, 13 Nov 2018 at 08:37, Antoine Isaac <aisaac@few.vu.nl> wrote: > Dear Conneg-by-ap editors, all, > > As requested I've read https://w3c.github.io/dxwg/conneg-by-ap/ (FPWD, > dated November 8 2018). > Here's a quick review of it. > > The summary: the document reads quite well (until the Appendices) and I > don't see a major blocker. Honestly I feel uneasy about moving into FPWD a > document for which major parts did not exist at the last F2F, 3 weeks ago. > And there are some bits (especially for the QSA) that seem could have > matured more before being included. Some of my issues are not editorial... > But, in accordance with the mantra of publishing often, I clearly don't > feel like objecting to this FPWD publication. > The level of quality seems high enough, even if I hope you can address > some of my comments before releasing it ;-) > > My comments follow below. I have not created github issues, partly because > I didn't have the time and partly because there might already be issues > created for these issues (there was at least one, which I've re-opened). > I've tried to number my comments in case one wants to refer to them in > later emails. They sometimes align with section numbers, but it's not on > purpose :-) > > Note that there is one matter which I think should stand out: it's #15, on > compatibility with Linked Data conneg. > > I hope this helps, > > Antoine > > ============= > > 1. Abstract > The two last paragraphs ("For details about what a profile is, see the > [PROF-GUIDE] [...]" and "For the formal ontology describing profiles, > [...]") are clearly not abstract-level material. > > 2. Introduction (section 1) > "Thus, resources available in different languages" wrongly uses "thus". > There's no direct logical implication between Media Type considerations and > Language ones. > > 3. Motivation (3) > To me this section could be merged with the introduction. There's quite a > bit of overlap, and I think putting the motivation early in documents > always help. > I've re-opened https://github.com/w3c/dxwg/issues/379 > > 4. Related Work content (4) > "What a profile is and how to create one is detailed in the [PROF-GUIDE] > document [...]", > "Issue 380: Remove text in favour of full reference to final IETF doc > [...]" and > "Describing the parts of profiles and their relation to other profiles is > done within the Profiles Ontology" > are not related work material to me. They're rather about explaining our > current (pieces of) work, and therefore seem a better fit for the intro. > > 5. Abstract Model/Context (5.1) > The paragraph that includes "For this reason, other than a directive to > maintain independence, no further discussion of negotiation by profile and > this relations to other forms of negotiation are given" reads strange in > the flow of other paragraphs. It doesn't read like context, in fact. > > 6. Abstract Model/Context (5.1) > The paragraph starting with "A client requesting the representation of a > resource conforming to a profile MUST identify the resource" clearly > doesn't read like a piece of context, as it gives normative instructions. > > 7. Abstract Model/Context (5.1) > The sentence "In this abstract model, we don't assume any specifics about > client, server, resource, metadata, request or response" reads strange as > definitions have been given earlier about these notions. So there is a form > of assumption going on. > > 8. Abstract Model/Requests and Responses (5.2) > I don't get why there's such a long introduction to 5.2. Not only this is > long, but it results in splitting information that would be easier to > understand if it was kept together in each of the subsections. For example > it's strange to have 5.2.2 not saying what the server should do (this info > is only in the intro). > > 9. Abstract Model/Requests and Responses (5.2) > "a server responds the list of profile tokens it is able to deliver > resource representations conforming to and their mapping to profile URIs" > is quite hard a sentence to swallow. Maybe adding a bit of punctuation > and/or a conjunction would help. > > 10. Abstract Model/Requests and Response (5.2.1) > "The list profiles request MAY be an independent request or part of > another realization's request". I'm not sure this requires such emphasis > (the 'MAY'); it doesn't strike me as spec-level, compared to the paragraph > just after. > > 11. Abstract Model/preferences (5.2 and 6.1) > 5.2.2 mentions that preferences are expressed in 'some form of list > ordering'. This is a bit different from the quality indicators from 6.1.2. > And (a question real question at the same time as a possible example of > issue:) can q values have ties? > > 12. Abstract Model/tokens (5.2.3) > Typo on 'refere'. > > 13. HTTP intro (6.1) > "namely media type (Accept/Content-Type), encoding > (Accept-Encoding/Content-Encoding) and language > (Accept-Language/Content-Language)" could be in the introduction instead > (where these precise formulations of the 'other' accept headers are not > quite there. > > 14. HTTP OPTIONS (6.1.1) > It is strange to find this section first in 6.1 while (according to the > wording of issue 510) OPTIONS is not recommended practice. > > 15. Compatibility of examples with Linked Data conneg (6.1.1 and 6.1.2) > Examples 2 and 3 are at odds with the conneg recipes derived from > Http-range-14. In RDF statements, the 'most interesting' URIs are URIs of > non-information resources. These non-information resources are expected to > first be de-referenced to the URI of a representation via a 303-redirect. > That URI is then served with a 200. > There are of course cases where the pattern of examples 2 and 3 will be > the right one. But now the text really says that the simple 200 pattern is > the one expected ("a request/response pair would look as follows"). > At least, there should be a prominent note/issue saying that there are > other content negotiation patterns. Ideally, an example with 303-redirect > would be introduced - or perhaps even replace the simple 200 one. > > 16. QSA - motivation (6.2) > In the end, QSA requires a lot of rather subtle instructions and text, but > there is little motivation for it in the draft. I'm ready to accept that we > have some cases and requirements somewhere, but they are not rendered. Or > if they are, they should be more prominently advertised, as I've missed > them :-/ . > > 17. QSA - level of specification (6.2) > The wording around what the draft recommends on QSA is quite confusing. > In the intro of 6.2 the sentence > "this realization is fully specified here and this document is considered > normative for the QSA realization." > seems to contradict the one that follows it: > "This realization does not preclude other QSA specifications for profile > and content negotiation" > I think I understand where the draft wants to go, in fact. But then I > really feel uneasy when I read rather strong recommendations like "The QSA > key/value pair _profile=list SHOULD be used" in 6.2.1. > > 18. QSA - mention of mediatype (6.2) > "In this realization, _profile and _mediatype are used to indicate[...]" > hints that media type is a key aspect of the realization. I guess it's not. > I mean, I'm not sure why a spec about getting profile-specific > representation would blur the picture by also discussing media types quite > extensively. > > 19. QSA - example 7 > I'm struggling to see why example 7 ("GET /a/resource?_profile=aaa,bbb,ccc > HTTP/1.1") is about "Requesting a list of profiles for a resource by QSA in > HTML" > >
Received on Tuesday, 13 November 2018 00:22:26 UTC