[Oslc-Automation] Definition of "parameter"

[Charles Rankin]

At the last workgroup meeting there was some discussion about whether we 
should define what is on the other end of a "parameter" property or leave 
it up to implementations.  I'd like to revisit that discussion.  I'm of 
the opinion that we should provide a minimally useful definition that 
implementers could extend if necessary.  One of the key scenarios that we 
want to enable with this first version of the specification is the 
"execution" scenario [1].  I'm concerned about the viability of this 
scenario without having a minimally useful definition of parameters.  To 
that end, I'd like to take a stab at an initial representation for others 
to throw darts at.  My RDF-Fu is weak, so please be kind.  :)

There are at least two different parameters in question.  One is on an 
Automation Plan and provides the name and constraints on possible input 
values.  The other is associated with Automation Requests and Automation 
Results and represents the mapping of a specific value to a specific named 
parameter.  For lack of better names, I'm going to call the former a 
Parameter Definition and the latter a Parameter Instance.  Let's start 
with the Parameter Definition.  To provide a minimally useful Parameter 
Definition I think we need at least two pieces of information (possibly 
represented as three pieces of data).  The first is simply the name of the 
parameter.  The other is an indication of whether the parameter must be 
specified in order for the automation to be successfully executed.  One 
mechanism for this is to indicate a "default value" to be used if none is 
provided.  The presence of this also provides some potentially useful 
information to those looking at an Automation Result, as they can see if 
the value provided was different than the default.  It isn't clear to me 
that the absence of this data necessarily means that the parameter is 
required.  To that end, another option is to have a "required" property 
that indicates whether the parameter must be specified.  Without further 
ado. let's take a stab at how this might look ( in Turtle).

@prefix ap:     <http://somewhere.com/oslc-automation-provider> .

ap:plan1        oslc_auto:parameter     _:parm1 .
ap:plan1        oslc_auto:parameter     _:parm2 .
ap:plan1        oslc_auto:parameter     _:parm3 .

_:parm1 foaf:name               "must_have" .
_:parm1 oslc_auto:required      oslc_auto:required_yes .

_:parm2 foaf:name               "might_have" .
_:parm2 oslc:defaultValue       "some value" .
_:parm2 oslc_auto:required      oslc_auto:required_no .

_:parm3 foaf:name               "may_have" .
_:parm3 oslc_auto:required      oslc_auto:required_no .

The first definition indicates there is a required parameter with a name 
of "must_have". The second definition indicates there is an optional 
parameter with a name of "might_have", which if no value is specified a 
default value of "some value" will be used.  The third definition 
indicates there is an optional parameter with a name of "may_have", which 
if no value is specified, no default value will be provided.

The information needed to define a Parameter Instance is a little less 
than for a Parameter Definition.  All that is required is the name of the 
parameter and the value of the parameter.  While these could be specified 
as direct "name=value" strings, I think it is better to separate the name 
from the value.  So, an Automation Request specifying information for the 
plan above, might have parameters as such.

@prefix ap:     <http://somewhere.com/oslc-automation-provider> .

ap:req1         oslc_auto:parameter     _:parm1 .
ap:req1         oslc_auto:parameter     _:parm2 .

_:parm1 foaf:name               "must_have" .
_:parm1 rdf:value               "here you go" .

_:parm2 foaf:name               "may_have" .
_:parm2 rdf:value               "more information" .

This indicates that there are two parameters specified one with a name of 
"must_have" and corresponding value of "here you go", and another with a 
name of "may have" and a corresponding value of "more information".

A few more thoughts/questions before I finish.

1) I did not specify any type for the Parameter Definition default value 
or the Parameter Instance value.  Pragmatically, I think the only viable 
choice is String.  I'm not sure if we should spec that or leave it up to 
the discretion of implementers.

2) I did not attempt to support the ordering of parameters.  I don't 
believe there are any likely target systems where that would be required, 
but thought I'd mention it in case anyone else knew of a case where it 
might be necessary.

3) Given the distinction above between a Parameter Definition and a 
Parameter Instance, should we name the properties in Automation Plan 
differently than in Automation Request and Automation Result or keep it 
"parameters" and let the context be sufficient?

That's enough for now.  Have at it.  :)

[1] http://open-services.net/bin/view/Main/AutomationExecutionScenario 

Charles Rankin
Rational CTO Team -- Mobile Development Strategy
101/4L-002 T/L 966-2386
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20120116/2234b1a0/attachment-0003.html>