[Oslc-Automation] Comments on current draft specification

[Charles Rankin]

Here are my comments on the current draft.  The first two are just 
general, and the remainder are more or less in-order as I read the spec.

1.      I'm not commenting on parameters, as I know there are going to be 
some updates there based on recent meetings and mailing list traffic.
2.      We should have a bit of text at the definition of each resource 
type to describe when/how/why it is used.  At a minimum, we could repeat 
the blurbs listed under Introduction->Terminology
3.      Base Requirements -> Compliance, I think we should make it a MUST 
for creation of Automation Requests, and a MAY for the others.  For 
Delegated UIs, I think it should be a MUST/MAY or a SHOULD/MAY with the 
MUST (or SHOULD) being for Automation Request and the MAY for the other 
resource types
4.      Resource Formats->HTTP GET->1st bullet, the comment about XML 
following the MUST of RDF/XML feels out of context, as it (I think) is 
actually talking about if the consumer requests XML, not RDF/XML.  Not 
sure about the rewording, maybe 'If an XML representation is requested, it 
SHOULD …".  And/or pull that part out into a separate bullet.
5.      Resource Formats->HTTP PUT/POST, since we earlier state you MAY 
support JSON, it should be mentioned here as well.  I *think* the 
statement that the CM spec uses is accurate for us.
6.      Resource Foramts->HTTP GET, JSON should be in the list of MAYs.
7.      Resource Formats->"When Automation Consumers request", the 
statements around "xml" and "atom+xml" should be SHOULDs.
8.      We SHOULD support Resource Paging.  Insert after Error Responses 
(as CM spec does)
9.      AutomationPlan properties->dcterms:description indicates content 
suitable for <div> and <span>.  Should it just be <div>?
10.     AutomationPlan properties->oslc_auto:automationInstructions, I may 
have missed the meeting where this was discussed, but I have no idea what 
I would expect on the other side of this.  I suggest that we don't include 
this property for v1.
11.     AutomationRequest properties->oslc_auto:status and 
oslc_auto:desiredStatus, should we provide a non-exhaustive enumeration of 
values for these?  My feeling is "Yes".
12.     AutomationRequest properties->oslc_auto:executesAutomationPlan, I 
wonder if this shouldn't be zero-or-one, not exactly-one.
13.     AutomationResult properties, it seems like this should have 
dcterms:creator and dcterms:contributor like the other resource types.
14.     AutomationResult properties->oslc_auto:verdict and 
oslc_auto:status, similar to AutomationRequest->oslc_auto:status, I think 
we should consider providing an open-ended enumerations for these.
15.     AutomationResult properties->oslc_auto:producedByAutomationRequest 
and oslc_auto:reportsOnAutomationPlan (no 't'), I think we should consider 
changing these from exactly-one to zero-or-one.
16.     On Resource Shapes, I'm not sure we need to say anything beyond 
what the core spec says.  If we have to have this here, I would suggest we 
drop from SHOULD to MAY on the need for Resource Shapes.
17.     Under Creation Factories, I think we should provide some 
specificity about creating resources.  I'd say MUST support creating 
AutomationRequests and MAY support the creation of all other types.
18.     Under Query Capabilities, I think we should put a SHOULD for 
support of oslc:properties and oslc:prefix.  
19.     Under Delegated UIs, I think we should remove the rows for 
AutomationEnvironment and ResultContribution.  Also, I think selection of 
AutomationRequest should be changed to a MAY, as not all of them may be 
able to support these in a way that makes selection feasible.

Charles Rankin
Rational CTO Team -- Mobile Development Strategy
101/4L-002 T/L 966-2386

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20120125/e759822e/attachment-0003.html>