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

[Martin P Pain]

Section 7: "Resources" section

7.1 Titles for bindings

The consumer doesn't give the choice of bindings to the user. Or, if it 
does, I would expect it to use the name of the Interaction Pattern (e.g. 
"Dialog" for any bindings using the "Delegated UI Dialog" interaction 
pattern) together with the name of the Action.

We can add text to clarify that, if other members of the group agree.


7.2 OSLC Workgroup operation

Same as earlier comment.


7.3 Red text in "Request" resource section about "http in RDF" vocab.

We should move the red text into the "description" column of the 
"requestUri" property (editing it to reflect just the change of value-type 
from string to Resource).

The value of this change is allowing URIs relative to the containing 
document's base URI (e.g. In Turtle, using "<>" to refer to the base URI 
itself, if the binding is to send a request to URI of the Action itself 
[and if the document/representation served from the URI of the Action]). 
This might be premature optimisation, so I'm happy to raise this in the 
next meeting.


7.4 "results" resource table,oslc:label mention of action dialog

The Action Dialog interaction pattern: 
http://open-services.net/wiki/core/Exposing-arbitrary-actions-on-RDF-resources/#pattern-immed-dialog
is the only place in this spec that we use that table. So it's technically 
correct, although it might be better to be more general and just say 
"Short label describing the result (verdict)" or "...of the action".


7.5 ParameterInstance rdf:value property literal values

The http:headers property should specify the Content-Type. We should state 
that.

Having said that, the recognition rule for the "HTTP request with fixed 
body" pattern says the ParameterInstance "MUST have exactly one rdf:value 
property that links to the resource that is to be serialised". We should 
clarify whether that restricts it to being a resource (in which case we 
should also change the resource table for ParameterInstance in the form 
it's used in this spec), or change that sentence to allow literals.


Section 8: "Specification Profiles" section

8.1 Distinct actions for each profile

No, the providers would use multiple bindings on a single action to 
support multiple profiles simultaneously.

I would expect all actions offered by a provider to adhere to the profile 
(however, the definition of "provider" might be loose enough for the 
provider to claim that it is really two providers, one of which adheres to 
the profile and the other doesn't - I don't think we explicitly link the 
term "provider" to the oslc:ServiceProvider resource).

In any case, that sentence you quoted Ian is saying that for an Action 
binding to meet the constraints of its profile it MUST use one of those 
interaction patterns. (We can reword it to be in that order if that is 
clearer).

The restriction on providers is further up:
http://open-services.net/wiki/core/Exposing-arbitrary-actions-on-RDF-resources/#Using-specification-profiles
"To “comply with” a profile a provider MUST, for each Action resource 
created by that provider, provide at least one Action binding that meets 
the constraints of that profile - as well as meeting any other 
requirements imposed on a provider by that profile."

So if a provider says (in its docs, for example) "this product complies 
with the OSLC Actions profile X" then it means ALL their actions meet the 
constraints of the profile. But they can always say something like "all 
our start and stop actions meet the constraints of OSLC Actions profile X, 
but other actions may not".

Feel free to suggest ways that could be clarified - either by changing the 
wording, or by changing what we require of providers.


8.2 Identifiers for spec profiles

Any suggestions? "self-post-resource-shape-profile" & 
"automation-request-profile"?


Section 9: "Appendix A"

9.1 Dealing with multi-valued properties.

We dealt with this in the last call, saying that each http:Request object 
must only describe one possibly request, not giving the client options.
We may need to update the examples to reflect this.


9.2 Which Content-type to use

Content-Type is a header, so it would be specified by the http:headers 
property. But we could make that explicit, yes.


9.3 "speci
fies the http:requestURI value as a URI, NOT a literal"

This is intended to be a re-statement of what the table in the "Resource: 
Request" states. We can make that explicit.
(And we ought to move the red text from below that table - in some form - 
into a note or requirement in the "description" of the http:requestURI 
property in that table, so we have something specific to refer to. - The 
purpose of allowing/requiring a URI there is to allow URIs that are 
relative to the base URI of the document - i.e. "<>" in Turtle - as one of 
the major use cases was for actions whose own URI was the one to use for 
the HTTP request.)


9.4 Standard restrictions for simple profiles

I have no objection to a simple identifier, but cannot think of a good 
one. What sort of format were you thinking of? 
"standard-restrictions-for-simple-profiles"?

The intention was that "1.1" would be one of the values, not the only one 
(to allow 2.0 to be supported in parallel - by the same bindings if all 
else is equal).





I'll raise for discussion: 7.1, 7.3, (7.4), 7.5, 8.1, 8.2, 9.3, 9.4
I won't raise for discussion unless someone explicitly asks to discuss it: 
7.2, 9.1, 9.2


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/20140819/7a1e3255/attachment-0003.html>