TAB comments on OSLC-Query v.3.0

[Patrick Durusau <patrick@durusau.net>]

Greetings!

Members of the Technical Advisory Board endeavor to comment on all 30
day public review drafts.

Comments on: OSLC-Query-v3.0 are attached.

It isn't necessary to acknowledge each comment separately. A single
email acknowledging this email will be sufficient.

If the TC chooses to ?defer? resolution of an issue to a later version,
please choose Defer Issue under Available Workflow Actions (after
opening the issue).

When the TC has acted on these issues, I would appreciate a pointer to
the TCs resolution as the TAB is tracking the resolution of comments
from TAB members.

Hope everyone is having a great week!

Patrick

-- 
Patrick Durusau
patrick@durusau.net
Technical Advisory Board, OASIS (TAB)
Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC 26300
Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps)

Another Word For It (blog): http://tm.durusau.net
Homepage: http://www.durusau.net
Twitter: patrickDurusau 

Issue key,Issue id,Affects Version/s,Issue Type,Custom field (Proposal),Description
TAB-1660,47674,OSLC Query Version 3.0,Bug,"Â 

A large number of these errors are repetitive and so despite the large number of them, could be corrected without undue effort. The utility I used also displays the source of the document, making correction fairly straight forward.","The accessibility checker at: [https://achecker.ca/checker/index.php] when given the HTML version of OSLC Query Version 3.0, [https://docs.oasis-open.org/oslc-core/oslc-query/v3.0/csprd01/oslc-query-v3.0-csprd01.html] , reports as follows:

Against WCAG 2.0 (Level AAA)

Known Problems 736

Likely Problems 21

Potential Problems 501

HTML Validation 27

CSS Validation 2

 

 "
TAB-1659,47673,OSLC Query Version 3.0,Bug,"At a minimum, the conformance section should name conformance targets and treat their requirements *separately*. That is, for example, Server ... here follows what a server must, should or may accept, what responses it generates, etc.

If query rules vary from server to client, create separate targets for server query rules and client query rules.

If conformance to the data types varies from server to client, create separate conformance clauses for servers and clients. An implementer should not have to paw through all 70 clauses to discover the data types a client must, should or may support.

 ","In the best light, the conformance clauses 1-70 are an unordered list of conformance requirements for undefined conformance targets. Which ones must a client follow? Which ones must a server follow? The server question is potentially answerable, but the client question is not.

There are at least 20 possible conformance targets or properties in the conformance clauses:

oslc:Service
query capacity
resource shape
member resource
servers
OSLC paged result
response body
Get or Post
container
paged response
OSLC domain specification
string_esc term
scoped_term
XMLLiteral
oslc:searchTerms
oslc:score
oslc:orderBy
oslc:where
query result

Not to mention that clauses 26 - 45 mention datatypes not defined or referenced and say nothing about clients creating queries using those data types.

 "
TAB-1658,47671,OSLC Query Version 3.0,Bug,Caption and number all tables.,"The lack of table captions and/or numbering has forced the authors to say ""table below"" several times. That leaves a reader using text to speech or other assistive technology uncertain about which ""table below"" is the target of your reference. All tables should bear captions and numbers. Moreover, Table N, is the proper way to reference a table."
TAB-1657,47670,OSLC Query Version 3.0,Bug,"Re-write the example and all other normative statements to be shorter, more direct and less confusing. ","Using 7.2.3 oslc.where Semantics as only one example (there are numerous others, all of which need correction), it reads in part:

*****
|{{}}|
An XMLLiteral, such as {{""abc""^^rdf:XMLLiteral}}, _MUST_ be supported. A server _MAY_ treat the literal in the same way as a plain string literal with the data type removed such as {{""abc""}}.
A plain string literal, such as {{""abc""}} _MUST_ be supported. A server _MAY_ treat the literal in the same way as an XML literal string such as {{""abc""^^rdf:XMLLiteral}}.
An xsd:string typed literal, such as {{""abc""^^xsd:string}},_MUST_ be supported. A server _MAY_ treat the literal in the same way as an XML literal string such as {{""abc""^^rdf:XMLLiteral}}.
*****
The problem is that the normative requirement is being specified by example and not by reference to say the definition in the XML standard of a string. 
BTW, don't mix non-normative examples in normative requirements. BTW, you could just say that servers must support XMLLiterals [citation]. Servers may support strings that are unaccompanied by an XMLLiteral [citation] datatype designation. 

Short, sweet and none of the back and forth of your prose. Try something similar on the other sections.|"
TAB-1656,47669,OSLC Query Version 3.0,Bug,Better normative referencing and citation should solve this problem.,"In the unnumbered and unnamed table under 7.2.3 oslc.where Semantics, there is a reference to ""compliance to the XMLLiteral standard.""

That's a new one on me. Can you insert a normative reference and cite it here?"
TAB-1655,47668,OSLC Query Version 3.0,Bug,Supply normative reference for datatypes and cite it appropriately where data types are discussed.,"The unnamed and unnumbered table that appears in section 7.2.3 oslc.where Semantics appears to rely on part 2 of the W3C XML Schema standard, in part: xsd:boolean, xsd:DateTime, xsd:Decimal, and others. Failing to provide a normative reference for these datatypes is fatal."
TAB-1654,47667,OSLC Query Version 3.0,Bug,Correct citations to conform to lists maintained by the TC Admin,"Section 1.3 has five (5) incorrect citations. 

You can help us understand why lists maintained by the TC Admin for RFCs,  [http://docs.oasis-open.org/templates/ietf-rfc-list/ietf-rfc-list.html] and W3C documents, [http://docs.oasis-open.org/templates/w3c-recommendations-list/w3c-recommendations-list.html] were NOT used in your work.

Were you unaware of these lists? What could have been done better to bring them to your attention? Please correct all the RFC and W3C citations to conform to the lists maintained by the TC Admin. "
TAB-1653,47666,OSLC Query Version 3.0,Bug,Change section to normative and insert sources for terminology not defined in this document.,"1.2 Terminology is marked as ""non-normative."" Yet, terms such as ""query capacity"" occur in the conformance clauses.

I suspect terminology is normative and the better practice is to list the sources for the terminology listed in this section."
TAB-1652,47665,OSLC Query Version 3.0,Bug,,"In the conformance section, we read:  ""Implementations of this specification need to satisfy the following conformance clauses."" But what follows is just a recap of the normative requirements in the specification body. If you replace in this sentence ""...the following conformance clauses"" with ""...the following normative requirements"" it would be correct. The whole content of section 10 becomes then a single conformance clause.

It is good to refer to normative requirements, but a conformance clause is something different. It should say something like ""In order to conform [ as an OSLCv3 server], an OSLC implementation must satisfy this set of normative statements [ here provide a list or a reference to the section in spec body that contains them]."" The clause is more general. Its focus is the implementation and under which conditions it conforms. It may tighten a SHOULD into a MUST for a higher level of conformance. The clause should have a name.

See the conformance clauses guidelines on TAB page: [https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=tab]Â ; (guideline doc on conformance clauses: [http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html] )

 "
TAB-1651,47664,OSLC Query Version 3.0,Bug,,"The conformance clause is referring to normative statements in the specification body. This is good, an these are clearly labelled. But again due to the fuzziness around the notion of ""implementation"", it is not always clear what to expect from implementation. We will assume here that the implementation is a ""server"".

Query-1: ""An {{oslc:Service}} _MAY_ declare zero, one, or..."" What is the constraint on servers here? As mentioned before, wouldn't a blanket statement like: ""an OSLC:Service MUST be structured in accordance to the model described in...""Â  do the job? (allowing for ""zero, one, or..."") As for MAY statements they will not in general play a role in conformance.

Query-7: appears to be a requirement for a client, not the server. Do we have client conformance requirements? if yes, should be in a separate clause. Same if we decide that a query  or a query response can be separately subject to conformance."
TAB-1650,47663,OSLC Query Version 3.0,Bug,,"The COnformance section talks of ""Implementations of this specification "" but these are not explicitly defined, even if concisely. We gather that an OSLC server is such an implementation (a definition is missing, even if it just refers to another OSLC spec .) But we also see normative requirements associated with query result containers, or queries themselves as issued by a client. Can such objects be also seen separately as ""implementations"" of the spec? Could they claim conformance?  Could a client that issues well-formed queries claim to be OSLCv3-conforming? We need to know what an ""implementation"" can and cannot be. Such implementations then can become ""conformance targets"".

_See conformance clause guideline: [http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html]_

_On TAB public page: [https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=tab]_

 "
TAB-1649,47662,OSLC Query Version 3.0,Bug,,"The model/schema diagram in Section 3 does not have a title, is never referenced. It seems to be normative - isn't it? Then what should be required to conform to it should be clearly stated (provider OSLC service?). When doing so, I suspect several normative statements - like query 2, query 3 - would be superfluous, per the model definition itself. What is concerning is that the textual statements in that section, seem to imply that other parts of this model that do not have textual statements, are unimportant."
TAB-1648,47651,OSLC Query Version 3.0,Bug,"Correct duplicate anchors by assigning unique anchors, assuming anything is pointing at them. Consider less fierce looking anchors.","The W3C link checker at: [http://validator.w3.org/checklink] reports a duplicated anchor at lines 1192 and 1318.

That's really helpful I know. ;)

Well, if you look at 7.2.3 oslc.whereSemantics, it appears that the <td> element following rdf:XMLLiteral, has the same id, as the <td> element following [QUERY-26].

I verified the issue visually and suggest you can point to rdf:XMLLiteral (with an anchor there), or you can point at the present <td> element following it, or you can point to [QUERY-26], but in all three cases, you need to use unique anchors (ids). 

BTW, that is a hellish id. Is it auto-generated in some fashion?

 "
TAB-1647,47649,OSLC Query Version 3.0,Bug,Update the links as indicated.,"The link checker at: [http://validator.w3.org/checklink] reports there are six (6) permanent redirects of URLs. These should be revised to point to the ""permanent"" location. Those redirects are:

warning Line: 518 http://en.wikipedia.org/wiki/Full_text_search redirected to https://en.wikipedia.org/wiki/Full_text_search
 Status: 301 -> 200 OK
 This is a permanent redirect. The link should be updated.

warning Line: https://www.oasis-open.org/policies-guidelines/tc-process redirected to https://www.oasis-open.org/policies-guidelines/tc-process-2017-05-26
 Status: 301 -> 200 OK
 This is a permanent redirect. The link should be updated.

warning Lines: 291, 298 http://www.ibm.com/ redirected to https://www.ibm.com/us-en/?ar=1
 Status: 301 -> 200 OK
 This is a permanent redirect. The link should be updated.

warning Line: 293 http://www.ptc.com/ redirected to https://www.ptc.com/
 Status: 301 -> 200 OK
 This is a permanent redirect. The link should be updated.

warning Line: 300 http://persistent.com/ redirected to https://www.persistent.com/
 Status: 301 -> 200 OK
 This is a permanent redirect. The link should be updated.

warning Line: 309 http://open-services.net/ns/core redirected to http://docs.oasis-open.org/oslc-core/oslc-core/v3.0/oslc-core-v3.0-part7-core-vocabulary.html
 Status: 301 -> 200 OK
 This is a permanent redirect. The link should be updated.

 "

Attachment: signature.asc
Description: OpenPGP digital signature