draft-jenkins-jscalendar-04.txt   draft-jenkins-jscalendar-05.txt 
Calendaring extensions N. Jenkins Calendaring extensions N. Jenkins
Internet-Draft R. Stepanek Internet-Draft R. Stepanek
Intended status: Standards Track FastMail Intended status: Standards Track FastMail
Expires: July 16, 2018 January 12, 2018 Expires: July 23, 2018 January 19, 2018
JSCalendar: A JSON representation of calendar data JSCalendar: A JSON representation of calendar data
draft-jenkins-jscalendar-04 draft-jenkins-jscalendar-05
Abstract Abstract
This specification defines a data model and JSON representation of This specification defines a data model and JSON representation of
calendar data that can be used for storage and data exchange in a calendar data that can be used for storage and data exchange in a
calendaring and scheduling environment. It aims to be an alternative calendaring and scheduling environment. It aims to be an alternative
to the widely deployed iCalendar data format and to be unambiguous, to the widely deployed iCalendar data format and to be unambiguous,
extendable and simple to process. extendable and simple to process.
Status of This Memo Status of This Memo
skipping to change at page 1, line 34 skipping to change at page 1, line 34
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 July 16, 2018. This Internet-Draft will expire on July 23, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 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 . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Relation to the iCalendar format . . . . . . . . . . . . 4 1.1. Relation to the iCalendar format . . . . . . . . . . . . 4
1.2. Notational Conventions . . . . . . . . . . . . . . . . . 5 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 5
2. JSCalendar objects . . . . . . . . . . . . . . . . . . . . . 5 2. JSCalendar objects . . . . . . . . . . . . . . . . . . . . . 5
2.1. JSEvent . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.1. JSEvent . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2. JSTask . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.2. JSTask . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3. JSGroup . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.3. JSGroup . . . . . . . . . . . . . . . . . . . . . . . . . 6
3. Structure of JSCalendar objects . . . . . . . . . . . . . . . 6 3. Structure of JSCalendar objects . . . . . . . . . . . . . . . 6
3.1. Type signatures . . . . . . . . . . . . . . . . . . . . . 6 3.1. Type signatures . . . . . . . . . . . . . . . . . . . . . 6
3.2. Data Types . . . . . . . . . . . . . . . . . . . . . . . 6 3.2. Data Types . . . . . . . . . . . . . . . . . . . . . . . 6
3.2.1. UTCDate . . . . . . . . . . . . . . . . . . . . . . . 6 3.2.1. UTCDate . . . . . . . . . . . . . . . . . . . . . . . 7
3.2.2. LocalDate . . . . . . . . . . . . . . . . . . . . . . 7 3.2.2. LocalDate . . . . . . . . . . . . . . . . . . . . . . 7
3.2.3. Duration . . . . . . . . . . . . . . . . . . . . . . 7 3.2.3. Duration . . . . . . . . . . . . . . . . . . . . . . 7
3.2.4. PatchObject . . . . . . . . . . . . . . . . . . . . . 7 3.2.4. PatchObject . . . . . . . . . . . . . . . . . . . . . 7
3.2.5. Normalisation and equivalence . . . . . . . . . . . . 8 3.2.5. Normalisation and equivalence . . . . . . . . . . . . 8
3.3. Custom property extensions and values . . . . . . . . . . 9 3.3. Custom property extensions and values . . . . . . . . . . 9
4. Common JSCalendar properties . . . . . . . . . . . . . . . . 9 4. Common JSCalendar properties . . . . . . . . . . . . . . . . 9
4.1. Metadata properties . . . . . . . . . . . . . . . . . . . 9 4.1. Metadata properties . . . . . . . . . . . . . . . . . . . 9
4.1.1. @type . . . . . . . . . . . . . . . . . . . . . . . . 9 4.1.1. @type . . . . . . . . . . . . . . . . . . . . . . . . 9
4.1.2. uid . . . . . . . . . . . . . . . . . . . . . . . . . 9 4.1.2. uid . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.1.3. relatedTo . . . . . . . . . . . . . . . . . . . . . . 10 4.1.3. relatedTo . . . . . . . . . . . . . . . . . . . . . . 10
4.1.4. prodId . . . . . . . . . . . . . . . . . . . . . . . 10 4.1.4. prodId . . . . . . . . . . . . . . . . . . . . . . . 11
4.1.5. created . . . . . . . . . . . . . . . . . . . . . . . 11 4.1.5. created . . . . . . . . . . . . . . . . . . . . . . . 11
4.1.6. updated . . . . . . . . . . . . . . . . . . . . . . . 11 4.1.6. updated . . . . . . . . . . . . . . . . . . . . . . . 11
4.1.7. sequence . . . . . . . . . . . . . . . . . . . . . . 11 4.1.7. sequence . . . . . . . . . . . . . . . . . . . . . . 11
4.1.8. method . . . . . . . . . . . . . . . . . . . . . . . 11 4.1.8. method . . . . . . . . . . . . . . . . . . . . . . . 11
4.2. What and where properties . . . . . . . . . . . . . . . . 11 4.2. What and where properties . . . . . . . . . . . . . . . . 11
4.2.1. title . . . . . . . . . . . . . . . . . . . . . . . . 11 4.2.1. title . . . . . . . . . . . . . . . . . . . . . . . . 12
4.2.2. description . . . . . . . . . . . . . . . . . . . . . 11 4.2.2. description . . . . . . . . . . . . . . . . . . . . . 12
4.2.3. htmlDescription . . . . . . . . . . . . . . . . . . . 12 4.2.3. htmlDescription . . . . . . . . . . . . . . . . . . . 12
4.2.4. locations . . . . . . . . . . . . . . . . . . . . . . 12 4.2.4. locations . . . . . . . . . . . . . . . . . . . . . . 12
4.2.5. links . . . . . . . . . . . . . . . . . . . . . . . . 14 4.2.5. links . . . . . . . . . . . . . . . . . . . . . . . . 14
4.2.6. locale . . . . . . . . . . . . . . . . . . . . . . . 15 4.2.6. locale . . . . . . . . . . . . . . . . . . . . . . . 15
4.2.7. keywords . . . . . . . . . . . . . . . . . . . . . . 15 4.2.7. keywords . . . . . . . . . . . . . . . . . . . . . . 15
4.2.8. categories . . . . . . . . . . . . . . . . . . . . . 15 4.2.8. categories . . . . . . . . . . . . . . . . . . . . . 16
4.2.9. color . . . . . . . . . . . . . . . . . . . . . . . . 16 4.2.9. color . . . . . . . . . . . . . . . . . . . . . . . . 16
4.3. Recurrence properties . . . . . . . . . . . . . . . . . . 16 4.3. Recurrence properties . . . . . . . . . . . . . . . . . . 16
4.3.1. recurrenceRule . . . . . . . . . . . . . . . . . . . 16 4.3.1. recurrenceRule . . . . . . . . . . . . . . . . . . . 16
4.3.2. recurrenceOverrides . . . . . . . . . . . . . . . . . 18 4.3.2. recurrenceOverrides . . . . . . . . . . . . . . . . . 18
4.4. Sharing and scheduling properties . . . . . . . . . . . . 19 4.4. Sharing and scheduling properties . . . . . . . . . . . . 19
4.4.1. priority . . . . . . . . . . . . . . . . . . . . . . 19 4.4.1. priority . . . . . . . . . . . . . . . . . . . . . . 19
4.4.2. freeBusyStatus . . . . . . . . . . . . . . . . . . . 19 4.4.2. freeBusyStatus . . . . . . . . . . . . . . . . . . . 19
4.4.3. privacy . . . . . . . . . . . . . . . . . . . . . . . 19 4.4.3. privacy . . . . . . . . . . . . . . . . . . . . . . . 19
4.4.4. replyTo . . . . . . . . . . . . . . . . . . . . . . . 20 4.4.4. replyTo . . . . . . . . . . . . . . . . . . . . . . . 21
4.4.5. participants . . . . . . . . . . . . . . . . . . . . 21 4.4.5. participants . . . . . . . . . . . . . . . . . . . . 22
4.5. Alerts properties . . . . . . . . . . . . . . . . . . . . 24 4.5. Alerts properties . . . . . . . . . . . . . . . . . . . . 24
4.5.1. useDefaultAlerts . . . . . . . . . . . . . . . . . . 24 4.5.1. useDefaultAlerts . . . . . . . . . . . . . . . . . . 25
4.5.2. alerts . . . . . . . . . . . . . . . . . . . . . . . 25 4.5.2. alerts . . . . . . . . . . . . . . . . . . . . . . . 25
4.6. Multilingual properties . . . . . . . . . . . . . . . . . 27 4.6. Multilingual properties . . . . . . . . . . . . . . . . . 28
4.6.1. localizations . . . . . . . . . . . . . . . . . . . . 27 4.6.1. localizations . . . . . . . . . . . . . . . . . . . . 28
5. Type-specific JSCalendar properties . . . . . . . . . . . . . 28 5. Type-specific JSCalendar properties . . . . . . . . . . . . . 28
5.1. JSEvent properties . . . . . . . . . . . . . . . . . . . 28 5.1. JSEvent properties . . . . . . . . . . . . . . . . . . . 28
5.1.1. start . . . . . . . . . . . . . . . . . . . . . . . . 28 5.1.1. start . . . . . . . . . . . . . . . . . . . . . . . . 29
5.1.2. timeZone . . . . . . . . . . . . . . . . . . . . . . 28 5.1.2. timeZone . . . . . . . . . . . . . . . . . . . . . . 29
5.1.3. duration . . . . . . . . . . . . . . . . . . . . . . 28 5.1.3. duration . . . . . . . . . . . . . . . . . . . . . . 29
5.1.4. isAllDay . . . . . . . . . . . . . . . . . . . . . . 29 5.1.4. isAllDay . . . . . . . . . . . . . . . . . . . . . . 29
5.1.5. status . . . . . . . . . . . . . . . . . . . . . . . 29 5.1.5. status . . . . . . . . . . . . . . . . . . . . . . . 30
5.2. JSTask properties . . . . . . . . . . . . . . . . . . . . 29 5.2. JSTask properties . . . . . . . . . . . . . . . . . . . . 30
5.2.1. due . . . . . . . . . . . . . . . . . . . . . . . . . 29 5.2.1. due . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.2.2. start . . . . . . . . . . . . . . . . . . . . . . . . 30 5.2.2. start . . . . . . . . . . . . . . . . . . . . . . . . 30
5.2.3. timeZone . . . . . . . . . . . . . . . . . . . . . . 30 5.2.3. timeZone . . . . . . . . . . . . . . . . . . . . . . 30
5.2.4. estimatedDuration . . . . . . . . . . . . . . . . . . 30 5.2.4. estimatedDuration . . . . . . . . . . . . . . . . . . 30
5.2.5. completed . . . . . . . . . . . . . . . . . . . . . . 30 5.2.5. completed . . . . . . . . . . . . . . . . . . . . . . 31
5.2.6. isAllDay . . . . . . . . . . . . . . . . . . . . . . 30 5.2.6. isAllDay . . . . . . . . . . . . . . . . . . . . . . 31
5.2.7. progress . . . . . . . . . . . . . . . . . . . . . . 31 5.2.7. progress . . . . . . . . . . . . . . . . . . . . . . 31
5.2.8. status . . . . . . . . . . . . . . . . . . . . . . . 31 5.2.8. status . . . . . . . . . . . . . . . . . . . . . . . 32
5.3. JSGroup properties . . . . . . . . . . . . . . . . . . . 32 5.3. JSGroup properties . . . . . . . . . . . . . . . . . . . 32
5.3.1. entries . . . . . . . . . . . . . . . . . . . . . . . 32 5.3.1. entries . . . . . . . . . . . . . . . . . . . . . . . 33
5.3.2. source . . . . . . . . . . . . . . . . . . . . . . . 32 5.3.2. source . . . . . . . . . . . . . . . . . . . . . . . 33
6. Conversion from and to iCalendar . . . . . . . . . . . . . . 33 6. Conversion from and to iCalendar . . . . . . . . . . . . . . 33
6.1. JSEvent . . . . . . . . . . . . . . . . . . . . . . . . . 33 6.1. JSEvent . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.2. JSTask . . . . . . . . . . . . . . . . . . . . . . . . . 33 6.2. JSTask . . . . . . . . . . . . . . . . . . . . . . . . . 34
6.3. JSGroup . . . . . . . . . . . . . . . . . . . . . . . . . 34 6.3. JSGroup . . . . . . . . . . . . . . . . . . . . . . . . . 35
6.4. Common properties . . . . . . . . . . . . . . . . . . . . 35 6.4. Common properties . . . . . . . . . . . . . . . . . . . . 36
6.5. Locations and participants . . . . . . . . . . . . . . . 37 6.5. Locations and participants . . . . . . . . . . . . . . . 38
6.6. Unknown properties . . . . . . . . . . . . . . . . . . . 39 6.6. Unknown properties . . . . . . . . . . . . . . . . . . . 40
7. JSCalendar object examples . . . . . . . . . . . . . . . . . 39 7. JSCalendar object examples . . . . . . . . . . . . . . . . . 40
7.1. Simple JSEvent . . . . . . . . . . . . . . . . . . . . . 39 7.1. Simple event . . . . . . . . . . . . . . . . . . . . . . 40
7.2. Recurring JSEvent with exception . . . . . . . . . . . . 40 7.2. Simple task . . . . . . . . . . . . . . . . . . . . . . . 41
8. Security Considerations . . . . . . . . . . . . . . . . . . . 42 7.3. Simple group . . . . . . . . . . . . . . . . . . . . . . 41
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 7.4. All-day event . . . . . . . . . . . . . . . . . . . . . . 42
10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 42 7.5. Task with a due date . . . . . . . . . . . . . . . . . . 42
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 42 7.6. Event with end time-zone . . . . . . . . . . . . . . . . 43
11.1. Normative References . . . . . . . . . . . . . . . . . . 42 7.7. Floating-time event (with recurrence) . . . . . . . . . . 43
11.2. Informative References . . . . . . . . . . . . . . . . . 44 7.8. Event with multiple locations and localization . . . . . 44
11.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 45 7.9. Recurring event with overrides . . . . . . . . . . . . . 45
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 45 7.10. Recurring event with participants . . . . . . . . . . . . 45
8. Security Considerations . . . . . . . . . . . . . . . . . . . 47
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47
10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 47
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 47
11.1. Normative References . . . . . . . . . . . . . . . . . . 47
11.2. Informative References . . . . . . . . . . . . . . . . . 50
11.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 50
1. Introduction 1. Introduction
This document defines a data model for calendar event and task This document defines a data model for calendar event and task
objects, or groups of such objects, in electronic calendar objects, or groups of such objects, in electronic calendar
applications and systems. It aims to be unambiguous, extendable and applications and systems. It aims to be unambiguous, extendable and
simple to process. simple to process.
The key design considerations for this data model are as follows: The key design considerations for this data model are as follows:
skipping to change at page 13, line 30 skipping to change at page 13, line 44
* "video": video conferencing * "video": video conferencing
* any vendor-prefixed custom value * any vendor-prefixed custom value
o *timeZone*: "String|null" (Defaults to "null" if omitted) A time- o *timeZone*: "String|null" (Defaults to "null" if omitted) A time-
zone for this location. zone for this location.
If "null", the *timeZone* from the JSCalendar object MUST be If "null", the *timeZone* from the JSCalendar object MUST be
presumed when a time-zone is needed in relation to this location. presumed when a time-zone is needed in relation to this location.
This property MUST be "null" if the *rel* property value of this
location is "start".
o *coordinates*: "String" An [RFC5870] "geo:" URI for the location. o *coordinates*: "String" An [RFC5870] "geo:" URI for the location.
o *uri*: "String" A URI that represents how to connect to this o *uri*: "String" A URI that represents how to connect to this
location. location.
This may be a telephone number (represented as This may be a telephone number (represented as
"tel:+1-555-555-555") for a teleconference, a web address for "tel:+1-555-555-555") for a teleconference, a web address for
online chat, or any custom URI. online chat, or any custom URI.
skipping to change at page 16, line 11 skipping to change at page 16, line 19
Specifies the categories related to the calendar object. Array Specifies the categories related to the calendar object. Array
values MUST be URIs. In contrast to *keywords*, categories typically values MUST be URIs. In contrast to *keywords*, categories typically
are structured. are structured.
For example, a vendor owning the domain "example.com" might define For example, a vendor owning the domain "example.com" might define
the categories "http://example.com/categories/sports/american- the categories "http://example.com/categories/sports/american-
football"" and "http://example.com/categories/music/r-b". football"" and "http://example.com/categories/music/r-b".
4.2.9. color 4.2.9. color
Type: "String" Type: "String|null"
Specifies a color clients MAY use when displaying this calendar Specifies a color clients MAY use when displaying this calendar
object. The value is a case-insensitive color name taken from the object. The value is a case-insensitive color name taken from the
CSS3 set of names, defined in Section 4.3 of W3C.REC- CSS3 set of names, defined in Section 4.3 of W3C.REC-
css3-color-20110607 [3] or a CSS3 RGB color hex value. css3-color-20110607 [3] or a CSS3 RGB color hex value.
4.3. Recurrence properties 4.3. Recurrence properties
4.3.1. recurrenceRule 4.3.1. recurrenceRule
skipping to change at page 27, line 14 skipping to change at page 27, line 26
* *textBody*: "String" (optional) The plain-text body to use for * *textBody*: "String" (optional) The plain-text body to use for
the email. If omitted, the body of the email is implementation the email. If omitted, the body of the email is implementation
specific, but the server SHOULD include all pertinent details specific, but the server SHOULD include all pertinent details
about the calendar object, such as summary, location and start about the calendar object, such as summary, location and start
time. time.
* *htmlBody*: "String" (optional) The HTML body to use for the * *htmlBody*: "String" (optional) The HTML body to use for the
email, with rich-media content processed as for the email, with rich-media content processed as for the
*htmlDescription* property of the JSCalendar object (see *htmlDescription* property of the JSCalendar object (see
Section 4.2.3). If the textBody property of this alert action Section 4.2.3), e.g. all CID URLs MUST be embedded in the
is not set, the server SHOULD generate a plain-text version generated alert email HTML body, or the *htmlBody* property
from the HTML body and include it in a "multipart/alternative" ignored completely. If the textBody property of this alert
MIME message. action is not set, the server SHOULD generate a plain-text
version from the HTML body and include it in a "multipart/
alternative" MIME message.
* *attachments*: "String[]|null" (optional) A list of link
identifiers in the JSCalendar object links property. Included
attachments SHOULD be embedded in the MIME message with the
"Content-Disposition" header value set to "attachment" (see
[RFC2183]). Implementations MAY refuse to include one or more
attachments when building an alert email, in which case they
MUST ignore the contents of the *attachments* property (e.g.
they MUST NOT include a subset of attachments).
An *UnknownAction* object is an object that contains a *type * An *UnknownAction* object is an object that contains a *type *
property whose value is not "email" or "string", plus zero or more property whose value is not "email" or "string", plus zero or more
other properties. This is for compatibility with client other properties. This is for compatibility with client
extensions and future RFCs. The client or server SHOULD NOT extensions and future RFCs. The client or server SHOULD NOT
trigger any type of alert for action types they do not understand, trigger any type of alert for action types they do not understand,
but MUST preserve them. but MUST preserve them.
4.6. Multilingual properties 4.6. Multilingual properties
skipping to change at page 30, line 52 skipping to change at page 31, line 31
a current, single instance of JSTask with this instance completion a current, single instance of JSTask with this instance completion
time and a future recurring instance. Also see the definition of the time and a future recurring instance. Also see the definition of the
*relatedTo* on splitting. *relatedTo* on splitting.
5.2.6. isAllDay 5.2.6. isAllDay
Type: "Boolean" (optional, defaults to "false") Type: "Boolean" (optional, defaults to "false")
Specifies if the task is an all day task. Specifies if the task is an all day task.
If *isAllDay* is true, then the following restrictions apply: If *isAllDay* is true, then the *start* and *due* properties MUST
have a time component of "T00:00:00". Note that the
o the *start* and *due* properties MUST have a time component of *estimatedDuration* property MAY contain a non-zero time duration.
"T00:00:00". All-day tasks MAY be bound to a specific time-zone, as defined by the
*timeZone* property.
o the *estimatedDuration* property MUST only include a day
component.
Note that all-day tasks MAY be bound to a specific time-zone, as
defined by the *timeZone* property.
5.2.7. progress 5.2.7. progress
In addition to the common properties of a *Participant* object In addition to the common properties of a *Participant* object
(Section 4.4.5), a Participant within a JSTask supports the following (Section 4.4.5), a Participant within a JSTask supports the following
property: property:
o *progress*: "ParticipantProgress|null" The progress of the o *progress*: "ParticipantProgress|null" The progress of the
participant for this task, if known. participant for this task, if known.
skipping to change at page 39, line 38 skipping to change at page 40, line 38
o *Alternate link*: Define an alternate link (Section 4.2.5) value o *Alternate link*: Define an alternate link (Section 4.2.5) value
pointing to the iCalendar representation of the JSCalendar object. pointing to the iCalendar representation of the JSCalendar object.
E.g. the alternative representation of a VEVENT would be E.g. the alternative representation of a VEVENT would be
represented as a link with rel "alternate" and type "text/ represented as a link with rel "alternate" and type "text/
calendar;component=VEVENT". calendar;component=VEVENT".
7. JSCalendar object examples 7. JSCalendar object examples
The following examples illustrate several aspects of the JSCalendar The following examples illustrate several aspects of the JSCalendar
data model and format. data model and format. The examples may omit mandatory or additional
properties, which is indicated by a placeholder property with key
"...". While most of the examples use calendar event objects, they
are also illustrative for tasks.
7.1. Simple JSEvent 7.1. Simple event
This JSEvent object represents a one-time event taking place on This example illustrates a simple one-time event. It specifies a
September 28 at 4pm, UTC for one hour. one-time event that begins on January 15, 2018 at 1pm New York local
time and ends after 1 hour.
{
"@type": "jsevent",
"uid": "2a358cee-6489-4f14-a57f-c104db4dc2f1",
"updated": "2018-01-15T18:00:00Z",
"title": "Some event",
"start": "2018-01-15T13:00:00",
"timeZone": "America/New_York",
"duration": "PT1H"
}
7.2. Simple task
This example illustrates a simple task for a plain to-do item.
{
"@type": "jstask",
"uid": "2a358cee-6489-4f14-a57f-c104db4dc2f2",
"updated": "2018-01-15T18:00:00Z",
"title": "Do something"
}
7.3. Simple group
This example illustrates a simple calendar object group that contains
an event and a task.
{
"@type": "jsgroup",
"uid": "2a358cee-6489-4f14-a57f-c104db4dc343",
"updated": "2018-01-15T18:00:00Z",
"name": "A simple group",
"entries": [
{ {
"@type": "jsevent", "@type": "jsevent",
"uid": "2a358cee-6489-4f14-a57f-c104db4dc357", "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f1",
"updated": "2016-09-14T13:24:34Z", "updated": "2018-01-15T18:00:00Z",
"title": "Squash", "title": "Some event",
"description": "", "start": "2018-01-15T13:00:00",
"htmlDescription": "", "timeZone": "America/New_York",
"start": "2016-09-28T16:00:00", "duration": "PT1H"
"timeZone": "Etc/UTC", },
"duration": "PT1H", {
"recurrenceRule": null, "@type": "jstask",
"recurrenceOverrides": null, "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f2",
"freeBusyStatus": "free", "updated": "2018-01-15T18:00:00Z",
"replyTo": null, "title": "Do something"
"participants": null,
"alerts": null,
"links": null,
"locations": null,
"locale": "en",
"localizations": null,
} }
]
}
Since properties can be omitted if their default value is used, this 7.4. All-day event
can be simplified to:
{ This example illustrates an event for an international holiday. It
"@type": "jsevent", specifies an all-day event on April 1 that occurs every year since
"uid": "2a358cee-6489-4f14-a57f-c104db4dc357", the year 1900.
"updated": "2016-09-14T13:24:34Z",
"title": "Squash", {
"start": "2016-09-28T16:00:00", "...": "",
"timeZone": "Etc/UTC", "title": "April Fool's Day",
"duration": "PT1H", "isAllDay": true,
"locale": "en" "start": "1900-04-01T00:00:00",
"duration": "P1D",
"recurrenceRule": {
"frequency": "yearly"
}
}
7.5. Task with a due date
This example illustrates a task with a due date. It is a reminder to
buy groceries before 6pm Vienna local time on January 19, 2018. The
calendar user expects to need 1 hour for shopping.
{
"...": "",
"title": "Buy groceries",
"due": "2018-01-19T18:00:00",
"timeZone": "Europe/Vienna",
"estimatedDuration": "PT1H"
}
7.6. Event with end time-zone
This example illustrates the use of end time-zones by use of an
international flight. The flight starts on April 1, 2018 at 9am in
Berlin local time. The duration of the flight is scheduled at 10
hours 30 minutes. The time at the flights destination is in the same
time-zone as Tokyo. Calendar clients could use the end time-zone to
display the arrival time in Tokyo local time and highlight the time-
zone difference of the flight.
{
"...": "",
"title": "Flight XY51 from FRA to NRT",
"start": "2018-04-01T09:00:00",
"timeZone": "Europe/Berlin",
"duration": "PT10H30M",
"locations": {
"2a358cee-6489-4f14-a57f-c104db4dc2f1": {
"rel": "end",
"timeZone": "Asia/Tokyo"
} }
}
}
7.2. Recurring JSEvent with exception 7.7. Floating-time event (with recurrence)
This JSEvent object represents a recurring event, taking place the This example illustrates the use of floating-time. Since January 1,
first time on January 1, 2016 at 1pm in Vienna, Europe. It recurs 2018, a calendar user blocks 30 minutes every day to practice Yoga at
monthly, but does not occur on February 1, 2016. In addition to the 7am local time, in whatever time-zone the user is located on that
regular recurrences it also occurs on December 5, 2016 at 5pm, Vienna date.
time. On May 1, it takes place at another location and lasts for two
hours, in contrast to the regular one-hour duration.
{ {
"@type": "jsevent", "...": "",
"uid": "89eee195-600b-423b-b3a6-52b3a420e556", "title": "Yoga",
"title": "Tennis", "start": "2018-01-01T07:00:00",
"duration": "PT30M",
"recurrenceRule": {
"frequency": "daily"
}
}
7.8. Event with multiple locations and localization
This example illustrates an event that happens at both a physical and
a virtual location. Fans can see a live convert on premises or
online. The event title and descriptions are localized. (Note: the
localization of the event description contains an UTF-8 encoded
German Umlaut. This characte r may have been replaced with ASCII
characters in the plain-text rendering of this RFC document.)
{
"...": "",
"title": "Live from Music Bowl: The Band",
"description": "Go see the biggest music event ever!",
"locale": "en",
"start": "2018-07-04T17:00:00",
"timeZone": "America/New_York",
"duration": "PT3H",
"locations": {
"9366e041-bb4c-4aa4-b249-b4657cab925c": {
"name": "The Music Bowl",
"description": "Music Bowl, Central Park, New York",
"coordinates": "geo:40.7829,73.9654"
},
"6f3696c6-1e07-47d0-9ce1-f50014b0041a": {
"name": "Free live Stream from Music Bowl",
"rel": "virtual",
"features": [
"video",
"audio",
"chat"
],
"uri": "https://stream.example.com/the_band_2018"
}
},
"localizations": {
"de": {
"title": "Live von der Music Bowl: The Band!",
"description": "Schau dir das groesste Musikereignis an!",
"locations/6f3696c6-1e07-47d0-9ce1-f50014b0041a/name":
"Gratis Live-Stream aus der Music Bowl"
}
}
}
7.9. Recurring event with overrides
This example illustrates the use of recurrence overrides. A math
course at a University is held for the first time on January 8, 2018
at 9am London time and occurs every week until June 25, 2018. Each
lecture lasts for one hour and 30 minutes and is located at the
Mathematics department. This event has exceptional occurrences: at
the last occurrence of the course is an exam, which lasts for 2 hours
and starts at 10am. Also, the location of the exam differs from the
usual location. On April 2, May 7 and May 28 no course is held.
{
"...": "",
"title": "Calculus I",
"start": "2018-01-08T09:00:00",
"timeZone": "Europe/London",
"duration": "PT1H30M",
"locations": {
"2a358cee-6489-4f14-a57f-c104db4dc2f1": {
"title": "Math lab room 1",
"description": "Math Lab I, Department of Mathematics"
},
"recurrenceRule": {
"frequency": "weekly",
"until": "2018-06-25T09:00:00"
},
"2018-04-02T09:00:00": null,
"2018-05-07T09:00:00": null,
"2018-05-28T09:00:00": null,
"2018-06-25T09:00:00": {
"title": "Calculus I Exam",
"start": "2018-06-25T10:00:00",
"duration": "PT2H",
"locations": { "locations": {
"loc1" : { "2a358cee-6489-4f14-a57f-c104db4dc2f1": {
"description" : "Joe's Tennis Plaza, Court #1" "title": "Big Auditorium",
} "description": "Big Auditorium, Other Road"
},
"isAllDay": false,
"start": "2016-01-01T13:00:00",
"timeZone": "Europe/Vienna",
"duration": "PT1H",
"recurrenceRule": {
"frequency": "monthly",
},
"recurrenceOverrides": {
"2016-02-01T13:00:00": null,
"2016-05-01T13:00:00": {
"duration": "PT2H",
"locations": {
"loc2": {
"description": "Tennis Fritz&Mayer, Ltd."
}
},
"2016-12-05T17:00:00": {},
} }
} }
} }
}
}
Note that the recurrenceOverride on May 1 overrides the complete 7.10. Recurring event with participants
location object. If the event should occur at *both* locations, the
PatchObject would be defined as follows:
{ This example illustrates scheduled events. A team meeting occurs
[...] every week since January 8, 2018 at 9am Johannesburg time. The event
"recurrenceOverrides": { owner also chairs the event. Participants meet in a virtual meeting
[...] room. An attendee has accepted the invitation, but on March 8, 2018
"2016-05-01T13:00:00": { he is unavailable and declined participation for this occurrence.
"duration": "PT2H",
"locations/loc2": { {
"description": "Tennis Fritz&Mayer, Ltd." "...": "",
} "title": "FooBar team meeting",
} "start": "2018-01-08T09:00:00",
} "timeZone": "Africa/Johannesburg",
"duration": "PT1H",
"locations": {
"2a358cee-6489-4f14-a57f-c104db4dc2f1": {
"title": "ChatMe meeting room",
"rel": "virtual",
"features": [
"audio",
"chat",
"video"
],
"uri": "https://chatme.example.com?id=1234567"
}
},
"recurrenceRule": {
"frequency": "weekly"
},
"replyTo": {
"imip": "zoe@foobar.example.com"
},
"participants": {
"tom@foobar.example.com": {
"name": "Tom Tool",
"email": "tom@foobar.example.com",
"rsvpResponse": "accepted",
"roles": [
"attendee"
]
},
"zoe@foobar.example.com": {
"name": "Zoe Zelda",
"email": "zoe@foobar.example.com",
"rsvpResponse": "accepted",
"roles": [
"owner",
"chair"
]
},
"...": ""
},
"recurrenceOverrides": {
"2018-03-08T09:00:00": {
"participants/tom@foobar.example.com/rsvpResponse": "declined"
}
}
}
8. Security Considerations 8. Security Considerations
The use of JSON as a format does have its own inherent security risks The use of JSON as a format does have its own inherent security risks
as discussed in Section 12 of [RFC8259]. Even though JSON is as discussed in Section 12 of [RFC8259]. Even though JSON is
considered a safe subset of JavaScript, it should be kept in mind considered a safe subset of JavaScript, it should be kept in mind
that a flaw in the parser processing JSON could still impose a that a flaw in the parser processing JSON could still impose a
threat, which doesn't arise with conventional iCalendar data. threat, which doesn't arise with conventional iCalendar data.
With this in mind, a parser for JSON data aware of the security With this in mind, a parser for JSON data aware of the security
skipping to change at page 42, line 44 skipping to change at page 48, line 5
11. References 11. References
11.1. Normative References 11.1. Normative References
[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>.
[RFC2183] Troost, R., Dorner, S., and K. Moore, Ed., "Communicating
Presentation Information in Internet Messages: The
Content-Disposition Header Field", RFC 2183,
DOI 10.17487/RFC2183, August 1997,
<https://www.rfc-editor.org/info/rfc2183>.
[RFC2392] Levinson, E., "Content-ID and Message-ID Uniform Resource [RFC2392] Levinson, E., "Content-ID and Message-ID Uniform Resource
Locators", RFC 2392, DOI 10.17487/RFC2392, August 1998, Locators", RFC 2392, DOI 10.17487/RFC2392, August 1998,
<https://www.rfc-editor.org/info/rfc2392>. <https://www.rfc-editor.org/info/rfc2392>.
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
<https://www.rfc-editor.org/info/rfc3339>. <https://www.rfc-editor.org/info/rfc3339>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
 End of changes. 39 change blocks. 
139 lines changed or deleted 339 lines changed or added

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