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 <[email protected]> wrote on 05/27/2010 09:15:48 AM: > From: Olivier Berger <[email protected]> > To: "[email protected]" <[email protected]> > Date: 05/27/2010 09:16 AM > Subject: [oslc-cm] V2 specs comments [long] > Sent by: [email protected] > > 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.
