OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

oslc-core message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: OSLC Query 3.0 public review responses

Here's the comments from the TAB with my initial responses. Could you (especially David) provide any needed corrections to my responses.

Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data

Issue key,Issue id,Affects Version/s,Issue Type,Custom field (Proposal),Description,Action,TC Response
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",Defer,"These are all excellent things to do, but are beyond the scope of what the TC can do at this time. Nor has accessibility been addressed in any of the other OSLC Core or Domains specifications. Note also that a lot of the HTML in these specifications is generated by ReSpec, so addressing accessibility would likely require significant ReSpec development.  "
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:
query capacity
resource shape
member resource
OSLC paged result
response body
Get or Post
paged response
OSLC domain specification
string_esc term
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.","Close, no action","OSLC conformance clauses only specify what an OSLC server MUST, SHOULD, or MAY do in order to provide a conforming implementation. There are no OSLC client conformance clauses. Rather clients simply provide requests that match what the server supports. If a client request cannot be processed by a server, OSLC specifies error responses that are sent to the client to inform them of the reason for refusing the request."
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.",Fix,Will be fixed in a subsequent revision.
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.|",Defer,"Section 7.2.3 is a table of normative statements on the oslc.where clause (other clauses have similar tables). The open-services.net specification had simpler normative statements about supported values and comparison operators that lead to a lot of confusion about what a server had to implement. These specific tables were created to be more specific, and remove server confusion about how different values are compared. ��We understand that the normative rules here are specified by individual cases, rather than more general rules. But experience has shown that this may be necessary for OSLC query."
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?",Fix,Should be [[!rdf-syntax-grammar-20040210]]
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.",Fix,Should reference XML Schema
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.",Fix,
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.",Fix,
TAB-1652,47665,OSLC Query Version 3.0,Bug,"In conformance section, normative statements are confused with ""conformance clause""","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] )",Fix,
TAB-1651,47664,OSLC Query Version 3.0,Bug,"Conformance clause refers to normative statements inthe specification body, but it is not clear what is the conformance requirement for some of these","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.",Fix,
TAB-1650,47663,OSLC Query Version 3.0,Bug,"Not clear what are the ""implementations"" of the specification supposed to conform","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]_",Fix,
TAB-1649,47662,OSLC Query Version 3.0,Bug,Unclear role of diagram in Section 3 (discovering...),"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.",Fix,Add a reference to OSLC Core service discovery.
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?",Fix,
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.",Fix,

Attachment: oslc-query-v3.0.numbers
Description: application/iwork-numbers-sffnumbers

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]