[oslc-core] Comments on OSLCCoreSpecDRAFT (resend)
Dave
snoopdave at gmail.com
Tue Mar 16 15:14:09 EDT 2010
On Mon, Mar 15, 2010 at 9:06 AM, Steve K Speicher <sspeiche at us.ibm.com> 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
> Oslc-Core at open-services.net
> http://open-services.net/mailman/listinfo/oslc-core_open-services.net
>
>
More information about the Oslc-Core
mailing list