[Oslc-Automation] review of actions 2.0 - Part II (4-6) : Typos, clarifications

[Martin P Pain]

Section 4: "Types of actions" section

4.1 OSLC workgroup operation details in spec

Covered in previous comment.

4.2 subClassOf for action sub-types

subClassOf is used to describe the semantic relationship between the 
classes, however I guess that doesn't really buy us anything. Yes, we 
should require that both types are specified explicitly - we already do: " 
Since informal OSLC Core guidance states that providers cannot depend upon 
client-side inferencing, action representations are multi-typed: they MUST 
contain oslc:Action as one type, and MAY (usually do, in practice) contain 
additional types that convey more specific semantics necessary for 
programmatic consumption."

I might consider qualifying that by saying "If consumers do not need 
knowledge specific to that action type then action representations MUST be 
multi-types: they MUST...". (IIRC, there was discussion that OSLC CM's use 
of actions might define a sub-type that identified an action as being a 
simple, empty POST on the action's own URI - where clients could either 
hard-code knowledge of that type [which would be defined in the CM spec - 
for simple consumers] or use inferencing [for advanced consumers only] to 
determine some of the values that are "Exactly-one" in this spec, so the 
provider doesn't have to explicitly specify them. It might be unhelpful to 
multi-type in those circumstances as a generic non-inferencing consumer 
would not be able to find the request URI ) But I don't think there would 
be any incompatibility caused by us weakening this restriction in future, 
so we should probably keep it as strict as it is. (And encourage 
specs/providers not to try & prematurely optimise in terms of number of 
triples.)

Section 5: "Instructions for executing" section

5.1 Zero bindings & "resource shape"/table

"Resource shape" is being used to refer to the resource table for 
oslc:Action. We could say "resource table" or "resource definition" 
instead, or just say "this specification allows...". (The table says 
oslc:binding occurs Zero-or-many - but the "instructions for executing" 
says "one or more bindings". The final clause is saying that the table 
allows for zero oslc:binding properties for cases outside of "currently 
available" actions (there's that phrase again).)

Section 6: "Interaction patterns" section

6.0 All-caps section titles

The h4-level & h5-level section titles are all-caps. (Presumably as they 
are the same font size as the paragraph text). It's part of the wiki 
stylesheets. This is the first occurrence of any heading that deep.

6.1 Title "interaction patterns' final status" -> just "final status"

I'd probably go for "Final status of execution" to make it clearer in the 
TOC.

6.2 finalStatusLocation values - wording.

I'm happy with your suggested re-wording.

6.3 "patterns' recognition rules" apostraphe.

It was intended to be plural, but the singular would work fine. So that 
would be "the pattern's recognition rule".

Additional comment: As we've ruled out cherry-picking values from 
http:Request resources - and having one resource per permutation/possible 
request - should we do the same for other bindings' resources? The comment 
in the spec here says "For example, a binding using the Automation Request 
pattern could have both oslc-automation:AutomationRequest and 
http:StatusCode as its oslc:finalStatusLocation values if the provider 
always performs synchronous execution of the Automation Request and sets 
the response’s status code to match the Automation Result’s verdict." - 
although this is not cherry-picking, but it is allowing multiple patterns 
for a single binding. It's not saying "you can choose which one sets the 
result" it's saying "they both reflect the result"... although the 
consumer still has to check which one to use to discover the result - but 
as they are specified in the recognition rules and the consumer has 
already chosen a pattern, hopefully that choice has been made for them.

6.4 oslc:ActionDialog initial capital when not a class

Somewhere I had read that "individuals" should use an initial capital, 
only properties/predicates have a lower-case initial letter. Googling for 
that now, all I can come up with is page 18 of this OWL/Protégé PDF here: 
http://deim.urv.cat/~itaka/CMS/images/pdf/session2%263.pdf
However, I might have assumed that everything that isn't a class or a 
property is an individual. Even if that convention for individuals' names 
is correct, that assumption that all terms are classes, properties or 
individuals might be wrong. I think it's jazz.net vocabs that call 
everything else "individuals", e.g: 
https://jazz.net/wiki/bin/view/LinkedData/RtcpVocabulary (the capital 
letter in the one term in that document reflects my understanding at the 
point at which I created it).

Does anyone know if OSLC has a stated/linked set of conventions we follow? 
(I know our existing usage is inconsistent - Automation's state & verdict 
properties are lower-case, but the resource table's "occurs" values have 
capital initial letters.) 

6.5 Substitute the word "target" (of a property) with "object"

I think we went for "target" as it is easier to infer (for someone new to 
RDF) what it means, whereas "object" has multiple meanings. However, 
"object" is the technically-correct word (and in this case probably isn't 
ambiguous anyway given its immediate context), so I'm happy to change 
that.

6.6 "oslc-automation:canceled means that the dialog was cancelled, whether 
or not it was attempted"

The dialog displays and gives the user the option to start the automation, 
"and SHOULD be displayed until the action is completed or canceled". It 
may give the option to cancel both before the automation has started & 
while the automation is running. oslc-automation:canceled is used for 
either of those cases. We can clarify the wording by replacing "it" with 
"the automation" or similar.

Yes, we can add a note. Such as:
"Non-normative note: The dialog displays and gives the user the option to 
start the automation, and should be displayed until the action is 
completed or canceled. It may give the option to cancel both before the 
automation has started & while the automation is running. 
oslc-automation:canceled is used for either of those cases."



I'm happy to accept: 6.1, 6.2, 6.3, 6.5, 6.6
I'll additionally raise for discussion: 4.2, 5.1, my comment after 6.3, 
6.4
Which leaves these which I won't raise unless anyone wants to push them 
further: 4.1, 6.0


Martin

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/20140815/2644ff6f/attachment-0003.html>