DTB

From RIF

Document title:: RIF Data Types and Built-Ins

Editors: Axel Polleres, DERI; Harold Boley, NRC

Abstract
Status of this Document: rough draft

This document, developed by the Rule Interchange Format (RIF) Working Group, specifies a list of primitive datatypes, built-in functions and built-in predicates supported by the RIF Basic Logic Dialect (http://www.w3.org/TR/rif-bld/ RIF-BLD). The definitions of the listed functions and operators are taken from XQuery 1.0 and XPath 2.0 Functions and Operators (W3C Recommendation 23 January 2007).

The following list of built-ins for RIF-BLD is currently under discussion within the Rule Interchange Format (RIF) Working Group. The Discussion section lists a couple of open issues regarding datatypes and built-ins for RIF-BLD and, more general, for other RIF dialects. They are to be used as starting point for discussion within the group and will be removed before publishing this document.

1 Datatypes
2 Syntax and Semantics of Built-ins
3 Discussion (Open Issues)

[edit] 1 Datatypes

Data types in RIF are symbol spaces (which are part of the RIF syntactic framework) which have special semantics. That is, each datatype is characerized by a fixed lexical space, value space and lexical-to-value-mapping as defined in the RIF Framework for Logic Dialects (http://www.w3.org/TR/rif-fld/ RIF-FLD).

All RIF dialects are expected to support the following primitive data types:

   * xsd:long
   * xsd:integer
   * xsd:decimal
   * xsd:string
   * xsd:time
   * xsd:dateTime
   * rdf:XMLLiteral
   * rif:text

Copy/Move Section 3.3 from FLD here

[edit] 2 Syntax and Semantics of Built-ins

[edit] 2.1 Syntax of Built-ins

The working group decided to use a special syntax to distinguish evaluated predicates/functions (built-ins, external function calls) from logical predicates/functions in RIF-BLD. As such, atomic and term productions are to be extended:

   ATOMIC      ::= Uniterm | Equal | ExtTerm

   TERM        ::= Const | Var | Uniterm | ExtTerm

and a new production for ExtTerm is to be added. One proposal for a syntactical symbol for built-ins is:

   ExtTerm     ::= 'Builtin ( ' Uniterm ' ) '

[edit] 2.1.1 Other proposals for the syntax

[edit] 2.1.1.1 Eval proposal

   ExtTerm     ::= 'Eval ( ' Uniterm ' ) '

[edit] 2.1.1.2 Apply proposal

   ExtTerm     ::= 'Apply ( ' Uniterm ' ) '

Comment by csma: I would prefer something like

   ExtTerm      ::= ' ( Apply ' Const TERM* ' ) '

Presentation Syntax	XML Syntax
( Apply predfunc argument₁ . . . argument_n )	<ExtTerm> <op>predfunc</op> <arg>argument₁</arg> . . . <arg> argument_n</arg> </ExtTerm>

[edit] 2.1.1.3 & proposal (Axel's proposal)

Example: Strawman for the presentation syntax

 &fn:dateTime( "2006-08-15"^^xs:date "12:30:45-05:00"xs:time )

leading '&' followed by Const, ideally I (Axel, personal statement) would prefer CURIs and not to allow full IRIs here, but it seems that a CURI and a prefix definiton mechanism are still missing in the current BNF.

      ExtTerm     ::= '&' Const ' ( ' TERM* ' ) '

      <ExtTerm>
       <op>
        <Const type="&rif;iri">
          http://www.w3.org/2005/xpath-functions/#dateTime
        </Const>
       </op>
       <arg><Const type="&xs;date">2006-08-15</Const></arg>
       <arg><Const type="&xs;time">12:30:45-05:00</Const></arg>
      <ExtTerm>

The abstract model would likewise need to be extended, but this extension is minor. Comment by Jos: I do not find the "&"-prefix solution very elegant. It suggests that "&" is a part of the name, or a modifier of the name, where as it is meant as a modifier of the complete term.

[edit] 2.1.1.4 Designated symbol space proposal (Axel's proposal : NEW)

Finally, an alternative would be to use an own symbolspace (or separate symbolspaces for functions and predicates, respectively) for built-ins instead of a separate keyword, ie. rif:builtin (or rif:builtinFn, rif:builtinOp, respectively).

[edit] 2.2 Semantics of Built-ins

Built-in functions and predicates in BLD are function or predicate symbols with a fixed interpretation, that is, similar to the restrictions imposed on I_C for datatypes, RIF-FLD needs to restrict I_F on built-in functions and predicates. Details of this definition are expected to be defined in the RIF FLD and BLD documents.

This should probably rather go into FLD/BLD.

[edit] 2.3 List of Supported Built-in Predicates and Functions

RIF compliant systems have to support the following list of builtin Predicates. The list of functions and predicates (also called operators) overlaps with the functions and operators defined in [http://www.w3.org/TR/xpath-functions/ XQuery 1.0 and XPath 2.0 Functions and Operators] and unless stated otherwise we refer to the definitions therein for the concrete semantics of of the respective built-ins.

[edit] 2.3.1 Guard Predicates for Datatypes

RIF requires guard predicates for all its supported datatypes. These predicates have the form

rifBuiltinPred:isDATATYPE($arg1 as TERM )

with the fixed interpretation of being true if and only if I_C of TERM is in the value space of DATATYPE and false otherwise.

  rifBuiltinPred:isLong($arg1 as TERM )

 rifBuiltinPred:isInteger($arg1 as TERM )

 rifBuiltinPred:isDecimal($arg1 as TERM )

 rifBuiltinPred:isString($arg1 as TERM )

 rifBuiltinPred:isTime($arg1 as TERM )

 rifBuiltinPred:isDateTime($arg1 as TERM )

 rifBuiltinPred:isXMLLiteral($arg1 as TERM )

 rifBuiltinPred:isText($arg1 as TERM )

Likewise, RIF has negative guards for all its supported datatypes. These builtin predicates have the form

rifBuiltinPred:isNotDATATYPE($arg1 as TERM )

with the fixed interpretation of being false if and only if I_C of TERM is in the value space of DATATYPE and false otherwise.

 rifBuiltinPred:isNotLong($arg1 as TERM )

 rifBuiltinPred:isNotInteger($arg1 as TERM )

 rifBuiltinPred:isNotDecimal($arg1 as TERM )

 rifBuiltinPred:isNotString($arg1 as TERM )

 rifBuiltinPred:isNotTime($arg1 as TERM )

 rifBuiltinPred:isNotDateTime($arg1 as TERM )

 rifBuiltinPred:isNotXMLLiteral($arg1 as TERM )

 rifBuiltinPred:isNotText($arg1 as TERM )

Future dialects may extend this list of guards to other datatypes, but RIF does not require guards for all datatypes.

[edit] 2.3.2 Cast functions for Datatypes and rif:iri

RIF requires cast functions for all its supported datatypes. Partial conversion functions between the datatypes xsd:xsd:time, xsd:string, xsd:dateTime are defined as in the conversion table in Section 17.1 of XQuery 1.0 and XPath 2.0 Functions and Operators.

Note that the types xs:long, rif:XMLLiteral, and rif:iri do not appear in that table, but the following applies to :

* The conversions from and to xs:long follow the same considerations as xs:integer in that table, by the XPath, XQuery type hierarchy in Sec 1.6 of XQuery 1.0 and XPath 2.0 Functions and Operators.
* Any rif:XMLLiteral can be cast to xsd:string by preserving the lexical value and just changing the symbol space. An xsd:string can be cast to rdf:XMLLiteral if and only if its value is in the lexical space of rdf:XMLLiteral as defined in Resource Description Framework (RDF): Concepts and Abstract Syntax.
* The conversions from and to rif:iri follow the same considerations as conversions from and to xs:anyURI.

Although rif:iri is not a datatype, I left conversions from and to rif:iris in the list of casts functions, since I see some use cases in the context of RDF if you want to extract a string from an IRI and vice versa. See also the use case mentioned in http://lists.w3.org/Archives/Public/public-rif-wg/2008Mar/0011.html

[edit] 2.3.3 Functions and Operators on Numerics

If not stated otherwise the following functions and operators are defined on the numeric datatypes defined in XML Schema Part 2: Datatypes Second Edition.

- - Issues: prefixes must be documented. ***

[edit] 2.3.3.1 Functions on Numeric Values

1. op:numeric-add (Builtin Function)

op:numeric-add($arg1 as TERM, $arg2 as TERM) as numeric

only defined if all arguments are numeric (i.e. their interpretation is in the value space of xsd:integer, xsd:long, or xsd:decimal), otherwise returns an error.

Is this definition "i.e. their interpretation is in the value space of xsd:integer, xsd:long, or xsd:decimal" ok? The actual XPath functions are only defined for certain inputs, but as we do not talk about "invocations" or "bindings" of values, but only about fixed interpretations, I see no other way of defining type compliance than via the interpretation. Also, since built-in functions are functions, we have to accept TERMs as inputs, which can be variables, constants or any other nested function terms.

2. op:numeric-subtract (Builtin Function)

op:numeric-subtract($arg1 as TERM, $arg2 as TERM) as numeric

only defined if all arguments are numeric, otherwise returns an error.

3. op:numeric-multiply (Builtin Function)

op:numeric-multiply($arg1 as TERM, $arg2 as TERM) as numeric

only defined if all arguments are numeric, otherwise returns an error.

4. op:numeric-divide (Builtin Function)

op:numeric-divide($arg1 as TERM, $arg2 as TERM) as numeric

only defined if all arguments are numeric, otherwise returns an error.

[edit] 2.3.3.2 Predicates on Numeric Values

1. op:numeric-equal (Builtin Predicate)

op:numeric-equal($arg1 as TERM, $arg2 as TERM)

only defined if all arguments are numeric, otherwise returns false.

Shall we return false or error for mistypes in predicates? The corresponding XPath operator would throw an error (to be checked). Depends on final decision on error handling.

2. op:numeric-less-than (Builtin Predicate)

op:numeric-less-than($arg1 as TERM, $arg2 as TERM)

only defined if all arguments are numeric, otherwise returns false.

3. op:numeric-greater-than (Builtin Predicate)

op:numeric-greater-than($arg1 as TERM, $arg2 as TERM)

only defined if all arguments are numeric, otherwise returns false.

[edit] 2.3.4 Functions and Predicates on Strings

The functions and operators are defined on the XML Schema Part 2: Datatypes Second Edition xs:string datatype and the datatypes derived from it.

- - Issues: prefixes must be documented. ***

- - Issue: Collation support. The functions compare, contains, starts-with, ends-with, string-before, string-after all have both a form that allows specification of a collation order and a form which does not. If these are really required we should define which collation orders implementations are required to support. Two options: (a) drop the forms which include collation arguments. These could be added in future dialects or local extensions but would not be required in conformant BLD implements; (b) include the collation forms and specify that conformant implementations are only required to support collation order: http://www.w3.org/2005/xpath-functions/collation/codepoint as described in http://www.w3.org/TR/xpath-functions/#collations. ***

[edit] 2.3.4.1 Functions on Strings

1. fn:compare

fn:compare($comparand1 as TERM,
           $comparand2 as TERM) as xs:integer?

only defined if all arguments are strings (i.e. their interpretation is in the value space of xsd:string), otherwise returns an error.

fn:compare($comparand1   as xs:string?,
           $comparand2   as xs:string?,
           $collation    as xs:string) as xs:integer?

Returns -1, 0, or 1, depending on whether the value of the $comparand1 is respectively less than, equal to, or greater than the value of $comparand2, according to the rules of the collation that is used.

2. fn:concat

fn:concat($arg1  as TERM,
          $arg2  as TERM ) as xs:string

Accepts two xs:anyAtomicType arguments and casts them to xs:string. Returns the xs:string that is the concatenation of the values of its arguments after conversion. Only defined if all arguments are castable to strings (see Section on Cast functions above), otherwise returns an error.

The original definition of fn:concat allows an arbitrary number of arguments: "Accepts two xs:anyAtomicType arguments". This is not compliant with the definition of BLD that each function (builtin or not) has a fixed arity. However, srictly speaking any n-ary concat can be expressed by nesting binary concats. Also note that this function has implicit casts (as defined in the XPath/XQuery functions and operators document).

2. fn:string-join

fn:string-join($arg1 as xs:string*, $arg2 as xs:string) as xs:string

Returns a xs:string created by concatenating the members of the $arg1 sequence using $arg2 as a separator. Only defined if all arguments are strings, otherwise returns an error.

Same issue as for concat, we cannot allow arbitrary arity accordin g to the BLD definitions, so, we either nest ternary string-joins, or define a "macro".

3. fn:substring

fn:substring( $sourceString      as TERM,
              $startingLoc       as TERM) as xs:string

Only defined if the first argument is a string, and the second argument an xsd:double, (i.e. the interpretation of the second TERM is in the intersection of the value spaces of xsd:integer, xsd:long, xsd:decimal with xsd:double), returns an error otherwise.

fn:substring( $sourceString      as TERM,
              $startingLoc       as TERM,
              $length            as TERM) as xs:string

Only defined if the first argument is a string, and the second and third arguments an xsd:double, (i.e. the interpretation of the second TERM is in the intersection of the value spaces of xsd:integer, xsd:long, xsd:decimal with xsd:double), returns an error otherwise.

We have a problem with overloading here. According to BLD, we cannot allow overloading, i.e. substring occurring with both arity 2 and 3. We have to decide for one version or provide different names.

Returns the portion of the value of $sourceString beginning at the position indicated by the value of $startingLoc and continuing for the number of characters indicated by the value of $length. The characters returned do not extend beyond $sourceString. If $startingLoc is zero or negative, only those characters in positions greater than zero are returned.

4. fn:string-length

fn:string-length() as xs:integer

fn:string-length($arg as TERM) as xs:integer

Returns an xs:integer equal to the length in characters of the value of $arg. Only defined if the argument is a string.

We have a problem with overloading here. According to BLD, we cannot allow overloading, i.e. string-length occurring with both arity 0 and 1. I suggest to drop string-length without arguments, it seems superfluous.

5. fn:upper-case

fn:upper-case($arg as TERM) as xs:string

Only defined if the argument is a string, returns an error otherwise.

6. fn:lower-case

fn:lower-case($arg as TERM) as xs:string

Only defined if the argument is a string, returns an error otherwise.

7. fn:encode-for-uri

fn:encode-for-uri($uri-part as TERM) as xs:string

This function encodes reserved characters in an xs:string that is intended to be used in the path segment of a URI. It is invertible but not idempotent. Only defined if the argument is a string, returns an error otherwise.

8. fn:iri-to-uri

fn:iri-to-uri($iri as TERM) as xs:string

Only defined if the argument is a string, returns an error otherwise.

9. fn:escape-html-uri

fn:escape-html-uri($uri as TERM) as xs:string

This function escapes all characters except printable characters of the US-ASCII coded character set, specifically the octets ranging from 32 to 126 (decimal). The effect of the function is to escape a URI in the manner html user agents handle attribute values that expect URIs. Each character in $uri to be escaped is replaced by an escape sequence, which is formed by encoding the character as a sequence of octets in UTF-8, and then representing each of these octets in the form %HH, where HH is the hexadecimal representation of the octet. This function must always generate hexadecimal values using the upper-case letters A-F. Only defined if the argument is a string, returns an error otherwise.

10. fn:substring-before

fn:substring-before($arg1 as TERM, $arg2 as TERM) as xs:string

fn:substring-before( $arg1       as TERM,
                     $arg2       as TERM,
                     $collation  as TERM) as xs:string

Returns the substring of the value of $arg1 that precedes in the value of $arg1 the first occurrence of a sequence of collation units that provides a minimal match to the collation units of $arg2 according to the collation that is used.

Only defined if the arguments are strings, returns an error otherwise. Again the problem of overloading occurs. We have to decide for one version or provide different names.

11. fn:substring-after

fn:substring-after($arg1 as TERM, $arg2 as TERM) as xs:string

fn:substring-after( $arg1    as TERM,
                    $arg2        as TERM,
                    $collation   as TERM) as xs:string

Only defined if the arguments are strings, returns an error otherwise Again the problem of overloading occurs. We have to decide for one version or provide different names.

12. fn:replace

fn:replace( $input       as TERM,
            $pattern     as TERM,
            $replacement as TERM) as xs:string

fn:replace( $input       as TERM,
            $pattern     as TERM,
            $replacement as TERM,
            $flags       as TERM) as xs:string

The function returns the xs:string that is obtained by replacing each non-overlapping substring of $input that matches the given $pattern with an occurrence of the $replacement string.

Only defined if the arguments are strings, returns an error otherwise Again the problem of overloading occurs. We have to decide for one version or provide different names.

13. fn:tokenize

fn:tokenize($input as TERM, $pattern as TERM) as xs:string*

fn:tokenize( $input      as TERM,
             $pattern    as TERM,
             $flags      as TERM) as xs:string*

This function breaks the $input string into a sequence of strings, treating any substring that matches $pattern as a separator. The separators themselves are not returned.

Only defined if the arguments are strings, returns an error otherwise Again the problem of overloading occurs. We have to decide for one version or provide different names.

[edit] 2.3.4.2 Predicates on Strings

The predicates described here examine a string $arg1 to see whether it contains another string $arg2 as a substring. The result depends on whether $arg2 is a substring of $arg1, and if so, on the range of characters in $arg1 which $arg2 matches.

1. fn:contains

fn:contains($arg1 as TERM, $arg2 as TERM) 

fn:contains( $arg1      as TERM,
             $arg2      as TERM,
             $collation as TERM)

Returns true or false indicating whether or not the value of $arg1 contains (at the beginning, at the end, or anywhere within) at least one sequence of collation units that provides a minimal match to the collation units in the value of $arg2, according to the collation that is used. "Minimal match" is defined in Unicode Collation Algorithm.

Only defined if the arguments are strings. Shall we return an error or false otherwise? Again the problem of overloading occurs. We have to decide for one version or provide different names.

2. fn:starts-with

fn:starts-with($arg1 as xs:string?, $arg2 as xs:string?)

fn:starts-with( $arg1      as TERM,
                $arg2      as TERM,
                $collation as TERM)

Returns true or false indicating whether or not the value of $arg1 starts with a sequence of collation units that provides a minimal match to the collation units of $arg2 according to the collation that is used. "Minimal match" is defined in Unicode Collation Algorithm.

Only defined if the arguments are strings. Shall we return an error or false otherwise? Again the problem of overloading occurs. We have to decide for one version or provide different names.

3. fn:ends-with

fn:ends-with($arg1 as xs:string?, $arg2 as xs:string?) as xs:boolean

fn:ends-with( $arg1      as TERM,
              $arg2      as TERM,
              $collation as TERM)

Only defined if the arguments are strings. Shall we return an error or false otherwise? Again the problem of overloading occurs

4. fn:matches

fn:matches($input as TERM, $pattern as TERM) as xs:boolean

fn:matches( $input       as TERM,
            $pattern     as TERM,
            $flags       as TERM)

The function returns true if $input matches the regular expression supplied as $pattern as influenced by the value of $flags, if present; otherwise, it returns false.

The effect of calling the first version of this function (omitting the argument $flags) is the same as the effect of calling the second version with the $flags argument set to a zero-length string. Flags are defined in 7.6.1.1 Flags.

Only defined if the arguments are strings. Shall we return an error or false otherwise? Again the problem of overloading occurs

[edit] 2.3.5 Functions and Predicates on Dates and Times

Date/time datatype values

As defined in Section 3.3.2 Dates and Times, xs:dateTime, xs:date, xs:time, xs:gYearMonth, xs:gYear, xs:gMonthDay, xs:gMonth, xs:gDay values, referred to collectively as date/time values, are represented as seven components or properties: year, month, day, hour, minute, second and timezone. The value of the first five components are xs:integers. The value of the second component is an xs:decimal and the value of the timezone component is an xs:dayTimeDuration. For all the date/time datatypes, the timezone property is optional and may or may not be present. Depending on the datatype, some of the remaining six properties must be present and some must be absent. Absent, or missing, properties are represented by the empty sequence. This value is referred to as the local value in that the value is in the given timezone. Before comparing or subtracting xs:dateTime values, this local value must be translated or normalized to UTC.

- - Issues: prefixes must be documented. ***

[edit] 2.3.5.1 Predicates on Date and Time Values

1. op:dateTime-equal

op:dateTime-equal($arg1 as TERM, $arg2 as TERM)

Returns true if and only if the value of $arg1 is equal to the value of $arg2 according to the algorithm defined in section 3.2.7.4 of XML Schema Part 2: Datatypes Second Edition "Order relation on dateTime" for xs:dateTime values with timezones. Returns false otherwise.

Only defined if both arguments are xsd:dateTime (i.e. the interpretation is in the value space of dateTime), returns false otherwise.

2. op:dateTime-less-than

op:dateTime-less-than($arg1 as TERM, $arg2 as TERM)

Only defined if both arguments are xsd:dateTime, returns false otherwise.

3. op:dateTime-greater-than

op:dateTime-greater-than( $arg1  as TERM,
                          $arg2  as TERM)

Only defined if both arguments are xsd:dateTime, returns false otherwise.

4. op:date-equal

op:date-equal($arg1 as TERM, $arg2 as TERM)

Returns true if and only if the starting instant of $arg1 is equal to starting instant of $arg2. Returns false otherwise. The starting instant of an xs:date is the xs:dateTime at time 00:00:00 on that date.

Only defined if both arguments are xsd:date (i.e. the interpretation is in the value space of xsd:date), returns false otherwise.

5. op:date-less-than

op:date-less-than($arg1 as TERM, $arg2 as TERM)

Only defined if both arguments are xsd:date, returns false otherwise.

6. op:date-greater-than

op:date-greater-than($arg1 as TERM, $arg2 as TERM)

Only defined if both arguments are xsd:date, returns false otherwise.

What about: op:time-equal, op:time-less-than, op:time-greater-than ? Were not in Paula's list

[edit] 2.3.5.1.1 Functions on Dates and Times

1. fn:year-from-dateTime

fn:year-from-dateTime($arg as TERM) as xs:integer?

Returns an xs:integer representing the year component in the localized value of $arg. The result may be negative.