[oslc-cm] V2 specs comments [long]

[Steve K Speicher]

Hi Olivier,

Many thanks for the thorough review.  Responses included inline...

Sorry for the delay in response, started to draft it over a week ago and 
logged/worked some of the issues already.

Thanks,
Steve Speicher | IBM Rational Software | (919) 254-0645

Olivier Berger <olivier.berger at it-sudparis.eu> wrote on 05/27/2010 
09:15:48 AM:

> From: Olivier Berger <olivier.berger at it-sudparis.eu>
> To: "oslc-cm at open-services.net" <oslc-cm at open-services.net>
> Date: 05/27/2010 09:16 AM
> Subject: [oslc-cm] V2 specs comments [long]
> Sent by: oslc-cm-bounces at open-services.net
> 
> Hi.
> 
> I've finally taken some time today to review the
> http://open-services.net/bin/view/Main/CmSpecificationV2 (as of r. 28)
> and here's a list of my comments / questions / issues found :
> 
> Issues already tracked in
> http://open-services.net/bin/view/Main/CmSpecV2Issues :
> 
>         1. -> need to fix the examples in appendix a to use something
>         else than oslc_cm for severity/prority prefix ?

DONE, ns prefix fixed

>         4. -> the discussion inline example in appendix a is misleading
>         as looks like complete doc, even no mandatory attributes are
>         there : suggestion : remove it completely if discussion is now
>         in core.

DONE, removed example

> 
> New comments / suggestion / issues in the order I spotted them reading
> the specs draft:
> 
> * suggestion to add in the introduction some mention that these specs
> regard both data types and protocol elements regarding the service
> interfaces behaviours (i.e. OSLC-CM is not a data format nor a simple
> API, but a full set of a quit extensive protocol).

ISSUE logged

> * add in terminology something about "Resource" mentioning somehow the
> RDF / SemWeb context (hence URIs, resource links, etc.)

ISSUE logged

> * in terminology "Change Request resource", mention "bug report" as
> another possible explanation of what a CR is

DONE, updated.

> * terminology - Consumer : replace "consume" by interoperate to refer to
> a protocol more than a data format (for instance in context of delegated
> dialogs)

No action taken, a client can "consume" either delegated dialogs or 
RESTful services.  I may take a another pass at a writeup but nothing 
better comes to mind.

> * Base requirements / Compliance : which OSLC-Core version explicitely ?
> (1.0 ?) must OSLC-CM V2 be compliant with ? (I assume not any later
> version without OSLC-CM version increment ?)

I am not sure I understand the issue here.  The current draft says that it 
depends on Core 2.0. Are you suggesting that is should state "at least" 
Core 2.0?
ISSUE logged to track this

> * Namespace : the prefix "oslc_cm" is a convention in the specs document
> but not mandatory for services implementation, I think (at least in
> XML/RDF fragments, the xmlns may be named any way provided it's
> consistent)... in JSON maybe mandatory ?

It is intended to both be a convention in the spec, as well as required in 
some cases.  For example, when used in URL query syntax and property 
requests, to not have to define well-known namespaces.

Will work to update this.

> * Resource formats / UIs : mentioning (X)HTML explicitely for UIs (since
> REST HTTP-based protocol, that would make sense/ be implicit ?) ?

ISSUE logged, agree we should be more explicit here.
 
> * Authentication, Error response, Pagination, etc. up to CM Resource
> Definition may not be placed early in the docs, as not so much
> important, and the impatient reader may prefer to learn about more
> important aspects, i.e. what change requests are ? so, I'd suggest
> mentioning that details about these aspects will be provided later in
> the docs, and directly introducing the resource description as soon as
> possible.

ISSUE logged, attempted to do this and agree these sections should be 
first. 

> * Request and Updating Properties -> add ... Updating /RESOURCE/
> Properties.

I don't understand this comment, what are you proposing as a change?  Is 
it the need to qualify properties as being "Resource" properties?

> * Requesting subset of properties : what is a "non-extended" resource
> property ? What is a wildcard ?

Extended properties are defined in the core.
Wildcard ('*') is a way to define that a client wants all properties.

I have updated this section to be more clear.

> * Updating a Subset of Properties : changed GET to PUT for in the wiki.

Thanks

> * State Predicates : definition of what a predicate is should go first
> (or in terminology at beginning ?) : on the 3 paragraphs, the last one
> should be first IMHO : the rules first, and the rationale / use case
> later.

ISSUE logged, will work to better define this section.

> * Resource Changerequests : explain why "properties are not limited to
> the ones defined in these specs" : extensibility seeked by OSLC, RDF
> natively extensible, etc.

Intent is to just make it clear, that definition is open.
 
