sep-0002.md

Add Support Durations, Dates, and Times

• Short Name: date-time-arithmetic
• SEP Number: SEP-0002
• Author: Gregory Todd Williams

Notes

This might be affected by work on sparql-dev#97 (supporting XPath 3.1). For the purposes of this SEP, it is assumed that XPath 3.1 is not supported, and existing SPARQL semantics continue to be based on XQuery 1.0 and XPath 2.0 Functions and Operators.

Not all of the relevant operators are described below or implemented in the linked tests, but the tests repo does list them in the README.

Abstract

Update SPARQL to better support handling of duration, date, and time values. This would add new supported datatypes xsd:time, xsd:date, xsd:duration, and the two derived types xsd:dayTimeDuration, and xsd:yearMonthDuration. New functions and operators for working with these types would be added, drawn from the XPath and XQuery Functions and Operators (similar to existing functions and operators already supported in SPARQL 1.1).

Motivation

As raised in sparql-dev#32, the support in SPARQL 1.1 for xsd:dateTime allows only a narrow range of queries, and is often insufficient to express queries over temporal data. Among other limitations, the supported types, functions, and operators available in SPARQL 1.1:

• cannot be used with xsd:date values
• cannot be used with xsd:time values
• cannot perform arithmetic operations over temporal values (computing differences, adding/subtracting durations)
• cannot extract components from xsd:date values
• cannot extract components from xsd:time values

This proposal would improve SPARQL's support for temporal data by supporting common datatypes such as dates, times, and durations, and allow natural operations over those datatypes (and the already supported xsd:dateTime type).

Rationale and Alternatives

This proposal follows the SPARQL 1.1 spec in natively supporting XPath operators where appropriate, and in exposing XPath functions using keywords that fit stylistically with existing functions.

Evidence of consensus

TODO: To be filled in when/if such evidence becomes available

Specification:

The following datatypes are added to the list of supported Operand Data Types and to the list of XPath Constructor Functions:

• xsd:time
• xsd:date
• xsd:duration
• xsd:dayTimeDuration
• xsd:yearMonthDuration

The following function is added to the Functions on Dates and Times:

• xsd:dateTime ADJUST(xsd:dateTime arg, xsd:dayTimeDuration timezone) (fn:adjust-dateTime-to-timezone)
• xsd:date ADJUST(xsd:date arg, xsd:dayTimeDuration timezone) (fn:adjust-date-to-timezone)
• xsd:time ADJUST(xsd:time arg, xsd:dayTimeDuration timezone) (fn:adjust-time-to-timezone)

The following functions are updated in Functions on Dates and Times to accept parameters of more types:

• xsd:integer YEAR (xsd:date arg) (fn:year-from-date)
• xsd:integer MONTH (xsd:date arg) (fn:month-from-date)
• xsd:integer DAY (xsd:date arg) (fn:day-from-date)
• xsd:integer HOURS (xsd:time arg) (fn:hours-from-time)
• xsd:integer MINUTES (xsd:time arg) (fn:minutes-from-time)
• xsd:decimal SECONDS (xsd:time arg) (fn:seconds-from-time)
• xsd:dayTimeDuration TIMEZONE (xsd:date arg) (fn:timezone-from-date)
• xsd:dayTimeDuration TIMEZONE (xsd:time arg) (fn:timezone-from-time)
• simple literal TZ (xsd:date arg)
• simple literal TZ (xsd:time arg)

The following entries are added to the Operator Mapping table:

• xsd:yearMonthDuration < xsd:yearMonthDuration (op:yearMonthDuration-less-than)
• xsd:yearMonthDuration > xsd:yearMonthDuration (op:yearMonthDuration-greater-than)
• xsd:dayTimeDuration < xsd:dayTimeDuration (op:dayTimeDuration-less-than)
• xsd:dayTimeDuration > xsd:dayTimeDuration (op:dayTimeDuration-greater-than)
• xsd:duration = xsd:duration (op:duration-equal)
• xsd:date = xsd:date (op:date-equal)
• xsd:date < xsd:date (op:date-less-than)
• xsd:date > xsd:date (op:date-greater-than)
• xsd:date - xsd:date (op:subtract-dates)
• xsd:date - xsd:dayTimeDuration (op:subtract-dayTimeDuration-from-date)
• xsd:date - xsd:yearMonthDuration (op:subtract-yearMonthDuration-from-date)
• xsd:date + xsd:dayTimeDuration (op:add-dayTimeDuration-to-date)
• xsd:date + xsd:yearMonthDuration (op:add-yearMonthDuration-to-date)
• xsd:time = xsd:time (op:time-equal)
• xsd:time < xsd:time (op:time-less-than)
• xsd:time > xsd:time (op:time-greater-than)
• xsd:time - xsd:time (op:subtract-times)
• xsd:time - xsd:dayTimeDuration (op:subtract-dayTimeDuration-from-time)
• xsd:time + xsd:dayTimeDuration (op:add-dayTimeDuration-to-time)
• xsd:dateTime - xsd:dateTime (op:subtract-dateTimes)
• xsd:dateTime - xsd:dayTimeDuration (op:subtract-dayTimeDuration-from-dateTime)
• xsd:dateTime - xsd:yearMonthDuration (op:subtract-yearMonthDuration-from-dateTime)
• xsd:dateTime + xsd:dayTimeDuration (op:add-dayTimeDuration-to-dateTime)
• xsd:dateTime + xsd:yearMonthDuration (op:add-yearMonthDuration-to-dateTime)

Backwards Compatibility

This proposal is purely additive to SPARQL 1.1.

Tests and implementations

• Tests
• Implementations:
  • Kineo (sparql-dev branch)
  • Comunica (Excluding the ADJUST function)