Abstract

This document describes a RESTful web service for calendar access and update.

Foreword

This document incorporates by reference the CalConnect Intellectual Property Rights, Appropriate Usage, Trademarks and Disclaimer of Warranty for External (Public) Documents as located at

http://www.calconnect.org/documents/disclaimerpublic.pdf.

This document was editorially updated to ensure synchronization with the OASIS WS-Calendar publication of CalWS-SOAP as V1.0 for public review and contains the same content.

http://creativecommons.org/licenses/by/3.0/.

Chair(s)

Michael A Douglass, Paul Tischhauser

Related work

This specification is related to:

https://datatracker.ietf.org/idtracker/draft-daboo-et-al-icalendar-in-xml

Introduction

The CalWS protocol is built upon and makes the same assumptions about structure as the CalDAV protocol defined in IETF RFC 4791 and related specifications. It does NOT require nor assume the WebDAV nor CalDAV protocol but does make use of some of the same elements and structures in the CalDAV XML namespace.

Calendar resources, for example events and tasks are stored as named resources (files) inside special collections (folders) known as “ Calendar Collections”.

This specification can be looked upon as a layer built on top of CalDAV and defines the basic operations which allow creation, retrieval, update and deletion. In addition, query and freebusy operations are defined to allow efficient, partial retrieval of calendar data.

This does not mean that a CalWS service must be built on CalDAV, merely that a degree of conformity is established such that services built in that manner do not have a significant mismatch. It is assumed that some CalWS services will be built without any CalDAV support.

Terminology

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this specification are to be interpreted as described in IETF RFC 2119.

Namespace

Declared XML Namespace(s): http://docs.oasis-open.org/ns/wscal/calws
Declared Properties and Relations Namespaces: Properties and extended relation types are prefixed with the URL http://docs.oasis-open.org/ns/wscal/calwsrel

1. Normative references

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

IETF RFC 2119, S. BRADNER. Key words for use in RFCs to Indicate Requirement Levels. 1997. RFC Publisher. https://www.rfc-editor.org/info/rfc2119.

IETF RFC 2616, R. FIELDING, J. GETTYS, J. MOGUL, H. FRYSTYK, L. MASINTER, P. LEACH and T. BERNERS-LEE. Hypertext Transfer Protocol — HTTP/1.1. 1999. RFC Publisher. https://www.rfc-editor.org/info/rfc2616.

IETF RFC 3339, G. KLYNE and C. NEWMAN. Date and Time on the Internet: Timestamps. 2002. RFC Publisher. https://www.rfc-editor.org/info/rfc3339.

IETF RFC 4791, C. DABOO, B. DESRUISSEAUX and L. DUSSEAULT. Calendaring Extensions to WebDAV (CalDAV). 2007. RFC Publisher. https://www.rfc-editor.org/info/rfc4791.

IETF RFC 4918, L. DUSSEAULT (ed.). HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV). 2007. RFC Publisher. https://www.rfc-editor.org/info/rfc4918.

IETF RFC 5545, B. DESRUISSEAUX (ed.). Internet Calendaring and Scheduling Core Object Specification (iCalendar). 2009. RFC Publisher. https://www.rfc-editor.org/info/rfc5545.

IETF RFC 5546, C. DABOO (ed.). iCalendar Transport-Independent Interoperability Protocol (iTIP). 2009. RFC Publisher. https://www.rfc-editor.org/info/rfc5546.

Internet-Draft draft-daboo-et-al-icalendar-in-xml-11, MIKE DOUGLASS, CYRUS DABOO and STEVEN LEES. xCal: The XML Format for iCalendar. 2011. https://datatracker.ietf.org/doc/html/draft-daboo-et-al-icalendar-in-xml-11.

Internet-Draft draft-nottingham-http-link-header-10, MARK NOTTINGHAM. Web Linking. 2010. https://datatracker.ietf.org/doc/html/draft-nottingham-http-link-header-10.

CC/S 0903:2009, Freebusy Read URL V1.0 (CD 0903). https://standards.calconnect.org/pubdocs/CD0903%20Freebusy%20Read%20URL%20V1.0.pdf.

XRD-1.0, E. Hammer, W. Norris, Extensible Resource Descriptor (XRD) Version 1.0, http://docs.oasis-open.org/xri/xrd/v1.0/xrd-1.0.html

CalWS-Rest - Restful Web Services Protocol for Calendaring

2. Issues not addressed by this specification

A number of issues are not addressed by this version of the specification, either because they should be addressed elsewhere or will be addressed at some later date.

2.1. Access Control

It is assumed that the targeted server will set an appropriate level of access based on authentication. This specification will not attempt to address the issues of sharing or ACLs.

2.2. Provisioning

The protocol will not provide any explicit provisioning operations. If it is possible to authenticate or address a principals calendar resources then they MUST be automatically created if necessary or appropriate

2.3. Copy/Move

These operations are not yet defined for this version of the CalWS protocol. Both operations raise a number of issues. In particular implementing a move operation through a series of retrievals, insertions and deletions may cause undesirable side-effects. Both these operations will be defined in a later version of this specification.

2.4. Creating Collections

We will not address the issue of creating collections within the address space. The initial set is created by provisioning.

2.5. Retrieving collections

This operation is currently undefined. A GET on a collection may fail or return a complete calendar object representing the collection.

2.6. Setting service and resource properties.

These operations are not defined in this version of the specification. In the future it will be possible to define or set the properties for the service or resources within the service.

3. CalWS Glossary

3.1. Hrefs

An href is a URI reference to a resource, for example

"http://example.org/user/fred/calendar/event1.ics".

The URL above reflects a possible structure for a calendar server. All URLs should be absolute or path-absolute following the rules defined in IETF RFC 4918, Section 8.3.

3.2. Calendar Object Resource

A calendar object resource is an event, meeting or a task. Attachments are resources but NOT calendar object resources. An event or task with overrides is a single calendar resource entity.

3.3. Calendar Collection

A folder only allowed to contain calendar object resources.

3.4. Scheduling Calendar Collection

A folder only allowed to contain calendar resources which is also used for scheduling operations. Scheduling events placed in such a collection will trigger implicit scheduling activity on the server.

