5.1.  iSchedule Sender Actions

A Calendar Service will generate an iTIP IETF RFC 5546 scheduling message for transmission. It will additionally provide details of the Originator and Recipients. The Calendar Service will “submit” the scheduling message and details to the iSchedule Sender, through a process that is outside the scope of this document.

The iSchedule Sender MUST verify the authenticity of the Originator and the Originator’s authorization to send the scheduling message. In particular the “ORGANIZER” iCalendar property value MUST match the Originator calendar user address. The process by which this authentication and authorization is done is outside the scope of this document.

For each Recipient, the iSchedule Sender will attempt to lookup a matching iSchedule Receiver to which the iSchedule message can be sent, following the rules in Clause 6. After determining the iSchedule Receiver to use, the iSchedule Sender MUST check the capabilities of the iSchedule Receiver to ensure it will be able to accept the scheduling message that needs to be sent, as per Clause 7.

The iSchedule Sender MUST group together Recipients for whom the iSchedule Receiver is the same, so that a single scheduling message is sent for multiple Recipients, within the limits of the IS:max-recipients value specified in the iSchedule Receiver’s capabilities.

For each group of Recipients handled by the same iSchedule Receiver, the iSchedule Sender will construct an HTTP request, as per Clause 8, with the body of the HTTP request containing the iSchedule message. Note, in the case of a “VFREEBUSY” iSchedule message, the iSchedule Sender MUST ensure that iCalendar “ATTENDEE” properties in the iSchedule message match one-for-one with the Recipients listed in the HTTP request header.

The iSchedule Sender then sends the HTTP request to the iSchedule Receiver handling the Recipient group, and receives the HTTP response, which will be an XML document with either an IS:schedule-response or IS:error element as the root element.

The iSchedule Sender aggregates the results for each Recipient group receiving an iSchedule message, and returns the resulting status information for each Recipient to the Calendar Service that generated the schedule message. The process by which this is done is outside the scope of this document.

5.2.  iSchedule Receiver Actions

iSchedule Receivers MUST provide a capabilities document to Senders, as per Clause 7.

Once the authenticity of the message is confirmed, the iSchedule Receiver delivers the scheduling message to the indicated recipients, collects and aggregates the delivery status for each recipient, and returns the result in the HTTP response body.

In the event of a processing error related to the overall request, iSchedule Receivers MUST return an error response as per Clause 8.3.

6.1.  iSchedule SRV Service Type

This specification adds an SRV service label for use with iSchedule:

6.2.  iSchedule Service TXT Records

When SRV RRs are used to advertise iSchedule services, it is also convenient to be able to specify a “context path” in the DNS to be retrieved at the same time. To enable that, this specification uses a TXT RR that follows the syntax defined in IETF RFC 6763, Section 6 and defines a “path” key for use in that record. The value of the key MUST be the actual “context path” to the corresponding service on the iSchedule Receiver.

A site might provide TXT records in addition to SRV records for the service. When present, iSchedule Senders MUST use the “path” value as the “context path” for the service in HTTP requests. When not present, iSchedule Senders use the “.well-known” URI approach described next.

6.3.  iSchedule Receiver Request-URI

This specification registers a well-known URI IETF RFC 5785 for the iSchedule service, namely, “ischedule” (see Clause 12.3.1). iSchedule Receivers MUST support requests targeted at this well-known URI. iSchedule Senders MUST handle HTTP redirects on this well-known URI.

7.1.  Example: Querying iSchedule Receiver Capabilities

GET /.well-known/ischedule?action=capabilities HTTP/1.1
Host: cal.example.com

>> Request <<

HTTP/1.1 200 OK
Date: Mon, 15 Dec 2008 09:32:12 GMT
Content-Type: application/xml; charset=utf-8
Content-Length: xxxx
iSchedule-Version: 1.0
iSchedule-Capabilities: 123
ETag: "afasdf-132afds"

