draft-ietf-jmap-calendars-01.txt   draft-ietf-jmap-calendars-02.txt 
JMAP N. Jenkins JMAP N. Jenkins
Internet-Draft Fastmail Internet-Draft Fastmail
Intended status: Standards Track M. Douglass Intended status: Standards Track M. Douglass
Expires: April 30, 2020 Spherical Cow Group Expires: September 11, 2020 Spherical Cow Group
October 28, 2019 March 10, 2020
JMAP for Calendars JMAP for Calendars
draft-ietf-jmap-calendars-01 draft-ietf-jmap-calendars-02
Abstract Abstract
This document specifies a data model for synchronizing calendar data This document specifies a data model for synchronizing calendar data
with a server using JMAP. with a server using JMAP.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
skipping to change at page 1, line 32 skipping to change at page 1, line 32
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 30, 2020. This Internet-Draft will expire on September 11, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2020 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 3 1.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 4
1.2. Accounts, Push, and the Session Object . . . . . . . . . 4 1.2. Accounts, Push, and the Session Object . . . . . . . . . 4
1.2.1. UIDs and CalendarEvent Ids . . . . . . . . . . . . . 5 1.2.1. UIDs and CalendarEvent Ids . . . . . . . . . . . . . 5
1.3. Notational Conventions . . . . . . . . . . . . . . . . . 5 1.3. Notational Conventions . . . . . . . . . . . . . . . . . 5
1.4. The LocalDate Data Type . . . . . . . . . . . . . . . . . 6 1.4. The LocalDate Data Type . . . . . . . . . . . . . . . . . 6
1.5. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 1.5. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6
1.6. Addition to the Capabilities Object . . . . . . . . . . . 6 1.6. Addition to the Capabilities Object . . . . . . . . . . . 6
1.6.1. urn:ietf:params:jmap:calendars . . . . . . . . . . . 6 1.6.1. urn:ietf:params:jmap:calendars . . . . . . . . . . . 6
1.6.2. urn:ietf:params:jmap:calendarprincipals . . . . . . . 7 1.6.2. urn:ietf:params:jmap:calendarprincipals . . . . . . . 7
2. Calendar Principals . . . . . . . . . . . . . . . . . . . . . 8 2. Calendar Principals . . . . . . . . . . . . . . . . . . . . . 7
2.1. CalendarPrincipal/get . . . . . . . . . . . . . . . . . . 9 2.1. CalendarPrincipal/get . . . . . . . . . . . . . . . . . . 9
2.2. CalendarPrincipal/changes . . . . . . . . . . . . . . . . 9 2.2. CalendarPrincipal/changes . . . . . . . . . . . . . . . . 9
2.3. CalendarPrincipal/set . . . . . . . . . . . . . . . . . . 9 2.3. CalendarPrincipal/set . . . . . . . . . . . . . . . . . . 9
2.4. CalendarPrincipal/query . . . . . . . . . . . . . . . . . 9 2.4. CalendarPrincipal/query . . . . . . . . . . . . . . . . . 9
2.4.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 9 2.4.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 9
2.5. CalendarPrincipal/queryChanges . . . . . . . . . . . . . 10 2.5. CalendarPrincipal/queryChanges . . . . . . . . . . . . . 10
2.6. CalendarPrincipal/getAvailability . . . . . . . . . . . . 10 2.6. CalendarPrincipal/getAvailability . . . . . . . . . . . . 10
3. Calendars . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3. Calendars . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.1. Calendar/get . . . . . . . . . . . . . . . . . . . . . . 17 3.1. Per-user properties . . . . . . . . . . . . . . . . . . . 16
3.2. Calendar/changes . . . . . . . . . . . . . . . . . . . . 17 3.2. Calendar/get . . . . . . . . . . . . . . . . . . . . . . 16
3.3. Calendar/set . . . . . . . . . . . . . . . . . . . . . . 17 3.3. Calendar/changes . . . . . . . . . . . . . . . . . . . . 17
3.4. Calendar/set . . . . . . . . . . . . . . . . . . . . . . 17
4. Calendar Share Notifications . . . . . . . . . . . . . . . . 18 4. Calendar Share Notifications . . . . . . . . . . . . . . . . 18
4.1. Auto-deletion of Notifications . . . . . . . . . . . . . 19 4.1. Auto-deletion of Notifications . . . . . . . . . . . . . 18
4.2. Object Properties . . . . . . . . . . . . . . . . . . . . 19 4.2. Object Properties . . . . . . . . . . . . . . . . . . . . 18
4.3. CalendarShareNotification/get . . . . . . . . . . . . . . 20 4.3. CalendarShareNotification/get . . . . . . . . . . . . . . 19
4.4. CalendarShareNotification/changes . . . . . . . . . . . . 20 4.4. CalendarShareNotification/changes . . . . . . . . . . . . 19
4.5. CalendarShareNotification/set . . . . . . . . . . . . . . 20 4.5. CalendarShareNotification/set . . . . . . . . . . . . . . 19
4.6. CalendarShareNotification/query . . . . . . . . . . . . . 20 4.6. CalendarShareNotification/query . . . . . . . . . . . . . 20
4.6.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 20 4.6.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 20
4.6.2. Sorting . . . . . . . . . . . . . . . . . . . . . . . 20 4.6.2. Sorting . . . . . . . . . . . . . . . . . . . . . . . 20
4.7. CalendarShareNotification/queryChanges . . . . . . . . . 20 4.7. CalendarShareNotification/queryChanges . . . . . . . . . 20
5. Calendar Events . . . . . . . . . . . . . . . . . . . . . . . 20 5. Calendar Events . . . . . . . . . . . . . . . . . . . . . . . 20
5.1. Attachments . . . . . . . . . . . . . . . . . . . . . . . 21 5.1. Attachments . . . . . . . . . . . . . . . . . . . . . . . 21
5.2. Per-user properties . . . . . . . . . . . . . . . . . . . 22 5.2. Per-user properties . . . . . . . . . . . . . . . . . . . 21
5.3. Recurring events . . . . . . . . . . . . . . . . . . . . 22 5.3. Recurring events . . . . . . . . . . . . . . . . . . . . 22
5.4. CalendarEvent/get . . . . . . . . . . . . . . . . . . . . 23 5.4. Updating for "this-and-future" . . . . . . . . . . . . . 22
5.5. CalendarEvent/changes . . . . . . . . . . . . . . . . . . 24 5.4.1. Splitting an event . . . . . . . . . . . . . . . . . 23
5.6. CalendarEvent/set . . . . . . . . . . . . . . . . . . . . 24 5.4.2. Updating the master and overriding previous . . . . . 23
5.6.1. Sending invitations and responses . . . . . . . . . . 25 5.5. CalendarEvent/get . . . . . . . . . . . . . . . . . . . . 23
5.7. CalendarEvent/copy . . . . . . . . . . . . . . . . . . . 28 5.6. CalendarEvent/changes . . . . . . . . . . . . . . . . . . 24
5.8. CalendarEvent/query . . . . . . . . . . . . . . . . . . . 28 5.7. CalendarEvent/set . . . . . . . . . . . . . . . . . . . . 24
5.8.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 29 5.7.1. Sending invitations and responses . . . . . . . . . . 26
5.8.2. Sorting . . . . . . . . . . . . . . . . . . . . . . . 30 5.8. CalendarEvent/copy . . . . . . . . . . . . . . . . . . . 29
5.9. CalendarEvent/queryChanges . . . . . . . . . . . . . . . 31 5.9. CalendarEvent/query . . . . . . . . . . . . . . . . . . . 29
5.10. Examples . . . . . . . . . . . . . . . . . . . . . . . . 31 5.9.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 30
5.9.2. Sorting . . . . . . . . . . . . . . . . . . . . . . . 31
6. Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 5.10. CalendarEvent/queryChanges . . . . . . . . . . . . . . . 32
6.1. Push events . . . . . . . . . . . . . . . . . . . . . . . 31 5.11. Examples . . . . . . . . . . . . . . . . . . . . . . . . 32
6.2. Acknowledging an alert . . . . . . . . . . . . . . . . . 32 6. Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
6.3. Snoozing an alert . . . . . . . . . . . . . . . . . . . . 32 6.1. Push events . . . . . . . . . . . . . . . . . . . . . . . 32
7. Calendar Event Notifications . . . . . . . . . . . . . . . . 33 6.2. Acknowledging an alert . . . . . . . . . . . . . . . . . 33
7.1. Auto-deletion of Notifications . . . . . . . . . . . . . 33 6.3. Snoozing an alert . . . . . . . . . . . . . . . . . . . . 33
7.2. Object Properties . . . . . . . . . . . . . . . . . . . . 33 7. Calendar Event Notifications . . . . . . . . . . . . . . . . 34
7.3. CalendarEventNotification/get . . . . . . . . . . . . . . 34 7.1. Auto-deletion of Notifications . . . . . . . . . . . . . 34
7.4. CalendarEventNotification/changes . . . . . . . . . . . . 34 7.2. Object Properties . . . . . . . . . . . . . . . . . . . . 34
7.5. CalendarEventNotification/set . . . . . . . . . . . . . . 34 7.3. CalendarEventNotification/get . . . . . . . . . . . . . . 35
7.6. CalendarEventNotification/query . . . . . . . . . . . . . 35 7.4. CalendarEventNotification/changes . . . . . . . . . . . . 35
7.6.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 35 7.5. CalendarEventNotification/set . . . . . . . . . . . . . . 35
7.6.2. Sorting . . . . . . . . . . . . . . . . . . . . . . . 35 7.6. CalendarEventNotification/query . . . . . . . . . . . . . 36
7.7. CalendarEventNotification/queryChanges . . . . . . . . . 35 7.6.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 36
8. Security Considerations . . . . . . . . . . . . . . . . . . . 35 7.6.2. Sorting . . . . . . . . . . . . . . . . . . . . . . . 36
8.1. Denial-of-service Expanding Recurrences . . . . . . . . . 35 7.7. CalendarEventNotification/queryChanges . . . . . . . . . 36
8.2. Privacy . . . . . . . . . . . . . . . . . . . . . . . . . 36 8. Security Considerations . . . . . . . . . . . . . . . . . . . 36
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 8.1. Denial-of-service Expanding Recurrences . . . . . . . . . 36
9.1. JMAP Capability Registration for "calendars" . . . . . . 36 8.2. Privacy . . . . . . . . . . . . . . . . . . . . . . . . . 37
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37
9.1. JMAP Capability Registration for "calendars" . . . . . . 37
9.2. Reservation of JMAP attributes in JSCalendar Property 9.2. Reservation of JMAP attributes in JSCalendar Property
registry . . . . . . . . . . . . . . . . . . . . . . . . 36 registry . . . . . . . . . . . . . . . . . . . . . . . . 37
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 37
10.1. Normative References . . . . . . . . . . . . . . . . . . 36 10.1. Normative References . . . . . . . . . . . . . . . . . . 37
10.2. Informative References . . . . . . . . . . . . . . . . . 37 10.2. Informative References . . . . . . . . . . . . . . . . . 38
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 37 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 38
1. Introduction 1. Introduction
JMAP ([RFC8620] - JSON Meta Application Protocol) is a generic JMAP ([RFC8620] - JSON Meta Application Protocol) is a generic
protocol for synchronizing data, such as mail, calendars or contacts, protocol for synchronizing data, such as mail, calendars or contacts,
between a client and a server. It is optimized for mobile and web between a client and a server. It is optimized for mobile and web
environments, and aims to provide a consistent interface to different environments, and aims to provide a consistent interface to different
data types. data types.
This specification defines a data model for synchronizing calendar This specification defines a data model for synchronizing calendar
skipping to change at page 6, line 48 skipping to change at page 6, line 48
property is an object that MUST contain the following information on property is an object that MUST contain the following information on
server capabilities and permissions for that account: server capabilities and permissions for that account:
o *accountIdForCalendarPrincipal*: "String|null" The id of an o *accountIdForCalendarPrincipal*: "String|null" The id of an
account with the "urn:ietf:params:jmap:calendarprincipals" account with the "urn:ietf:params:jmap:calendarprincipals"
capability that contains the corresponding CalendarPrincipal capability that contains the corresponding CalendarPrincipal
object. This may be the same account id. This is null for object. This may be the same account id. This is null for
single-user systems that do not support the CalendarPrincipal data single-user systems that do not support the CalendarPrincipal data
type. type.
o *maxSizeCalendarEvent*: "UnsignedInt" The maximum size in octets
of the largest CalendarEvent the server is willing to store.
TODO: How can you relate this to what the client knows?
o *minDateTime*: "LocalDate" The earliest date-time the server is o *minDateTime*: "LocalDate" The earliest date-time the server is
willing to accept for any date stored in a CalendarEvent. willing to accept for any date stored in a CalendarEvent.
o *maxDateTime*: "LocalDate" The latest date-time the server is o *maxDateTime*: "LocalDate" The latest date-time the server is
willing to accept for any date stored in a CalendarEvent. willing to accept for any date stored in a CalendarEvent.
o *maxExpandedQueryDuration*: "Duration" The maximum duration the o *maxExpandedQueryDuration*: "Duration" The maximum duration the
user may query over when asking the server to expand recurrences. user may query over when asking the server to expand recurrences.
o *maxParticipantsPerEvent*: "Number|null" The maximum number of o *maxParticipantsPerEvent*: "Number|null" The maximum number of
participants a single event may have, or null for no limit. participants a single event may have, or null for no limit.
o *maxNumberEventNotifications*: "UnsignedInt" The maximum number of
CalendarEventNotification objects the server will store for this
account. If new notifications are added in excess of this number,
older notifications will be automatically deleted by the server.
o *mayCreateCalendar*: "Boolean" If true, the user may create a o *mayCreateCalendar*: "Boolean" If true, the user may create a
calendar in this account. calendar in this account.
1.6.2. urn:ietf:params:jmap:calendarprincipals 1.6.2. urn:ietf:params:jmap:calendarprincipals
Represents support for the CalendarPrincipal and Represents support for the CalendarPrincipal and
CalendarShareNotification data types and associated API methods. CalendarShareNotification data types and associated API methods.
Single user systems do not need this and MAY choose not to support Single user systems do not need this and MAY choose not to support
it. it.
skipping to change at page 7, line 47 skipping to change at page 7, line 36
server capabilities and permissions for that account: server capabilities and permissions for that account:
o *currentUserPrincipalId*: "String|null" The id of the principal in o *currentUserPrincipalId*: "String|null" The id of the principal in
this account that corresponds to the user fetching this object, if this account that corresponds to the user fetching this object, if
any. any.
o *maxAvailabilityDuration*: The maximum duration over which the o *maxAvailabilityDuration*: The maximum duration over which the
server is prepared to calculate availability in a single call (see server is prepared to calculate availability in a single call (see
Section XXX). Section XXX).
o *maxNumberShareNotifications*: "UnsignedInt" The maximum number of
CalendarShareNotification objects the server will store for a
principal in this account. If new notifications are added in
excess of this number, older notifications will be automatically
deleted by the server.
2. Calendar Principals 2. Calendar Principals
A CalendarPrincipal represents an individual, group, schedulable A CalendarPrincipal represents an individual, group, schedulable
location (e.g. a room), bookable resource (e.g. a projector) or other location (e.g. a room), bookable resource (e.g. a projector) or other
entity in the calendar system. In a shared calendar environment such entity in the calendar system. In a shared calendar environment such
as a workplace, a user may have access to a large number of as a workplace, a user may have access to a large number of
principals. principals.
In most systems the user will have access to a single Account In most systems the user will have access to a single Account
containing CalendarPrincipal objects, but they may have access to containing CalendarPrincipal objects, but they may have access to
skipping to change at page 12, line 18 skipping to change at page 12, line 5
Finally, the server MUST merge and split BusyPeriod objects where the Finally, the server MUST merge and split BusyPeriod objects where the
"event" property is null, such that none of them overlap and either "event" property is null, such that none of them overlap and either
there is a gap in time between any two objects (the utcEnd of one there is a gap in time between any two objects (the utcEnd of one
does not equal the utcStart of another) or those objects have a does not equal the utcStart of another) or those objects have a
different busyStatus property. If there are overlapping BusyPeriod different busyStatus property. If there are overlapping BusyPeriod
time ranges with different "busyStatus" properties the server MUST time ranges with different "busyStatus" properties the server MUST
choose the value in the following order: confirmed > unavailable > choose the value in the following order: confirmed > unavailable >
tentative. tentative.
The response has the following arguments: The response has the following argument:
o *accountId*: "Id" The id of the account used for the call.
o *id*: "Id" The id of the CalendarPrincipal availability is being
returned for.
o *utcStart*: "UTCDate" The start time (inclusive) of the period for
which availability is being returned.
o *utcEnd*: "UTCDate" The end time (exclusive) of the period for
which availability is being returned.
o *list*: "BusyPeriod[]" The list of BusyPeriod objects calculated o *list*: "BusyPeriod[]" The list of BusyPeriod objects calculated
as described above. as described above.
The following additional errors may be returned instead of the The following additional errors may be returned instead of the
"CalendarPrincipal/getAvailability" response: "CalendarPrincipal/getAvailability" response:
"notFound": No principal with this id exists, or the user does not "notFound": No principal with this id exists, or the user does not
have permission to see that this principal exists. have permission to see that this principal exists.
skipping to change at page 15, line 9 skipping to change at page 14, line 30
first item in the array is the default. A *ParticipantIdentity* first item in the array is the default. A *ParticipantIdentity*
object has the following properties: object has the following properties:
* *name*: "String" The display name of the participant to use * *name*: "String" The display name of the participant to use
when adding this participant to an event, e.g. "Joe Bloggs". when adding this participant to an event, e.g. "Joe Bloggs".
* *type*: "String" The method for sending scheduling messages to * *type*: "String" The method for sending scheduling messages to
this identity, e.g. "imip" this identity, e.g. "imip"
* *uri*: "String" The URI for sending scheduling messages to this * *uri*: "String" The URI for sending scheduling messages to this
identity, e.g. "mailto:foo@example.com" identity, e.g. "mailto:foo@example.com"
The user is an *owner* for an event if the CalendarEvent object The user is an *owner* for an event if the CalendarEvent object
has a "participants" property, and one of the Participant objects has a "participants" property, and one of the Participant objects
has both: a) The "owner" role. b) A "sendTo" property that has has both: a) The "owner" role. b) A "sendTo" property that has
"type" and "uri" equal to one of the ParticipantIdentity objects "type" and "uri" equal to one of the ParticipantIdentity objects
returned with the calendar. returned with the calendar.
o *shareWith*: "Id[CalendarRights]|null" A map of CalendarPrincipal o *shareWith*: "Id[CalendarRights]|null" A map of CalendarPrincipal
id to rights for principals this calendar is shared with. The id to rights for principals this calendar is shared with. The
pricincipal to which this calendar belongs MUST NOT be in this pricincipal to which this calendar belongs MUST NOT be in this
set. This is null if the user requesting the object does not have set. This is null if the user requesting the object does not have
the mayAdmin right, or if the calendar is not shared with anyone. the mayAdmin right, or if the calendar is not shared with anyone.
May be modified only if the user has the mayAdmin right. May be modified only if the user has the mayAdmin right.
o *shareesActAs*: "String" (immutable; default server-dependent) o *shareesActAs*: "String" (immutable; default server-dependent)
This MUST be one of: This MUST be one of:
* "owner" * "secretary"
* "self" * "self"
If "self", sharees act as themselves when using this calendar. If If "self", sharees act as themselves when using this calendar. If
"owner", they act as the pricincipal to which this calendar "secretary", they act as the pricincipal to which this calendar
belongs (secretary mode). If omitted, the default is server belongs (secretary mode). If omitted, the default is server
dependent. For example, it may be "self" if creating a calendar dependent. For example, it may be "self" if creating a calendar
in a CalendarPrincipal representing a group, and "owner" if in a CalendarPrincipal representing a group, and "secretary" if
creating a calendar for an individual. Users may attempt to set creating a calendar for an individual. Users may attempt to set
this on creation, but the server may reject with an this on creation, but the server may reject with an
"invalidProperties" error if the value is not permissible. "invalidProperties" error if the value is not permissible.
o *myRights*: "CalendarRights" (server-set) The set of access rights o *myRights*: "CalendarRights" (server-set) The set of access rights
the user has in relation to this Calendar. the user has in relation to this Calendar.
A *CalendarRights* object has the following properties: A *CalendarRights* object has the following properties:
o *mayReadFreeBusy*: "Boolean" The user may read the free-busy o *mayReadFreeBusy*: "Boolean" The user may read the free-busy
skipping to change at page 16, line 14 skipping to change at page 15, line 34
o *mayAddItems*: "Boolean" The user may create new events on this o *mayAddItems*: "Boolean" The user may create new events on this
calendar or move events to this calendar. For recurring events, calendar or move events to this calendar. For recurring events,
they may add an override to add an occurrence, or remove an they may add an override to add an occurrence, or remove an
existing override that is excluding an occurrence. existing override that is excluding an occurrence.
o *mayUpdatePrivate*: "Boolean" The user may modify the following o *mayUpdatePrivate*: "Boolean" The user may modify the following
properties on all events in the calendar. If shareesActAs is properties on all events in the calendar. If shareesActAs is
"self", these properties MUST all be stored per-user, and changes "self", these properties MUST all be stored per-user, and changes
do not affect any other user of the calendar. If shareesActAs is do not affect any other user of the calendar. If shareesActAs is
"owner", the values are shared between all users. "secretary", the values are shared between all users.
* keywords * keywords
* color * color
* freeBusyStatus * freeBusyStatus
* useDefaultAlerts * useDefaultAlerts
* alerts * alerts
skipping to change at page 17, line 13 skipping to change at page 16, line 32
override to remove an occurrence. override to remove an occurrence.
o *mayAdmin*: "Boolean" The user may modify sharing for this o *mayAdmin*: "Boolean" The user may modify sharing for this
calendar. calendar.
o *mayDelete*: "Boolean" (server-set) The user may delete the o *mayDelete*: "Boolean" (server-set) The user may delete the
calendar itself. This property MUST be false if the account to calendar itself. This property MUST be false if the account to
which this calendar belongs has the _isReadOnly_ property set to which this calendar belongs has the _isReadOnly_ property set to
true. true.
3.1. Calendar/get 3.1. Per-user properties
The following properties MUST be stored per-user:
o name
o color
o sortOrder
o isVisible
3.2. Calendar/get
This is a standard "/get" method as described in [RFC8620], This is a standard "/get" method as described in [RFC8620],
Section 5.1. The _ids_ argument may be "null" to fetch all at once. Section 5.1. The _ids_ argument may be "null" to fetch all at once.
If mayReadFreeBusy is the only permission the user has, the calendar If mayReadFreeBusy is the only permission the user has, the calendar
MUST NOT be returned in Calendar/get and Calendar/query; it must MUST NOT be returned in Calendar/get and Calendar/query; it must
behave as though it did not exist. The data is just used as part of behave as though it did not exist. The data is just used as part of
CalendarPrincipal/getAvailability. CalendarPrincipal/getAvailability.
3.2. Calendar/changes 3.3. Calendar/changes
This is a standard "/changes" method as described in [RFC8620], This is a standard "/changes" method as described in [RFC8620],
Section 5.2. Section 5.2.
3.3. Calendar/set 3.4. Calendar/set
This is a standard "/set" method as described in [RFC8620], This is a standard "/set" method as described in [RFC8620],
Section 5.3 but with the following additional request argument: Section 5.3 but with the following additional request argument:
o *onDestroyRemoveEvents*: "Boolean" (default: false) o *onDestroyRemoveEvents*: "Boolean" (default: false)
If false, any attempt to destroy a Calendar that still has If false, any attempt to destroy a Calendar that still has
CalendarEvents in it will be rejected with a "calendarHasEvents" CalendarEvents in it will be rejected with a "calendarHasEvents"
SetError. If true, any CalendarEvents that were in the Calendar will SetError. If true, any CalendarEvents that were in the Calendar will
be destroyed. This SHOULD NOT send scheduling messages to be destroyed. This SHOULD NOT send scheduling messages to
participants or create CalendarEventNotification objects. participants or create CalendarEventNotification objects.
The role and shareWith properties may only be set by users that have The "role" and "shareWith" properties may only be set by users that
the mayAdmin right. The value is shared across all users, although have the mayAdmin right. The value is shared across all users,
users without the mayAdmin right cannot see the value. although users without the mayAdmin right cannot see the value.
Users can subscribe or unsubscribe to a calendar by setting the Users can subscribe or unsubscribe to a calendar by setting the
isSubscribed property. The server MAY forbid users from subscribing "isSubscribed" property. The server MAY forbid users from
to certain calendars even though they haver permission to see them, subscribing to certain calendars even though they have permission to
rejecting the update with a "forbidden" SetError. see them, rejecting the update with a "forbidden" SetError.
The timeZone, includeInAvailability, defaultAlertsWithoutTime and The "timeZone", "includeInAvailability", "defaultAlertsWithoutTime"
defaultAlertsWithTime properties are stored per-user if the calendar and "defaultAlertsWithTime" properties are stored per-user if the
shareesActAs is "self" and may be set by any user who is subscribed calendar "shareesActAs" value is "self", and may be set by any user
to the calendar. Otherwise, these properties are shared, and may who is subscribed to the calendar. Otherwise, these properties are
only be set by users that have the mayAdmin right. shared, and may only be set by users that have the mayAdmin right.
The following properties may be set by anyone who is subscribed to The following properties may be set by anyone who is subscribed to
the calendar and are all stored per-user: the calendar and are all stored per-user:
o name o name
o description
o color o color
o sortOrder o sortOrder
o isVisible o isVisible
These properties are initially inherited from the owner's copy of the These properties are initially inherited from the owner's copy of the
calendar, but if set by a sharee that user gets their own copy of the calendar, but if set by a sharee that user gets their own copy of the
property; it does not change for any other principals. If the value property; it does not change for any other principals. If the value
of the property in the owner's calendar changes after this, it does of the property in the owner's calendar changes after this, it does
not overwrite the sharee's value. not overwrite the sharee's value.
The following extra SetError types are defined: The following extra SetError types are defined:
For "destroy": For "destroy":
skipping to change at page 19, line 29 skipping to change at page 19, line 11
The *CalendarShareNotification* object has the following properties: The *CalendarShareNotification* object has the following properties:
o *id*: "String" The id of the CalendarShareNotification. o *id*: "String" The id of the CalendarShareNotification.
o *created*: "UTCDate" The time this notification was created. o *created*: "UTCDate" The time this notification was created.
o *changedBy*: "Person" Who made the change. o *changedBy*: "Person" Who made the change.
* *name*: "String" The name of the person who made the change. * *name*: "String" The name of the person who made the change.
* *email*: "String" The email of the person who made the change. * *email*: "String|null" The email of the person who made the
change, or null if no email is available.
* *calendarPrincipalId*: "String|null" The id of the calendar * *calendarPrincipalId*: "String|null" The id of the
principal corresponding to the person who made the change. CalendarPrincipal corresponding to the person who made the
change, or null if no associated princiapal.
o *calendarAccountId*: "String" The id of the account where this o *calendarAccountId*: "String" The id of the account where this
calendar exists. Calendar exists.
o *calendarId*: "String" The id of the CalendarEvent that this o *calendarId*: "String" The id of the Calendar that this
notification is about. notification is about.
o *calendarName*: "String" The name of the calendar at the time the o *calendarName*: "String" The name of the Calendar at the time the
notification was made. notification was made.
o *oldRights*: "CalendarRights|null" The rights the user had before o *oldRights*: "CalendarRights|null" The rights the user had before
the change. the change.
o *newRights*: "CalendarRights|null" The rights the user has after o *newRights*: "CalendarRights|null" The rights the user has after
the change. the change.
4.3. CalendarShareNotification/get 4.3. CalendarShareNotification/get
skipping to change at page 21, line 12 skipping to change at page 20, line 43
It is a JSEvent object, as defined in [I-D.ietf-calext-jscalendar], It is a JSEvent object, as defined in [I-D.ietf-calext-jscalendar],
with the following additional properties: with the following additional properties:
o *id*: "Id" The id of the CalendarEvent. This property is o *id*: "Id" The id of the CalendarEvent. This property is
immutable. The id uniquely identifies a JSEvent with a particular immutable. The id uniquely identifies a JSEvent with a particular
"uid" and "recurrenceId" within a particular account. "uid" and "recurrenceId" within a particular account.
o *calendarId*: "Id" The id of the Calendar this event belongs to. o *calendarId*: "Id" The id of the Calendar this event belongs to.
o *isDraft*: "Boolean" If true, this event is to be considered a o *isDraft*: "Boolean" If true, this event is to be considered a
draft; the server will not send any scheduling messages to draft. The server will not send any scheduling messages to
participants while this is true. To use, this must be set on participants or send push notifications for alerts. This may only
creation. Once set to false, the value cannot be updated to true. be set to true upon creation. Once set to false, the value cannot
be updated to true. This property MUST NOT appear in
"recurrenceOverrides".
o *utcStart*: "UTCDate" For simple clients that do not or cannot o *utcStart*: "UTCDate" For simple clients that do not or cannot
implement time zone support. Clients should only use this if also implement time zone support. Clients should only use this if also
asking the server to expand recurrences, as you cannot accurately asking the server to expand recurrences, as you cannot accurately
expand a recurrence without the original time zone. This property expand a recurrence without the original time zone. This property
is calculated at fetch time by the server. Time zones are is calculated at fetch time by the server. Time zones are
political and they can and do change at any time. Fetching political and they can and do change at any time. Fetching
exactly the same property again may return a different results if exactly the same property again may return a different results if
the time zone data has been updated on the server. Time zone data the time zone data has been updated on the server. Time zone data
changes are not considered "updates" to the event. If set, server changes are not considered "updates" to the event. If set, server
will convert to the event's current time zone using its current will convert to the event's current time zone using its current
time zone data and store the local time. This is not included by time zone data and store the local time. This is not included by
default and must be requested explicitly. Floating events will be default and must be requested explicitly. Floating events will be
interpreted as per calendar's time zone property; or if not set, interpreted as per calendar's time zone property; or if not set,
the the principal's time zone property. the the principal's time zone property. Note that it is not
possible to accurately calculate the expansion of recurrence rules
or recurrence overrides with the utcStart property rather than the
local start time. Even simple recurrences such as "repeat weekly"
may cross a daylight-savings boundary and end up at a different
UTC time. Clients that wish to use "utcStart" are RECOMMENDED to
request the server expand recurrences (see Section XXX).
o *utcEnd*: "UTCDate" The server calculates the end time in UTC from o *utcEnd*: "UTCDate" The server calculates the end time in UTC from
the start/timeZone/duration properties of the event. This is not the start/timeZone/duration properties of the event. This is not
included by default and must be requested explicitly. Like included by default and must be requested explicitly. Like
utcStart, this is calculated at fetch time if requested and may utcStart, this is calculated at fetch time if requested and may
change due to time zone data changes. change due to time zone data changes.
CalendarEvent objects MUST NOT have a "method" property as this is CalendarEvent objects MUST NOT have a "method" property as this is
only used when representing iTIP [RFC5546] scheduling messages, not only used when representing iTIP [RFC5546] scheduling messages, not
events in a data store. events in a data store.
skipping to change at page 22, line 13 skipping to change at page 22, line 4
to expose these files as managed attachments [?@RFC8607]. to expose these files as managed attachments [?@RFC8607].
5.2. Per-user properties 5.2. Per-user properties
In shared calendars where "shareesActAs" is "self", the following In shared calendars where "shareesActAs" is "self", the following
properties MUST be stored per-user: properties MUST be stored per-user:
o keywords o keywords
o color o color
o freeBusyStatus o freeBusyStatus
o useDefaultAlerts o useDefaultAlerts
o alerts o alerts
The user may also modify the above on a per-occurrence basis for The user may also modify these properties on a per-occurrence basis
recurring events; again, these MUST be stored per-user. for recurring events; again, these MUST be stored per-user.
When writing per-user properties, the "updated" property MUST also be When writing per-user properties, the "updated" property MUST also be
stored just for that user. When fetching the "updated" property, the stored just for that user. When fetching the "updated" property, the
value to return is whichever is later of the per-user updated time or value to return is whichever is later of the per-user updated time or
the updated time of the master event. the updated time of the master event.
5.3. Recurring events 5.3. Recurring events
Events may recur, in which case they represent multiple occurrences Events may recur, in which case they represent multiple occurrences
or instances. The data store will either contain a single master or instances. The data store will either contain a single master
skipping to change at page 23, line 5 skipping to change at page 22, line 39
The client can fetch and update the objects using these ids and the The client can fetch and update the objects using these ids and the
server will make the appropriate changes to the master event. server will make the appropriate changes to the master event.
Synthetic ids do not appear in "CalendarEvent/changes" responses; Synthetic ids do not appear in "CalendarEvent/changes" responses;
only the ids of events as actually stored on the server. only the ids of events as actually stored on the server.
If the user is invited to specific instances then later added to the If the user is invited to specific instances then later added to the
master event, "CalendarEvent/changes" will show the ids of all the master event, "CalendarEvent/changes" will show the ids of all the
individual instances being destroyed and the id for the master event individual instances being destroyed and the id for the master event
being created. being created.
5.4. CalendarEvent/get 5.4. Updating for "this-and-future"
When editing a recurring event, you can either update the master
event (affecting all instances unless overriden) or update an
override for a specific occurrence. To update all occurrences from a
specific point onwards, there are therefore two options: split the
event, or update the master and override all occurrences before the
split point back to their original values.
5.4.1. Splitting an event
If the event is not scheduled (has no participants), the simplest
thing to do is to duplicate the event, modifying the recurrence rules
of the original so it finishes before the split point, and the
duplicate so it starts at the split point. As per JSCalendar
{TODO:ref} Section 4.1.3, a "next" and "first" relation MUST be set
on the new objects respectively.
Splitting an event however is problematic in the case of a scheduled
event, because the iTIP messages generated make it appear like two
unrelated changes, which can be confusing.
5.4.2. Updating the master and overriding previous
For scheduled events, a better approach is to avoid splitting and
instead update the master event with the new property value for "this
and future", then create overrides for all occurrences before the
split point to restore the property to its previous value. Indeed,
this may be the only option the user has permission to do if not an
owner of the event.
Clients may choose to skip creating the overrides if the old data is
not important, for example if the "alerts" property is being updated,
it is probably not important to create overrides for events in the
past with the alerts that have already fired.
5.5. CalendarEvent/get
This is a standard "/get" method as described in [RFC8620], This is a standard "/get" method as described in [RFC8620],
Section 5.1, with three extra arguments: Section 5.1, with three extra arguments:
o *recurrenceOverridesBefore*: "UTCDate|null" If given, only o *recurrenceOverridesBefore*: "UTCDate|null" If given, only
recurrence overrides with a recurrence id on or after this date recurrence overrides with a recurrence id on or after this date
(when translated into UTC) will be returned. (when translated into UTC) will be returned.
o *recurrenceOverridesAfter*: "UTCDate|null" If given, only o *recurrenceOverridesAfter*: "UTCDate|null" If given, only
recurrence overrides with a recurrence id before this date (when recurrence overrides with a recurrence id before this date (when
skipping to change at page 23, line 29 skipping to change at page 24, line 7
participants with the "owner" role or corresponding to the user's participants with the "owner" role or corresponding to the user's
participant identities will be returned in the "participants" participant identities will be returned in the "participants"
property of the master event and any recurrence overrides. If property of the master event and any recurrence overrides. If
false, all participants will be returned. false, all participants will be returned.
A CalendarEvent object is a JSEvent object so may have arbitrary A CalendarEvent object is a JSEvent object so may have arbitrary
properties. If the client makes a "CalendarEvent/get" call with a properties. If the client makes a "CalendarEvent/get" call with a
null or omitted "properties" argument, all properties defined on the null or omitted "properties" argument, all properties defined on the
JSEvent object in the store are returned, along with the "id", JSEvent object in the store are returned, along with the "id",
"calendarId", and "isDraft" properties. The "utcStart" and "utcEnd" "calendarId", and "isDraft" properties. The "utcStart" and "utcEnd"
computed properties are only returned if explicitly requested. computed properties are only returned if explicitly requested. If
either are requested, the "recurrenceOverrides" property MUST NOT be
requested (recurrence overrides cannot be interpreted accurately with
just the UTC times).
If specific properties are requested from the JSEvent and the If specific properties are requested from the JSEvent and the
property is not present on the object in the server's store, the property is not present on the object in the server's store, the
server SHOULD return the default value if known for that property. server SHOULD return the default value if known for that property.
An id requested by the server may represent a single instance of a A requested id may represent a single instance of a recurring event
recurring event if the client asked the server to expand recurrences if the client asked the server to expand recurrences in
in "CalendarEvent/query". In such a case, the server will resolve "CalendarEvent/query". In such a case, the server will resolve any
any overrides and set the appropriate "start" and "recurrenceId" overrides and set the appropriate "start" and "recurrenceId"
properties on the CalendarEvent object returned to the client. The properties on the CalendarEvent object returned to the client. The
"recurrenceRule" and "recurrenceOverrides" properties MUST be "recurrenceRule" and "recurrenceOverrides" properties MUST be
returned as null if requested for such an event. returned as null if requested for such an event.
An event with the same uid/recurrenceId may appear in different An event with the same uid/recurrenceId may appear in different
accounts. Clients may coalesce the view of such events, but must be accounts. Clients may coalesce the view of such events, but must be
aware that the data may be different in the different accounts due to aware that the data may be different in the different accounts due to
per-user properties, difference in permissions etc. per-user properties, difference in permissions etc.
The "privacy" property of a JSEvent object allows the owner to The "privacy" property of a JSEvent object allows the owner to
override how sharees of the calendar see the event. If this is set override how sharees of the calendar see the event. If this is set
to "private", when a sharee fetches the event the server MUST only to "private", when a sharee fetches the event the server MUST only
return the basic time and metadata properties of the JSEvent object return the basic time and metadata properties of the JSEvent object
as specified in [I-D.ietf-calext-jscalendar], Section 4.4.3. If set as specified in [I-D.ietf-calext-jscalendar], Section 4.4.3. If set
to "secret", the server MUST behave as though the event does not to "secret", the server MUST behave as though the event does not
exist for all users other than the owner. exist for all users other than the owner.
5.5. CalendarEvent/changes 5.6. CalendarEvent/changes
This is a standard "/changes" method as described in [RFC8620], This is a standard "/changes" method as described in [RFC8620],
Section 5.2. Section 5.2.
5.6. CalendarEvent/set 5.7. CalendarEvent/set
This is a standard "/set" method as described in [RFC8620], This is a standard "/set" method as described in [RFC8620],
Section 5.3, with the following extra argument: Section 5.3, with the following extra argument:
o *sendSchedulingMessages*: "Boolean" (default: true) If true then o *sendSchedulingMessages*: "Boolean" (default: true) If true then
any changes to scheduled events will be sent to all the any changes to scheduled events will be sent to all the
participants (if the user is an owner of the event) or back to the participants (if the user is an owner of the event) or back to the
owners (otherwise). If false, the changes only affect this owners (otherwise). If false, the changes only affect this
calendar and no scheduling messages will be sent. calendar and no scheduling messages will be sent.
skipping to change at page 24, line 40 skipping to change at page 25, line 22
a specific instance in a single "/set" request; the result of this is a specific instance in a single "/set" request; the result of this is
undefined. undefined.
Servers MUST enforce the user's permissions as returned in the Servers MUST enforce the user's permissions as returned in the
"myRights" property of the Calendar object and reject changes with a "myRights" property of the Calendar object and reject changes with a
"forbidden" SetError if not allowed. "forbidden" SetError if not allowed.
The "privacy" property MUST NOT be set to anything other than The "privacy" property MUST NOT be set to anything other than
"public" (the default) for events in a calendar that does not belong "public" (the default) for events in a calendar that does not belong
to the user (e.g. a shared team calendar). The server MUST reject to the user (e.g. a shared team calendar). The server MUST reject
this with an _invalidProperties_ SetError. this with an "invalidProperties" SetError.
The server MUST reject attempts to add events with a "participants" The server MUST reject attempts to add events with a "participants"
property where none of the participants correspond to one of the property where none of the participants correspond to one of the
calendar's participant identities with a "forbidden" SetError. calendar's participant identities with a "forbidden" SetError.
If omitted on create, the server MUST set the following properties to If omitted on create, the server MUST set the following properties to
an appropriate value: an appropriate value:
o @type o @type
skipping to change at page 25, line 4 skipping to change at page 25, line 34
The server MUST reject attempts to add events with a "participants" The server MUST reject attempts to add events with a "participants"
property where none of the participants correspond to one of the property where none of the participants correspond to one of the
calendar's participant identities with a "forbidden" SetError. calendar's participant identities with a "forbidden" SetError.
If omitted on create, the server MUST set the following properties to If omitted on create, the server MUST set the following properties to
an appropriate value: an appropriate value:
o @type o @type
o uid o uid
o created o created
o updated o updated
When modifying the event, the server MUST set the following When modifying the event, the server MUST set the following
properties if not explicitly set in the update: properties if the server is the source of the event and the property
is not explicitly set in the update:
o updated: set to the current time. o updated: set to the current time.
o sequence: increment by one, unless only per-user properties (see o sequence: increment by one, unless only per-user properties (see
Section XXX) were changed. Section XXX) were changed.
The "created" property MUST NOT be updated after creation. The The "created" property MUST NOT be updated after creation. The
"sequence" property MUST NOT be set to a lower number than its "sequence" property MUST NOT be set to a lower number than its
current value. The "method" property MUST NOT be set. Any attempt current value. The "method" property MUST NOT be set. Any attempt
to do these is rejected with a standard "invalidProperties" SetError. to do these is rejected with a standard "invalidProperties" SetError.
If "utcStart" is set, this is translated into a "start" property
using the server's current time zone information. It MUST NOT be set
in addition to a "start" property and it cannot be set inside
"recurrenceOverrides"; this MUST be rejected with an
"invalidProperties" SetError.
Similarly, the "utcEnd" property is translated into a "duration"
property if set. It MUST NOT be set in addition to a "duration"
property and it cannot be set inside "recurrenceOverrides"; this MUST
be rejected with an "invalidProperties" SetError.
The server does not automatically reset the "partipationStatus" or The server does not automatically reset the "partipationStatus" or
"expectReply" properties of a Participant if the event details "expectReply" properties of a Participant if the event details
change. Clients should either be intelligent about whether the change. Clients should either be intelligent about whether the
change necessitates resending RSVP requests, or ask the user whether change necessitates resending RSVP requests, or ask the user whether
to send them. to send them.
The server MAY enforce that all events have an owner, for example in The server MAY enforce that all events have an owner, for example in
team calendars. If the user tries to create an event without team calendars. If the user tries to create an event without
participants in such a calendar, the server MUST automatically add a participants in such a calendar, the server MUST automatically add a
participant with the "owner" role corresponding to one of the user's participant with the "owner" role corresponding to one of the user's
"participantIdentities" for the calendar. "participantIdentities" for the calendar.
When creating an event with participants, or adding participants to When creating an event with participants, or adding participants to
an event that previously did not have participants, the server MUST an event that previously did not have participants, the server MUST
set the "replyTo" property of the event if not present. Clients set the "replyTo" property of the event if not present. Clients
SHOULD NOT set the replyTo property for events when the user adds SHOULD NOT set the replyTo property for events when the user adds
participants; the server is better positioned to add all the methods participants; the server is better positioned to add all the methods
it supports to receive replies. it supports to receive replies.
5.6.1. Sending invitations and responses 5.7.1. Sending invitations and responses
Unless "sendSchedulingMessages" is false, the server MUST send Unless "sendSchedulingMessages" is false, the server MUST send
appropriate iTIP [RFC5546] scheduling messages after successfuly appropriate iTIP [RFC5546] scheduling messages after successfuly
creating, updating or destroying a calendar event. creating, updating or destroying a calendar event.
When determining which scheduling messages to send, the server must When determining which scheduling messages to send, the server must
first establish whether it is the _source_ of the event. The server first establish whether it is the _source_ of the event. The server
is the source if it will receive messages sent to any of the methods is the source if it will receive messages sent to any of the methods
specified in the "replyTo" property of the event. specified in the "replyTo" property of the event.
skipping to change at page 26, line 33 skipping to change at page 27, line 26
If the server is the source of the event it MUST NOT send messages to If the server is the source of the event it MUST NOT send messages to
any participant corresponding to the participantIdentities of the any participant corresponding to the participantIdentities of the
calendar it is in. calendar it is in.
If sending via iMIP [RFC6047], the server MAY choose to only send If sending via iMIP [RFC6047], the server MAY choose to only send
updates it deems "essential" to avoid flooding the recipient's email updates it deems "essential" to avoid flooding the recipient's email
with changes they do not care about. For example, changes to the with changes they do not care about. For example, changes to the
participationStatus of another participant, or changes to events participationStatus of another participant, or changes to events
solely in the past may be omitted. solely in the past may be omitted.
5.6.1.1. REQUEST 5.7.1.1. REQUEST
When the server is the source for the event, a REQUEST message When the server is the source for the event, a REQUEST message
([RFC5546], Section 3.2.2) is sent to all current participants if: ([RFC5546], Section 3.2.2) is sent to all current participants if:
o The event is being created. o The event is being created.
o Any non per-user property (see Section XXX) is updated on the o Any non per-user property (see Section XXX) is updated on the
event (including adding/removing participants), except if just event (including adding/removing participants), except if just
modifying the recurrenceOverrides such that CANCEL messages are modifying the recurrenceOverrides such that CANCEL messages are
generated (see the next section). generated (see the next section).
Note, if the only change is adding an additional instance (not Note, if the only change is adding an additional instance (not
generated by the event's recurrence rule) to the recurrenceOverrides, generated by the event's recurrence rule) to the recurrenceOverrides,
this could be handled via sending an ADD message ([RFC5546], this MAY be handled via sending an ADD message ([RFC5546],
Section 3.2.4) for the single instance rather than a REQUEST message Section 3.2.4) for the single instance rather than a REQUEST message
for the master. However, for interoperability reasons this is not for the master. However, for interoperability reasons this is not
recommended due to poor support in the wild for this type of message. recommended due to poor support in the wild for this type of message.
The server MUST ensure participants are only sent information about The server MUST ensure participants are only sent information about
recurrence instances they are added to when sending scheduling recurrence instances they are added to when sending scheduling
messages for recurring events. If the participant is not invited to messages for recurring events. If the participant is not invited to
the master recurring event but only individual instances, scheduling the master recurring event but only individual instances, scheduling
messages MUST be sent for just those expanded occurrences messages MUST be sent for just those expanded occurrences
individually. If a participant is invited to a recurring event, but individually. If a participant is invited to a recurring event, but
removed via a recurrence override from a particular instance, any removed via a recurrence override from a particular instance, any
scheduling messages to this participant MUST return the instance as scheduling messages to this participant MUST return the instance as
"excluded" (if it matches a recurrence rule for the event) or omit "excluded" (if it matches a recurrence rule for the event) or omit
the instance entirely (otherwise). the instance entirely (otherwise).
5.6.1.2. CANCEL 5.7.1.2. CANCEL
When the server is the source for the event, a CANCEL message When the server is the source for the event, a CANCEL message
([RFC5546], Section 3.2.5) is sent if: ([RFC5546], Section 3.2.5) is sent if:
o A participant is removed from either the master event or a single o A participant is removed from either the master event or a single
instance (the message is only sent to this participant; remaining instance (the message is only sent to this participant; remaining
participants will get a REQUEST, as described above). participants will get a REQUEST, as described above).
o The event is destroyed. o The event is destroyed.
o An exclusion is added to recurrenceOverrides to remove an instance o An exclusion is added to recurrenceOverrides to remove an instance
generated by the event's recurrence rule. generated by the event's recurrence rule.
o An additional instance (not generated by the event's recurrence o An additional instance (not generated by the event's recurrence
rule) is removed from the recurrenceOverrides. rule) is removed from the recurrenceOverrides.
In each of the latter 3 cases, the message is sent to all In each of the latter 3 cases, the message is sent to all
participants. participants.
5.6.1.3. REPLY 5.7.1.3. REPLY
When the server is _not_ the source for the event, a REPLY message When the server is _not_ the source for the event, a REPLY message
([RFC5546], Section 3.2.3) is sent for any participant corresponding ([RFC5546], Section 3.2.3) is sent for any participant corresponding
to the participantIdentities of the calendar it is in if: to the participantIdentities of the calendar it is in if:
o The "participationStatus" property of the participant is changed. o The "participationStatus" property of the participant is changed.
o The event is destroyed and the participationStatus was not "needs- o The event is destroyed and the participationStatus was not "needs-
action". action".
skipping to change at page 28, line 20 skipping to change at page 29, line 14
o An instance not generated by the event's recurrence rule is added o An instance not generated by the event's recurrence rule is added
to the recurrenceOverrides (this is presumed to be the client to the recurrenceOverrides (this is presumed to be the client
undoing the deletion of a single instance). undoing the deletion of a single instance).
A reply is not sent when deleting an event where the current status A reply is not sent when deleting an event where the current status
is "needs-action" as if a junk calendar event gets added by an is "needs-action" as if a junk calendar event gets added by an
automated system, the user MUST be able to delete the event without automated system, the user MUST be able to delete the event without
sending a reply. sending a reply.
5.7. CalendarEvent/copy 5.8. CalendarEvent/copy
This is a standard "/copy" method as described in [RFC8620], This is a standard "/copy" method as described in [RFC8620],
Section 5.4. Section 5.4.
5.8. CalendarEvent/query 5.9. CalendarEvent/query
This is a standard "/query" method as described in [RFC8620], This is a standard "/query" method as described in [RFC8620],
Section 5.5, with two extra arguments: Section 5.5, with two extra arguments:
o *expandRecurrences*: "Boolean" (default: false) If true, the o *expandRecurrences*: "Boolean" (default: false) If true, the
server will expand any recurring event. If true, the filter MUST server will expand any recurring event. If true, the filter MUST
be just a FilterCondition (not a FilterOperator) and MUST include be just a FilterCondition (not a FilterOperator) and MUST include
both a before and after property. This ensures the server is not both a before and after property. This ensures the server is not
asked to return an infinite number of results. asked to return an infinite number of results.
o *timeZone*: "String" The time zone for before/after filter o *timeZone*: "String" The time zone for before/after filter
conditions (default: "Etc/UTC") conditions (default: "Etc/UTC")
If expandRecurrences is true, a separate id will be returned for each If expandRecurrences is true, a separate id will be returned for each
instance of a recurring event that matches the query. Otherwise, a instance of a recurring event that matches the query. This synthetic
single id will be returned for matching recurring events that id is opaque to the client, but allows the server to resolve the id +
represents the entire event. recurrence id for "/get" and "/set" operations. Otherwise, a single
id will be returned for matching recurring events that represents the
entire event.
There is no necessary correspondence between the ids of different There is no necessary correspondence between the ids of different
instances of the same expanded event. instances of the same expanded event.
The following additional error may be returned instead of the The following additional error may be returned instead of the
"CalendarEvent/query" response: "CalendarEvent/query" response:
"cannotCalculateOccurrences": the server cannot expand a recurrence "cannotCalculateOccurrences": the server cannot expand a recurrence
required to return the results for this query. required to return the results for this query.
5.8.1. Filtering 5.9.1. Filtering
A *FilterCondition* object has the following properties: A *FilterCondition* object has the following properties:
o *inCalendars*: "Id[]|null" A list of calendar ids. An event must o *inCalendars*: "Id[]|null" A list of calendar ids. An event must
be in ANY of these calendars to match the condition. be in ANY of these calendars to match the condition.
o *after*: "LocalDate|null" The end of the event, or any recurrence o *after*: "LocalDate|null" The end of the event, or any recurrence
of the event, in the time zone given as the timeZone argument, of the event, in the time zone given as the timeZone argument,
must be after this date to match the condition. must be after this date to match the condition.
skipping to change at page 30, line 33 skipping to change at page 31, line 33
literal """, "'" and "\" respectively in a phrase. literal """, "'" and "\" respectively in a phrase.
o Outside of a phrase, white-space SHOULD be treated as dividing o Outside of a phrase, white-space SHOULD be treated as dividing
separate tokens that may be searched for separately in the event, separate tokens that may be searched for separately in the event,
but MUST all be present for the event to match the filter. but MUST all be present for the event to match the filter.
o Tokens MAY be matched on a whole-word basis using stemming (so for o Tokens MAY be matched on a whole-word basis using stemming (so for
example a text search for "bus" would match "buses" but not example a text search for "bus" would match "buses" but not
"business"). "business").
5.8.2. Sorting 5.9.2. Sorting
The following properties MUST be supported for sorting: The following properties MUST be supported for sorting:
o start o start
o uid o uid
o recurrenceId o recurrenceId
The following properties SHOULD be supported for sorting: The following properties SHOULD be supported for sorting:
o created o created
o updated o updated
5.9. CalendarEvent/queryChanges 5.10. CalendarEvent/queryChanges
This is a standard "/queryChanges" method as described in [RFC8620], This is a standard "/queryChanges" method as described in [RFC8620],
Section 5.6. Section 5.6.
5.10. Examples 5.11. Examples
TODO: Add example of how to get event by uid: query uid=foo and TODO: Add example of how to get event by uid: query uid=foo and
backref. Return multiple with recurrenceId set (user invited to backref. Return multiple with recurrenceId set (user invited to
specific instances of recurring event). specific instances of recurring event).
6. Alerts 6. Alerts
Alerts may be specified on events as described in Alerts may be specified on events as described in
[I-D.ietf-calext-jscalendar], Section 4.5. If the "useDefaultAlerts" [I-D.ietf-calext-jscalendar], Section 4.5. If the "useDefaultAlerts"
property is true, the alerts are taken from the Calendar property is true, the alerts are taken from the Calendar
skipping to change at page 33, line 49 skipping to change at page 34, line 49
The *CalendarEventNotification* object has the following properties: The *CalendarEventNotification* object has the following properties:
o *id*: "String" The id of the CalendarEventNotification. o *id*: "String" The id of the CalendarEventNotification.
o *created*: "UTCDate" The time this notification was created. o *created*: "UTCDate" The time this notification was created.
o *changedBy*: "Person" Who made the change. o *changedBy*: "Person" Who made the change.
* *name*: "String" The name of the person who made the change. * *name*: "String" The name of the person who made the change.
* *email*: "String" The email of the person who made the change. * *email*: "String" The email of the person who made the change,
or null if no email is available.
* *calendarPrincipalId*: "String|null" The id of the calendar * *calendarPrincipalId*: "String|null" The id of the calendar
principal corresponding to the person who made the change, if principal corresponding to the person who made the change, if
any. This will be null if the change was due to receving an any. This will be null if the change was due to receving an
iTIP message. iTIP message.
o *comment*: "String|null" Comment sent along with the change by the o *comment*: "String|null" Comment sent along with the change by the
user that made it. (e.g. COMMENT property in an iTIP message). user that made it. (e.g. COMMENT property in an iTIP message).
o *type*: "String" This MUST be one of o *type*: "String" This MUST be one of
skipping to change at page 36, line 36 skipping to change at page 37, line 38
TODO. TODO.
10. References 10. References
10.1. Normative References 10.1. Normative References
[I-D.ietf-calext-jscalendar] [I-D.ietf-calext-jscalendar]
Jenkins, N. and R. Stepanek, "JSCalendar: A JSON Jenkins, N. and R. Stepanek, "JSCalendar: A JSON
representation of calendar data", draft-ietf-calext- representation of calendar data", draft-ietf-calext-
jscalendar-20 (work in progress), October 2019. jscalendar-26 (work in progress), March 2020.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC2397] Masinter, L., "The "data" URL scheme", RFC 2397, [RFC2397] Masinter, L., "The "data" URL scheme", RFC 2397,
DOI 10.17487/RFC2397, August 1998, DOI 10.17487/RFC2397, August 1998,
<https://www.rfc-editor.org/info/rfc2397>. <https://www.rfc-editor.org/info/rfc2397>.
 End of changes. 62 change blocks. 
142 lines changed or deleted 191 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/