3.5. Principal Home

The collection under which all the resources for a given principal are stored. For example, for principal “fred” the principal home might be “/user/fred/”

4. Overview of the CalWS protocol

The protocol is an HTTP based RESTful protocol using a limited set of methods. Each request may be followed by a response containing status information.

4.1. HTTP Methods

The following methods are specified in the protocol description, PUT, POST, GET, DELETE. To avoid various issues with certain methods being blocked clients may use the X-HTTP-Method-Override: header to specify the intended operation. Servers SHOULD behave as if the named method was used.

POST /user/fred/calendar/ HTTP/1.1
...
X-HTTP-Method-Override: PUT

4.2. Properties

A service or resource will have a number of properties which describe the current state of that service or resource. These properties are accessed through a GET on the target resource or service with an ACCEPT header specifying application/xrd+xml. See Clause 7.

4.3. Operations

The following operations are defined by this specification:

Retrieval and update of service and resource properties
Creation of a calendar object
Retrieval of a calendar object
Update of a calendar object
Deletion of a calendar object
Query
Free-busy query

4.4. Calendar Object Resources

The same restrictions apply to Calendar Object Resources as specified in CalDAV IETF RFC 4791, Section 4.2. An additional constraint for CalWS is that no timezone specifications are transferred.

4.5. Timezone information

It is assumed that the client and server each have access to a full set of up to date timezone information. Timezones will be referenced by a timezone identifier from the full set of Olson data together with a set of well-known aliases defined [where?]. CalWS services may advertise themselves as timezone servers through the server properties object.

5. Error conditions

Each operation on the calendar system has a number of pre-conditions and post-conditions that apply.

A “precondition” for a method describes the state of the server that must be true for that method to be performed. A “postcondition” of a method describes the state of the server that must be true after that method has been completed. Any violation of these conditions will result in an error response in the form of a CalWS XML error element containing the violated condition and an optional description.

Each method specification defines the preconditions that must be satisfied before the method can succeed. A number of postconditions are generally specified which define the state that must exist after the execution of the operation. Preconditions and postconditions are defined as error elements in the CalWS XML namespace.

5.1. Example: error with CalDAV error condition

<?xml version="1.0" encoding="utf-8"
  xmlns:CW="http://docs.oasis-open.org/ns/wscal/calws""
  xmlns:C="urn:ietf:params:xml:ns:caldav" ?>
<CW:error>
  <C:supported-filter>
    <C:prop-filter name="X-ABC-GUID"/>
  </C:supported-filter>
  <CW:description>Unknown property </CW:description>
</CW:error>

6. Properties and link relations

6.1. Property and relation-type URIs

In the XRD entity returned properties and related services and entities are defined by absolute URIs which correspond to the extended relation type defined in Internet-Draft draft-nottingham-http-link-header-10, Section 4.2. These URIs do NOT correspond to any real entity on the server and clients should not attempt to retrieve any data at that target.

Certain of these property URIs correspond to CalDAV preconditions. Each URL is prefixed by the CalWS relations and properties namespace http://docs.oasis-open.org/ns/wscal/calws. Those properties which correspond to CalDAV properties have the additional path element “ caldav/”, for example

http://docs.oasis-open.org/ns/wscal/calws/caldav/supported-calendar-data

corresponds to

CalDAV:supported-calendar-data

In addition to those CalDAV properties, the CalWS specification defines a number of other properties and link relations with the URI prefix of http://docs.oasis-open.org/ns/wscal/calws.

6.2. `supported-features` property

http://docs.oasis-open.org/ns/wscal/calws/supported-features

This property defines the features supported by the target. All resources contained and managed by the service should return this property. The value is a comma separated list containing one or more of the following

calendar-access — the service supports all MUST requirements in this specification

<Property type="http://docs.oasis-open.org/ns/wscal/calws/supported-features">calendar-access</Property>

6.3. `max-attendees-per-instance`

http://docs.oasis-open.org/ns/wscal/calws/max-attendees-per-instance

Defines the maximum number of attendees allowed per event or task.

6.4. `max-date-time`

http://docs.oasis-open.org/ns/wscal/calws/max-date-time

Defines the maximum date/time allowed on an event or task

6.5. `max-instances`

http://docs.oasis-open.org/ns/wscal/calws/max-instances

Defines the maximum number of instances allowed per event or task

6.6. `max-resource-size`

http://docs.oasis-open.org/ns/wscal/calws/max-resource-size

Provides a numeric value indicating the maximum size of a resource in octets that the server is willing to accept when a calendar object resource is stored in a calendar collection.

6.7. `min-date-time`

http://docs.oasis-open.org/ns/wscal/calws/min-date-time

Provides a DATE-TIME value indicating the earliest date and time (in UTC) that the server is willing to accept for any DATE or DATE-TIME value in a calendar object resource stored in a calendar collection.

6.8. `description`

http://docs.oasis-open.org/ns/wscal/calws/description

Provides some descriptive text for the targeted collection.

6.9. `timezone-service` relation

http://docs.oasis-open.org/ns/wscal/calws/timezone-service

The location of a timezone service used to retrieve timezone information and specifications. This may be an absolute URL referencing some other service or a relative URL if the current server also provides a timezone service.

<Link rel="http://docs.oasis-open.org/ns/wscal/calws/calws/timezone-service"
           href="http://example.com/tz" />

6.10. `principal-home` relation

http://docs.oasis-open.org/ns/wscal/calws/principal-home

Provides the URL to the user home for the currently authenticated principal.

<Link rel="http://docs.oasis-open.org/ns/wscal/calws/principal-home"
           href="http://example.com/user/fred" />

6.11. `current-principal-freebusy` relation

http://docs.oasis-open.org/ns/wscal/calws/current-principal-freebusy

Provides the URL to use as a target for freebusy requests for the current authenticated principal.

<Link rel="http://docs.oasis-open.org/ns/wscal/calws/current-principal-freebusy"
           href="http://example.com/freebusy/user/fred" />

6.12. `principal-freebusy` relation

http://docs.oasis-open.org/ns/wscal/calws/principal-freebusy

Provides the URL to use as a target for freebusy requests for a different principal.

