[xacml] external functions

[Simon Godik <simon@godik.com>]

Here is my proposal for external functions in general

and for date-time and strings in particular. (text and schema)

Please comment.

 

Simon

 

Attribute Functions.

We can define attribute functions in one of 2 ways: free-form or with
specialized schema. Even when schema is specialized not everything could
be validated by the parser. For example, very often we have to pass
attribute values as function arguments and this can not be validated.

I start with free-form definition of external function and then outline
what could be done with specialization schemas.

Free form attribute functions.

Each function is identified by it's name, optional return type uri 
and a list of arguments.

Suppose we want to call 'ComputeDateTime' function that computes dates and
times. This function can return it's result in any predefined date-time
format. Since each built-in datatype can be uniquely addressed via a uri
reference (see xml schema part2: datatypes), function return type is
indicated by the 'uri' attribute of the <Return> element.

<x:extFunction FunctionName="ComputeDateTime">
   <x:Return uri="www.w3.org/2001/XMLSchema#date"/>
   <x:Args>
	... Arguments (see below)
   </x:Args>
</x:extFunction>

Each argument is identified by an optional name and argument type uri,
and argument value.

When attribute function is called it can be passed arguments from
foreign namespaces that have to be converted to the argument type.
This conversion is achived with 'ConversionURI' attribute of
the <argValue> tag. (If no conversion is nessessary, 'ConversionURI'
attribute can be ommitted.)

Suppose we want to pass a value of a booking date (defined by the california
department of corrections in the 'cdc' namespace) as the first argument
to ComputeDateTime function.

<x:Arg ArgTypeURI="http:www.w3.org/XMLSchema#date">
   <x:ArgValue ConversionURI="http://www.cdc.ca/converter";>
      <x:Attribute AttributeName="BookingDate">
         <x:AttributeValue>
            <cdc:BookingDate>05-31-2002</cdc:BookingDate>
	 </x:AttributeValue>
      </x:Attribute>
   </x:ArgValue>
</x:Arg>

'ArgTypeURI' attribute of the <x:Arg> element specifies expected type of the 
argument. 'ConversionURI' attribute of the <x:ArgValue> identifies conversion
function to be used to convert a value from the 'cdc' namespace to the
standard 'date' format.

The second argument to the ComputeDateTime is a time interval that will
be added to the first argument. We will pass <cdc:DaysHeld> element as
the second argument.

Here is complete function ivocation:

<x:extFunction FunctionName="ComputeDateTime">
   <x:Return uri="http:www.w3.org/XMLSchema#date"/>
   <x:Args>
      <x:Arg ArgTypeURI="http:www.w3.org/XMLSchema#date">
         <x:ArgValue ConversionURI="http://www.cdc.ca/converter";>
	    <x:Attribute AttributeName="BookingDate">
	       <cdc:BookingDate>05-31-2002</cdc:BookingDate>
	    </x:Attribute>
	 </x:ArgValue>
      </x:Arg>
      <x:Agr ArgTypeURI="http:www.w3.org/XMLSchema#duration">
         <x:ArgValue ConversionURI="http:www.cdc.ca/converter">
	    <x:Attribute AttributeName="DaysHeld">
	       <x:AttributeValue>
	          <cdc:DaysHeld>5</cdc:DaysHeld>
	       </x:AttributeValue>
	    </x:Attribute>
	 </x:ArgValue>
      </x:Arg>
   </x:Args>
</x:extFunction>

Free form schema notes.
1. Free form schema uses <xs:any> as a child of <x:ArgValue>. We can be
more specific and list a choice of 'AttributeDesignator', 'Attribute',
or an attirbute function, or one of global elements of predefined simple types.
2. We can get rid of <ArgValue> element by moving 'ConversionURI' attribute
to it's parent element <Arg>. (I'm in favor of keeping ArgValue).
3. Global elements of simple built-in types are defined so they can be
used to pass constant values to attribute functions.

Specialization Schemas.
It is obvious that very little validation can be done by xml parser
on free form function. For example number of arguments and their types
can not be validated. To get around this problem we can create specialization
schemas for different functions. For example, we can indicate that function
takes that many parameters etc. But still, we can not take care of all
important things like what types are compatable with each other and with
the return type, etc. Specialized schema is not a substitute for function
documentation and that's why I decided to use free form schema.

