ࡱ > y 3 bjbj z* { { ) ~ `, `, `, `, `, $ , , , P , 4 / , ^
0 8 A d PB PB PB C F b k | $ h `, 7r C C 7r 7r `, `, PB PB 4 7r D# `, PB `, PB 7r $ G PB ۦ { 8 . 0 ^ 7 } p G G `, A :p Z p @ p 4 q / :p :p :p Y :p :p :p ^ 7r 7r 7r 7r :p :p :p :p :p :p :p :p :p &+ :
WS-Calendar Calendar Update and Synchronization with REST-based Services Version 1.0
Committee Specification Draft 01 /Public Review Draft 01
24 February 2012
Specification URIs
This version:
HYPERLINK "http://docs.oasis-open.org/ws-calendar/ws-calendar-rest/v1.0/csprd01/ws-calendar-rest-v1.0-csprd01.pdf"http://docs.oasis-open.org/ws-calendar/ws-calendar-rest/v1.0/csprd01/ws-calendar-rest-v1.0-csprd01.pdf (Authoritative)
HYPERLINK "http://docs.oasis-open.org/ws-calendar/ws-calendar-rest/v1.0/csprd01/ws-calendar-rest-v1.0-csprd01.html"http://docs.oasis-open.org/ws-calendar/ws-calendar-rest/v1.0/csprd01/ws-calendar-rest-v1.0-csprd01.html
HYPERLINK "http://docs.oasis-open.org/ws-calendar/ws-calendar-rest/v1.0/csprd01/ws-calendar-rest-v1.0-csprd01.doc"http://docs.oasis-open.org/ws-calendar/ws-calendar-rest/v1.0/csprd01/ws-calendar-rest-v1.0-csprd01.doc
Previous version:
N/A
Latest version:
HYPERLINK "http://docs.oasis-open.org/ws-calendar/ws-calendar-rest/v1.0/ws-calendar-rest-v1.0.pdf"http://docs.oasis-open.org/ws-calendar/ws-calendar-rest/v1.0/ws-calendar-rest-v1.0.pdf (Authoritative)
HYPERLINK "http://docs.oasis-open.org/ws-calendar/ws-calendar-rest/v1.0/ws-calendar-rest-v1.0.html"http://docs.oasis-open.org/ws-calendar/ws-calendar-rest/v1.0/ws-calendar-rest-v1.0.html
HYPERLINK "http://docs.oasis-open.org/ws-calendar/ws-calendar-rest/v1.0/ws-calendar-rest-v1.0.doc"http://docs.oasis-open.org/ws-calendar/ws-calendar-rest/v1.0/ws-calendar-rest-v1.0.doc
Technical Committee:
HYPERLINK "http://www.oasis-open.org/committees/ws-calendar/" OASIS Web Services Calendar (WS-Calendar) TC
Chair:
Toby Considine ( HYPERLINK "mailto:toby.considine@unc.edu" toby.considine@unc.edu), HYPERLINK "http://www.unc.edu" University of North Carolina at Chapel Hill
Editor:
Michael Douglass ( HYPERLINK "mailto:douglm@rpi.edu" douglm@rpi.edu), HYPERLINK "http://www.rpi.edu" Rensselaer Polytechnic Institute
Related work:
This specification is related to:
WS-Calendar Version 1.0. Latest version. HYPERLINK "http://docs.oasis-open.org/ws-calendar/ws-calendar/v1.0/ws-calendar-1.0-spec.html" http://docs.oasis-open.org/ws-calendar/ws-calendar/v1.0/ws-calendar-1.0-spec.html
Abstract:
This document describes standard messages and interactions for RESTful interactions with a system that hosts calendar-based information. Hosted information can be either traditional personal and enterprise calendar information or services that are represented as system resources accessible as URIs. These resources can be queried and updated using HTTP methods.
In this version of the specification, only XML payloads developed in conformance with the WS-Calendar specification are used. A future version may address JSON messages after the ongoing efforts to standardize the JSON serialization of iCalendar information are complete.
Status:
This document was last revised or approved by the OASIS Web Services Calendar (WS-Calendar) TC on the above date. The level of approval is also listed above. Check the Latest version location noted above for possible later revisions of this document.
Technical Committee members should send comments on this specification to the Technical Committees email list. Others should send comments to the Technical Committee by using the HYPERLINK "http://www.oasis-open.org/committees/comments/form.php?wg_abbrev=ws-calendar" Send A Comment button on the Technical Committees web page at HYPERLINK "http://www.oasis-open.org/committees/ws-calendar/" http://www.oasis-open.org/committees/ws-calendar/.
For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page ( HYPERLINK "http://www.oasis-open.org/committees/ws-calendar/ipr.php" http://www.oasis-open.org/committees/ws-calendar/ipr.php).
Citation format:
When referencing this specification the following citation format should be used:
[WS-Calendar-REST]
WS-Calendar Calendar Update and Synchronization with REST-based Services Version 1.0. 24 February 2012. OASIS Committee Specification Draft 01 / Public Review Draft 01. HYPERLINK "http://docs.oasis-open.org/ws-calendar/ws-calendar-rest/v1.0/csprd01/ws-calendar-rest-v1.0-csprd01.html"http://docs.oasis-open.org/ws-calendar/ws-calendar-rest/v1.0/csprd01/ws-calendar-rest-v1.0-csprd01.html.
Notices
Copyright OASIS Open 2012. All Rights Reserved.
All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full HYPERLINK "http://www.oasis-open.org/who/intellectualproperty.php"Policy may be found at the OASIS website.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.
OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.
OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.
The name "OASIS" is a trademark of HYPERLINK "http://www.oasis-open.org/" OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see HYPERLINK "http://www.oasis-open.org/who/trademark.php" http://www.oasis-open.org/who/trademark.php for above guidance.
Table of Contents
TOC \o "1-3" \h \z \u HYPERLINK \l "_Toc319504728" 1 Introduction PAGEREF _Toc319504728 \h 6
HYPERLINK \l "_Toc319504729" 1.1 Terminology PAGEREF _Toc319504729 \h 6
HYPERLINK \l "_Toc319504730" 1.2 Normative References PAGEREF _Toc319504730 \h 6
HYPERLINK \l "_Toc319504731" 1.3 Non-Normative References PAGEREF _Toc319504731 \h 6
HYPERLINK \l "_Toc319504732" 1.4 Namespace PAGEREF _Toc319504732 \h 6
HYPERLINK \l "_Toc319504733" 2 Calendar Services PAGEREF _Toc319504733 \h 7
HYPERLINK \l "_Toc319504734" 2.1 Overview of the protocol PAGEREF _Toc319504734 \h 7
HYPERLINK \l "_Toc319504735" 2.1.1 Calendar Object Resources PAGEREF _Toc319504735 \h 7
HYPERLINK \l "_Toc319504736" 2.1.2 Timezone information PAGEREF _Toc319504736 \h 7
HYPERLINK \l "_Toc319504737" 2.1.3 Issues not addressed by this specification. PAGEREF _Toc319504737 \h 8
HYPERLINK \l "_Toc319504738" 2.1.4 CalWS Glossary PAGEREF _Toc319504738 \h 8
HYPERLINK \l "_Toc319504739" 2.2 Error conditions PAGEREF _Toc319504739 \h 9
HYPERLINK \l "_Toc319504740" 2.2.1 Example: error with CalDAV error condition PAGEREF _Toc319504740 \h 9
HYPERLINK \l "_Toc319504741" 3 Properties and link relations PAGEREF _Toc319504741 \h 10
HYPERLINK \l "_Toc319504742" 3.1 Property and relation-type URIs PAGEREF _Toc319504742 \h 10
HYPERLINK \l "_Toc319504743" 3.2 supported-features property. PAGEREF _Toc319504743 \h 10
HYPERLINK \l "_Toc319504744" 3.3 max-attendees-per-instance PAGEREF _Toc319504744 \h 10
HYPERLINK \l "_Toc319504745" 3.4 max-date-time PAGEREF _Toc319504745 \h 10
HYPERLINK \l "_Toc319504746" 3.5 max-instances PAGEREF _Toc319504746 \h 10
HYPERLINK \l "_Toc319504747" 3.6 max-resource-size PAGEREF _Toc319504747 \h 10
HYPERLINK \l "_Toc319504748" 3.7 min-date-time PAGEREF _Toc319504748 \h 11
HYPERLINK \l "_Toc319504749" 3.8 description PAGEREF _Toc319504749 \h 11
HYPERLINK \l "_Toc319504750" 3.9 timezone-service relation. PAGEREF _Toc319504750 \h 11
HYPERLINK \l "_Toc319504751" 3.10 principal-home relation. PAGEREF _Toc319504751 \h 11
HYPERLINK \l "_Toc319504752" 3.11 current-principal-freebusy relation. PAGEREF _Toc319504752 \h 11
HYPERLINK \l "_Toc319504753" 3.12 principal-freebusy relation. PAGEREF _Toc319504753 \h 11
HYPERLINK \l "_Toc319504754" 3.13 child-collection relation. PAGEREF _Toc319504754 \h 11
HYPERLINK \l "_Toc319504755" 3.14 created link property PAGEREF _Toc319504755 \h 12
HYPERLINK \l "_Toc319504756" 3.15 last-modified property PAGEREF _Toc319504756 \h 12
HYPERLINK \l "_Toc319504757" 3.16 displayname property PAGEREF _Toc319504757 \h 12
HYPERLINK \l "_Toc319504758" 3.17 timezone property PAGEREF _Toc319504758 \h 12
HYPERLINK \l "_Toc319504759" 3.18 owner property PAGEREF _Toc319504759 \h 12
HYPERLINK \l "_Toc319504760" 3.19 collection link property PAGEREF _Toc319504760 \h 12
HYPERLINK \l "_Toc319504761" 3.20 calendar-collection link property PAGEREF _Toc319504761 \h 12
HYPERLINK \l "_Toc319504762" 3.21 calWS:privilege-set XML element PAGEREF _Toc319504762 \h 13
HYPERLINK \l "_Toc319504763" 4 Retrieving Collection and Service Properties PAGEREF _Toc319504763 \h 14
HYPERLINK \l "_Toc319504764" 4.1 Request parameters PAGEREF _Toc319504764 \h 14
HYPERLINK \l "_Toc319504765" 4.2 Responses: PAGEREF _Toc319504765 \h 14
HYPERLINK \l "_Toc319504766" 4.3 Example - retrieving server properties: PAGEREF _Toc319504766 \h 14
HYPERLINK \l "_Toc319504767" 5 Creating Calendar Object Resources PAGEREF _Toc319504767 \h 16
HYPERLINK \l "_Toc319504768" 5.1 Request parameters PAGEREF _Toc319504768 \h 16
HYPERLINK \l "_Toc319504769" 5.2 Responses: PAGEREF _Toc319504769 \h 16
HYPERLINK \l "_Toc319504770" 5.3 Preconditions for Calendar Object Creation PAGEREF _Toc319504770 \h 16
HYPERLINK \l "_Toc319504771" 5.4 Example - successful POST: PAGEREF _Toc319504771 \h 17
HYPERLINK \l "_Toc319504772" 5.5 Example - unsuccessful POST: PAGEREF _Toc319504772 \h 17
HYPERLINK \l "_Toc319504773" 6 Retrieving resources PAGEREF _Toc319504773 \h 18
HYPERLINK \l "_Toc319504774" 6.1 Request parameters PAGEREF _Toc319504774 \h 18
HYPERLINK \l "_Toc319504775" 6.2 Responses: PAGEREF _Toc319504775 \h 18
HYPERLINK \l "_Toc319504776" 6.3 Example - successful fetch: PAGEREF _Toc319504776 \h 18
HYPERLINK \l "_Toc319504777" 6.4 Example - unsuccessful fetch: PAGEREF _Toc319504777 \h 18
HYPERLINK \l "_Toc319504778" 7 Updating resources PAGEREF _Toc319504778 \h 19
HYPERLINK \l "_Toc319504779" 7.1 Responses: PAGEREF _Toc319504779 \h 19
HYPERLINK \l "_Toc319504780" 8 Deletion of resources PAGEREF _Toc319504780 \h 21
HYPERLINK \l "_Toc319504781" 8.1 Delete for Collections PAGEREF _Toc319504781 \h 21
HYPERLINK \l "_Toc319504782" 8.2 Responses: PAGEREF _Toc319504782 \h 21
HYPERLINK \l "_Toc319504783" 9 Querying calendar resources PAGEREF _Toc319504783 \h 22
HYPERLINK \l "_Toc319504784" 9.1 Limiting data returned PAGEREF _Toc319504784 \h 22
HYPERLINK \l "_Toc319504785" 9.2 Pre/postconditions for calendar queries PAGEREF _Toc319504785 \h 22
HYPERLINK \l "_Toc319504786" 9.3 Example: time range limited retrieval PAGEREF _Toc319504786 \h 22
HYPERLINK \l "_Toc319504787" 10 Free-busy queries PAGEREF _Toc319504787 \h 27
HYPERLINK \l "_Toc319504788" 10.1 ACCEPT header PAGEREF _Toc319504788 \h 27
HYPERLINK \l "_Toc319504789" 10.2 URL Query Parameters PAGEREF _Toc319504789 \h 27
HYPERLINK \l "_Toc319504790" 10.2.1 start PAGEREF _Toc319504790 \h 27
HYPERLINK \l "_Toc319504791" 10.2.2 end PAGEREF _Toc319504791 \h 28
HYPERLINK \l "_Toc319504792" 10.2.3 period PAGEREF _Toc319504792 \h 28
HYPERLINK \l "_Toc319504793" 10.2.4 account PAGEREF _Toc319504793 \h 28
HYPERLINK \l "_Toc319504794" 10.3 URL parameters - notes PAGEREF _Toc319504794 \h 28
HYPERLINK \l "_Toc319504795" 10.4 HTTP Operations PAGEREF _Toc319504795 \h 28
HYPERLINK \l "_Toc319504796" 10.5 Response Codes PAGEREF _Toc319504796 \h 28
HYPERLINK \l "_Toc319504797" 10.6 Examples PAGEREF _Toc319504797 \h 29
HYPERLINK \l "_Toc319504798" 11 Conformance PAGEREF _Toc319504798 \h 32
HYPERLINK \l "_Toc319504799" Appendix A. Acknowledgments PAGEREF _Toc319504799 \h 33
HYPERLINK \l "_Toc319504800" Appendix B. An Introduction to Internet Calendaring PAGEREF _Toc319504800 \h 34
HYPERLINK \l "_Toc319504801" B.1 icalendar PAGEREF _Toc319504801 \h 34
HYPERLINK \l "_Toc319504802" B.1.1 History PAGEREF _Toc319504802 \h 34
HYPERLINK \l "_Toc319504803" B.1.2 Data model PAGEREF _Toc319504803 \h 34
HYPERLINK \l "_Toc319504804" B.1.3 Scheduling PAGEREF _Toc319504804 \h 35
HYPERLINK \l "_Toc319504805" B.1.4 Extensibility PAGEREF _Toc319504805 \h 35
HYPERLINK \l "_Toc319504806" B.2 Calendar data access and exchange protocols PAGEREF _Toc319504806 \h 35
HYPERLINK \l "_Toc319504807" B.2.1 Internet Calendar Subscriptions PAGEREF _Toc319504807 \h 35
HYPERLINK \l "_Toc319504808" B.2.2 CalDAV PAGEREF _Toc319504808 \h 35
HYPERLINK \l "_Toc319504809" B.2.3 ActiveSync/SyncML PAGEREF _Toc319504809 \h 36
HYPERLINK \l "_Toc319504810" B.2.4 CalWS PAGEREF _Toc319504810 \h 36
HYPERLINK \l "_Toc319504811" B.2.5 iSchedule PAGEREF _Toc319504811 \h 36
HYPERLINK \l "_Toc319504812" B.3 References PAGEREF _Toc319504812 \h 36
HYPERLINK \l "_Toc319504813" Appendix C. Revision History PAGEREF _Toc319504813 \h 37
Introduction
The CalWS REST protocol is built upon and makes the same assumptions about structure as the CalDAV protocol defined in [RFC 4791] and related specifications. It does NOT require nor assume the WebDAV nor CalDAV protocol.
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 REST services will be built without any CalDAV support.
Terminology
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in REF rfc2119 \h [RFC2119].
Normative References
[RFC2119] S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, HYPERLINK "http://www.ietf.org/rfc/rfc2119.txt" http://www.ietf.org/rfc/rfc2119.txt, IETF RFC 2119, March 1997.
[RFC4791] C. Daboo, B. Desruisseaux, L. Dusseault, Calendaring Extensions to WebDAV (CalDAV), HYPERLINK "http://www.ietf.org/RFC/RFC4791.txt" http://www.ietf.org/RFC/RFC4791.txt, IETF RFC4791, March 1997.
[WS-Calendar] WS-Calendar Version 1.0. 19 January 2011. OASIS Committee Specification HYPERLINK "http://docs.oasis-open.org/ws-calendar/ws-calendar-spec/v1.0/cs01/ws-calendar-spec-v1.0-cs01.pdf" http://docs.oasis-open.org/ws-calendar/ws-calendar-spec/v1.0/cs01/ws-calendar-spec-v1.0-cs01.pdf.
[XRD] Extensible Resource Descriptor (XRD) Version 1.0, 1 November 2010, OASIS Standard, HYPERLINK "http://docs.oasis-open.org/xri/xrd/v1.0/os/xrd-1.0-os.xml" http://docs.oasis-open.org/xri/xrd/v1.0/os/xrd-1.0-os.xml
Non-Normative References
REST T Fielding, Architectural Styles and the Design of Network-based Software Architectures, HYPERLINK "http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm" http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm.
Namespace
XML namespaces and prefixes used in this standard:
Table 11: XML Namespaces in this standard
PrefixNamespacexcalurn:ietf:params:xml:ns:icalendar-2.0calWS HYPERLINK "http://docs.oasis-open.org/ws-calendar/ns/REST" http://docs.oasis-open.org/ws-calendar/ns/REST xrd HYPERLINK "http://docs.oasis-open.org/ns/xri/xrd-1.0" http://docs.oasis-open.org/ns/xri/xrd-1.0
Calendar Services
The Service interactions are built upon and make the same assumptions about structure as the CalDAV protocol defined in [RFC4791] 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".
These services 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 free-busy operations are defined to allow efficient, partial retrieval of calendar data.
These services assume a degree of conformity with CalDAV is established such that services built in that manner do not have a significant mismatch. It is assumed that some WS-Calendar services will be built without any CalDAV support.
Overview of the protocol
The protocol is an HTTP based RESTfull protocol using a limited set of methods. Each request may be followed by a response containing status information.
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
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 Section REF _Ref272246482 \r \h 2.1.3.6
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
Calendar Object Resources
The same restrictions apply to Calendar Object Resources as specified in CalDAV [RFC4791] section 4.2. An additional constraint for CalWS is that no timezone specifications are transferred.
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 [TZDB]. CalWS services may advertise themselves as timezone servers through the server properties object.
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.
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 Access Control Lists (ACLs).
Provisioning
The protocol will not provide any explicit provisioning operations. If it is possible to authenticate or address a principal's calendar resources then they MUST be automatically created if necessary or appropriate
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.
Creating Collections
We will not address the issue of creating collections within the address space. The initial set is created by provisioning.
Retrieving collections
This operation is currently undefined. A GET on a collection may fail or return a complete calendar object representing the collection.
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.
CalWS Glossary
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 REF Ref_rfc4918 \h \* MERGEFORMAT Error! Reference source not found. Section 8.3.
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.
Calendar Collection
A folder only allowed to contain calendar object resources.
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.
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/"
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 "post-condition" 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 post-conditions are generally specified which define the state that must exist after the execution of the operation. Preconditions and post-conditions are defined as error elements in the CalWS XML namespace.
Example: error with CalDAV error condition
Unknown property
Properties and link relations
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 [web linking] 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 SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calws http://docs.oasis-open.org/ws-calendar/ns/REST/. Those properties which correspond to CalDAV properties have the additional path element "caldav/", for example
SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calwshttp://docs.oasis-open.org/ws-calendar/ns/REST/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/ws-calendar/ns/REST.
supported-features property.
SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calws http://docs.oasis-open.org/ws-calendar/ns/REST/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
calendar-access
max-attendees-per-instance
SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calws http://docs.oasis-open.org/ws-calendar/ns/REST/max-attendees-per-instance
Defines the maximum number of attendees allowed per event or task.
max-date-time
SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calws http://docs.oasis-open.org/ws-calendar/ns/REST/max-date-time
Defines the maximum date/time allowed on an event or task
max-instances
SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calws http://docs.oasis-open.org/ws-calendar/ns/REST/max-instances
Defines the maximum number of instances allowed per event or task
max-resource-size
SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calws http://docs.oasis-open.org/ws-calendar/ns/REST/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.
min-date-time
SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calws http://docs.oasis-open.org/ws-calendar/ns/REST/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.
description
SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calws http://docs.oasis-open.org/ws-calendar/ns/REST/description
Provides some descriptive text for the targeted collection.
timezone-service relation.
SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calws http://docs.oasis-open.org/ws-calendar/ns/REST/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.
principal-home relation.
SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calws http://docs.oasis-open.org/ws-calendar/ns/REST/principal-home
Provides the URL to the user home for the currently authenticated principal.
current-principal-freebusy relation.
SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calws http://docs.oasis-open.org/ws-calendar/ns/REST/current-principal-freebusy
Provides the URL to use as a target for freebusy requests for the current authenticated principal.
principal-freebusy relation.
SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calws http://docs.oasis-open.org/ws-calendar/ns/REST/principal-freebusy
Provides the URL to use as a target for freebusy requests for a different principal.
child-collection relation.
SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calws http://docs.oasis-open.org/ws-calendar/ns/REST/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.
Calendar
created link property
SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calws http://docs.oasis-open.org/ws-calendar/ns/REST/created
Appears within a link relation describing collections or entities. The value is a date-time as defined in [WS-Calendar] Section 5.6
1985-04-12T23:20:50.52Z
last-modified property
SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calws http://docs.oasis-open.org/ws-calendar/ns/REST/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 [RFC2616], Section 3.3.1
Mon, 12 Jan 1998 09:25:56 GMT
displayname property
SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calws http://docs.oasis-open.org/ws-calendar/ns/REST/displayname
Appears within an xrd object describing collections or entities. The value is a localized name for the entity or collection.
My Calendar
timezone property
SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calws http://docs.oasis-open.org/ws-calendar/ns/REST/timezone
Appears within an xrd object describing collections. The value is a text timezone identifier.
America/New_York
owner property
SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calws http://docs.oasis-open.org/ws-calendar/ns/REST/owner
Appears within an xrd object describing collections or entities. The value is a server specific uri.
/principals/users/mike
collection link property
SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calws http://docs.oasis-open.org/ws-calendar/ns/REST/collection
Appears within a link relation describing collections or entities. The property takes no value and indicates that this child element is a collection.
calendar-collection link property
SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calws http://docs.oasis-open.org/ws-calendar/ns/REST/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.
calWS:privilege-set XML element
SET calwsrelns "http://docs.oasis-open.org/ns/wscal/calws" http://docs.oasis-open.org/ns/wscal/calws http://docs.oasis-open.org/ws-calendar/ns/REST/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.
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
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.
Request parameters
None
Responses:
200: OK
403: Forbidden
404: Not found
Example - retrieving server properties:
>>Request
GET / HTTP/1.1
Host: example.com
ACCEPT:application/xrd+xml
>>Response
1970-01-01T00:00:00Zhttp://example.com/calWS1970-01-01Fred's calendar homeCalendar1000100
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.
Request parameters
action=create
Responses:
201: created
403: Forbidden - no access
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
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;
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: ?
...
>>Response
HTTP/1.1 201 Created
Location: http://example.com/user/fred/calendar/event1.ics
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
Not an icalendar object
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
Request parameters
none
Responses:
200: OK
403: Forbidden - no access
406 The requested format specified in the accept header is not supported.
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: ?
...
Example - unsuccessful fetch:
>>Request
PUT /user/fred/calendar/noevent1.ics HTTP/1.1
Host: example.com
>>Response
HTTP/1.1 404 Not found
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 Section REF _Ref272182523 \r \h 5.3 are applicable.
Responses:
200: OK
304: Not modified - entity was modified by some other request
403: Forbidden - no access, does not exist etc. See error response
Example STYLEREF 1 \s 7 SEQ Example \* ARABIC \s 1 1: 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: ?
...
>>Response
HTTP/1.1 200 OK
Example STYLEREF 1 \s 7 SEQ Example \* ARABIC \s 1 2: 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: ?
...
>>Response
HTTP/1.1 403 Forbidden
Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx
Target of update must exist
Deletion of resources
Delete is defined in [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.
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.
Responses:
200: OK
403: Forbidden - no access
404: Not Found
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 [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 [RFC 5545] and assume that as the default, the delivery format for CalWS will, by default, be [draft-xcal].
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.
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.
Pre/postconditions for calendar queries
The preconditions as defined in in [RFC 4791] Section 7.8 apply here. CalDav errors may be reported by the service when preconditions or postconditions are violated.
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
>> 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
http://cal.example.com/bernard/work/abcd2.ics"fffff-abcd2"GREGORIAN-//Example Inc.//Example Calendar//EN2.0US/Eastern20060102T120000PT1HEvent #200959BC664CA650E933C892C@example.comDAILY5US/Eastern20060104T140000PT1HEvent #2 bis00959BC664CA650E933C892C@example.comUS/Eastern20060104T120000DAILY5US/Eastern20060106T140000PT1HEvent #2 bis bis00959BC664CA650E933C892C@example.comUS/Eastern20060106T120000DAILY5HTTP/1.1 200 OKhttp://cal.example.com/bernard/work/abcd3.ics"fffff-abcd3"GREGORIAN-//Example Inc.//Example Calendar//EN2.0US/Eastern20060104T100000PT1HEvent #3DC6C50A017428C5216A2F1CD@example.comDAILY5HTTP/1.1 200 OK
Free-busy queries
Free-busy queries are used to obtain free-busy 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 free-busy URL the result will be based on all information which affect the principals free-busy 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 [FreeBusy Read URL] 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 [draft-xcal]. Such a component is not meant to conform to the requirements of VFREEBUSY components in [RFC 5546]. The VFREEBUSY component SHOULD conform to section "4.6.4 Free/Busy Component" of [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.
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 [draft-xcal], that is, as if the following had been specified
ACCEPT: application/xml+calendar
URL Query Parameters
None of these parameters are required except for the conditions noted below. Appropriate defaults will be supplied by the server.
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 [RFC3339] 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
Notes: Specifying only a start date/time without specifying an end-date/time or period should be interpreted as in [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.
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
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 section 4.3.6 of [RFC 5545]
Example:
P42D
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
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.
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.
Response Codes
Below are the typical status codes returned by a GET request targeting a Free-busy URL. Note that other HTTP status codes not listed here might also be returned by a server.
200 OK
302 Found
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
Examples
The following are examples of URLs used to retrieve Free-busy data for a user:
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:
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
GREGORIAN-//Example Inc.//Example Calendar//EN2.076ef34-54a3d2@example.com20060101T000000Z20060108T000000Z20050530T123421ZBUSYTENTATIVE20060102T100000Z/20060102T120000Z20060103T100000Z/20060103T120000Z20060104T100000Z/20060104T120000ZBUSYUNAVAILABLE20060105T100000Z/20060105T120000Z20060106T100000Z/20060106T120000Z
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
GREGORIAN-//Example Inc.//Example Calendar//EN2.076ef34-54a3d2@example.com20070901T000000Z20070931T000000Z20050530T123421Z20070915T230000Z/20070916T010000Z
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
Conformance
The last numbered section in the specification must be the Conformance section. Conformance Statements/Clauses go here.
Acknowledgments
The following individuals have participated in the creation of this specification and are gratefully acknowledged:
Participants: MACROBUTTON
Bruce Bartell, Southern California Edison
Brad Benson, Trane
Edward Cazalet, Individual
Toby Considine, University of North Carolina at Chapel Hill
William Cox, Individual
Sharon Dinges, Trane
Mike, Douglass, Rensselaer Polytechnic Institute
Craig Gemmill, Tridium, Inc.
Girish Ghatikar, Lawrence Berkeley National Laboratory
Gerald Gray, Southern California Edison
David Hardin, ENERNOC
Gale Horst, Electric Power Research Institute (EPRI)
Gershon Janssen, Individual
Ed Koch, Akuacom Inc.
Benoit Lepeuple, LonMark International*
Carl Mattocks, CheckMi*
Robert Old, Siemens AG
Alexander Papaspyrou, Technische Universitat Dortmund
Joshua Phillips, ISO/RTO Council (IRC)
Jeremy J. Roberts, LonMark International
David Thewlis, CalConnect
The Calendaring and Scheduling Consortium (CalConnect) TC-XML committee worked closely with WS-Calendar Technical Committee, bridging to developing IETF standards and contributing the services definitions that make up Services in Section 4. The Technical Committee gratefully acknowledges their assistance and cooperation as well. Contributors to TC XML include:
Cyrus Daboo, Apple
Mike Douglass, Rensselaer Polytechnic Institute
Steven Lees, Microsoft
Tong Li, IBM
An Introduction to Internet Calendaring
The WS-Calendar Technical Committee thanks CalConnect for contributing this overview of iCalendar and its use.
icalendar
History
The iCalendar specification was first produced by the IETF in 1998 as RFC 2445 [1]. Since then it has become the dominant standard for calendar data interchange on the internet and between devices (desktop computers, mobile phones etc.). The specification was revised in 2009 as RFC 5545 [4].
Alongside iCalendar is the iTIP specification (RFC 2446 [2] and revised as RFC 5546[5]) that defines how iCalendar is used to carry out scheduling operations (for example, how an organizer can invite attendees to a meeting and receive their replies). This forms the basis for email-based scheduling using iMIP (the specification that describes how to use iTIP with email - RFC 6047 [3]).
iCalendar itself is a text-based data format. However, an XML format is also available, providing a one-to-one mapping to the text format (draft [7]).
iCalendar data files typically have a .ics file name extension. Most desktop calendar clients can import or export iCalendar data, or directly access such data over the Internet using a variety of protocols.
Data model
The iCalendar data format has a well defined data model. "iCalendar objects" encompass a set of "iCalendar Components" each of which contains a set of "iCalendar properties" and possibly other sub-Components. An iCalendar property consists of a name, a set of optional parameters (specified as "key-value" pairs) and a value.
iCalendar Components include:
"VEVENT" which represents an event
"VTODO" which represents a task or to-do
"VJOURNAL" which represents a journal entry
"VFREEBUSY" which represents periods of free or busy time information
"VTIMEZONE" which represents a timezone definition (timezone offset and daylight saving rules)
"VALARM" is currently the only defined sub-Component and is used to set alarms or reminders on events or tasks.
Properties include:
"DTSTART" which represents a start time for a Component
"DTEND" which represents an end time for a Component
"SUMMARY" which represents a title or summary for a Component
"RRULE" which can specify rules for repeating events or tasks (for example, every day, every week on Tuesdays, etc.)
"ORGANIZER" which represents the calendar user who is organizing an event or assigning a task
"ATTENDEE" which represents calendar users attending an event or assigned a task
In addition to this data model and the pre-defined properties, the specification defines how all those are used together to define the semantics of calendar objects and scheduling. The semantics are basically a set of rules stating how all the Components and properties are used together to ensure that all iCalendar products can work together to achieve good interoperability. For example, a rule requires that all events must have one and only one "DTSTART" property. The most important part of the iCalendar specification is the semantics of the calendaring model that it represents. The use of text or XML to encode those is secondary.
Scheduling
The iTIP specification defines how iCalendar objects are exchanged in order to accomplish the key task needed to schedule events or tasks. An example of a simple workflow is as follows:
To schedule an event, an organizer creates the iCalendar object representing the event and adds calendar users as attendees.
The organizer then sends an iTIP "REQUEST" message to all the attendees.
Upon receipt of the scheduling message, each attendee can decide whether they want to attend the meeting or not.
Each attendee can then respond back to the organizer using an iTIP "REPLY" message indicating their own attendance status.
iTIP supports other types of scheduling messages, for example, to cancel meetings, add new instances to a repeating meeting, etc.
Extensibility
iCalendar was designed to be extensible, allowing for new Components, properties and parameters to be defined as needed. A registry exists to maintain the list of standard extensions with references to their definitions to ensure anyone can use them and work well with others.
Calendar data access and exchange protocols
Internet Calendar Subscriptions
An Internet calendar subscription is simply an iCalendar data file made available on a web server. Users can use this data in two ways:
The data can be downloaded from the web server and then imported directly into an iCalendar aware client. This solution works well for calendar data that is not likely to change over time (for example the list of national holidays for the next year).
Calendar clients that support "direct" subscriptions can use the URL to the calendar data on the web server to download the calendar data themselves. Additionally, the clients can check the web server on a regular basis for updates to the calendar data, and then update their own cached copy of it. This allows calendar data that changes over time to be kept synchronized.
CalDAV
CalDAV is a calendar access protocol and is defined in RFC 4791 [6]. The protocol is based on WebDAV which is an extension to HTTP that provides enhanced capabilities for document management on web servers.
CalDAV is used in a variety of different environments, ranging from very large internet service providers, to large and small corporations or institutions, and to small businesses and individuals.
CalDAV clients include desktop applications, mobile devices and browser-based solutions. It can also be used by "applets", for example, a web page panel that displays a user's upcoming events.
One of the key aspects of CalDAV is its data model. Simply put, it defines a "calendar home" for each calendar user, within which any number of "calendars" can be created. Each "calendar" can contain any number of iCalendar objects representing individual events, tasks or journal entries. This data model ensures that clients and servers can interoperate well.
In addition to providing simple operations to read, write and delete calendar data, CalDAV provides a querying mechanism to allow clients to fetch calendar data matching specific criteria. This is commonly used by clients to do "time-range" queries, i.e., find the set of events that occur within a given start/end time period.
CalDAV also supports access control allowing for features such as delegated calendars and calendar sharing.
CalDAV also specifies how scheduling operations can be done using the protocol. Whilst it uses the semantics of the iTIP protocol, it simplifies the process by allowing simple calendar data write operations to trigger the sending of scheduling messages, and it has the server automatically process the receipt of scheduling messages. Scheduling can be done with other users on the CalDAV server or with calendar users on other systems (via some form of "gateway").
ActiveSync/SyncML
ActiveSync and SyncML are technologies that allow multiple devices to synchronize data with a server, with calendar data being one of the classes of data supported. These have typically been used for low-end and high-end mobile devices.
CalWS
CalWS refers to a set of web services calendar access APIs developed under a cooperative agreement between The Calendaring and Scheduling Consortium (CalConnect) and OASIS, and being published as a work product of the WS-Calendar Technical Committee. CalWS defines an API to access and manipulate calendar data stored on a server. It follows a similar data model to CalDAV and has been designed to co-exist with a CalDAV service offering the same data.
This specification is part of the CalWS set.
iSchedule
iSchedule is a protocol to allow scheduling between users on different calendaring systems and across different internet domains. It transports iTIP scheduling messages using HTTP between servers. Servers use DNS and various security mechanisms to determine the authenticity of messages received.
It has been specifically designed to be independent of any calendar system in use at the endpoints, so that it is compatible with many different systems. This allows organizations with different calendar systems to exchange scheduling messages with each other, and also allows a single organization with multiple calendar systems (for example due to mergers, or different departmental requirements) to exchange scheduling messages between users of each system.
References
[1] https://datatracker.ietf.org/doc/rfc2445/ : Internet Calendaring and Scheduling Core Object Specification
[2] https://datatracker.ietf.org/doc/rfc2446/ :iCalendar Transport-Independent Interoperability Protocol
[3] https://datatracker.ietf.org/doc/rfc6047/ : iCalendar Message-Based Interoperability Protocol
[4] https://datatracker.ietf.org/doc/rfc5545/ :Internet Calendaring and Scheduling Core Object Specification
[5] https://datatracker.ietf.org/doc/rfc5546/ : iCalendar Transport-Independent Interoperability Protocol
[6] https://datatracker.ietf.org/doc/rfc4791/ : Calendaring Extensions to WebDAV
[7] https://datatracker.ietf.org/doc/draft-daboo-et-al-icalendar-in-xml/ : xCal: The XML format for iCalendar
Revision History
RevisionDateEditorChanges Madews-calendar-wd1919-Mar-2011Toby ConsidineOriginally contributed by Mike Douglass as part of WS-Calendar v1.0 Specification. See full history in that document.WD0213-Feb-2012Toby ConsidinePorted to separate document. Promoted all section headers.WD0315 Feb-2012Toby ConsidineAdded Intro, updated namespaces to meet OASIS standardWD0417 February 2012Toby ConsidineAdditional namespace clean-up in response to Cover comments.
Consisten capitalization of calWS when used as a namespace identifier
Clean-up of CalWS discussion in appendixWD0517 February 2012Toby ConsidineTypes, capitalization, missing XRD reference
ws-calendar-rest-v1.0-csprd01 24 February 2012
Standards Track Work Product Copyright OASIS Open 2012. All Rights Reserved. Page PAGE 1 of NUMPAGES 37
MACROBUTTON NoMacro [document identifier] MACROBUTTON NoMacro [specification date]
Copyright OASIS Open 2004.All Rights Reserved. Page PAGE 5 of NUMPAGES 5
U V W u w 6 7 8 $
%
&
Ƚ}pj
hs 0J j? h!# 0J Uh7 h1D 0J B* ph hY&