<Link rel="http://docs.oasis-open.org/ns/wscal/calws/principal-freebusy"
           href="http://example.com/freebusy" />

6.13. `child-collection` relation

http://docs.oasis-open.org/ns/wscal/calws/child-collection

Provides information about a child collections for the target. The href attribute gives the URI of the collection. The element should only have CalWS child elements giving the type of the collection, that is the CalWS:collection link property and the CalWS-calendar-collection link property. This allows clients to determine the structure of a hierarchical system by targeting each of the child collections in turn.

The xrd:title child element of the link element provides a description for the child-collection.

<Link rel="http://http://docs.oasis-open.org/ns/wscal/calws/child-collection"
           href="http://example.com/calws/user/fred/calendar">
  <Title xml:lang="en">Calendar</Title>
  <Property type="http://docs.oasis-open.org/ns/wscal/calws/collection"
            xsi:nil="true" />
  <Property type="http://docs.oasis-open.org/ns/wscal/calws/calendar-collection"
            xsi:nil="true" />
</Link>

6.14. `created` link property

http://docs.oasis-open.org/ns/wscal/calws/created

Appears within a link relation describing collections or entities. The value is a date-time as defined in IETF RFC 3339, Section 5.6.

<Property type="http://docs.oasis-open.org/ns/wscal/calws/created">1985-04-12T23:20:50.52Z</Property>

6.15. `last-modified` property

http://docs.oasis-open.org/ns/wscal/calws/last-modified

Appears within an xrd object describing collections or entities. The value is the same format as would appear in the Last-Modified header and is defined in IETF RFC 2616, Section 3.3.1

<Property type="http://docs.oasis-open.org/ns/wscal/calws/last-modified">Mon, 12 Jan 1998 09:25:56 GMT</Property>

6.16. `displayname` property

http://docs.oasis-open.org/ns/wscal/calws/displayname

Appears within an xrd object describing collections or entities. The value is a localized name for the entity or collection.

<Property type="http://docs.oasis-open.org/ns/wscal/calws/displayname">My Calendar</Property>

6.17. `timezone` property

http://docs.oasis-open.org/ns/wscal/calws/timezone

Appears within an xrd object describing collections. The value is a text timezone identifier.

<Property type="http://docs.oasis-open.org/ns/wscal/calws/timezone">America/New_York</Property>

6.18. `owner` property

http://docs.oasis-open.org/ns/wscal/calws/owner

Appears within an xrd object describing collections or entities. The value is a server specific uri.

<Property type="http://docs.oasis-open.org/ns/wscal/calws/owner">/principals/users/mike</Property>

6.19. `collection` link property

http://docs.oasis-open.org/ns/wscal/calws/collection

Appears within a link relation describing collections or entities. The property takes no value and indicates that this child element is a collection.

<Property type="http://docs.oasis-open.org/ns/wscal/calws/collection"
          xsi:nil="true" />

6.20. `calendar-collection` link property

http://docs.oasis-open.org/ns/wscal/calws/calendar-collection

Appears within a link relation describing collections or entities. The property takes no value and indicates that this child element is a calendar collection.

<Property type="http://docs.oasis-open.org/ns/wscal/calws/calendar-collection"
          xsi:nil="true" />

6.21. `CalWS:privilege-set` XML element

http://docs.oasis-open.org/ns/wscal/calws:privilege-set

Appears within a link relation describing collections or entities and specifies the set of privileges allowed to the current authenticated principal for that collection or entity.

<!ELEMENT calws:privilege-set (calws:privilege*)>
<!ELEMENT calws:privilege ANY>

Each privilege element defines a privilege or access right. The following set is currently defined

CalWS: Read — current principal has read access
CalWS: Write — current principal has write access

<calWS:privilege-set>
  <calWS:privilege><calWS:read></calWS:privilege>
  <calWS:privilege><calWS:write></calWS:privilege>
</calWS:privilege-set>

7. Retrieving Collection and Service Properties

Properties, related services and locations are obtained from the service or from service resources in the form of an XRD document as defined by XRD-1.0.

Given the URL of a CalWS service a client retrieves the service XRD document through a GET on the service URL with an ACCEPT header specifying application/xrd+xml.

Retrieving resource properties is identical to obtaining service properties, that is, execute a GET on the target URL with an ACCEPT header specifying application/xrd+xml.

The service properties define the global limits and defaults. Any properties defined on collections within the service hierarchy override those service defaults. The service may choose to prevent such overriding of defaults and limits when appropriate.

7.1. Request parameters

None

7.2. Responses

200: OK
403: Forbidden
404: Not found

7.3. Example — retrieving server properties

>>Request

GET / HTTP/1.1
Host: example.com
ACCEPT:application/xrd+xml

>>Response
<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Expires>1970-01-01T00:00:00Z</Expires>
  <Subject>http://example.com/calws</Subject>
  <Property type="http://docs.oasis-open.org/ns/wscal/calws/created">1970-01-01</Property>

  <Link rel="http://docs.oasis-open.org/ns/wscal/calws/timezone-service"
        href="http://example.com/tz" />

  <calWS:privilege-set>
    <calWS:privilege><calWS:read></calWS:privilege>
  </calWS:privilege-set>

  <Link rel="http://docs.oasis-open.org/ns/wscal/calws/principal-home"
        type="collection"
        href="http://example.com/calws/user/fred">
    <Title xml:lang="en">Fred's calendar home</Title>
  </Link>

  <Link rel="http://docs.oasis-open.org/ns/wscal/calws/child-collection"
        type="calendar,scheduling"
        href="http://example.com/calws/user/fred/calendar">
    <Title xml:lang="en">Calendar</Title>
  </Link>

  <Property type="http://docs.oasis-open.org/ns/wscal/calws/max-instances">1000</Property>

  <Property type="http://docs.oasis-open.org/ns/wscal/calws/max-attendees-per-instance">100</Property>
    ...
</XRD>

8. Creating Calendar Object Resources

Creating calendar object resources is carried out by a POST on the parent collection. The body of the request will contain the resource being created. The request parameter “action=create” indicates this POST is a create. The location header of the response gives the URL of the newly created object.

8.1. Request parameters