> * Resource properties tables : Type columns values should be documented
> (or pointer to the legend of the table, i.e. a "Resource" is a URI, what
> a XMLLiteral is (examples of these may be welcome here) ... etc.

These are defined in the Core.  Reference will be added.

> * dc:identifier : the rationale of having it in addition to the resource
> URI may be necessary, IMHO (in particular due to the fact that it is
> "not meant for user display") should updates be made using it and such
> (in principle not for REST API where URL of resource may be the only way
> to manipulate resources from the consumers ?)

The rationale of having this as many bug trackers have the notion of a 
"Bug ID".  It is often, if not always, defined by the tool upon creation 
of a bug record.  This is different than something such as dc:name, which 
defines short "display" string.  For example, I could see something like 
this:
<oslc_cm:ChangeRequest rdf:about="http://example.com/bugtracker/rec421">
   <dc:type>Bug</dc:type>
   <dc:identifier>123</dc:identifier>
   <dc:name>Bug-123</dc:name>
</oslc_cm:ChangeRequest>

I will provide a better example to illustrate these.

ISSUE logged to track action.
 
> * dc:creator : this has been discussed several times but the end
> result / rationale is not clear : explain if specific requirements
> (original submitter or user in app, and if none, then provide some
> example with explicit list of potential different uses) ?

ISSUE logged.  As stated, this has been discussed by WG and this was the 
resolution.  We will review your issue.

> * rdf:type : should it be constant and set to
> http://open-services.net/xmlns/cm/2.0#ChangeRequest ? if not, then
> example ? (/me thinks not, as subclassing would be useful for
> polymorphism)

ISSUE logged, agree that it is not constant but should be either that or a 
subclass of.

> * oslc:serviceProvider : shouldn't it be more "meaningful" if named
> like : changeManagementService, even if the target resource is a
> oslc:Serviceprovider ? what's the rationale for zero-to-many ? wouldn't
> zero-to-one be enough ? (and if possible then provide an example of a CM
> resource "shared" by multiple services ?)

ISSUE logged. oslc:serviceProvider is common property and makes it easy 
for clients to just ask any OSLC resource for its service provider 
definition, agree it should be zero-to-one.
 
> * oslc:instanceShape : "oslc:ResourceShape" in Type and "Response" look
> inconsistent : what is a Response here ? (ok, one may RTFM the core, but
> should be as explicit as possible IMHO)

ISSUE logged, there has been some recent discussion in core regarding this 
space.

> * oslc:discussion : Resource -> Resource or Local Inline Resource ?

Intent is to say that a service provider can either include it inline 
(blank node) or as a URIref to another resource.


> * Additional properties -> OSLC-CM specific properties ?
> 
> * dc:type : ain't it a core property (since "dc", would look like") ?
> looks ambiguous with rdf:type for non-experts... and error-prone... why
> not explicitely using some oslc_cm:changeRequestType ? and... the
> examples of potential values would be helpful, me thinks (what's the use
> of it if there's rdf:type that can refer to specific subclasses of
> oslc_cm:ChangeRequest (OWL in mind)) ?

ISSUE logged, there has been some recent core discussion and will bring 
this in line with that.

> * oslc_cm:status : maybe should refer to the predicates ? (am I right
> that the String litteral refers to the oslc_cm:open..oslc_cm:reviewed) ?
> "performing an action"... uh... how ? a REST call on one of the
> Services' Description's endpoints ? Something as common question as "how
> OSLC-CM V2 specifies the way to close a change request ?" should be
> straightforward to ask (even if the answer is : we don't specify this in
> OSLC-CM, only the way to know a Change Request's status).

ISSUE logged.  There are no standard values for oslc_cm:status.  This is 
intended to be a representation of the current status (single value) of a 
change request.  Will rework the "performing an action" statement.

> * State predicate properties : that is far from clear and needs examples
> I think... I'd be very much annoyed to have to implement such specs at
> the moment for our Mantis add-on> * May a basic workflow diagram / 
matrix help here, since some predicates
> values seem mutually exclusive ?

ISSUE logged

> * Relationship properties : the specs should convey non-ambiguous
> semantics as much as possible (at least if refining "related" into more
> precise variants)... and I'm afraid the context and vocabulary is far
> from obvious for plan item, tasks, requirement, etc. Examples would help
> a great deal ;-)

ISSUE logged, clean up wording and examples
 
> * Relationship descriptions would benefit from some OWL like domain +
> range resource types (and in this part of the document we'd assume that
> only domains being Change Request would be mentioned first, and inverse
> relationships whose range is Change Request would be flagged separately,
> in case there's no bi-jection)

ISSUE logged, incorporate additional relationship guidance from core

> * Resource ProgressTracking : what's a "child task" (btw, what's the
> semantic distinction between a task and a change request may be detailed
> fruitfully ?)

ISSUE already logged on this

> * Creation factories : "Services definition." -> "Service Provider's
> Resource definition." ?
> 
> * Query Capabilities : fixed "creation" -> "querying" in the wiki

Thanks 

> * Version Compatibility with 1.0 Specifications / Media Types : what's
> the difference (not) with 1.0, exactly here ?

ISSUE logged, action to update spec. 

> * Samples : may need update (TODO to be added ?)
Outstanding action on the editor (me) to do this.

> Hope this helps.

Yes, very much.