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 <[email protected]> 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)
