[Oslc-Automation] Comments on current draft specification
Michael F Fiedler
fiedler at us.ibm.com
Tue Feb 7 14:15:46 EST 2012
I've made some updates to the Automation Specification thanks to some
comments. In particular please have a look at the Compliance table [1]
and the HTTP method support table [2].
I've also started a new Issues page [3] which will become a part of the
workgroup meetings starting this week.
Additional comments on Charles's review are inline below.
[1] -
http://open-services.net/bin/view/Main/AutoSpecificationV1#Compliance
[2] -
http://open-services.net/bin/view/Main/AutoSpecificationV1#Automation_Service_Provider_HTTP
[3] - http://open-services.net/bin/view/Main/AutoSpecificationV1Issues
Regards,
Mike
Michael Fiedler
IBM Rational Software
fiedler at us.ibm.com
919-254-4170
Charles
Rankin/Austin/IBM
@IBMUS To
Sent by: oslc-automation at open-services.net,
oslc-automation-b cc
ounces at open-servi
ces.net Subject
[Oslc-Automation] Comments on
current draft specification
01/25/2012 05:12
PM
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
MF> Done
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
MF> I did an extensive rework of the Compliance table based on other
comments from John Arwe. Please take a look. There is a table now on the
Delegated UIs for each artifact as well at:
MF>
http://open-services.net/bin/view/Main/AutoSpecificationV1#Delegated_UIs
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.
MF> For 4-6, take a look at the new Compliance and HTTP support tables
referenced above.
7. Resource Formats->"When Automation Consumers request", the
statements around "xml" and "atom+xml" should be SHOULDs.
MF> Done
8. We SHOULD support Resource Paging. Insert after Error Responses
(as CM spec does)
MF> Done
9. AutomationPlan properties->dcterms:description indicates content
suitable for <div> and <span>. Should it just be <div>?
MF> Done
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.
MF> Added to issues page. There was some discussion on this in the last
meeting - still unclear if it is needed to satisfy the scenarios.
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".
MF> Added to the issues page - I've include a link to the CM spec's state
predicate properties definition.
12. AutomationRequest properties->oslc_auto:executesAutomationPlan,
I wonder if this shouldn't be zero-or-one, not exactly-one.
MF> Done for now and issue added. I could see creating a request and
later hooking it up to a specific plan instance.
13. AutomationResult properties, it seems like this should have
dcterms:creator and dcterms:contributor like the other resource types.
MF> Done - made them zero-or-one and zero-or-many respectively
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.
MF> Covered these ones in the same issue as #11
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.
MF> Added to issues. My opinion is every result should have an associated
plan. The plan may be deleted later, but can't see where results are
created in the absence of a plan.
MF> Agree on AutomationRequest due to its possibly transitory nature.
Fixed typo
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.
MF> Done
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.
MF> New HTTP support covers this. Added a reference to it.
18. Under Query Capabilities, I think we should put a SHOULD for
support of oslc:properties and oslc:prefix.
MF> Logged an issue for this based on your comment and John Arwe's.
Currently we are following QM and CM by making Query Capabilities and OSLC
Query Syntax MUSTs. Is that desirable? They are MAY in the core.
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.
MF> Updated this table - we can discuss if it makes sense. Opened an
issue for it.
Charles Rankin
Rational CTO Team -- Mobile Development Strategy
101/4L-002 T/L 966-2386_______________________________________________
Oslc-Automation mailing list
Oslc-Automation at open-services.net
http://open-services.net/mailman/listinfo/oslc-automation_open-services.net
More information about the Oslc-Automation
mailing list