RE: Review of FPWD Conneg-by-ap

Agree, thanks Antoine, really useful edits. Will work with Rob to incorporate all and will create Issues/Pulls as appropriate to track progress referring to your numbers below.

Nick


From: Rob Atkinson <rob@metalinkage.com.au>
Sent: Tuesday, 13 November 2018 10:22 AM
To: Antoine Isaac <aisaac@few.vu.nl>
Cc: Dataset Exchange Working Group <public-dxwg-wg@w3.org>
Subject: 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<mailto: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"