action=create

8.2. Responses

201: created
403: Forbidden — no access

8.3. Preconditions for Calendar Object Creation

CalWS:target-exists: The target of a PUT must exist. Use POST to create entities and PUT to update them.
CalWS:not-calendar-data: The resource submitted in the PUT request, or targeted by a COPY or MOVE request, MUST be a supported media type (i.e., iCalendar) for calendar object resources;
CalWS:invalid-calendar-data: The resource submitted in the PUT request, or targeted by a COPY or MOVE request, MUST be valid data for the media type being specified (i.e., MUST contain valid iCalendar data);
CalWS:invalid-calendar-object-resource: The resource submitted in the PUT request, or targeted by a COPY or MOVE request, MUST obey all restrictions specified in Calendar Object Resources (e.g., calendar object resources MUST NOT contain more than one type of calendar component, calendar object resources MUST NOT specify the iCalendar METHOD property, etc.);
CalWS:unsupported-calendar-component: The resource submitted in the PUT request, or targeted by a COPY or MOVE request, MUST contain a type of calendar component that is supported in the targeted calendar collection;
CalWS:uid-conflict: The resource submitted in the PUT request, or targeted by a COPY or MOVE request, MUST NOT specify an iCalendar UID property value already in use in the targeted calendar collection or overwrite an existing calendar object resource with one that has a different UID property value. Servers SHOULD report the URL of the resource that is already making use of the same UID property value in the CalWS:href element
```
<!ELEMENT uid-conflict (CalWS:href)>
```
CalWS:invalid-calendar-collection-location: In a COPY or MOVE request, when the Request- URI is a calendar collection, the Destination-URI MUST identify a location where a calendar collection can be created;
CalWS:exceeds-max-resource-size: The resource submitted in the PUT request, or targeted by a COPY or MOVE request, MUST have an octet size less than or equal to the value of the CalDAV:max-resource-size property value on the calendar collection where the resource will be stored;
CalWS:before-min-date-time: The resource submitted in the PUT request, or targeted by a COPY or MOVE request, MUST have all of its iCalendar DATE or DATE-TIME property values (for each recurring instance) greater than or equal to the value of the CalDAV:min-date-time property value on the calendar collection where the resource will be stored;
CalWS:after-max-date-time: The resource submitted in the PUT request, or targeted by a COPY or MOVE request, MUST have all of its iCalendar DATE or DATE-TIME property values (for each recurring instance) less than the value of the CalDAV:max-date-time property value on the calendar collection where the resource will be stored;
CalWS:too-many-instances: The resource submitted in the PUT request, or targeted by a COPY or MOVE request, MUST generate a number of recurring instances less than or equal to the value of the CalDAV:max-instances property value on the calendar collection where the resource will be stored;
CalWS:too-many-attendees-per-instance: The resource submitted in the PUT request, or targeted by a COPY or MOVE request, MUST have a number of ATTENDEE properties on any one instance less than or equal to the value of the CalDAV:max-attendees-per-instance property value on the calendar collection where the resource will be stored;

8.4. Example — successful `POST`

>>Request

POST /user/fred/calendar/?action=create HTTP/1.1
Host: example.com
Content-Type: application/xml+calendar; charset="utf-8"
Content-Length: ?

<?xml version="1.0" encoding="utf-8" ?>
<icalendar xmlns="urn:ietf:params:xml:ns:icalendar-2.0">
  <vcalendar>
  ...
  </vcalendar>
</icalendar>

>>Response

HTTP/1.1 201 Created
Location: http://example.com/user/fred/calendar/event1.ics

8.5. Example — unsuccessful `POST`

>>Request

POST /user/fred/readcalendar/?action=create HTTP/1.1
Host: example.com
Content-Type: text/text; charset="utf-8"
Content-Length: ?

This is not an xml calendar object

>>Response

HTTP/1.1 403 Forbidden
  <?xml version="1.0" encoding="utf-8"
    xmlns:D="DAV:"
    xmlns:C="urn:ietf:params:xml:ns:caldav" ?>
<D:error>
    <C:supported-calendar-data/>
    <D:description>Not an icalendar object</C:description>
</D:error>

9. Retrieving resources

A simple GET on the href will return a named resource. If that resource is a recurring event or task with overrides, the entire set will be returned. The desired format is specified in the ACCEPT header. The default form is application/xml+calendar

9.1. Request parameters

none

9.2. Responses

200: OK
403: Forbidden — no access
406 The requested format specified in the accept header is not supported.

9.3. Example — successful fetch

>>Request

GET /user/fred/calendar/event1.ics HTTP/1.1
Host: example.com

>>Response

HTTP/1.1 200 OK
Content-Type: application/xml+calendar; charset="utf-8"
Content-Length: ?

<?xml version="1.0" encoding="utf-8" ?>
<icalendar xmlns="urn:ietf:params:xml:ns:icalendar-2.0">
  <vcalendar>
  ...
  </vcalendar>
</icalendar>

9.4. Example — unsuccessful fetch

>>Request

PUT /user/fred/calendar/noevent1.ics HTTP/1.1
Host: example.com

>>Response

HTTP/1.1 404 Not found

10. Updating resources

Resources are updated with the PUT method targeted at the resource href. The body of the request contains a complete new resource which effectively replaces the targeted resource. To allow for optimistic locking of the resource use the if-match header.

When updating a recurring event all overrides and master must be supplied as part of the content.

Preconditions as specified in Preconditions for Calendar Object Creation are applicable.

10.1. Responses

200: OK
304: Not modified — entity was modified by some other request
403: Forbidden — no access, does not exist etc. See error response

10.2. Example — successful update

>>Request

PUT /user/fred/calendar/event1.ics HTTP/1.1
Host: example.com
Content-Type: application/xml+calendar; charset="utf-8"
Content-Length: ?

<?xml version="1.0" encoding="utf-8" ?>
<icalendar xmlns="urn:ietf:params:xml:ns:icalendar-2.0">
  <vcalendar>
  ...
  </vcalendar>
</icalendar>

>>Response

HTTP/1.1 200 OK

10.3. Example — unsuccessful update

>>Request

