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
