[oslc-core] Comments on OSLCCoreSpecDRAFT (resend)

[Steve K Speicher]

(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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://open-services.net/pipermail/oslc-core_open-services.net/attachments/20100315/ca2a6eea/attachment-0003.html>