<?xml version="1.0" encoding="utf-8" ?>
<query-result xmlns="urn:ietf:params:xml:ns:ischedule">
  <capabilities>
    <serial-number>123</serial-number>
    <versions>
      <version>1.0</version>
    </versions>
    <scheduling-messages>
      <component name="VEVENT">
        <method name="REQUEST"/>
        <method name="ADD"/>
        <method name="REPLY"/>
        <method name="CANCEL"/>
      </component>
      <component name="VTODO">
        <method name="REQUEST"/>
        <method name="ADD"/>
        <method name="REPLY"/>
        <method name="CANCEL"/>
      </component>
      <component name="VFREEBUSY">
        <method name="REQUEST"/>
      </component>
    </scheduling-messages>
    <calendar-data-types>
      <calendar-data-type
       content-type="text/calendar" version="2.0"/>
    </calendar-data-types>
    <attachments>
      <inline/>
      <external/>
    </attachments>
    <rscales>
      <rscale>GREGORIAN</rscale>
      <rscale>CHINESE</rscale>
    </rscales>
    <max-content-length>102400</max-content-length>
    <min-date-time>19910101T000000Z</min-date-time>
    <max-date-time>20381231T000000Z</max-date-time>
    <max-instances>150</max-instances>
    <max-recipients>250</max-recipients>
    <administrator>mailto:ischedule-admin@example.com</administrator>
  </capabilities>
</query-result>

>> Response <<

8.1.  POST Method

The POST method submits a scheduling message to one or more Recipients by targeting the request at the Request-URI of an iSchedule Receiver. The request body of a POST method MUST contain a scheduling message (i.e., an iCalendar object that follows the iTIP semantic).

The submitted scheduling message will be delivered to the Recipients, with status information about per-recipient delivery returned in the HTTP response. However, when the scheduling message is a request for free-busy time, the iSchedule Receiver will immediately execute the free-busy request for the Recipients and return per-recipient iCalendar data in the response for successful free-busy queries.

Every POST request MUST include the ”iSchedule-Version” general header.

Every POST request SHOULD include the ”iSchedule-Message-ID” request header.

Every POST request MUST include the “Cache-Control” HTTP general header containing the cache-directives “no-cache” and “no-transform” to prevent intermediary caches from caching or transforming responses.

Every POST request MUST include a single “Originator” request header that specifies the calendar user address of the Originator of the scheduling message. The value of the “Originator” request header MUST match the value of the “ORGANIZER” iCalendar property or one of the specified “ATTENDEE” iCalendar properties in the scheduling message, depending on the specified “METHOD” iCalendar property value as summarized in the following table:

Table 1

Every POST request MUST include one or more “Recipient” request headers. The value of this header is a list of one or more calendar user addresses and corresponds to the set of calendar users who will have the scheduling message delivered to them. The value of the “Recipient” request header MUST match the value of the “ORGANIZER” iCalendar property or one of the specified “ATTENDEE” iCalendar properties in the scheduling message, depending on the specified “METHOD” iCalendar property value as summarized in the following table:

Table 2

The Content-Type general header MUST include the type parameters “component” and “method” defined in IETF RFC 5545. The value of the “component” MUST correspond to the iCalendar component type (e.g., “VEVENT”) specified in the scheduling message. The value of the “method” parameter MUST be the same as the value of the “METHOD” iCalendar property in the scheduling message. If iCalendar data is returned in the response, within an IS:calendar-data XML element, then the media type of that data in the response MUST match the media type in the request.

8.2.  Schedule Response

A POST request may deliver a scheduling message to one or more calendar users specified in the Recipient request header. Since the behavior of each recipient may vary, it is useful to get response status information for each recipient in the overall POST response. This specification defines a new XML response to convey multiple recipient status.

A response to a POST method that indicates status for one or more recipients MUST be an XML document with IS:schedule-response as its root element. This MUST contain one or more response elements for each recipient, with each of those containing elements that indicate which recipient they correspond to, the scheduling status of the request for that recipient, any error codes and an optional description.

In the case of a free-busy request, the response elements can also contain calendar-data elements which contain free busy information (e.g., an iCalendar VFREEBUSY component) indicating the busy state of the corresponding recipient, assuming that the free-busy request for that recipient succeeded.

Every POST response MUST include the “Cache-Control” HTTP general header containing the cache-directives “no-cache” and “no-transform” to prevent intermediary caches from caching or transforming responses.

8.3.  Failed Schedule Response

When there is an overall, as opposed to per-recipient, failure of the POST request, the iSchedule Receiver SHOULD return an XML document with IS:error as its root element. The child elements of the IS:error element are used to indicate an error code and description, primarily meant for service administrators.

