W3C home > Mailing lists > Public > public-dxwg-wg@w3.org > November 2018

[dxwg] Antoine's conneg doc edits

From: Nicholas Car via GitHub <sysbot+gh@w3.org>
Date: Tue, 13 Nov 2018 22:22:47 +0000
To: public-dxwg-wg@w3.org
Message-ID: <issues.opened-380450710-1542147766-sysbot+gh@w3.org>
nicholascar has just created a new issue for https://github.com/w3c/dxwg:

== Antoine's conneg doc edits ==
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"

Please view or discuss this issue at https://github.com/w3c/dxwg/issues/575 using your GitHub account
Received on Tuesday, 13 November 2018 22:22:49 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 19:42:10 UTC