JMAP for Tasks

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 23 April 2022.¶

Copyright Notice

Copyright (c) 2021 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶

Table of Contents

1. Introduction

JMAP ([RFC8620] - JSON Meta Application Protocol) is a generic protocol for synchronizing data, such as mail, calendars or contacts, between a client and a server. It is optimized for mobile and web environments, and aims to provide a consistent interface to different data types.¶

JMAP for Calendars ([I-D.ietf-jmap-calendars]) defines a data model for synchronizing calendar data between a client and a server using JMAP. The data model is designed to allow a server to provide consistent access to the same data via CalDAV [RFC4791] as well as JMAP.¶

While CalDAV defines access to tasks, JMAP for Calendars does not. This specification fills this gap and defines a data model for synchronizing task data between a client and a server using JMAP. It is built upon JMAP for Calendars and reuses most of its definitions. For better readability this document only outlines differences between this specification and JMAP for Calendars. If not stated otherwise, the same specifics that apply to Calendar, CalendarEvent and CalendarEventNotification objects as defined in the aforemetioned specification also apply to similar data types introduced in this specification.¶

2. Principals

For systems that also support JMAP Sharing [I-D.ietf-jmap-sharing], the tasks capability is used to indicate that this principal may be used with tasks.¶

3. Assignee Identities

An AssigneeIdentity stores information about a URI that represents the user within that account in a task's assignees. It has the following properties:¶

• id: Id (immutable; server-set) The id of the AssigneeIdentity.¶
• name: String (default: "") The display name of the assignee to use when adding this assignee to a task, e.g. "Jane Bloggs".¶

• sendTo: String[String] Represents methods by which the participant may receive invitations and updates to a task.¶

  The keys in the property value are the available methods and MUST only contain ASCII alphanumeric characters (A-Za-z0-9). The value is a URI for the method specified in the key.¶

An assignee in an task corresponds to an AssigneeIdentity if any of the method/uri pairs in the sendTo property of the participant are identical to a method/uri pair in the sendTo property of the identity.¶

The following JMAP methods are supported.¶

4. TaskLists

A TaskList is a named collection of tasks. All tasks are associated with exactly one TaskList.¶

A TaskList object has the following properties:¶

• id: Id (immutable; server-set) The id of the task list.¶

• role: String|null (default: null) Denotes the task list has a special purpose. This MUST be one of the following:¶

  • inbox: This is the principal's default task list;¶
  • trash: This task list holds messages the user has discarded;¶

• name: String The user-visible name of the task list. This may be any UTF-8 string of at least 1 character in length and maximum 255 octets in size.¶

• description: String|null (default: null) An optional longer-form description of the task list, to provide context in shared environments where users need more than just the name.¶

• color: String|null (default: null) A color to be used when displaying tasks associated with the task list.¶

  If not null, the value MUST be a case-insensitive color name taken from the set of names defined in Section 4.3 of CSS Color Module Level 3 COLORS, 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.¶

• sortOrder: UnsignedInt (default: 0) Defines the sort order of task lists when presented in the client's UI, so it is consistent between devices. The number MUST be an integer in the range 0 <= sortOrder < 2^31.¶

  A task list with a lower order should be displayed before a list with a higher order in any list of task lists in the client's UI. Task lists with equal order SHOULD be sorted in alphabetical order by name. The sorting should take into account locale-specific character order convention.¶

• isSubscribed: Boolean Has the user indicated they wish to see this task list in their client? This SHOULD default to false for task lists in shared accounts the user has access to and true for any new task list created by the user themself.¶

  If false, the task list should only be displayed when the user explicitly requests it or to offer it for the user to subscribe to.¶

• defaultAlertsWithTime: Id[Alert]|null (default: null) A map of alert ids to Alert objects (see [I-D.ietf-calext-jscalendar], Section 4.5.2) to apply for tasks where "showWithoutTime" is false and "useDefaultAlerts" is true. Ids MUST be unique across all default alerts in the account, including those in other task lists; a UUID is recommended.¶

• defaultAlertsWithoutTime: Id[Alert]|null (default: null) A map of alert ids to Alert objects (see [I-D.ietf-calext-jscalendar], Section 4.5.2) to apply for tasks where "showWithoutTime" is true and "useDefaultAlerts" is true. Ids MUST be unique across all default alerts in the account, including those in other task lists; a UUID is recommended.¶

• timeZone: String|null (default: null) The time zone to use for tasks without a time zone when the server needs to resolve them into absolute time, e.g., for alerts or availability calculation. The value MUST be a time zone id from the IANA Time Zone Database TZDB. If null, the timeZone of the account's associated Principal will be used. Clients SHOULD use this as the default for new tasks in this task list if set.¶

• shareWith: Id[TaskRights]|null (default: null) A map of Principal id to rights for principals this task list is shared with. The principal to which this task list belongs MUST NOT be in this set. This is null if the user requesting the object does not have the mayAdmin right, or if the task list is not shared with anyone. May be modified only if the user has the mayAdmin right. The account id for the principals may be found in the urn:ietf:params:jmap:principals:owner capability of the Account to which the task list belongs.¶

