[Oslc-Automation] Actions: Top-to-bottom read: Feedback

[Martin P Pain]

I did a top-to-bottom read of the Actinos spec to review the recent 
changes. Most of those changes were ok (including the "no cherry picking"! 
change, apart from one minor omission that has already been covered).

Mostly minor changes, including grammatical ones. So I'm hoping that 
(apart from #7 and #10, and maybe #5) someone can just give a "+1" to the 
list as a whole.

Terminology -> Action. Replace "its" with "the term's" to make "Although 
the term's use in this specification is primarily to actions available 
when the response is formed, that limit does not come from this 
definition."
Terminology -> Action. "Actions could be re-used describe other varieties, 
like past, future, or potential actions;" should probably start either "
Action resources can be used to describe other varieties, like past, 
future, or potential actions" or "The term "action" can also be used to 
refer to other varieties...". I propose the first of these two 
suggestions. (Although this is slightly inconsistent with my suggested 
change to the previous sentence, but I don't think it matters.)
Terminology -> Spec profile: "An actions specification profile includes 
one or more interaction patterns for which Actions governed by that 
profile must provide Action bindings." I propose replace "Actions 
governed" with "Action resources governed" to make "An actions 
specification profile includes one or more interaction patterns for which 
Action resources governed by that profile must provide Action bindings.".
Terminology -> provider: Insert "that serves" before "action bindings" to 
make "any OSLC implementation that serves resources of type oslc:Action or 
that serves action bindings"
Overview -> What are actions?: "Each action provides a few primary pieces 
of information described in the normative specification sections: “what 
does this action do?”, “how do I execute this action?”, and “how do I 
determine if the action succeeded or failed?”." I suggest "Each action 
provides a few primary pieces of information: “what does this action do?”, 
“how do I execute this action?”, and “how do I determine if the action 
succeeded or failed?”. These are described in the _normative specification 
sections_ below." Currently at first glance it looks like it's listing 
section names, so it looks like they could be links. So I suggest we move 
out the reference to "sections" after the list (and we might as well make 
it a link to the header at the start of the normative part of the spec).
Overview -> What do consumers needs to know? -> 2nd list: Change "how to 
determine the success/failure of its request to execute the action" to "
how to determine the success/failure of its request to execute the action 
(as defined by this specification)" to match the previous bullet points
Overview -> Domain-specific consumers: I think the fix we put in for one 
of Ian's comments has made it worse. I suggest we change "For each 
interaction pattern that is supported by the consumer (the interaction 
patterns supported by the consumer, along with any restrictions, if any, 
defined by the profile(s) they were implemented against):" to "For each 
interaction pattern that is supported by the consumer (which must include, 
at a minimum, the interaction patterns required by the chosen profile)" or 
we could just remove the section in brackets altogether.
Interaction patterns -> final execution status: Change "Actions defines a 
predicate oslc:finalStatusLocation..." to "The Actions vocabulary defines 
a predicate oslc:finalStatusLocation..."
Pattern: HTTP request with fixed body -> execution: The note at the end of 
this section should be formatted in the same was as other non-normative 
notes.
Pattern: Automation Request -> Pattern recognition rule: Non-normative 
note formatting.
Pattern: Automation Request -> Exection. I believe this is wrong: "When 
executing an action binding according to this interaction pattern, a 
consumer follows the execution instructions of the HTTP request with fixed 
body interaction pattern, with the exception that they may construct the 
HTTP body by merely serialising the Automation Request that has been 
provided (as is described by the HTTP request with fixed body interaction 
pattern), or..." as we now link to the AutomationRequest resource 
directly, rather than providing it as a "fixed body" template. However, we 
still ought to avoid duplication, so I suggest we change it to: "When 
executing an action binding according to this interaction pattern, a 
consumer follows the execution instructions of the HTTP request with fixed 
body interaction pattern, with the exception that the consumer constructs 
the HTTP body content from the Automation Request. The consumer may 
construct this body content by merely serialising the Automation Request 
that has been provided, or they may alter that Automation Request to 
provide additional or different parameter values if they understand the 
parameters that the linked Automation Plan takes, or they may find another 
way to construct an Automation Request for that Automation Plan (e.g. by 
using a stored Automation Request created earlier, or by finding a 
deferred-execution creation dialog to create the Automation Request)."
Resources -> Action -> oslc:binding: Value-type should be AnyResuorce, as 
I believe we allow blank nodes as bindings (I believe the examples use 
blank nodes).
Resources -> Common Property: oslc:action: Value-type = AnyResource
Same for Resources -> HTTPRequest -> http:body
Appendix C - I believe we can remove this.

Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 
741598. 
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU

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