PUT /user/fred/readcalendar/event1.ics HTTP/1.1
Host: example.com
Content-Type: application/xml+calendar; charset="utf-8"
Content-Length: ?

<?xml version="1.0" encoding="utf-8" ?>
<icalendar xmlns="urn:ietf:params:xml:ns:icalendar-2.0">
  <vcalendar>
  ...
  </vcalendar>
</icalendar>

>>Response

HTTP/1.1 403 Forbidden
Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx

<?xml version="1.0" encoding="utf-8"
  xmlns:D="DAV:"
  xmlns:CW="http://docs.oasis-open.org/ns/wscal/calws" ?>
<CW:error>
  <CW:target-exists/>
  <CW:description>Target of update must exist</C:description>
</CW:error>

11. Deletion of resources

Delete is defined in IETF RFC 2616, Section 9.7. In addition to conditions defined in that specification, servers must remove any references from the deleted resource to other resources. Resources are deleted with the DELETE method targeted at the resource URL. After a successful completion of a deletion a GET on that URL must result in a 404 — Not Found status.

11.1. Delete for Collections

Delete for collections may or may not be supported by the server. Certain collections are considered undeletable. On a successful deletion of a collection all contained resources to any depth must also be deleted.

11.2. Responses

200: OK
403: Forbidden — no access
404: Not Found

12. Querying calendar resources

Querying provides a mechanism by which information can be obtained from the service through possibly complex queries. A list of iCalendar properties can be specified to limit the amount of information returned to the client. A query takes the parts

Limitations on the data returned
Selection of the data
Optional timezone id for floating time calculations.

The current specification uses CalDAV multiget and calendar-query XML bodies as specified in IETF RFC 4791 with certain limitations and differences.

The POST method is used for all requests, the action being identified by the outer element.
While CalDAV servers generally only support IETF RFC 5545 and assume that as the default, the delivery format for CalWS will, by default, be Internet-Draft draft-daboo-et-al-icalendar-in-xml-11.
The CalDAV query allows the specification of a number of DAV properties. Specification of these properties, with the exception of DAV:getetag, is considered an error in CalWS.
The CalDAV:propnames element is invalid

With those differences, the CalDAV specification is the normative reference for this operation.

12.1. Limiting data returned

This is achieved by specifying one of the following

CalDAV:allprop return all properties (some properties are specified as not being part of the allprop set so are not returned)
CalDAV:prop An element which contains a list of properties to be returned. May only contain DAV:getetag and CalDAV:calendar-data

Of particular interest, and complexity, is the calendar-data property which can contain a time range to limit the range of recurrences returned and/or a list of calendar properties to return.

12.2. Pre/postconditions for calendar queries

The preconditions as defined in IETF RFC 4791, Section 7.8 apply here. CalDav errors may be reported by the service when preconditions or postconditions are violated.

12.3. Example: time range limited retrieval

This example shows the time-range limited retrieval from a calendar which results in 2 events, one a recurring event and one a simple non-recurring event.

>> Request <<

POST /user/fred/calendar/ HTTP/1.1
Host: calws.example.com
Depth: 1
Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx

<?xml version="1.0" encoding="utf-8" ?>
<C:calendar-query xmlns:D="DAV:"
  xmlns:C="urn:ietf:params:xml:ns:caldav">
  <D:prop>
    <D:getetag/>
    <C:calendar-data content-type="application/xml+calendar" >
      <C:comp name="VCALENDAR">
        <C:prop name="VERSION"/>
        <C:comp name="VEVENT">
          <C:prop name="SUMMARY"/>
          <C:prop name="UID"/>
          <C:prop name="DTSTART"/>
          <C:prop name="DTEND"/>
          <C:prop name="DURATION"/>
          <C:prop name="RRULE"/>
          <C:prop name="RDATE"/>
          <C:prop name="EXRULE"/>
          <C:prop name="EXDATE"/>
          <C:prop name="RECURRENCE-ID"/>
        </C:comp>
      </C:comp>
    </C:calendar-data>
  </D:prop>
  <C:filter>
    <C:comp-filter name="VCALENDAR">
      <C:comp-filter name="VEVENT">
        <C:time-range start="20060104T000000Z"
                      end="20060105T000000Z"/>
      </C:comp-filter>
    </C:comp-filter>
  </C:filter>
</C:calendar-query>

>> Response <<

HTTP/1.1 207 Multi-Status
Date: Sat, 11 Nov 2006 09:32:12 GMT
Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx

