<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
        <!ENTITY RFC5545 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5545.xml">
        ]>
<rfc ipr="trust200902" category="std"
     docName="draft-douglass-icalendar-fractional-time-00">
  <?rfc toc="yes"?>
  <?rfc symrefs="yes"?>
  <?rfc sortrefs="yes"?>
  <?rfc compact="no"?>
  <?rfc subcompact="no"?>
  <?rfc private=""?>
  <?rfc topblock="yes"?>
  <?rfc comments="no"?>

  <front>
    <title abbrev="iCalendar Fractional Time">iCalendar: Representing fractional seconds in iCalendar</title>
    <author initials="N.M." surname="Jenkins" fullname="Neil Jenkins">
      <organization>FastMail</organization>
      <address>
        <postal>
          <street>PO Box 234</street>
          <street>Collins St West</street>
          <city>Melbourne</city>
          <code>VIC 8007</code>
          <country>Australia</country>
          <region/>
        </postal>
        <phone/>
        <email>neilj@fastmailteam.com</email>
        <uri>https://www.fastmail.com</uri>
      </address>
    </author>
    <author initials="R." surname="Stepanek" fullname="Robert Stepanek">
      <organization>FastMail</organization>
      <address>
        <postal>
          <street>PO Box 234</street>
          <street>Collins St West</street>
          <city>Melbourne</city>
          <code>VIC 8007</code>
          <country>Australia</country>
          <region/>
        </postal>
        <email>rsto@fastmailteam.com</email>
        <uri>https://www.fastmail.com</uri>
      </address>
    </author>
    <author initials="M." surname="Douglass" fullname="Michael Douglass">
      <organization abbrev="BCS">Bedework Commercial Services</organization>
      <address>
        <postal>
          <street>226 3rd Street</street>
          <city>Troy</city>
          <region>NY</region>
          <code>12180</code>
          <country>United States of America</country>
        </postal>
        <email>mdouglass@bedework.com</email>
        <uri>http://bedework.com</uri>
      </address>
    </author>
    <date year="2021" month="July" day="7"/>
    <area>Applications</area>
    <workgroup>Calendaring extensions</workgroup>
    <keyword>iCalendar</keyword>
    <keyword>calendar</keyword>
    <keyword>events</keyword>
    <keyword>time</keyword>
    <keyword>fractional</keyword>
    <abstract>
      <t>
        This document defines a way to represent fractional seconds in iCalendar.
      </t>
    </abstract>
  </front>

  <middle>
    <section anchor="introduction" title="Introduction">
      <t>
        There has been an expressed need for the ability to use
        fractional seconds in iCalendar. With the advent of JSCalendar
       there is a way to do so in that
        representation. This specification provides a - partially
        backwards compatible - way to represent such times in iCalendar.
      </t>
      <t>
        It is probable that applications needing fractional seconds require
        recurrence rules that use sub-second intervals.
      </t>
      <t>
        This specification also shows how values should be mapped to and
        from JSCalendar.
      </t>
    </section>

    <section anchor="new-icalendar-parameters"
             title="New iCalendar parameters">
      <section anchor="fractional-parameter" title="FRACTIONAL parameter">
        <t>
          <list style='hanging'>
            <t hangText="Parameter name:">
              FRACTIONAL
            </t>
            <t hangText="Purpose:">
              This parameter is used to contain a value with fractional seconds for
              time values and durations.
            </t>
            <t hangText="Description:">
              This parameter MAY be specified on properties of type DATE-TIME
              or DURATION.
              It MUST be a valid iCalendar DATE-TIME or DURATION value with
              the addition of
              fractional seconds. The value MUST NOT be negative
              for durations but MAY be negative for alarm triggers.
            </t>
            <t>
              Applications receiving a property with a FRACTIONAL parameter
              MUST ensure its value is consistent with the value of the
              property. The property value must match:
              <vspace/>
              - a positive FRACTIONAL value rounded up to the next non-fractional second
              or
              <vspace/>
              - a negative FRACTIONAL value rounded down the next non-fractional second
            </t>
            <t>
              If the values do not match the the application
              MUST assume that the property value has been
              updated by an application that is unaware
              of the FRACTIONAL parameter. The parameter should be
              ignored in this case.
            </t>
            <t hangText="Format Definition:">
              <figure>
                <preamble>
                  This parameter is defined by the following notation:
                </preamble>

                <artwork type="abnf">
                  fractional-param = DATE-TIME or DURATION
                </artwork>
              </figure>
            </t>
            <t hangText="Example:">
              <figure>
                <artwork><![CDATA[
    DTSTART;FRACTIONAL=20190605T133015.03:20190605T133015
]]></artwork>
              </figure>
            </t>
          </list>
        </t>
      </section>
    </section>

    <section anchor="obtaining-value"
             title="Obtaining a Property Value">
      <t>
        If the property has a FRACTIONAL parameter first
        check that it is a valid value using the criteria
        specified in <xref target="fractional-parameter"/>.
        if valid, use that value for the iCalendar property.
      </t>
      <t>
        If the property has no FRACTIONAL parameter or the
        value of that parameter is invalid then use the normal
        property value.
      </t>
      <t>
        For example:
        <figure>
          <artwork><![CDATA[
  ...
  ESTIMATED-DURATION;FRACTIONAL="PT17H15M23.5S:PT18H
  ...

  The value here is "PT18H" because the FRACTIONAL parameter is not valid.

  ...
  ESTIMATED-DURATION:PT18H
  ...

  The value here is "PT18H" because there is no FRACTIONAL parameter.

    ...
  ESTIMATED-DURATION;FRACTIONAL="PT17H15M23.5S:PT17H15M24S
  ...

  The value here is "PT17H15M23.5S" because the FRACTIONAL parameter is valid.

]]></artwork>
        </figure>
      </t>
    </section>

    <section anchor="mapping-icalendar-jscalendar"
             title="Mapping from iCalendar to JSCalendar">
      <t>
        When mapping properties possibly containing time, use the
        iCalendar property value obtained as specified in
        <xref target="obtaining-value"/>.
      </t>
      <t>
        For example:
        <figure>
          <artwork><![CDATA[
  ...
  ESTIMATED-DURATION;FRACTIONAL="PT17H15M23.5S:PT18H
  ...

  maps to

  ...
  "estimatedDuration": "PT18H"
  ...

  because the FRACTIONAL parameter is not valid..

  ...
  ESTIMATED-DURATION:PT18H
  ...

  maps to

  ...
  "estimatedDuration": "PT18H"
  ...

  and
    ...
  ESTIMATED-DURATION;FRACTIONAL="PT17H15M23.5S:PT17H15M24S
  ...

  maps to

  ...
  "estimatedDuration": "PT17H15M23.5S"
  ...

  because the FRACTIONAL parameter is valid.

]]></artwork>
        </figure>
      </t>
    </section>

    <section anchor="mapping-jscalendar-icalendar"
             title="Mapping from iCalendar to JSCalendar">
      <t>
        If the jscalendar property value has fractional
        seconds then the <xref target="RFC5545"/> value
        is set to the jscalendar property value rounded up to the
        next non-fractional value and a FRACTIONAL parameter
        is added with the full unrounded value.
      </t>
      <t>
        For example:
        <figure>
          <artwork><![CDATA[
   ...
   "duration": "PT0.5S"
   ...

  maps to

   ...
   DURATION;FRACTIONAL="PT0.5S":PT1S
   ...

and

   ...
   "duration": "PT1H"
   ...

  maps to

   ...
   DURATION:PT1H
   ...

]]></artwork>
        </figure>
      </t>
    </section>

    <section anchor="open-issues" title="Open issues">
      <section anchor="recurrences" title="Recurrences">
        <t>
          It is probably the case that subsecond intervals are most
          useful for short recurrence intervals. Neither JSCalendar nor
          iCalendar currently allows that.
        </t>
        <t>
          This probably only requires that the interval value be allowed
          to contain fractional values (for seconds frequency only?).
        </t>
      </section>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      &RFC5545;
    </references>
  </back>
</rfc>