Re: Review of FPWD Conneg-by-ap

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