[Oslc-Automation] Availability Spec review - my feedback

[Martin P Pain]

Here is my feedback on the original OSLC Availablility draft spec pdf (
http://open-services.net/wiki/automation/Availability-Specification/)

Key to my feedback notations:
* - A minor point, indicated by a leading hyphen/minus sign. (In grey in 
the original HTML email)
* . A medium-level point, indicated by a leading period/dot.
* + An important point, indicated by a leading plus sign.
* . "In quotes, -deleted- words are in red strikethrough with a hyphen 
either side , _inserted_ words are in green underline, with an underscore 
either side (in the original HTML email - which I believe you can find in 
a link in the archives)."


Here is my feedback. I suggest discussing this via e-mail, as getting as 
many point as possible sorted via e-mail should be more efficient than on 
the call. Anything contentious or that requires in-depth discussion can be 
discussed at the meeting next week. There are lots here, including many 
minor ones. Hopefully they're useful. Feel free to question anything 
(anyone). There are a couple of questions aimed at John Arwe for 
clarification - these are makred with "John" in bold.

Editorial comments:
* - The wiki page doesn't need to be "workgroup only".

Introduction:
* - Would this be better to extend Automation, to make best re-use of 
Automation's plans?
* - To be able to describe a system that is (highly) available

Terminology:
* - "Availability condition" - to me, "condition" suggests "requirement" 
(e.g. boolean expression, if-statement). However, on Googling it, the 
sense of "state, situation" does come out as the primary definition, so I 
won't make a fuss. "State"/"Status" would also have its problems (sense of 
state-machine versus wider condition). I've just mentioned it to make sure 
you've thought about the possible ambiguity when looking at the term 
"availability condition" when not next to its definition as it is in this 
section.
* - "Recommended as a specialization of an Availability Group." (also for 
"...of an Availability Resource")

Compliance:
* . Footnote 4: "3Support for all HTTP methods for all -automation-
_availability_ resources is not required "

Namespaces:
* - I expect John would suggest "oslc-availability" for the standard 
prefix, but oslc_avail is more consistent with Automation 2. I don't mind 
either way.
* . I would suggest something longer in the namespace URI though, perhaps: 
http://open-services.net/ns/availability# I know other specs used very 
short forms, but that caused problems with "Configuration management" 
versus "change management", and I believe the more recent convention is to 
use a longer string in the URI. Consistency here isn't important, as the 
URI is repeated less than the prefix.

Availability definitions:
* - "It is recommended that any additional properties exist in their own 
unique namespace and not use the namespaces defined in this specification.
" - I expect this was copied from Automation, but this could be a stronger 
requirement. It would be bad practice to define properties in the 
namespaces defined in this specification without the agreement of the 
working group or technical committee responsible for maintaining the 
namespace. (A few paragraphs down we make it a SHOULD - I guess that's the 
same as "recommended" in prose).
* + The arrow and name of the relationship between Group and Availability 
Resource (AR) appear to disagree with each other. Either the group is 
pointing to a resource as a "member", or the resource should be pointing 
to the group(s) it is a "memberOf". In the resource tables it suggests 
that the link is pointing from the AR to the Group.
* . When I first looked at this diagram I wasn't convinced about 
Availability Condition (AC) being a separate resource. Having read later 
it looks like there can be multiple ACs for an AR, each as a snapshot at a 
given timestamp (dcterms:created). Is that the intention? If not, what was 
the reasoning behind them being different resources?
* . I'm not sure dcterms:contributor is the best relation to use for the 
link to resources that the AR is affected by. dcterms deifne its raneg as 
Agent, which is "A resource that acts or has the power to act. ". Is it 
your intention to link to resources that can act on on the AR? As opposed 
to ones that the AR acts on? (Or can affect the AR's state not by acting 
on it, but merely by changing its own state). The definition in the 
resource table further down suggests the usage is correct - the target of 
the link is actively acting on the AR. This isn't clear in the diagram 
whether the contributor is affecting the AR actively, or merely its state 
is reflected in the AR.

