(Ignore previous send, was in middle of drafting my comments and had email issues)
These comments are on this document http://open-services.net/bin/view/Main/OSLCCoreSpecDRAFT 1) In "Design Considerations", I might add a few other points: - "simplest things that work" for key integration scenarios - "loosely coupled" - perhaps this is implied by "Build on the WWW", though a key point is to allow versions and implementations to evolve, while things "still work" 2) In "Glossary of terms" you reference the home page of w3.org, wouldn't it be more appropriate and helpful to reference directly the document that defines these terms? 3) In "Glossary of terms" there is a reference to "Application Lifecycle Management (ALM) product ", since we have a PLM-ALM topic, should we expand this to be something more open. A nit. 4) For "OSLC Query Resource" you mention "list of links", I assume this means "list of URIs"? Perhaps it should say this as links isn't in the glossary. 5) For "URI Query Parameters", this should also include "oslc.prefix" to allow for defining namespace prefixes 6) Terminology inconsistency, in "Resource Creation" you refer to "Creation Resource" instead of "OSLC Creation Resource". This occurs in a few other places. 7) In section "Unknown properties and content", it is unclear why a client MUST preserve all unknown content? What does preserve mean here? I think this is saying that OSLC Services are allowed to extend the resource definitions, providing properties from other namespaces, which the clients much not lose in transmission (updates) 8) In "OSLC Properties", I'm not sure I understand the need for "oslc:etag": is there some use cases that could be provided why this OSLC Property is needed? I have the use cases for the others already known but they are not explicitly stated. 8a) In "Resource Removal"....is service provider required to make this a hard or soft delete? A GET after a DELETE should result in what status code? Here's what we did for CM http://open-services.net/bin/view/Main/CmRestApiV1#Delete_a_change_request 8b) In "Dublin Core Properties", it should refer to which set of DC properties these are derived (namespace), namely: The Dublin Core Metadata Terms namespace - http://purl.org/dc/terms/ Also, why is dc:creator an "In-Line Resource" and not just resource link, of which it can be inlined? What is dc:contributor used for? Can you give an example of what it would be in the context of RTC Work Item attributes? According to DC, it says "An entity responsible for making contributions to the resource." so is it implied to be what we refer to as an Owner or Assigned To? 9) In "Service Resources", it would be good to have some additional information: - how service discovery works - nested service resources #Creation_Resources 10) In "Creation Resources", it would be useful to identify what HTTP status codes one would get back and why : missing required fields, etc....See http://open-services.net/bin/view/Main/CmRestApiV1#Create_a_new_change_request 11) In sub-section "unknown properties and conent", would it not be more appropriate for the service provider to reject the request if it receives unknown content. It seems odd that a client would be under the impression it is sending properties, server says it create resource and client can't locate those properties. I guess I don't understand what use case this is trying to solve, seems like it adds ambiguity to the service. #Query_Resources 12) General comment, not limited to Query's usage of dc:title, is representing alternative translations and how they'd be represented. For example, Accept-Language on requests and Content-Language on response. 13) I don't fully undertand what this looks like, like where are the resource links? Perhaps some examples in this section would help. 14) In section "Forming a Query Resource URI", it is not clear what the first paragraph is saying. I think some of what it is saying is what we put in the CM spec: If this parameter (oslc.query) is omitted, the server MAY respond with: * a page of results * reject the request with a HTTP response code of 403 Forbidden. * all results #Resource_Shape_Resources 15) For Property "oslc:preserveUnknown", is the default value "false"? Since it is "at-most-one", it implies its optional. 16) There is no definition of what "olsc:when" is used for. Likewise, it is unclear the purpose of "oslc:RdfTypeTest" 17) For "Resource: Property" there should be default values for some of these: oslc:readOnly, oslc:maxSize?, oslc:occurs #OSLC_Defined_Resource_Prepresentations 18) Read my lips, "No new content-types" (sorry chouldn't hold myself back)says: "those who are defining new OSLC Services are strongly discouraged from introducing new content-types. OSLC Services MUST not define new content-types. " This seems the say no and maybe. It seems hard to believe that we can predict that there will never be a case to add a new content type. Perhaps the rationale of no new content types should be given and how specs should follow that guidance. 19) In "JSON Representation", I think the first example doesn't have the multi-valued property as an array, it should be: { "qname" : "oslc_fm:FooReport", "uri" : "http://example.com/data/9D764F35AD1";, "dc:title": "Foo Report for development organization", "oslc_fm:measurement" : [ { "qname" : "oslc_fm:FooMeasurement", "dc:title" : "Foo Measurement for Accounting System UI Module", "oslc_fm:Index" : "34.55" }, { "qname" : "oslc_fm:FooMeasurement", "dc:title" : "Foo Measurement for Accounting System POS Module", "oslc_fm:Index" : "28.41" }, { "qname" : "oslc_fm:FooMeasurement", "dc:title" : "Foo Measurement for Accounting System AX5 Module", "oslc_fm:Index" : "30.08" } ] } 20) For "OSLC Form Based Authentication" I know this is a problem, but it seems to me to be a stretch to be able to solve this in the first core spec. Perhaps something could be done via service discovery. Misc comments 21) It would be good to clarify the usage of HTTP status codes: success or error code handling: when 400 vs 404 vs 409. This were useful in the definition of CM 1.0 spec. 22) Resource modifications and etag handling, it would be good to clarify usage of etag, 412 status codes and If-Match header: See http://open-services.net/bin/view/Main/CmRestApiV1#Update_a_change_request 23) lack of error message formats. A problem we found is that often clients would make a request for a JSON resource and get an error message in XML. It would be ideal to define a way that JSON errors be returned. Also, that there is a basic format for these error messages. See http://open-services.net/bin/view/Main/CmRestApiV1?sortcol=table;table=up#Error_Status_Information Thanks, Steve Speicher | IBM Rational Software | (919) 254-0645
