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: [email protected] 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