Resource: AR
* - dcterms:description "Descriptive text (reference: Dublin Core) about 
_the_ resource"
* + Availability-specific properties: Please create a vocab document (or a 
wiki page to use as a draft) to define each of these terms outside the 
conext of these particular resource tables. This helps create vocabularies 
with more value and reusability, and also helps discover any ways in which 
the terms can be improved even inside the scope of the resource tables.
* + oslc_avail:actualCondition: You have read-only set to true. I expect 
this is consistent with some other specs, but it's worth considering that 
in some scenarios (although admittedly not within our defined scope) might 
have the resources stored in a separate repository from the actor who 
determines their contents. In that case, they need to be updatable.
John: What does "read-only" technically mean here? The most important 
question here for this version is: would changing the read-only flag for a 
property in a subsequent version cause any problems? And is a provider 
non-compliant if they allow it to be written? If not, I'm happy to leave 
it, as it can always be changed if anyone raises a scenario for those 
cases.
* + oslc_avail:memberOf. Is there a particular reason why the link is 
pointing in this direction, and not from the group to the members? It 
would seem to me that you might more often want to find all members for a 
group (part of the scenario "Obtain redundancy information for workloads" 
- even if you do have to start at an AR). If we require looking up of 
reverse links, we ought to specify exactly how this is expected to be 
achieved. I know it's possible with query capabilities, but we ought to 
clearly spell out how, to make implementors lives easier. (Whichever 
direction the link goes in we might have to do reverse link lookups, but 
if the link pointed in the other direction it would only have to be one, 
rather than all but one of the group's members. But then again you have to 
do the lookup to find out if it's in a group. Perhaps that was your 
reasoning, if so you've probably got the link in the correct direction.)
* + oslc_avail:memberOf: Say in the description "It is expect that the 
target of this link will be of type Availability Group (or its sub-type 
Redundancy Group), but this is not necessarily the case".

Resource: AC
* + compoundState. Mention and link to the predefined values in the 
description. Can providers provide their own values? If they can, there 
may be a better alternative: The Change Management specs found that for 
their states it was useful to add in "state predicates" [1]. These are 
single-value properties that indicate some semantics of the resource's 
current state.e .g. oslc_cm:closed=[true|false] [2]. So in this case we 
could define this as oslc_avail:consistentState=[true|false]. If it is 
true, you can read either and get the actual state knowing it is also the 
desired state. If it's false you can read whichever one you need knowing 
that actual & desired are not consistent. (Is this explicitly mentioned in 
a scenario? Whenever someone asks about the reasoning behind something, as 
I'm doing here, it would be useful to add a note to any applicable 
scenario(s)' wiki pages about that reasoning and how it supports that 
scenario. [Although I admit I haven't done this in my work on the Actions 
spec.]) See comment below in "Predefined properties" section about 
warning/problem distinction. (If we still want that distinction, but also 
wanted to use state predicates, we could have a second one for the 
"problem" state... maybe).
* + desiredState & currentState. Mention and link to the predefined values 
in the description. Say whether provider-specific values are allowed.
* - If provider-specific state values are allowed (which might be a good 
idea to support extensibility) then we might want to consider state 
predicates for online, offline, stopping and starting. On the one hand 
this isn't required by the existing scenarios, but on the other hand it 
provides most flexibility going forwards.
* + mttf & mttr: What type of resource? Options probably include: using an 
integer, not resource, and specifying units in spec. Or using (hopefully 
re-using) some existing time-period resource that can specify its own 
units.

Resource: Availability Group
* + dcterms:created -remove "The point in time this condition has 
occurred."
* + dcterms:modified: Do we want to make it explicit that new members 
added to the group update this? (As they don't add any new triples to this 
group resource, so it may not by default.) What about changes to resources 
- I guess they don't update this timestamp - do we want to make that 
explicit?
* + AEC: Does the HRG AEC have an RDF vocab/representation? If so, can we 
link to it? If not, how is this represented?
* . currentlyActive: This predicate name doesn't indicate "count". I'd 
prefer something like "currentlyActiveCount" or "numberActive" or (to find 
a verb form) "hasActiveMembers" (note the trailing "s" - if it were 
linking to a currently active member, it would not have an "s", so this 
"S" could [very] subtly suggest that it is a count. But I don't like this 
one much, due to that being very subtle.)
* + John: Can range be used like this?
* + SLA: Mention and link to the predefined values in the description. Say 
whether provider-specific values are allowed.

Resource: Redundancy Group
* + Should this be an rdfs:subClassOf Availability Group. i.e. why is it 
"often" an AG, not always? (Admittedly, I think we can always add 
subClassOf in future, but removing it would be harder).
* . "maxActiveTarget", "minActiveTarget". Who is this a target for? Is 
this what the provider is trying to achieve, or could this be instructions 
to a consumer to start/stop members to meet this target? Could it be 
either, or do we want to specify one?
* . "redundancyCapability: Description: Starting with "Information 
about..." makes it sound, to me, like it's going to be a resource. Perhaps 
"An indication of level of redundancy provided by this group." might be 
more fitting for an integer value.
* + synchronizationType: Mention and link to the predefined values in the 
description. Say whether provider-specific values are allowed.

Resource: Redundancy Member
* + Again, same question about subClassOf.
* + redundancyRole: Mention and link to the predefined values in the 
description. Say whether provider-specific values are allowed.

Sub-domains:
* + No subdomains are explicitly defined.
* + If we only want vendor-specific sub-domains, should we specify an 
rdf:Class to use as the rdf:type value of the resource at the target of 
the sub-domains identifier URI, so generic consumers can identify which 
URIs identify Availability sub-domains? (i.e. This would be used in the 
vocab documents that define those sub-domain URIs).
* + In the example, a value is used for "System Automation for z/OS" 
sub-domain. (1) This value isn't defined in this spec (at least not that 
I've seen so far) so shouldn't use this spec's namespace. An example.com 
namespace would be appropriate for an example value. (2) If we want to use 
this value in IBM implementations (I presume we do) then it's still in the 
wrong namespace. It's a vendor-specific term, so I'd suggest it would be 
better in an ibm.com or jazz.net namespace (the latter is Rational-owned, 
but has an existing process for publishing public RDF vocab documents, so 
might be the path of least resistance). As far as the WG should be 
concerned: it's a vendor-specific term, discuss it inside the vendor. 
(Well, that's my opinion). We can always provide a list of links to known 
vendor-specific terms in an informative section of the spec.
* + "Depending on the sub-domain, an OSLC client can expect predefined 
values for the following attributes". Without defining any specific 
sub-domains, I'm not sure this communicates much information. Do you mean 
"Sub-domains may specify what sub-set of these predicates they use"? Or 
maybe "Sub-domains may specify which values they support for each of these 
properties"?

Creation Factories/Query Capabilities:
* - "at least one Creation Factor_y_-ies- entry" (perhaps use the 
qualified name for the type or predicate)
* - "at least one Query Capabilit_y_-ies- entry" (ditto)
* + "SHOULD support the oslc.properties syntax " SHOULD should be bold.

Delegated UIs:
* + RedundancyMember is missing from table
* . I'd suggest "SHOULD" for AR, AG, RG and RM selection dialogs, as I 
expect UI-based clients will really want to use these. Creation dialogs 
might not be appropriate for all providers, so MAY seems appropriate for 
them.

Predefined properties:
* + These are individuals (values), not properties.The sub-headings are 
ok, as they are the properties that the values are for, but the to-level 
"Predefined properties" heading seems wrong to me.
* + I know Automation uses a lower-case initial letter for its states, but 
I believe the current convention for these sorts of URIs ("individuals") 
is to use an initial capital. e.g. 
http://open-services.net/ns/availability#Offline.
* . These URIs will point to resources defined in the Availability vocab 
document. Should they have a particular rdf:Class for their rdf:type 
property, to identify what they are values of/for?
* . Some of these values might be appropriate for contribution to the 
Common IT Resource Vocabulary: 
http://open-services.net/wiki/reconciliation/Common-IT-Resource-Type-Vocabulary-Version-2.0/ 
(On the other hand, as all of the properties and values in this spec 
relate to resources, and specifically to their availability, perhaps we 
should keep them in a separate Availability namespace, but have that 
linked from the Common IT Resource Vocabulary, sort of as a 
sub-vocabulary.)
* . compountState: Does "warning" mean "currentState does not match 
desiredState, but may do at some time in the [near] future" and "problem" 
mean "they do not match, and the attempt to move to the desired state 
failed and cannot be [automatically] retried"? The description for 
"problem" suggests that, but what warning says - "the availablity resource 
is still usable" - seems to me to be orthogonal to whether or not it meets 
its desired state. It's usable if the currentState is "online", and not 
usable if it's any other state, right? I'd suggest letting compoundState 
just say whether or not the currentState matches the desiredState 
(yes/ok/match, or no/doesn't match. possibly with a "may match soon"/"in 
progress" option), and currentState say whether or not the resource is 
usable or not. Perhaps this was your intention, in which case I think the 
"warning" value needs a better description- and perhaps renaming to 
"InProgress" or "Changing".
* . Service Level Properties: Are these properties or values? If values 
how do these relate to the predicates of the same name?
* . redundancyRole: If there is only ever one master, would it be better 
for this to be a property on the redundancy Group pointing to the master?

HTTP method support:
* + Availability Component = Availablility Resource? Or = {AR, AG, RG, 
RM}?


[1] 
http://open-services.net/bin/view/Main/CmSpecificationV2?sortcol=table;up=#State_Predicates
[2] Approx 2 pages down from: 
http://open-services.net/bin/view/Main/CmSpecificationV2?sortcol=table;up=#Resource_ChangeRequest


Martin Pain
Software Developer - Green Hat
Rational Test Virtualization Server, Rational Test Control Panel
OASIS Open Services for Lifecycle Collaboration - Automation technical 
committee chair

E-mail: martinpain at uk.ibm.com
Find me on:  and within IBM on:  




IBM United Kingdom Limited
Registered in England and Wales with number 741598
Registered office: PO Box 41, North Harbour, Portsmouth, Hants. PO6 3AU
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/20140508/65a23cb7/attachment-0003.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: image/jpeg
Size: 518 bytes
Desc: not available
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20140508/65a23cb7/attachment.jpe>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: image/jpeg
Size: 1208 bytes
Desc: not available
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20140508/65a23cb7/attachment-0001.jpe>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: image/gif
Size: 360 bytes
Desc: not available
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20140508/65a23cb7/attachment.gif>