• myRights: TaskRights (server-set) The set of access rights the user has in relation to this TaskList.¶

  • The user may fetch the task if they have the mayReadItems right on any task list the task is in.¶
  • The user may remove a task from a task list (by modifying the task's "taskListId" property) if the user has the appropriate permission for that task list.¶
  • The user may make other changes to the task if they have the right to do so in all task list to which the task belongs.¶

A TaskRights object has the following properties:¶

• mayReadItems: Boolean The user may fetch the tasks in this task list.¶
• mayWriteAll: Boolean The user may create, modify or destroy all tasks in this task list, or move tasks to or from this task list. If this is true, the mayWriteOwn, mayUpdatePrivate and mayRSVP properties MUST all also be true.¶
• mayWriteOwn: Boolean The user may create, modify or destroy a task on this task list if either they are the owner of the task or the task has no owner. This means the user may also transfer ownership by updating a task so they are no longer an owner.¶

• mayUpdatePrivate: Boolean The user may modify the following properties on all tasks in the task list, even if they would not otherwise have permission to modify that task. If the shareesActAs account capability is "self", these properties MUST all be stored per-user, and changes do not affect any other user of the task list. If shareesActAs is "secretary", the values are shared between all users.¶

  • keywords¶
  • color¶
  • useDefaultAlerts¶
  • alerts¶

  The user may also modify the above on a per-occurrence basis for recurring tasks (updating the recurrenceOverrides property of the task to do so).¶

• mayRSVP: Boolean The user may modify the following properties of any Participant object that corresponds to one of the user's ParticipantIdentity objects in the account, even if they would not otherwise have permission to modify that task¶

  • participationStatus¶
  • participationComment¶
  • expectReply¶

  If the task has its "mayInviteSelf" property set to true (see Section XXX), then the user may also add a new Participant to the task with a sendTo property that is the same as the sendTo property of one of the user's AssigneeIdentity objects in the account. The roles property of the participant MUST only contain "attendee".¶

  If the task has its "mayInviteOthers" property set to true (see Section XXX) and there is an existing Participant in the task corresponding to one of the user's AssigneeIdentity objects in the account, 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 tasks (updating the recurrenceOverrides property of the task to do so).¶

• mayAdmin: Boolean The user may modify sharing for this task list.¶

• mayDelete: Boolean (server-set) The user may delete the task list itself. This property MUST be false if the account to which this task list belongs has the isReadOnly property set to true.¶

The user is an owner for a task if the Task object has an "assignee" property, and one of the Participant objects both:¶

1. Has the "chair" role.¶
2. Corresponds to one of the user's AssigneeIdentity objects in the account.¶

A task has no owner if its assignee property is null or omitted.¶

5. Tasks

A Task object contains information about a task, or recurring series of tasks. It is a JSTask object, as defined in [I-D.ietf-calext-jscalendar], with the following additional properties:¶

• id: Id The id of the Task. This property is immutable. The id uniquely identifies a JSTask with a particular "uid" and "recurrenceId" within a particular account.¶

• taskListId: Id The TaskList id this task belongs to. A task MUST belong to exactly one TaskList at all times (until it is destroyed).¶

• isDraft: Boolean If true, this task is to be considered a draft. The server will not send any push notifications for alerts. This may only be set to true upon creation. Once set to false, the value cannot be updated to true. This property MUST NOT appear in "recurrenceOverrides".¶

• utcStart: UTCDate For simple clients that do not or cannot implement time zone support. Clients should only use this if also asking the server to expand recurrences, as you cannot accurately expand a recurrence without the original time zone.¶

  This property is calculated at fetch time by the server. Time zones are political, and they can and do change at any time. Fetching exactly the same property again may return different results if the time zone data has been updated on the server. Time zone data changes are not considered "updates" to the task.¶

  If set, the server will convert to the task's current time zone using its current time zone data and store the local time.¶

  This is not included by default and must be requested explicitly.¶

  Floating tasks (tasks without a time zone) will be interpreted as per the time zone given as a Task/get argument.¶

  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).¶

• utcDue: UTCDate The server calculates the end time in UTC from the start/timeZone/duration properties of the task. This is not included by default and must be requested explicitly. Like utcStart, this is calculated at fetch time if requested and may change due to time zone data changes. Floating tasks will be interpreted as per the time zone given as a Task/get argument.¶

• sortOrder: UnsignedInt (default: 0) Defines the sort order of a task when presented in the client's UI, so it is consistent between devices. The number MUST be an integer in the range 0 <= sortOrder < 2^31.¶

  A task with a lower order should be displayed before a task with a higher order in any list of tasks in the client's UI. Tasks with equal order SHOULD be sorted in alphabetical order by name. The sorting should take into account locale-specific character order convention.¶

6. Task Notifications

The TaskNotification data type records changes made by external entities to tasks in task lists the user is subscribed to. Notifications are stored in the same Account as the Task that was changed.¶

This is the same specification as the CalendarEventNotification object from [I-D.ietf-jmap-calendars], Section XXX. Only the object properties differ slightly and are therefore fully described in this document.¶

7. Security Considerations

All security considerations of JMAP for Calendars [I-D.ietf-jmap-calendars] apply to this specification.¶

8. IANA Considerations

Authors' Addresses