I was very conservative with the selection of functions. I looked at
language libraries and xml specifications. I expect normative set of functions
to be small.

Date Time functions.
Function: dateTime GetCurrentDateTime().
Retuns current date or time in any of schema defined formats.

Valid values for the 'uri' attribute of the <Return> element:
(all preceded with http:www.w3.org/XMLSchema#)
dateTime, time, date, gYearMonth, gYear, gMonthDay, gDay, gMonth
Arguments: There are no arguments.

Function: dateTime ComputeDateTime(dateTime, duration).
Compute date-time. First argument is the start date-time instance. Second
argument is time interval. Value returned by this function should be compatable
with the value of the first argument. For example dateTime value could be
converted to any other value, date can be converted to gYear etc. Most
of the time these two types will be the same.

Valid values for the 'uri' attribute of the <Return> element:
(all preceded with http:www.w3.org/XMLSchema#)
dateTime, time, date, gYearMonth, gYear, gMonthDay, gDay, gMonth.

Arguments: 
first argument type can have any value listed above.
second argument type is http:www.w3.org/XMLSchema#duration

Function: duration ComputeTimeDifference(dateTime, dateTime).
Compute time interval between argument 2 and argument 1. Both arguments should
be either of the same type or compatable with each other. If arguments are
compatable with each other, more specific type will be converted to less
specific. For example, if dateTime and gYear are passed as arguments,
dateTime will be converted to gYear before computation.

Arg1: Start date-time instance. any-of: dateTime, time, date, gYearMonth,
gYear, gMonthDay, gDay, gMonth
Arg2: End date-time instance. any-of: dateTime, time, date, gYearMonth,
gYear, gMonthDay, gDay, gMonth
Return: duration.

Function: boolean Before(DateTime, DateTime).
First and second argument must be of the same date-time types.
Return uri: http:www.w3.org/XMLSchema#boolean

Function: OnOrAfter(DateTime, DateTime).
First and second argument must be of the same date-time types.
Return uri: http:www.w3.org/XMLSchema#boolean

String functions.
Function: int StringLength(string).
Computes string length.
Return type: any of integer, long, int, short.
Argument: Input string.

example:
<x:extFunction FunctionName="Stinglength">
   <x:Return uri="http:www.w3.org/XMLSchema#short"/>
   <x:Args>
      <x:Arg ArgTypeURI="http:www.w3.org/XMLSchema#string">
         <x:ArgValue>
            <x:String>hello world</x:String>
	 </x:ArgValue>
      </x:Arg>
   </x:Args>
</x:extFunction>

Function: string Concat(string1, string2).
Concatinate all it's arguments into one string.
Return type: string.
Arguments: any number of strings.

example:
<x:extFunction FunctionName="Concat">
   <x:Return uri="http:www.w3.org/XMLSchema#string"/>
   <x:Args>
      <x:Arg ArgTypeURI="http:www.w3.org/XMLSchema#string">
         <x:ArgValue>
            <x:String>hello</x:String>
	 </x:ArgValue>
      </x:Arg>
      <x:Arg ArgTypeURI="http:www.w3.org/XMLSchema#string">
         <x:ArgValue>
            <x:String>world</x:String>
	 </x:ArgValue>
   </x:Args>
</x:extFunction>

Function: int StringCompare(string1, string2).
Compare string1 with string2. Return 0 if they are the same, positive
integer if string1 is greater than string2, and negative integer if
string1 is less than string2.
Return uri: http:www.w3.org/XMLSchema#short
Arg1: normalizedString
Arg2: normalizedString

example:
<x:extFunction FunctionName="StringCompare">
   <x:Return uri="http:www.w3.org/XMLSchema#short">
   <x:Args>
      <x:Arg ArgTypeURI="http:www.w3.org/XMLSchema#normalizedString">
         <x:ArgValue>
            <x:NormalizedString>hello</x:NormalizedString>
         </x:ArgValue>
      </x:Arg>
   </x:Args>
</x:extFunction>

Function: string Substring(string, pos, len)
Return the substring of the first argument starting at the position
specified in the second argument with length specified in the third
argument.

Function: boolean Contains(string,string)
Return 'true' if the first argument string contains the second argument
string, otherwise return false.

Attachment: extfunc.xsd
Description: text/xml