<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:"
               xmlns:C="urn:ietf:params:xml:ns:caldav">
  <D:response>
    <D:href>http://cal.example.com/bernard/work/abcd2.ics</D:href>
    <D:propstat>
      <D:prop>
        <D:getetag>"fffff-abcd2"</D:getetag>
        <C:calendar-data content-type="application/xml+calendar" >
          <xc:icalendar
            xmlns:xc="urn:ietf:params:xml:ns:icalendar-2.0">
    <xc:vcalendar>
      <xc:properties>
      <xc:calscale><text>GREGORIAN</text></xc:calscale>
      <xc:prodid>
        <xc:text>-//Example Inc.//Example Calendar//EN</xc:text>
      </xc:prodid>
        <xc:version><xc:text>2.0</xc:text></xc:version>
      </xc:properties>
      <xc:components>
        <xc:vevent>
          <xc:properties>
            <xc:dtstart>
              <xc:parameters>
                <xc:tzid>US/Eastern<xc:tzid>
              <xc:parameters>
              <xc:date-time>20060102T120000</xc:date-time>
            </xc:dtstart>
            <xc:duration><xc:duration>PT1H</xc:duration></xc:duration>
            <xc:summary>
              <xc:text>Event #2</xc:text>
            </xc:summary>
            <xc:uid>
              <xc:text>00959BC664CA650E933C892C@example.com</xc:text>
            </xc:uid>
            <xc:rrule>
              <xc:recur>
                <xc:freq>DAILY</xc:freq>
                <xc:count>5</xc:count>
              </xc:recur>
            </xc:rrule>
          </xc:properties>
        </xc:vevent>

        <xc:vevent>
          <xc:properties>
            <xc:dtstart>
              <xc:parameters>
                <xc:tzid>US/Eastern<xc:tzid>
              <xc:parameters>
              <xc:date-time>20060104T140000</xc:date-time>
            </xc:dtstart>
            <xc:duration><xc:duration>PT1H</xc:duration></xc:duration>
            <xc:summary>
              <xc:text>Event #2 bis</xc:text>
            </xc:summary>
            <xc:uid>
              <xc:text>00959BC664CA650E933C892C@example.com</xc:text>
            </xc:uid>
            <xc:recurrence-id>
              <xc:parameters>
                <xc:tzid>US/Eastern<xc:tzid>
              <xc:parameters>
              <xc:date-time>20060104T120000</xc:date-time>
            </xc:recurrence-id>
            <xc:rrule>
              <xc:recur>
                <xc:freq>DAILY</xc:freq>
                <xc:count>5</xc:count>
              </xc:recur>
            </xc:rrule>
          </xc:properties>
        </xc:vevent>

        <xc:vevent>
          <xc:properties>
            <xc:dtstart>
              <xc:parameters>
                <xc:tzid>US/Eastern<xc:tzid>
              <xc:parameters>
              <xc:date-time>20060106T140000</xc:date-time>
            </xc:dtstart>
            <xc:duration><xc:duration>PT1H</xc:duration></xc:duration>
            <xc:summary>
              <xc:text>Event #2 bis bis</xc:text>
            </xc:summary>
            <xc:uid>
              <xc:text>00959BC664CA650E933C892C@example.com</xc:text>
            </xc:uid>
            <xc:recurrence-id>
              <xc:parameters>
                <xc:tzid>US/Eastern<xc:tzid>
              <xc:parameters>
              <xc:date-time>20060106T120000</xc:date-time>
            </xc:recurrence-id>
            <xc:rrule>
              <xc:recur>
                <xc:freq>DAILY</xc:freq>
                <xc:count>5</xc:count>
              </xc:recur>
            </xc:rrule>
          </xc:properties>
        </xc:vevent>
      </xc:components>
    </xc:vcalendar>
  </xc:icalendar>
            </C:calendar-data>
          </D:prop>
          <D:status>HTTP/1.1 200 OK</D:status>
        </D:propstat>
      </D:response>
      <D:response>
        <D:href>http://cal.example.com/bernard/work/abcd3.ics</D:href>
        <D:propstat>
          <D:prop>
            <D:getetag>"fffff-abcd3"</D:getetag>
            <C:calendar-data content-type="application/xml+calendar" >
              <xcal:icalendar
                xmlns:xc="urn:ietf:params:xml:ns:icalendar-2.0">
    <xc:vcalendar>
      <xc:properties>
        <xc:calscale><text>GREGORIAN</text></xc:calscale>
        <xc:prodid>
          <xc:text>-//Example Inc.//Example Calendar//EN</xc:text>
        </xc:prodid>
        <xc:version><xc:text>2.0</xc:text></xc:version>
      </xc:properties>
      <xc:components>
        <xc:vevent>
          <xc:properties>
            <xc:dtstart>
              <xc:parameters>
                <xc:tzid>US/Eastern<xc:tzid>
              <xc:parameters>
              <xc:date-time>20060104T100000</xc:date-time>
            </xc:dtstart>
            <xc:duration><xc:duration>PT1H</xc:duration></xc:duration>
            <xc:summary>
              <xc:text>Event #3</xc:text>
            </xc:summary>
            <xc:uid>
              <xc:text>DC6C50A017428C5216A2F1CD@example.com</xc:text>
            </xc:uid>
            <xc:rrule>
              <xc:recur>
                <xc:freq>DAILY</xc:freq>
                <xc:count>5</xc:count>
              </xc:recur>
            </xc:rrule>
          </xc:properties>
        </xc:vevent>
      </xc:components>
    </xc:vcalendar>
  </xc:icalendar>
        </C:calendar-data>
      </D:prop>
      <D:status>HTTP/1.1 200 OK</D:status>
    </D:propstat>
  </D:response>
</D:multistatus>

13. Free-busy queries

Freebusy queries are used to obtain freebusy information for a calendar-collection or principals. The result contains information only for events to which the current principal has sufficient access.

When targeted at a calendar collection the result is based only on the calendaring entities contained in that collection. When targeted at a principal freebusy URL the result will be based on all information which affect the principals freebusy status, for example availability.

The possible targets are:

A calendar collection URL
The XRD link with relation CalWS/current-principal-freebusy
The XRD link with relation CalWS/principal-freebusy with a principal given in the request.

The query follows the specification defined in CC/S 0903:2009 with certain limitations. As an authenticated user to the CalWS service scheduling read-freebusy privileges must have been granted. As an unauthenticated user equivalent access must have been granted to unauthenticated access.

Freebusy information is returned by default as xcalendar VFREEBUSY components, as defined by Internet-Draft draft-daboo-et-al-icalendar-in-xml-11. Such a component is not meant to conform to the requirements of VFREEBUSY components in IETF RFC 5546. The VFREEBUSY component SHOULD conform to section “4.6.4 Free/Busy Component” of IETF RFC 5545. A client SHOULD ignore the ORGANIZER field.

Since a Freebusy query can only refer to a single user, a client will already know how to match the result component to a user. A server MUST only return a single VFREEBUSY component.

13.1. `ACCEPT` header

The Accept header is used to specify the format for the returned data. In the absence of a header the data should be returned as specified in Internet-Draft draft-daboo-et-al-icalendar-in-xml-11, that is, as if the following had been specified

ACCEPT: application/xml+calendar

13.2. URL Query Parameters

None of these parameters are required except for the conditions noted below. Appropriate defaults will be supplied by the server.

13.2.1. `start`

Default

The default value is left up to the server. It may be the current day, start of the current month, etc.

Description

Specifies the start date for the Freebusy data. The server is free to ignore this value and return data in any time range. The client must check the data for the returned time range.

Format

A profile of an IETF RFC 3339 Date/Time. Fractional time is not supported. The server MUST support the expanded version e.g.

2007-01-02T13:00:00-08:00

It is up to the server to interpret local date/times.

EXAMPLE

2007-02-03T15:30:00-0800
2007-12-01T10:15:00Z

