Comments from Martin Nally, Rational CTO

(Responses from the RM workgroup are in italic.)

Overall looks like very nice work. You don't say anything about the mechanism for giving feedback. What do you want us to do? Lacking guidance, here is an email

A couple of small comments:
You already know that I think this proliferation of media types is a mistake. Just use "application/RDF+XML"
<img>I'm concerned that OSLC doesn't have a general story for versioning/evolvability. I don't deny that OSLC specs. are not following the accepted norms of REST API design. But, as I wrote in a comment on your blog, i don't see alternatives that OSLC is putting in place to deal with these issues. There is a "Versioning/Evolvability Architectural Topic on the Connections wiki - which would be a good place to discuss this further.</img>

Use of the RDF tag seems gratuitous in this example:
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:rdm="http://open-services.net/xmlns/rm/1.0/">
<rdm:Error>
<rdm:statusCode>404</rdm:statusCode>
<rdm:message>
A requirement with the given URI wasn't found on this server.
</rdm:message>
</rdm:Error>
</rdf:RDF>
why not just use:
<?xml version="1.0" encoding="UTF-8"?>
<rdm:Error xmlns:rdm="http://open-services.net/xmlns/rm/1.0/">
<rdm:statusCode>404</rdm:statusCode>
<rdm:message>
A requirement with the given URI wasn't found on this server.
</rdm:message>
</rdm:Error>
If the answer is that we do it this way to allow for multiple errors, then make the example show multiple errors
<img>This is a typo. Steve asked me to remove all RDF root tags and I missed this one.</img>

Another comment on the Error example. The message is in English. If the only intended reader of this text is the OSLC client programmer, this may be OK, but this assumption should be stated. If the audience could go beyond the OSLC programmer, then we need an internationalization strategy. I wonder if we should just remove the text?

<img>from the spec.: "[text] SHOULD be locale specific". This is presently the extent of OSLC globalization.</img>

Show a multi-values property case. In this example
<?xml version="1.0" encoding="UTF-8"?>
<oslc_rm:Requirement
...
<calm:implementedBy
rdf:resource="http://rtc.example.com/wi/242" />
<calm:validatedBy
rdf:resource="http://rqm.example.com/testcase/6524" />
</oslc_rm:Requirement>
it would be helpful to extend it to this:
<?xml version="1.0" encoding="UTF-8"?>
<oslc_rm:Requirement
...
<calm:implementedBy
rdf:resource="http://rtc.example.com/wi/242" />
<calm:validatedBy
rdf:resource="http://rqm.example.com/testcase/6524" />
<calm:validatedBy
rdf:resource="http://rqm.example.com/testcase/6525" />
</oslc_rm:Requirement>

<img>Good idea. I've updated the example as you suggest</img>

Where are the use-cases for requirements collections? When do I create one of these rather than just tag a bunch of requirements and then ask for the requirements so tagged? Why do I need a "requirements collection" rather than a more genenral "resource collection"?

<img>The supporting scenario is RmRequirementCompletedScenario. We make a distinction between the resource which is the requirement collection and the mechanism which causes that collection to be defined. If you like, we have a extensional definition, not an intensional one. So it could be that a provider uses tagging to mark out a collection, and it could be that some other mechanism is used. There are other scenarios that will cause us to talk about such mechanisms, I expect, and it may be that tagging will come out of this as a mechanism that we want to describe in our OSLC specifications.

The issue of a general collection of resources was also raised, but was deferred to post V1.0 timeframe since we didn't feel that we could sensibly generalize over a sample size of one. I think that across OSLC, there is scope for such generalization and we will get there in due course. The OSLC query recommendation in particular defines some collection-specific queries which RM would be able to adopt.

</img>

Does "Delegated Resource Selection" belong at the OSLC level rather than the RM level? Isn't this the same as or very similar to what CM does?

<img> There are several things that ought to be factored out ("Delegated Resource Selection", "Service Description", "globalization", "error handling", "response codes", "content negotiation" to name a few). OSLC should plan to get to some of these during 2010.

</img>

Best regards, Martin

Martin Nally, IBM Fellow
CTO and VP, IBM Rational
tel: (949)544-4691

=========================================

Comments from Steve Speicher (OSLC CM lead)

Ian,

Sorry that these haven't come sooner but was reading over some of RM specs and had a few comments. Let me know if you want me to put them somewhere else

In http://open-services.net/bin/view/Main/RmRequirementResourceDefinitionV1

In the table for resource requirements, there is a column titled "Required on Write". I assume this is meant to say "Required on Create" or "Required on POST" ? In reading the RmRestApiV1 I did not see correlation to these writable properties and resource creation.

img: Thanks Steve - I agreed that this was not clear. I've updated the RmRestAPIV1? page (section "Required and read-only properties) to define that read means GET/HEAD and that write means PUT/POST.

In the section "Links" it says "A link from a requirement is represented by a URI-valued property (an RDF URI Reference) ". When reading this I would expect the elements to look as:
<calm:implementedBy>rdf:resource="http://rtc.example.com/wi/242"</calm:implementedBy>
Perhaps the wording should say that it a link is represented by the @rdf:resource attribute on a element property.

img: Reworded to this effect.

---------------

Also in the section "Links" it states "Such properties MAY be multi-valued."
though I can't find a definition or description of how multi-valued properties are represented.

General comment, I believe that this spec makes more sense in the context of the RmRestApiV1 spec. It might be worth indicating that in the beginning.

img: I'm not sure I understand this comment. My feeling is that the multi-valuedness of links is part of the resource definition, rather than the REST API - but I think it's a fine line. The REST API describes the verbs over representations of resources of defined content types (media-types), and the resource definition describes the shape of those representations.

SteveSpeicher my comments were directly referring to the resource definition spec RmRequirementResourceDefinitionV1 and not RmRestApiV1. It just seems that somewhere there should be a definition of what is meant by "multi-valued": sample, etc

IanGreen: Sorry for my misunderstanding. I've added some words, and pointed out an example.

---------------

Mismatch of Content Types:
I see "x-oslc--rm--requirement-1.0+xml " in http://open-services.net/bin/view/Main/RmRequirementResourceDefinitionV1
I see "application/x-oslc-rm-requirement-1.0+xml" in http://open-services.net/bin/view/Main/RmRestApiV1

img: thanks Steve. Now FIXED

SteveSpeicher media type in RmRequirementResourceDefinitionV1 is still wrong, it is missing the "application/" prefix

img: Sorry Steve. Now fixed.

===================================