The following XML elements are error codes which can be used within an IS:error element to represent errors:

The following are examples of response codes one would expect to be used for this method. Note, however, that unless explicitly prohibited any 2/3/4/5xx series response code may be used in a response. Typically a 403 response code would be used when an XML document with an IS:error element as its root is also returned.

9.1.  iSchedule-Version General Header

The “iSchedule-Version” general header field MUST be specified by the iSchedule Sender on requests, and by the iSchedule Receiver on responses. It SHOULD be included in a response to any “OPTIONS *” HTTP request targeting the iSchedule Receiver, or any “OPTIONS” request on a resource supporting the iSchedule behaviors described in this specification (e.g., the .well-known resource or any resource that .well-known redirects to).

iSchedule-Version      = "iSchedule-Version" ":" OWS
                         iSchedule-Version-v
iSchedule-Version-v    = iSchedule-Version-elem
                         *( OWS "," OWS iSchedule-Version-elem )
iSchedule-Version-elem =  1*DIGIT "." 1*DIGIT

9.2.  iSchedule-Capabilities Response Header

The “iSchedule-Capabilities” response header field MUST be specified by the iSchedule Receiver on all responses. iSchedule Senders SHOULD cache this value and use it to detect a change in the iSchedule Receiver capabilities that cause the iSchedule Sender to reload capabilities. The value of this header is maintained by the iSchedule Receiver as described in Clause 10.2.1.1.

iSchedule-Capabilities = "iSchedule-Capabilities" ":" OWS 1*DIGIT

9.3.  iSchedule-Message-ID Request Header

The “iSchedule-Message-ID” request header field SHOULD be specified by the iSchedule Sender on requests. This header provides a unique identifier that refers to the specific iSchedule request in which it is included. The uniqueness of this identifier is guaranteed by the iSchedule Sender that generates it. This identifier is intended to be machine readable and not necessarily meaningful to humans.

iSchedule-Message-ID   = "iSchedule-Message-ID" ":" OWS token

9.4.  Originator Request Header

The “Originator” request header value is a URI which specifies the calendar user address of the originator of the scheduling message. Note that the absoluteURI rule is defined in IETF RFC 3986.

Originator   = "Originator" ":" OWS Originator-v
Originator-v = absoluteURI

9.5.  Recipient Request Header

The “Recipient” request header value is a URI which specifies the calendar user address of the recipients to which the POST method should deliver the submitted scheduling message. Note that the absoluteURI rule is defined in IETF RFC 3986.

Recipient      = "Recipient" ":" OWS Recipient-v
Recipient-v    = Recipient-elem *( OWS "," OWS Recipient-elem )
Recipient-elem = absoluteURI

10.1.  schedule-response XML Element

10.2.  query-result XML Element

11.1.  Privacy

iSchedule Senders and iSchedule Receivers MUST use an HTTP connection protected with TLS IETF RFC 5246 as defined in IETF RFC 2818 for all transactions.

11.2.  Authentication

11.3.  DNS Considerations

DNS security issues are addressed by DNSSEC IETF RFC 4033.

11.4.  Attachment Considerations

iCalendar data can include “inline” attachment data in the form of a base64-encoded “ATTACH” property value. iSchedule Receivers MUST take care when allowing “inline” attachments in scheduling messages as such data might contain malicious content, and SHOULD use some form of content scanner on the attachment data to verify its safety (e.g., a content scanner used for email messages). In addition, “inline” attachment data is likely to be much larger than the actual calendar-related data in a scheduling message, and thus could adversely affect the performance of an iSchedule Receiver processing it. If an iSchedule Receiver allows “inline” attachment data, it MUST apply a limit on the size of acceptable scheduling messages to prevent possible denial-of-service attacks using large “inline” attachment data. In general, it is best for iSchedule Receivers to simply disable the ability for scheduling messages to contain “inline” attachment data, and instead rely solely on “external” attachments in the form of URI attachment values.

12.1.  Namespace Registration

This specification registers a new URN to identify a new XML namespace as per IETF RFC 3688.

12.2.  HTTP Headers Registration

This specification registers new headers for use with HTTP as per IETF RFC 3864.

12.3.  Well-Known URI Registration

This specification registers a new well-known URI as per IETF RFC 5785.