Re: [oslc-core] Draft query spec

["Jim Amsden" <jamsden@us.ibm.com>]

David,
Here are my comments:

- You'll need to remove the Additional
Artifacts I added before we decided to publish OSLC Query as a separate
document.

- Abstract is missing

- Introduction is missing

- Terms are missing, suggest the following:
search term
sort key
query base

Motivation:

- linked-data entities --> resources.

- Linked Data Query Language Community
Group has not met that I know of and closed  2016-04-29. Probably
shouldn't reference this.

- [[OSLCCore2] introduced a Query Capability
--> [[!OSLCCore3]] specifies a Query Capability (we don't need to include
history in the motivation section.)

- Remove the bullets that describe what
OSLC Query 2.0 didn't do, and describe what OSLC Query 3.0 does and why
its interesting/important. e.g., OSLC Query 3.0 describes optional capabilities...

- provide a summary of changes from
Query 2.0 section at the end of the document that has these bullets 

Basic Concepts:

- Might be useful to mention OSLC Core
selective properties here, indicating they may be applied to the results
of a query.

Discovering a Query Capability

- needs a (UML) diagram introducing
the example. Its too hard to follow parsing the Turtle.

- Regarding the oslc:resourceShape (similar
comments apply to TRS membership), why is it necessary or even useful to
have different ways of packaging the results of a query into a container?
Why not simply state that the query results are in an ldp:Container, and
members are declared using the ldp:contains property? Why introduce additional
variability? This would seem to add client and server complexity with limited
value. If we need to do this, then it should be motivated here.

I think this was included so that any
given domain resource that happened to have an aggregation or composition
association to some other resources through a property (similar to UML
concepts), then a query on that resource could return its "members"
using that stated composition property. If Core 2.0 had this, then we need
to keep it. But an explanation of the motivation and example would be very
helpful here.

What are the defaults if no oslc:resourceShape
is specified on the QueryCapability?

- If the reason fro defining the isMemberProperty
is to support UML-like structural composition semantics (something that's
foreign to RDF), then it would seem natural to support more than one on
the resource shape. Then there's the question of how to relate the property
and value shape. Possibly allowing more than one oslc:resourceShape would
do it (which is supported). Each resourceShape would have one isMemberProperty
and valueShape


Using Query Capability..

- not sure I understand orderBy description.
Need definition of sort key and does this only apply to searchTerms (seems
like that's what's implied).

- oslc.select - should indicate the
results are resource URLs if not specified, and selective properties applies
additional filtering on the oslc.select properties (not sure why both would
be needed - this needs an example).

- can oslc.where and oslc:searchTerms
both be specified in the same query?

Query Result Containers:

- if a oslc:resourceShape isn't specified
for the query capability, lfp:contains and rdfs: member would both be specified?
Seems redundant.

- For the examples to be meaningful,
we need RDF describing what's being queried, and the GET request with the
query, followed by the results. 

- The examples here don't show the motivation
for the isMemberProperty. Rather they show how rdfs:member and is defined
in relation to ldp:contains. We need an example that motivates isMemberProperty
on a resource that has some containment association. Maybe something from
FOAF would be clear and simple.

- Might be useful to specifically call
out what's required for OSLC 2.0 compatibility here - what servers SHOULD
do if 2.0 compatibility is desirable.

Query Result Paging

- Doesn't a paged response have to provide
a ResponseInfo - otherwise how would the client get the next page?

Query Parameters

Introduction

- says the syntax is EBNF, and the semantics
is informally illustrated with examples - where is the formal specification
of the semantics?

- "We have adopted a consistent
naming convention for these query parameters to identify them as common
across all OSLC specifications, namely all query parameter names are prefixed
with the characters "oslc." The following sections define these
query parameters." --> All query parameter names are prefixed with
the characters "oslc." (just say what the rules are, not why
they were created).

The introduction jumps right in with
a number of special cases before the syntax and semantics are defined.
Maybe this could be organized as 1. introduction to the clause, 2. clause
syntax, 3. clause semantics (happy path), 4. Examples 5. special cases,
error conditions.

- what are "default set of properties"?
How is this specified?

- the only changes between this syntax
and the OSLC Query 2.0 oslc.where - explain the syntax and semantics here.
Put all the changes with OSLC Querh 2.0 in a separate section.


oslc.searchTerms

- "OSLC domain specification that
supports full-text search should specify which resource properties are
indexed". How is this specified? OSLC does not define database indices.

- "Results must be ordered with
the entry with the largest oslc:score occurring first." - even of
oslc:orderBy isn't specified?

oslc.orderBy

- Should this only be allowed if there's
an oslc:select to expose the available properties? Otherwise you'd have
sorted member URLs without being able to see the sorting property. That
might be oK, but is a little strange.

- the relationship between oslc.select
and oslc.properties needs an example.

- example 10 is missing the prefix for
oslc_cm and could also be returned as:

@prefix rdf:   <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
.
@prefix dcterms: <http://purl.org/dc/terms/>
.
@prefix ldp:   <http://www.w3.org/ns/ldp#>
.
@prefix rdfs:  <http://www.w3.org/2000/01/rdf-schema#>
.
@prefix oslc_cm: <http://open-services.net/ns/cm@>
.
@prefix oslc:  <http://open-services.net/ns/core#>
.

<https://host:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/8>
        a  
             oslc_cm:ChangeRequest ;
        dcterms:creator
 <https://host:9443/jts/users/deb>
;
        dcterms:title
   "Add context sensitive help support everywhere"^^rdf:XMLLiteral
.

<https://host:9443/ccm/resource/itemName/com.ibm.team.workitem.WorkItem/1>
        a  
             oslc_cm:ChangeRequest ;
        dcterms:creator
 <https://host:9443/jts/users/deb>
;
        dcterms:title
   "Not possible to change a user password"^^rdf:XMLLiteral
.
...


How would oslc.properties be applied
to the previous query results, using the presented form or the one above?

Error Handling

- this section seems odd since there
have already been a lot of error conditions described in the preceding
sections.

That said, it seem that perhaps one
reason the OSLC query capability might be hard to implement is because
of the significant number of special cases in the syntax and execution
semantics. I know this is necessary for compatibility, but...








Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575




From:      
 David Honey1 <DavidHoney@uk.ibm.com>
To:      
 "OSLC Core TC
(oslc-core@lists.oasis-open.org)" <oslc-core@lists.oasis-open.org>
Date:      
 05/24/2018 10:44 AM
Subject:    
   [oslc-core]
Draft query spec
Sent by:    
   <oslc-core@lists.oasis-open.org>

---

Dear TC member,

Please review the draft OSLC Query 3.0 specification at https://tools.oasis-open.org/version-control/browse/wsvn/oslc-core/trunk/specs/oslc-query.html.
The draft spec contains red editorial comments to guide reviewers about
issues we have previously discussed in TC meetings. and where appropriate,
references the related Issue(s) in Jira. The editorial comments would be
removed after TC review and discussion and before we go to public draft
committee spec. 

Please also review https://issues.oasis-open.org/browse/OSLCCORE-164.
Jim has already included proposed changes in the core spec that we have
previously discussed informally. However, we should formally vote on the
issue. 

Best regards,
David
Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number
741598. 
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6
3AU