NOTE Specifying only a start date/time without specifying an end-date/time or period should be interpreted as in IETF RFC 5545. The effective period should cover the remainder of that day.

Date-only values are disallowed as the server cannot determine the correct start of the day. Only UTC or date/time with offset values are permitted.

13.2.2. `end`

Default: Same as start
Description: Specifies the end date for the Freebusy data. The server is free to ignore this value.
Format: Same as start
Example: Same as start

13.2.3. `period`

Default: The default value is left up to the server. The recommended value is “P42D”.
Description: Specifies the amount of Freebusy data to return. A client cannot specify both a period and an end date. Period is relative to the start parameter.
Format: A duration as defined in IETF RFC 5545, Section 4.3.6

EXAMPLE

P42D

13.2.4. `account`

Default: none
Description: Specifies the principal when the request is targeted at the XRD CalWS/principal-freebusy. Specification of this parameter is an error otherwise.
Format: Server specific

EXAMPLE

fred
/principals/users/jim
user1@example.com

13.3. URL parameters — notes

The server is free to ignore the start, end and period parameters. It is recommended that the server return at least 6 weeks of data from the current day.

A client MUST check the time range in the VFREEBUSY response as a server may return a different time range than the requested range.

13.4. HTTP Operations

The server SHOULD return an Etag response header for a successful GET request targeting a Freebusy read URL. Clients MAY use the Etag response header value to do subsequent “conditional” GET requests that will avoid re-sending the Freebusy data again if it has not changed.

13.5. Response Codes

Below are the typical status codes returned by a GET request targeting a Freebusy URL. Note that other HTTP status codes not listed here might also be returned by a server.

200 OK
302 Redirect
400 Start parameter could not be understood / End parameter could not be understood / Period parameter could not be understood
401 Unauthorized
403 Forbidden
404 The data for the requested principal is not currently available, but may be available later.
406 The requested format in the accept header is not supported.
410 The data for the requested principal is no longer available
500 General server error

13.6. Examples

The following are examples of URLs used to retrieve Freebusy data for a user:

EXAMPLE 1

http://www.example.com/freebusy/user1@example.com?
start=2007-09-01T00:00:00-08:00&end=2007-09-31T00:00:00-08:00

http://www.example.com/freebusy/user1@example.com?
start=2007-09-01T00:00:00-08:00&end=2007-09-31T00:00:00-08:00

http://www.example.com/freebusy/user1@example.com

http://www.example.com/freebusy?user=user%201@example.com&
start=2008-01-01T00:00:00Z&end=2008-12-31T00:00:00Z

Some Request/Response Examples:

EXAMPLE 2 — A URL with no query parameters

>> Request <<
GET /freebusy/bernard/ HTTP/1.1
Host: www.example.com

>> Response <<
HTTP/1.1 200 OK
Content-Type: application/xml+calendar; charset="utf-8"
Content-Length: xxxx

<xc:icalendar xmlns:xc="urn:ietf:params:xml:ns:icalendar-2.0">
  <xc:vcalendar>
    <xc:properties>
      <xc:calscale><text>GREGORIAN</text></xc:calscale>
      <xc:prodid>
        <xc:text>-//Example Inc.//Example Calendar//EN</xc:text>
      </xc:prodid>
      <xc:version><xc:text>2.0</xc:text></xc:version>
    </xc:properties>
    <xc:components>
      <xc:vfreebusy>
        <xc:properties>
          <xc:uid>
            <xc:text>76ef34-54a3d2@example.com</xc:text>
          </xc:uid>
          <xc:dtstart>
            <xc:date-time>20060101T000000Z</xc:date-time>
          </xc:dtstart>
          <xc:dtend>
            <xc:date-time>20060108T000000Z</xc:date-time>
          </xc:dtend>
          <xc:dtstamp>
            <xc:date-time>20050530T123421Z</xc:date-time>
          </xc:dtstamp>
          <xc:freebusy>
            <xc:parameters>
              <xc:fbtype>BUSYTENTATIVE<xc:fbtype>
            <xc:parameters>
            <xc:period>20060102T100000Z/20060102T120000Z</xc:period>
          </xc:freebusy>
          <xc:freebusy>
            <xc:period>20060103T100000Z/20060103T120000Z</xc:period>
          </xc:freebusy>
          <xc:freebusy>
            <xc:period>20060104T100000Z/20060104T120000Z</xc:period>
          </xc:freebusy>
          <xc:freebusy>
            <xc:parameters>
              <xc:fbtype>BUSYUNAVAILABLE<xc:fbtype>
            <xc:parameters>
            <xc:period>20060105T100000Z/20060105T120000Z</xc:period>
          </xc:freebusy>
          <xc:freebusy>
            <xc:period>20060106T100000Z/20060106T120000Z</xc:period>
          </xc:freebusy>
        </xc:vfreebusy>
      </xc:components>
    </xc:vcalendar>
<xc:icalendar>

EXAMPLE 3 — A URL with start and end parameters

>> Request <<
GET /freebusy/user1@example.com?start=2007-09-01T00:00:00-08:00&end=2007-09-31T00:00:00-
08:00
HTTP/1.1
Host: www.example.com

>> Response <<
HTTP/1.1 200 OK
Content-Type: application/xml+calendar; charset="utf-8"
Content-Length: xxxx

<xc:icalendar xmlns:xc="urn:ietf:params:xml:ns:icalendar-2.0">
  <xc:vcalendar>
    <xc:properties>
       <xc:calscale><text>GREGORIAN</text></xc:calscale>
       <xc:prodid>
         <xc:text>-//Example Inc.//Example Calendar//EN</xc:text>
       </xc:prodid>
       <xc:version><xc:text>2.0</xc:text></xc:version>
     </xc:properties>
     <xc:components>
       <xc:vfreebusy>
         <xc:properties>
           <xc:uid>
             <xc:text>76ef34-54a3d2@example.com</xc:text>
           </xc:uid>
           <xc:dtstart>
             <xc:date-time>20070901T000000Z</xc:date-time>
           </xc:dtstart>
           <xc:dtend>
             <xc:date-time>20070931T000000Z</xc:date-time>
           </xc:dtend>
           <xc:dtstamp>
             <xc:date-time>20050530T123421Z</xc:date-time>
           </xc:dtstamp>
           <xc:freebusy>
             <xc:period>20070915T230000Z/20070916T010000Z</xc:period>
           </xc:freebusy>
         </xc:vfreebusy>
       </xc:components>
     </xc:vcalendar>
