Closed nicholascar closed 5 years ago
Point 2 resolved in pull request https://github.com/w3c/dxwg/commit/1fb870f32d0fe00fec76a24795947f2b7bab37d7#diff-da8389897e0fe9c86843de139503a4e7
Resolved with Commit https://github.com/w3c/dxwg/commit/67b483a9b1229a076c04945c4c06c02fc4aae241
Karen's commits has fixed it
You've re-opened Issue https://github.com/w3c/dxwg/issues/379 so we will address that there
I have moved all the inline descriptions of the other PROF docts to the end of the Introduction, so Commit https://github.com/w3c/dxwg/commit/67b483a9b1229a076c04945c4c06c02fc4aae241 also
It really is context as it's telling you what the limits of the discussion here are in the context of the other HTTP headers
Perhaps you're right but, at the moment, we have no were else to put this information. Can you make a structural suggestion?
Again, this is context in that this subsection is telling you what the limits of the advice here is in relation to other HTTP methods of more general conneg
"...there's such a long introduction..." sorry but that's a bit hard to deal with! Let's wait for a few other other edits to settle down and see if this is still an issue.
"it's strange to have 5.2.2 not saying what the server should do"
This has been flagged for attention with Issue https://github.com/w3c/dxwg/issues/588 in the document
This has been addressed by other text edits to this section since this issue was raised
Addressed by Commit https://github.com/w3c/dxwg/commit/798f292f561a7dd4e924e6c49ab93343e98e13f0
Issue https://github.com/w3c/dxwg/issues/591 has been created to address this specifically as it's been noticed by a couple of people now
Addressed by Commit https://github.com/w3c/dxwg/commit/095a2f5bb3296d5bd3f65e73fe34b9735bd64603
13 Addressed by Commit https://github.com/w3c/dxwg/commit/99d6a438539bda9dbc3bed1da7898a25e59ce886 and by merging the two sets of references to these other HTTP headers into one paragraph in the Introduction
OPTIONS
was raised by a reviewer and there is an Issue now to address this: Issue https://github.com/w3c/dxwg/issues/510. Note that the description of the Issue says that OPTIONS
use is discouraged so we will likely not end up using OPTIONS
more coming
Thanks a lot for the detailed answer and having already fixed many of my issues. And sorry that I have not reacted earlier. A detailed reaction follows for the first 15 issues.
OK
OK (but there's now an incomplete sentence just before it!)
OK let's discuss!
Partly solved. To me the IETF ID (and issue 380) is about a PROF document, even if it's not in W3C space, and thus doesn't belong to related work. It is (y)our work!
Can still be improved, but I can live with it. To me the argumentation of one's choices wrt. context is not "pure" context anymore. This is why I thought the flow was strange. It could have been moved elsewhere, maybe even just at the end of the context section.
I would suggest to put in in 6.2. In fact if the introduction to 6.2 was shorter (as per my point 8) I'm sure it would fit quite well there! At least better than in the context.
Not OK, but I can live with it. You answer would be very fine if the document had not introduced definitions (and thus assumptions) about some of these notions in an earlier section.
Fair enough, let's wait then - and maybe only come back to it in the next version.
OK
Not OK. I was actually not arguing for replacing MAY by MUST or anything else. In fact the issue still remain with a MUST. Essentially I think the sentence "The list profiles request MUST be either an independent request or part of another realization's request." doesn't not specifying anything. Everything is either independent or part of another request, isn't it? In this case the sentence is a mere clarification, not something with a strong recommendation content, and thus use of RDF2119 upper-case is not appropriate. But maybe I don't understand what's at stake in this sentence.
OK let's discuss there, then. But this issue should perhaps be referenced in the text? It would be great if we can get some feedback during the review process...
OK
OK
Not OK. I had seen issue 510, it was in fact why I've raised my concern. My suggestion was merely editorial: if there's a good chance that OPTIONS is not going to be used, then it doesn't look great if the section starts with it. The HTTP Link subsection should be first.
OK, though it raised another question (but I'm fine with the examples being published as they are now)
Antoine's 2: OK (but there's now an incomplete sentence just before it!) - I think instead there's an erroneous "." after Accept-Encoding
. Is that what you are referring to?
@kcoyle yes it is. Sorry I didn't even take the time to relate these two bits of sentence...
Can someone please quote the line number in the gh-pages doc now? Then I'll try and fix.
https://github.com/w3c/dxwg/pull/598
I did the change
Thanks very much Karen!
I've just tried to assess where we stand here... The numbers refer to @aisaac's original numbering.
Number | Antoine's original question | My comment (also referring to Antoine's last comment |
---|---|---|
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. | OK |
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. | OK (resolved through #598) |
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 #379 | OK |
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 | The text about "what a profile is …" is not in the document any more, so I'd say we can consider this point addressed |
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. | Still open; should be addressed through a re-write of section 6.1 |
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. | Still open; should be addressed through a re-write of section 6.1, putting this text in 6.2 |
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. | Still open; should be addressed through a re-write of section 6.1 |
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). | OK |
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. | OK |
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. | Still open; Antoine considers the use of RFC 2119 language inappropriate |
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? | Could be resolved by referencing #591 in the document |
12 | Abstract Model/tokens (5.2.3) Abstract Model/tokens (5.2.3) | OK |
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. | OK |
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. | Should be OK since #510 has been closed |
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"). | Could be OK, even though Antoine said that "it raised another question" |
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 :-/. | This comment has not yet been addressed |
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. | This comment has not yet been addressed |
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. | This comment has not yet been addressed |
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" | This comment has not yet been addressed |
Antoine, does that reflect your view, too?
@aisaac We discussed this issue in the CNEG meeting on 2019-04-11. It covers many topics, some of which have been addressed (and some not). In order to better monitor progress, the CNEG group would like to close this issue and open new issues for each of the still open points (e. g. 5, 6, 7, 10, 11, 15?, 16,17, 18, 19). Is that OK for you? ACTION-324
@larsgsvensson thanks for this. I am not sure opening new issues for every comment is the right thing to do, as it will create a lot of noise and some issues are rather small, but of course you are the one who should decide :-)
And here are some comments on the list - with specific attention to 4 and 15!
.4. It still holds! To me the IETF ID (and issue 380) is a PROF document, even if it's not in W3C space, and thus doesn't belong to related work. It is (y)our work.
.5. Can still be improved, indeed. To me the argumentation of one's choices wrt. context is not "pure" context anymore. This is why I thought the flow was strange. It could have been moved elsewhere, maybe even just at the end of the context section.
6, 7, 10. Indeed, still open.
.11. Indeed, still open, but could be resolved easily by making a reference to another issue (to which I've just added my comments).
.14. it's ok now indeed!
.15. In fact it may still be open! I'm not sure why I said at some point it was ok, even though there was no response given for it, and the examples or the text still apparently don't mention linked data style redirection. (NB: the numbers of sections and examples in the original comment are now probably all wrong, but the general issue remains).
16, 17, 18, 19. I guess they still are open, considering that there was no response. Maybe these can be grouped?
@aisaac As part of ACTION-351 I've reviewed this issue (again) and came to the following conclusions:
Of your original comments, the following can be considered addressed: Issue | Comment |
---|---|
1 | OK |
2 | OK |
3 | OK |
8 | OK |
9 | OK |
10 | OK (the text "The list profiles request MAY be an independent request or part of another realization's request" has been removed) |
12 | OK |
13 | OK |
14 | OK |
The following still need to be addressed: Issue | Proposed Solution |
---|---|
4 | Remove reference to IETF ID and #380 from related work (referenced in §5.1 |
5, 6 ,7 | Rewrite §6.1. Possibly we should rename it, too: "Context" might not be an appropriate title. |
11 | Reference #591 in §6.2.2 |
15 | Add/rewrite at least one example that uses a 303 redirect when performing the content negotiation |
16 | Rewrite §7.2 to provide a stronger motivation for QSA |
17 | Rewrite §7.2: Parts of Antoine's comment have been answered to, but the text now says that QSA is not normative whereas the §7.2 per definitionem is normative since it has no "this section is not normative" clause. |
18 | Rewrite §7.2. The text Antoine referred to is still in the document |
19 | Rename example 10 to something along the lines of "Requesting a resource using QSA by giving a list of preferred profiles" |
Hi @larsgsvensson , thanks for coming back to this!
1, 2, 3, 8, 9, 10, 12, 13, 14 can be considered addressed indeed.
For the others:
.4. Yes. Note that I'm agnostic wrt #380
.5,6,7. Yes. Indeed, renaming the subsection may improve the situation. Still it would be better to sort out what's about context from what's about proposals in the doc. And 7 is quite a contradiction with other parts.
.11. Yes
.15. Yes. Re-writing could be better than adding another example but I leave it to the editors :-)
.16. I'm split. There's now a motivation paragraph, so in principle my comment is addressed. Yet I'm puzzled by "it is also advisable to enable humans to select data by profile without requiring direct manipulation of request header content" and the rest. QSA are of course easier for humans, but there are tools that can help manipulate these headers. And the motivation given for QSA supposes that humans are helped by a web development tool, so they could pick one that helps manipulating headers. In addition, is human access the sole motivation for QSAs? I could imagine that some web programming styles/constraints could also give a motivation for prefering QSAs over header-based negotiation.
.17. I understand that there is a contradiction, but I will consider it's not related to my original comment anymore, as the contradictions within the text seems to be fixed now!
.18. Yes.
.19. Yes, but this is apparently Example 11 now. Note that my issue was the HTML bit. There's nothing obviously about HTML in GET /a/resource?_profile=aaa,bbb,ccc HTTP/1.1
. So the renaming you suggest could be lighter. Or it could be solved by changing the query itself!
Thanks @aisaac,
Rob and Nick are currently doing some major rewrites of the document (as part of ACTION-356 and ACTION-357) and we'll discuss that again in tomorrow's meeting (2019-08-08). So stay tuned...
Seriously I would like to review the version in PR #1037 before we can close this issue. Is that version at https://raw.githack.com/w3c/dxwg/conneg-ACTION-356/conneg-by-ap/index.html @nicholascar @rob-metalinkage ?
Since we've re-opened, I remove due-for-closing. (Obviously there isn't consensus on that...)
Well I'm actually quite confident that everything has been taken care of, considering the involvement of the editors. It's just that I thought that a final check (and the recording of it in the issue) could be useful, from the perspective of the formal process.
@aisaac scripsit:
Is that version at https://raw.githack.com/w3c/dxwg/conneg-ACTION-356/conneg-by-ap/index.html
Yes, I think it is. Once you've posted your review here, I think we can add back the "due-for-closing" label again (and then add it to the plenary meeting agenda again).
@aisaac can you please perform that final check? Note that the branch conneg-ACTION-356 is gone since the content is merged into the ED at https://w3c.github.io/dxwg/conneg-by-ap/.
Issue 4 remains. The IETF doc is still mentioned in related work, which is misleading. It's not like other related work at all, since it's rather a 'companion' document. I reckon the opening paragraph in the related work section mentions it will be removed, so maybe I could leave with keeping IETF mentioned there for the time being. But then it's confusing as this is presented as regular text. It would be better to put it as a formalized editors' note (in green). And it seems it could do with an update about what's happening with the IETF. I believe the same text has been here for quite a while.
Issues 5, 6, 7 have been handled.
Issue 11 also remain. I see in the abstract model 6.3.2 get resource by profile still says "preference expressed in a functional profile-specific ordering" while 7.1.2 get resource by profile still relies on "indicate preferences by using quality indicators (q-values)". q-values are not exactly equivalent to an ordering. If just because (as @larsgsvensson acknowledged in #591) q-values can have ties. So one can say the HTTP Headers realization is at odds with the abstract model. Is there any explanation about this in the new draft?
Issue 15 is still open. The content has changed, but I think that (at least) example 8 and 9 in 7.1.1 as well as example 11 in 7.1.2 are not compatible with Linked Data style Conneg. I repeat what I said about this: these examples 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 the current examples 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 per example [X]").
Issue 16 has been handled. I guess one may make comments on some sentences, but to me it's clearer now, what kind of motivation you have for QSA. Issues 17 has been handled too.
Issue 18 remains, and maybe is worse. The wording I was refering to in the old 6.2 (now 7.2) has been changed. And now 7.2.1.1 introduces media type QSA as an example of including other QSAs:
To demonstrate an acceptable inclusion, if the client using the URI in Example 12 wished to indicate a preference for the content of the request to be serialised as RDF, according to the Turtle [TURTLE] specification, it could use the IANA Media Types list's token for Turtle which is text/tur tle and formulate the URI as per Example 13 which is accordance with URI formulation requirements [RFC3986]. That is fine, but then why does the rest of the spec continues to say things about the _media_type QSA, even quite formal recommendations about them, like "SHOULD use _mediatype to indicate a resource representation's Media Type" in 7.2.1.2 ?
This again hints that media type is a key aspect of the realization, while it's not. I don't see why a spec about getting profile-specific representation would blur the picture by also discussing media types quite extensively. It's probably fine to keep the _media_type QSA in some examples, if it helps making some points, but frankly I believe there is too much, now.
Issue 19 seems to handled, or maybe it's obsolete now as I don't see any example that looks like the one I was refering to ("GET /a/resource?_profile=aaa,bbb,ccc HTTP/1.1")
Summarising @aisaac's comment, the following of his points are still open:
committed and added to PR https://github.com/w3c/dxwg/pull/1083
issue 4 - changed to note style as requested issue 11 - added "as an ordering mechanism" to as thats what q-values are! issue 15 - 8 and 9 are different and shows it works for both Linked Data (http-range-14) styles and static URLS) - this seems appropriate issue 18 - unresolved - use of _mediatype as a recommended parameter marked as a feature at risk
issue 4 - ok!
issue 11 - I'm still only mildly convinced. I see that the text is now "It is possible to specify a range of acceptable profile URIs and also to indicate preferences by using quality indicators (q-values) as an ordering mechanism.". This does not rule out that q values may have ties. Or are you actually trying to rule it out, by this text? If yes it would be better to be much more explicit about it. But I reckon would be rather an editorial issue, now.
Issue 15 -Linked Data (http-range-14) style negotiation is mostly based on 303 redirects and neither example 8 nor example 9 have a 303 redirect. So how can you claim these two examples work for Linked Data? On the other hand now I see that there is a 303 example: example 6. And even a note on "Redirection to another resource" that mentions http-range-14 and 303. So I guess I'm ok, but why hasn't anyone pointed me to these parts of the text, after the spec was changed and that the original examples that I mentioned were much earlier in the doc?
Issue 18 - I am of course very fine with this approach.
So I believe in the end the issue can be closed, but I'd welcome a couple of confirmations on whether my readings wrt 11 and 15 above are correct!
11 Having ties does not stop it being an ordering mechanism. 15 - sorry if we didnt make that clear enough - we certainly took it forward but may have lost track with the tendency to duplicate matters across multiple issues.
ok @rob-metalinkage !
Thanks @aisaac . Does that mean that we can mark this as due-for-closing?
@larsgsvensson yep.
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
=============
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.
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.
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
"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.
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.
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.
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.
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).
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.
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.
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?
Abstract Model/tokens (5.2.3) Typo on 'refere'.
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.
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.
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.
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 :-/.
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.
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.
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"