draft-ietf-jmap-calendars-03.txt   draft-ietf-jmap-calendars-04.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: December 17, 2020 Spherical Cow Group Expires: January 28, 2021 Spherical Cow Group
June 15, 2020 July 27, 2020
JMAP for Calendars JMAP for Calendars
draft-ietf-jmap-calendars-03 draft-ietf-jmap-calendars-04
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 December 17, 2020. This Internet-Draft will expire on January 28, 2021.
Copyright Notice Copyright Notice
Copyright (c) 2020 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 . . . . . . . . . . . . . . . . . . . 4 1.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 4
1.2. Accounts, Push, and the Session Object . . . . . . . . . 4 1.2. Accounts, Push, and the Session Object . . . . . . . . . 5
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 . . . . . . . . . . . . . . . . . 6
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 . . . . . . . . . . . . . . . . . . . . . 7 2. Calendar Principals . . . . . . . . . . . . . . . . . . . . . 8
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 . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3. Calendars . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.1. Per-user properties . . . . . . . . . . . . . . . . . . . 16 3.1. Calendar/get . . . . . . . . . . . . . . . . . . . . . . 17
3.2. Calendar/get . . . . . . . . . . . . . . . . . . . . . . 17 3.2. Calendar/changes . . . . . . . . . . . . . . . . . . . . 17
3.3. Calendar/changes . . . . . . . . . . . . . . . . . . . . 17 3.3. Calendar/set . . . . . . . . . . . . . . . . . . . . . . 17
3.4. Calendar/set . . . . . . . . . . . . . . . . . . . . . . 17
4. Calendar Share Notifications . . . . . . . . . . . . . . . . 18 4. Calendar Share Notifications . . . . . . . . . . . . . . . . 18
4.1. Auto-deletion of Notifications . . . . . . . . . . . . . 18 4.1. Auto-deletion of Notifications . . . . . . . . . . . . . 18
4.2. Object Properties . . . . . . . . . . . . . . . . . . . . 19 4.2. Object Properties . . . . . . . . . . . . . . . . . . . . 19
4.3. CalendarShareNotification/get . . . . . . . . . . . . . . 19 4.3. CalendarShareNotification/get . . . . . . . . . . . . . . 19
4.4. CalendarShareNotification/changes . . . . . . . . . . . . 19 4.4. CalendarShareNotification/changes . . . . . . . . . . . . 20
4.5. CalendarShareNotification/set . . . . . . . . . . . . . . 20 4.5. CalendarShareNotification/set . . . . . . . . . . . . . . 20
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. Additional JSCalendar properties . . . . . . . . . . . . 21 5.1. Additional JSCalendar properties . . . . . . . . . . . . 21
5.1.1. hideAttendees . . . . . . . . . . . . . . . . . . . . 21 5.1.1. mayInviteSelf . . . . . . . . . . . . . . . . . . . . 22
5.1.2. mayInviteOthers . . . . . . . . . . . . . . . . . . . 22
5.1.3. hideAttendees . . . . . . . . . . . . . . . . . . . . 22
5.2. Attachments . . . . . . . . . . . . . . . . . . . . . . . 22 5.2. Attachments . . . . . . . . . . . . . . . . . . . . . . . 22
5.3. Per-user properties . . . . . . . . . . . . . . . . . . . 22 5.3. Per-user properties . . . . . . . . . . . . . . . . . . . 22
5.4. Recurring events . . . . . . . . . . . . . . . . . . . . 22 5.4. Recurring events . . . . . . . . . . . . . . . . . . . . 23
5.5. Updating for "this-and-future" . . . . . . . . . . . . . 23 5.5. Updating for "this-and-future" . . . . . . . . . . . . . 23
5.5.1. Splitting an event . . . . . . . . . . . . . . . . . 23 5.5.1. Splitting an event . . . . . . . . . . . . . . . . . 24
5.5.2. Updating the master and overriding previous . . . . . 23 5.5.2. Updating the master and overriding previous . . . . . 24
5.6. CalendarEvent/get . . . . . . . . . . . . . . . . . . . . 24 5.6. CalendarEvent/get . . . . . . . . . . . . . . . . . . . . 24
5.7. CalendarEvent/changes . . . . . . . . . . . . . . . . . . 25 5.7. CalendarEvent/changes . . . . . . . . . . . . . . . . . . 25
5.8. CalendarEvent/set . . . . . . . . . . . . . . . . . . . . 25 5.8. CalendarEvent/set . . . . . . . . . . . . . . . . . . . . 26
5.8.1. Patching . . . . . . . . . . . . . . . . . . . . . . 27 5.8.1. Patching . . . . . . . . . . . . . . . . . . . . . . 27
5.8.2. Sending invitations and responses . . . . . . . . . . 30 5.8.2. Sending invitations and responses . . . . . . . . . . 31
5.9. CalendarEvent/copy . . . . . . . . . . . . . . . . . . . 33 5.9. CalendarEvent/copy . . . . . . . . . . . . . . . . . . . 34
5.10. CalendarEvent/query . . . . . . . . . . . . . . . . . . . 33 5.10. CalendarEvent/query . . . . . . . . . . . . . . . . . . . 34
5.10.1. Filtering . . . . . . . . . . . . . . . . . . . . . 34 5.10.1. Filtering . . . . . . . . . . . . . . . . . . . . . 35
5.10.2. Sorting . . . . . . . . . . . . . . . . . . . . . . 35 5.10.2. Sorting . . . . . . . . . . . . . . . . . . . . . . 36
5.11. CalendarEvent/queryChanges . . . . . . . . . . . . . . . 36 5.11. CalendarEvent/queryChanges . . . . . . . . . . . . . . . 37
5.12. Examples . . . . . . . . . . . . . . . . . . . . . . . . 36 5.12. Examples . . . . . . . . . . . . . . . . . . . . . . . . 37
6. Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 6. Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
6.1. Push events . . . . . . . . . . . . . . . . . . . . . . . 36 6.1. Push events . . . . . . . . . . . . . . . . . . . . . . . 37
6.2. Acknowledging an alert . . . . . . . . . . . . . . . . . 37 6.2. Acknowledging an alert . . . . . . . . . . . . . . . . . 38
6.3. Snoozing an alert . . . . . . . . . . . . . . . . . . . . 37 6.3. Snoozing an alert . . . . . . . . . . . . . . . . . . . . 38
7. Calendar Event Notifications . . . . . . . . . . . . . . . . 38 7. Calendar Event Notifications . . . . . . . . . . . . . . . . 39
7.1. Auto-deletion of Notifications . . . . . . . . . . . . . 38 7.1. Auto-deletion of Notifications . . . . . . . . . . . . . 39
7.2. Object Properties . . . . . . . . . . . . . . . . . . . . 38 7.2. Object Properties . . . . . . . . . . . . . . . . . . . . 39
7.3. CalendarEventNotification/get . . . . . . . . . . . . . . 39 7.3. CalendarEventNotification/get . . . . . . . . . . . . . . 40
7.4. CalendarEventNotification/changes . . . . . . . . . . . . 39 7.4. CalendarEventNotification/changes . . . . . . . . . . . . 40
7.5. CalendarEventNotification/set . . . . . . . . . . . . . . 39 7.5. CalendarEventNotification/set . . . . . . . . . . . . . . 40
7.6. CalendarEventNotification/query . . . . . . . . . . . . . 40 7.6. CalendarEventNotification/query . . . . . . . . . . . . . 41
7.6.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 40 7.6.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 41
7.6.2. Sorting . . . . . . . . . . . . . . . . . . . . . . . 40 7.6.2. Sorting . . . . . . . . . . . . . . . . . . . . . . . 41
7.7. CalendarEventNotification/queryChanges . . . . . . . . . 40 7.7. CalendarEventNotification/queryChanges . . . . . . . . . 41
8. Security Considerations . . . . . . . . . . . . . . . . . . . 40 8. Security Considerations . . . . . . . . . . . . . . . . . . . 41
8.1. Denial-of-service Expanding Recurrences . . . . . . . . . 40 8.1. Denial-of-service Expanding Recurrences . . . . . . . . . 41
8.2. Privacy . . . . . . . . . . . . . . . . . . . . . . . . . 41 8.2. Privacy . . . . . . . . . . . . . . . . . . . . . . . . . 42
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42
9.1. JMAP Capability Registration for "calendars" . . . . . . 41 9.1. JMAP Capability Registration for "calendars" . . . . . . 42
9.2. JSCalendar Property Registrations . . . . . . . . . . . . 41 9.2. JSCalendar Property Registrations . . . . . . . . . . . . 42
9.2.1. id . . . . . . . . . . . . . . . . . . . . . . . . . 41 9.2.1. id . . . . . . . . . . . . . . . . . . . . . . . . . 42
9.2.2. calendarId . . . . . . . . . . . . . . . . . . . . . 41 9.2.2. calendarId . . . . . . . . . . . . . . . . . . . . . 42
9.2.3. isDraft . . . . . . . . . . . . . . . . . . . . . . . 42 9.2.3. isDraft . . . . . . . . . . . . . . . . . . . . . . . 43
9.2.4. utcStart . . . . . . . . . . . . . . . . . . . . . . 42 9.2.4. utcStart . . . . . . . . . . . . . . . . . . . . . . 43
9.2.5. utcEnd . . . . . . . . . . . . . . . . . . . . . . . 42 9.2.5. utcEnd . . . . . . . . . . . . . . . . . . . . . . . 43
9.2.6. hideAttendees . . . . . . . . . . . . . . . . . . . . 42 9.2.6. mayInviteSelf . . . . . . . . . . . . . . . . . . . . 43
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 42 9.2.7. mayInviteOthers . . . . . . . . . . . . . . . . . . . 43
10.1. Normative References . . . . . . . . . . . . . . . . . . 43 9.2.8. hideAttendees . . . . . . . . . . . . . . . . . . . . 44
10.2. Informative References . . . . . . . . . . . . . . . . . 43 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 44
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 43 10.1. Normative References . . . . . . . . . . . . . . . . . . 44
10.2. Informative References . . . . . . . . . . . . . . . . . 45
10.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 45
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 8, line 37 skipping to change at page 8, line 45
* "group": This represents a group of people. * "group": This represents a group of people.
* "resource": This represents some resource, e.g. a projector. * "resource": This represents some resource, e.g. a projector.
* "location": This represents a location. * "location": This represents a location.
* "other": This represents some other undefined principal. * "other": This represents some other undefined principal.
o *timeZone*: "String" The time zone for this principal. The value o *timeZone*: "String" The time zone for this principal. The value
MUST be a time zone id from the IANA Time Zone Database. MUST be a time zone id from the IANA Time Zone Database TZDB [1].
o *mayGetAvailability*: "Boolean" May the user call the o *mayGetAvailability*: "Boolean" May the user call the
"CalendarPrincipal/getAvailability" method with this "CalendarPrincipal/getAvailability" method with this
CalendarPrincipal? CalendarPrincipal?
o *accountId*: "Id|null" Id of Account with the o *accountId*: "Id|null" Id of Account with the
"urn:ietf:params:jmap:calendars" capability that contains the data "urn:ietf:params:jmap:calendars" capability that contains the data
for this principal, or null if none (e.g. the CalendarPrincipal is for this principal, or null if none (e.g. the CalendarPrincipal is
a group just used for permissions management), or the user does a group just used for permissions management), or the user does
not have access to any data in the account (with the exception of not have access to any data in the account (with the exception of
skipping to change at page 12, line 43 skipping to change at page 12, line 47
3. Calendars 3. Calendars
A Calendar is a named collection of events. All events are A Calendar is a named collection of events. All events are
associated with one, and only one, calendar. associated with one, and only one, calendar.
A *Calendar* object has the following properties: A *Calendar* object has the following properties:
o *id*: "Id" (immutable; server-set) The id of the calendar. o *id*: "Id" (immutable; server-set) The id of the calendar.
o *role*: "String|null" Denotes the calendar has a special purpose. o *role*: "String|null" (default: null) Denotes the calendar has a
This MUST be one of the following: special purpose. This MUST be one of the following:
* "inbox": This is the principal's default calendar; when the * "inbox": This is the principal's default calendar; when the
principal is invited to an event, this is the calendar to which principal is invited to an event, this is the calendar to which
it will be added by the server. There MUST NOT be more than it will be added by the server. There MUST NOT be more than
one calendar with this role in an account. one calendar with this role in an account.
* "templates": This calendar holds templates for creating new * "templates": This calendar holds templates for creating new
events. All events in this calendar MUST have the "isDraft" events. All events in this calendar MUST have the "isDraft"
property set to true. Clients should not show this as a property set to true. Clients should not show this as a
regular calendar to users, but may offer users to create new regular calendar to users, but may offer users to create new
events by copying one of the events in here. events by copying one of the events in here.
o *name*: "String" The user-visible name of the calendar. This may o *name*: "String" The user-visible name of the calendar. This may
be any UTF-8 string of at least 1 character in length and maximum be any UTF-8 string of at least 1 character in length and maximum
255 octets in size. 255 octets in size.
o *description*: "String|null" An optional longer-form description o *description*: "String|null" (default: null) An optional longer-
of the calendar, to provide context in shared environments where form description of the calendar, to provide context in shared
users need more than just the name. environments where users need more than just the name.
o *color*: "String" The color to be used when displaying events o *color*: "String|null" (default: null) The color to be used when
associated with the calendar. The value MUST be a case- displaying events associated with the calendar.
insensitive color name taken from the CSS3 set of names, defined
in Section 4.3 of W3C.REC-css3-color-20110607, or a CSS3 RGB color If not null, the value MUST be a case-insensitive color name taken
hex value. The color SHOULD have sufficient contrast to be used from the set of names defined in Section 4.3 of CSS Color Module
as text on a white background. Level 3 COLORS [2], or an RGB value in hexadecimal notation, as
defined in Section 4.2.1 of CSS Color Module Level 3.
The color SHOULD have sufficient contrast to be used as text on a white background.
o *sortOrder*: "UnsignedInt" (default: 0) Defines the sort order of o *sortOrder*: "UnsignedInt" (default: 0) Defines the sort order of
calendars when presented in the client's UI, so it is consistent calendars when presented in the client's UI, so it is consistent
between devices. The number MUST be an integer in the range 0 <= between devices. The number MUST be an integer in the range 0 <=
sortOrder < 2^31. A calendar with a lower order should be sortOrder < 2^31. A calendar with a lower order should be
displayed before a calendar with a higher order in any list of displayed before a calendar with a higher order in any list of
calendars in the client's UI. Calendars with equal order SHOULD calendars in the client's UI. Calendars with equal order SHOULD
be sorted in alphabetical order by name. The sorting should take be sorted in alphabetical order by name. The sorting should take
into account locale-specific character order convention. into account locale-specific character order convention.
skipping to change at page 14, line 7 skipping to change at page 14, line 16
calendar's events be used as part of availability calculation? calendar's events be used as part of availability calculation?
This MUST be one of: This MUST be one of:
* "all": all events are considered. * "all": all events are considered.
* "attending": events the user is a confirmed or tentative * "attending": events the user is a confirmed or tentative
participant of are considered. participant of are considered.
* "none": all events are ignored. * "none": all events are ignored.
o *defaultAlertsWithTime*: "Alert[]" The alerts to apply for events o *defaultAlertsWithTime*: "Alert[]|null" (default: null) The alerts
where showWithoutTime is false that have "useDefaultAlerts" set. to apply for events where showWithoutTime is false that have
See [I-D.ietf-calext-jscalendar], Section 4.5.2 for the definition "useDefaultAlerts" set. See [I-D.ietf-calext-jscalendar],
of an Alert object. Section 4.5.2 for the definition of an Alert object.
o *defaultAlertsWithoutTime*: "Alert[]" The alerts to apply for o *defaultAlertsWithoutTime*: "Alert[]|null" (default: null) The
events where showWithoutTime is true that have "useDefaultAlerts" alerts to apply for events where showWithoutTime is true that have
set. See [I-D.ietf-calext-jscalendar], Section 4.5.2 for the "useDefaultAlerts" set. See [I-D.ietf-calext-jscalendar],
definition of an Alert object. Section 4.5.2 for the definition of an Alert object.
o *timeZone*: "String|null" The time zone to use for events without o *timeZone*: "String|null" (default: null) The time zone to use for
a time zone when the server needs to resolve them into absolute events without a time zone when the server needs to resolve them
time, e.g., for reminders, queries, or availability calculation. into absolute time, e.g., for reminders, queries, or availability
The value MUST be a time zone id from the IANA Time Zone Database. calculation. The value MUST be a time zone id from the IANA Time
If "null", the timeZone of the account's associated Zone Database TZDB [3]. If "null", the timeZone of the account's
CalendarPrincipal will be used. Clients SHOULD use this as the associated CalendarPrincipal will be used. Clients SHOULD use
default for new events in this calendar if set. this as the default for new events in this calendar if set.
o *participantIdentities*: "ParticipantIdentity[]|null" (server-set) o *participantIdentities*: "ParticipantIdentity[]|null" (server-set)
The identities that represent the user in this calendar. The The identities that represent the user in this calendar. The
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
skipping to change at page 14, line 45 skipping to change at page 15, line 5
* *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" (default: null) A map of
id to rights for principals this calendar is shared with. The CalendarPrincipal id to rights for principals this calendar is
pricincipal to which this calendar belongs MUST NOT be in this shared with. The pricincipal to which this calendar belongs MUST
set. This is null if the user requesting the object does not have NOT be in this set. This is null if the user requesting the
the mayAdmin right, or if the calendar is not shared with anyone. object does not have the mayAdmin right, or if the calendar is not
May be modified only if the user has the mayAdmin right. shared with anyone. 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:
* "secretary" * "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
"secretary", they act as the pricincipal to which this calendar "secretary", they act as the pricincipal to which this calendar
skipping to change at page 15, line 45 skipping to change at page 16, line 4
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
"secretary", 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
The user may also modify the above on a per-occurrence basis for The user may also modify the above on a per-occurrence basis for
recurring events. recurring events.
o *mayRSVP*: "Boolean" The user may modify the o *mayRSVP*: "Boolean" The user may modify the
"participationStatus", "participationComment", "expectReply", "participationStatus", "participationComment", "expectReply",
"scheduleAgent", "scheduleSequence", and "scheduleUpdated" "scheduleAgent", "scheduleSequence", and "scheduleUpdated"
properties of any Participant object that is represented in the properties of any Participant object where the sendTo property
"participantIdentities" property of the calendar. The user may matches a ParticipantIdentity of the calendar. If the event has
also modify the above on a per-occurrence basis for recurring its "mayInviteSelf" property set to true (see Section XXX), then
events. the user may also add a new Participant to the event with a sendTo
property that matches a ParticipantIdentity of the calendar. The
roles property of the participant MUST only contain "attendee".
If the event has its "mayInviteOthers" property set to true (see
Section XXX) and there is an existing Participant in the event
where the sendTo property matches a ParticipantIdentity of the
calendar, then the user may also add new participants. The roles
property of any new participant MUST only contain "attendee". The
user may also do all of the above on a per-occurrence basis for
recurring events.
o *mayUpdateOwn*: "Boolean" The user may modify an existing event on o *mayUpdateOwn*: "Boolean" The user may modify an existing event on
this calendar if either they are the owner of the event or the this calendar if either they are the owner of the event or the
event has no owner. event has no owner.
o *mayUpdateAll*: "Boolean" The user may modify all existing events o *mayUpdateAll*: "Boolean" The user may modify all existing events
on this calendar. on this calendar.
o *mayRemoveOwn*: "Boolean" The user may delete an event or move it o *mayRemoveOwn*: "Boolean" The user may delete an event or move it
to a different calendar if either they are the owner of the event to a different calendar if either they are the owner of the event
skipping to change at page 16, line 39 skipping to change at page 17, line 10
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. Per-user properties 3.1. Calendar/get
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.3. Calendar/changes 3.2. 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.4. Calendar/set 3.3. 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 "calendarHasEvent" CalendarEvents in it will be rejected with a "calendarHasEvent"
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
skipping to change at page 20, line 7 skipping to change at page 20, line 12
This is a standard "/get" method as described in [RFC8620], This is a standard "/get" method as described in [RFC8620],
Section 5.1. Section 5.1.
4.4. CalendarShareNotification/changes 4.4. CalendarShareNotification/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.
4.5. CalendarShareNotification/set 4.5. CalendarShareNotification/set
This is a standard "/changes" method as described in [RFC8620], This is a standard "/set" method as described in [RFC8620],
Section 5.3. Section 5.3.
Only destroy is supported; any attempt to create/update MUST be Only destroy is supported; any attempt to create/update MUST be
rejected with a "forbidden" SetError. rejected with a "forbidden" SetError.
4.6. CalendarShareNotification/query 4.6. CalendarShareNotification/query
This is a standard "/query" method as described in [RFC8620], This is a standard "/query" method as described in [RFC8620],
Section 5.5. Section 5.5.
skipping to change at page 21, line 41 skipping to change at page 21, line 47
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.
5.1. Additional JSCalendar properties 5.1. Additional JSCalendar properties
This document defines a new JSCalendar property. This document defines three new JSCalendar properties.
5.1.1. hideAttendees 5.1.1. mayInviteSelf
Type: "Boolean" (default: false)
If "true", any user that has access to the event may add themselves
to it as a participant with the "attendee" role. This property MUST
NOT be altered in the recurrenceOverrides; it may only be set on the
master object.
5.1.2. mayInviteOthers
Type: "Boolean" (default: false)
If "true", any current participant with the "attendee" role may add
new participants with the "attendee" role to the event. This
property MUST NOT be altered in the recurrenceOverrides; it may only
be set on the master object.
5.1.3. hideAttendees
Type: "Boolean" (default: false) Type: "Boolean" (default: false)
If "true", only the owners of the event may see the full set of If "true", only the owners of the event may see the full set of
participants. Other sharees of the event may only see the owners and participants. Other sharees of the event may only see the owners and
themselves. themselves. This property MUST NOT be altered in the
recurrenceOverrides; it may only be set on the master object.
5.2. Attachments 5.2. Attachments
The Link object, as defined in [I-D.ietf-calext-jscalendar] The Link object, as defined in [I-D.ietf-calext-jscalendar]
Section 4.2.7, with a "rel" property equal to "enclosure" is used to Section 4.2.7, with a "rel" property equal to "enclosure" is used to
represent attachments. Instead of mandating an "href" property, represent attachments. Instead of mandating an "href" property,
clients may set a "blobId" property instead to reference a blob of clients may set a "blobId" property instead to reference a blob of
binary data in the account, as per [RFC8620] Section 6. binary data in the account, as per [RFC8620] Section 6.
The server MUST translate this to an embedded "data:" URL [RFC2397] The server MUST translate this to an embedded "data:" URL [RFC2397]
skipping to change at page 22, line 26 skipping to change at page 23, line 4
to expose these files as managed attachments [?@RFC8607]. to expose these files as managed attachments [?@RFC8607].
5.3. Per-user properties 5.3. 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 these properties on a per-occurrence basis The user may also modify these properties on a per-occurrence basis
for 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 only per-user properties, the "updated" property MUST
stored just for that user. When fetching the "updated" property, the also be stored just for that user. When fetching the "updated"
value to return is whichever is later of the per-user updated time or property, the value to return is whichever is later of the per-user
the updated time of the master event. updated time or the updated time of the master event.
5.4. Recurring events 5.4. 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
event, containing a recurrence rule and/or recurrence overrides; or, event, containing a recurrence rule and/or recurrence overrides; or,
a set of individual instances (when invited to specific occurrences a set of individual instances (when invited to specific occurrences
only). only).
The client may ask the server to expand recurrences within a specific The client may ask the server to expand recurrences within a specific
skipping to change at page 25, line 26 skipping to change at page 26, line 10
5.7. CalendarEvent/changes 5.7. 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.8. CalendarEvent/set 5.8. 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: false) 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.
For recurring events, an id may represent the master event or a For recurring events, an id may represent the master event or a
specific instance. When the id for a specific instance is given, the specific instance. When the id for a specific instance is given, the
server MUST process an update as an update to the recurrence override server MUST process an update as an update to the recurrence override
for that instance on the master event, and a destroy as removing just for that instance on the master event, and a destroy as removing just
that instance. that instance.
skipping to change at page 26, line 18 skipping to change at page 26, line 48
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 The "updated" property MUST be set to the current time by the server
whenever an event is created or updated. If the client tries to set
When modifying the event, the server MUST set the following a value for this property it is not an error, but it MUST be
properties if the server is the source of the event (see Section XXX) overridden and replaced with the server's time.
and the property is not explicitly set in the update:
o updated: set to the current time.
o sequence: increment by one, unless only per-user properties (see When updating an event, if all of: * a non per-user property has been
Section XXX) were changed, in which case do not modify. changed; and * the server is the source of the event (see
Section XXX); and * the "sequence" property is not explicitly set in
the update, or the given value is less than or equal to the current
"sequence" value on the server; then the server MUST increment the
"sequence" value by one.
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 "method" property MUST NOT be set. Any attempt to do these is
current value. The "method" property MUST NOT be set. Any attempt 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 If "utcStart" is set, this is translated into a "start" property
using the server's current time zone information. It MUST NOT be set 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 in addition to a "start" property and it cannot be set inside
"recurrenceOverrides"; this MUST be rejected with an "recurrenceOverrides"; this MUST be rejected with an
"invalidProperties" SetError. "invalidProperties" SetError.
Similarly, the "utcEnd" property is translated into a "duration" Similarly, the "utcEnd" property is translated into a "duration"
property if set. It MUST NOT be set in addition to 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 property and it cannot be set inside "recurrenceOverrides"; this MUST
skipping to change at page 30, line 38 skipping to change at page 31, line 38
"participants/em9lQGZvb2GFtcGxlLmNvbQ/participationStatus": "participants/em9lQGZvb2GFtcGxlLmNvbQ/participationStatus":
"declined" "declined"
"participants/dG9tQGZvb2Jhci5xlLmNvbQ": null "participants/dG9tQGZvb2Jhci5xlLmNvbQ": null
} }
} }
} }
}, "0" ]] }, "0" ]]
5.8.2. Sending invitations and responses 5.8.2. Sending invitations and responses
Unless "sendSchedulingMessages" is false, the server MUST send If "sendSchedulingMessages" is true, the server MUST send appropriate
appropriate iTIP [RFC5546] scheduling messages after successfuly iTIP [RFC5546] scheduling messages after successfuly creating,
creating, updating or destroying a calendar event. 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.
Messages are only sent to participants with a "scheduleAgent" Messages are only sent to participants with a "scheduleAgent"
property set to "server" or omitted. If the effective property set to "server" or omitted. If the effective
"scheduleAgent" property is changed: "scheduleAgent" property is changed:
skipping to change at page 42, line 35 skipping to change at page 43, line 35
9.2.5. utcEnd 9.2.5. utcEnd
Property Name: utcEnd Property Name: utcEnd
Property Type: "UTCDateTime" Property Type: "UTCDateTime"
Property Context: JSEvent, JSTask Property Context: JSEvent, JSTask
Intended Use: Reserved Intended Use: Reserved
9.2.6. hideAttendees 9.2.6. mayInviteSelf
Property Name: mayInviteSelf
Property Type: "Boolean" (default: false)
Property Context: JSEvent, JSTask
Reference: This document, Section XXX.
Intended Use: Common
9.2.7. mayInviteOthers
Property Name: mayInviteOthers
Property Type: "Boolean" (default: false)
Property Context: JSEvent, JSTask
Reference: This document, Section XXX.
Intended Use: Common
9.2.8. hideAttendees
Property Name: hideAttendees Property Name: hideAttendees
Property Type: "Boolean" (default: false) Property Type: "Boolean" (default: false)
Property Context: JSEvent, JSTask Property Context: JSEvent, JSTask
Reference: This document, Section XXX. Reference: This document, Section XXX.
Intended Use: Common Intended Use: Common
skipping to change at page 43, line 4 skipping to change at page 44, line 23
Property Type: "Boolean" (default: false) Property Type: "Boolean" (default: false)
Property Context: JSEvent, JSTask Property Context: JSEvent, JSTask
Reference: This document, Section XXX. Reference: This document, Section XXX.
Intended Use: Common Intended Use: Common
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-26 (work in progress), March 2020. jscalendar-27 (work in progress), June 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>.
skipping to change at page 43, line 45 skipping to change at page 45, line 17
[RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
"Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
DOI 10.17487/RFC4791, March 2007, DOI 10.17487/RFC4791, March 2007,
<https://www.rfc-editor.org/info/rfc4791>. <https://www.rfc-editor.org/info/rfc4791>.
[RFC6047] Melnikov, A., Ed., "iCalendar Message-Based [RFC6047] Melnikov, A., Ed., "iCalendar Message-Based
Interoperability Protocol (iMIP)", RFC 6047, Interoperability Protocol (iMIP)", RFC 6047,
DOI 10.17487/RFC6047, December 2010, DOI 10.17487/RFC6047, December 2010,
<https://www.rfc-editor.org/info/rfc6047>. <https://www.rfc-editor.org/info/rfc6047>.
10.3. URIs
[1] https://www.iana.org/time-zones
[2] https://www.w3.org/TR/css-color-3/
[3] https://www.iana.org/time-zones
Authors' Addresses Authors' Addresses
Neil Jenkins Neil Jenkins
Fastmail Fastmail
PO Box 234, Collins St West PO Box 234, Collins St West
Melbourne VIC 8007 Melbourne VIC 8007
Australia Australia
Email: neilj@fastmailteam.com Email: neilj@fastmailteam.com
URI: https://www.fastmail.com URI: https://www.fastmail.com
Michael Douglass Michael Douglass
 End of changes. 43 change blocks. 
134 lines changed or deleted 190 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/