<xc:icalendar>

EXAMPLE 4 — A URL for which the server does not have any data for that user

>> Request <<
GET /freebusy/user1@example.com?start=2012-12-01T00:00:00-08:00&end=2012-12-31T00:00:00-
08:00
HTTP/1.1
Host: www.example.com

>> Response <<
HTTP/1.1 404 No data

14. CalWS XML Elements

14.1. `description` XML Element

Name: description
Purpose: May be used in error responses to provide some useful information about the error.
Description: A textual description of the error, which SHOULD be localized if possible. Mosylt of use to developers and debuggers.

<!ELEMENT description (#PCDATA) >

14.2. `error` XML Element

Name: error
Purpose: Error responses, particularly 403 Forbidden and 409 Conflict, sometimes need more information to indicate what went wrong. In these cases, servers MAY return an XML response body with a document element of ‘error’, containing child elements identifying particular condition codes.
Description: Contains at least one XML element, and MUST NOT contain text or mixed content. Any element that is a child of the ‘error’ element and is not the description element is considered to be a precondition or postcondition code. Unrecognized elements MUST be ignored.

<!ELEMENT error ANY >

14.3. `CalWS:href` XML Element

Name: href
Purpose: MUST contain a URI or a relative reference.
Description: There may be limits on the value of ‘href’ depending on the context of its use. Refer to the specification text where ‘href’ is used to see what limitations apply in each case.
Value: Simple-ref.

<!ELEMENT href (#PCDATA)>

14.4. `CalWS:target-exists` XML Element

Name: target-exists
Purpose: MUST contain a URI or a relative reference.
Description: See Clause 8.3

<!ELEMENT target-exists EMPTY >

14.5. `CalWS:not-calendar-data` XML Element

Name: not-calendar-data
Purpose: CalWS precondition.
Description: See Clause 8.3

<!ELEMENT not-calendar-data EMPTY >

14.6. `CalWS:invalid-calendar-data` XML Element

Name: invalid-calendar-data
Purpose: CalWS precondition.
Description: See Clause 8.3

<!ELEMENT invalid-calendar-data EMPTY >

14.7. `CalWS:invalid-calendar-object-resource` XML Element

Name: invalid-calendar-object-resource
Purpose: CalWS precondition.
Description: See Clause 8.3

<!ELEMENT invalid-calendar-object-resource EMPTY >

14.8. `CalWS:unsupported-calendar-component` XML Element

Name: unsupported-calendar-component
Purpose: CalWS precondition.
Description: See Clause 8.3

<!ELEMENT unsupported-calendar-component EMPTY >

14.9. `CalWS:uid-conflict` XML Element

Name: uid-conflict
Purpose: CalWS precondition.
Description: See Clause 8.3

<!ELEMENT uid-conflict (CalWS:href)>

14.10. `CalWS:invalid-calendar-collection-location` XML Element

Name: invalid-calendar-collection-location
Purpose: CalWS precondition.
Description: See Clause 8.3

<!ELEMENT invalid-calendar-collection-location EMPTY >

14.11. `CalWS:exceeds-max-resource-size` XML Element

Name: exceeds-max-resource-size
Purpose: CalWS precondition.
Description: See Clause 8.3

<!ELEMENT exceeds-max-resource-size EMPTY >

14.12. `CalWS:before-min-date-time` XML Element

Name: before-min-date-time
Purpose: CalWS precondition.
Description: See Clause 8.3

<!ELEMENT before-min-date-time EMPTY >

14.13. `CalWS:after-max-date-time` XML Element

Name: after-max-date-time
Purpose: CalWS precondition.
Description: See Clause 8.3

<!ELEMENT after-max-date-time EMPTY >

14.14. `CalWS:too-many-instances` XML Element

Name: too-many-instances
Purpose: CalWS precondition.
Description: See Clause 8.3

<!ELEMENT too-many-instances EMPTY >

14.15. `CalWS:too-many-attendees-per-instance` XML Element

Name: too-many-attendees-per-instance
Purpose: CalWS precondition.
Description: See Clause 8.3

<!ELEMENT too-many-attendees-per-instance EMPTY >

14.16. `CalWS:privilege-set`

Name: privilege-set
Purpose: Specify access rights to a collection or entity
Description: Appears within a link relation describing collections or entities and specifies the set of privileges allowed to the current authenticated principal for that collection or entity.

<!ELEMENT privilege-set (privilege*)>

14.17. `CalWS:privilege`

Name: privilege
Purpose: Specifies a single access right
Description: Each privilege element defines a privilege or access right. The following set is currently defined

<!ELEMENT privilege ANY>

14.18. `CalWS:read`

Name: read
Purpose: Specifies read access

<!ELEMENT read NONE>

14.19. `CalWS:write`

Name: read
Purpose: Specifies read access

<!ELEMENT write NONE>

15. Acknowledgments

The following individuals have participated in the creation of this specification and are gratefully acknowledged

Participants:

Cyrus Daboo, Apple

The authors would also like to thank the Calendaring and Scheduling Consortium and the TC-XML committee for help with this specification.

Appendix A
(informative)
Non-normative References

EXAMPLE

[Reference] [reference citation]

NOTE The proper format for a citation to an OASIS Technical Committee’s work (whether Normative or Non-Normative) is:

OASIS
Stage (Committee Draft 01, Committee Draft 02, Committee
Specification 01, etc. or Standard)
Title (italicized or in quotation marks)
Approval Date (Month YYYY)
URI of the actual Authoritative Specification (namespace is not acceptable as the content changes over time)

For example:

[EDXL-HAVE] OASIS Standard, “Emergency Data Exchange Language (EDXL) Hospital AVailability Exchange (HAVE) Version 1.0”, November 2008.http://docs.oasis-open.org/emergency/edxlhave/os/emergency_edxl_have-1.0-spec-os.doc