On Mon, Mar 15, 2010 at 9:06 AM, Steve K Speicher <[email protected]> wrote: > (Ignore previous send, was in middle of drafting my comments and had email > issues)
Oops! I went through my inbox in the wrong order. I'll go through one-by-one and merge these into the issues page. Thanks, - Dave > 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 > _______________________________________________ > Oslc-Core mailing list > [email protected] > http://open-services.net/mailman/listinfo/oslc-core_open-services.net > >
