[oslc-cm] V2 specs comments [long]

[Olivier Berger]

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 ?
        
        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.

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).

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

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

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

* 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 ?)

* 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 ?

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

* 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.

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

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

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

* 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.

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

* 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.

* 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 ?)

* 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) ?

* 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)

* 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 ?)

* 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)

* oslc:discussion : Resource -> Resource or Local Inline 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)) ?

* 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).

* 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 ?

* 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 ;-)

* 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)

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

* Creation factories : "Services definition." -> "Service Provider's
Resource definition." ?

* Query Capabilities : fixed "creation" -> "querying" in the wiki

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

* Samples : may need update (TODO to be added ?)

Hope this helps.

Best regards,

-- 
Olivier BERGER <olivier.berger at it-sudparis.eu>
http://www-public.it-sudparis.eu/~berger_o/ - OpenPGP-Id: 2048R/5819D7E8
Ingénieur Recherche - Dept INF
Institut TELECOM, SudParis (http://www.it-sudparis.eu/), Evry (France)