[Oslc-Automation] review of actions 2.0 - Part II (4-6) : Typos, clarifications
Martin P Pain
martinpain at uk.ibm.com
Fri Aug 15 08:14:42 EDT 2014
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
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
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
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:
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
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,
Which leaves these which I won't raise unless anyone wants to push them
further: 4.1, 6.0
Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Oslc-Automation