7Internet Engineering Task Force (IETF) P. Kewisch
8Request for Comments: 7265 Mozilla
9Category: Standards Track C. Daboo
10ISSN: 2070-1721 Apple, Inc.
16 jCal: The JSON Format for iCalendar
20 This specification defines "jCal", a JSON format for iCalendar data.
21 The iCalendar data format is a text format for capturing and
22 exchanging information normally stored within a calendaring and
23 scheduling application, for example, tasks and events. JSON is a
24 lightweight, text-based, language-independent data interchange format
25 commonly used in Internet applications.
29 This is an Internet Standards Track document.
31 This document is a product of the Internet Engineering Task Force
32 (IETF). It represents the consensus of the IETF community. It has
33 received public review and has been approved for publication by the
34 Internet Engineering Steering Group (IESG). Further information on
35 Internet Standards is available in Section 2 of RFC 5741.
37 Information about the current status of this document, any errata,
38 and how to provide feedback on it may be obtained at
39 http://www.rfc-editor.org/info/rfc7265.
43 Copyright (c) 2014 IETF Trust and the persons identified as the
44 document authors. All rights reserved.
46 This document is subject to BCP 78 and the IETF Trust's Legal
47 Provisions Relating to IETF Documents
48 (http://trustee.ietf.org/license-info) in effect on the date of
49 publication of this document. Please review these documents
50 carefully, as they describe your rights and restrictions with respect
51 to this document. Code Components extracted from this document must
52 include Simplified BSD License text as described in Section 4.e of
53 the Trust Legal Provisions and are provided without warranty as
54 described in the Simplified BSD License.
58Kewisch, et al. Standards Track [Page 1]
65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
66 2. Conventions Used in This Document . . . . . . . . . . . . . . 4
67 3. Converting from iCalendar to jCal . . . . . . . . . . . . . . 4
68 3.1. Pre-processing . . . . . . . . . . . . . . . . . . . . . 4
69 3.2. iCalendar Stream and Objects (RFC 5545, Section 3.4) . . 5
70 3.3. Components (RFC 5545, Section 3.6) . . . . . . . . . . . 6
71 3.4. Properties (RFC 5545, Sections 3.7 and 3.8) . . . . . . . 6
72 3.4.1. Special Cases for Properties . . . . . . . . . . . . 8
73 3.4.1.1. GEO Property (RFC 5545, Section 3.8.1.6) . . . . 8
74 3.4.1.2. REQUEST-STATUS Property (RFC 5545, Section
75 3.8.8.3) . . . . . . . . . . . . . . . . . . . . 8
76 3.5. Parameters (RFC 5545, Section 3.2) . . . . . . . . . . . 9
77 3.5.1. VALUE Parameter . . . . . . . . . . . . . . . . . . . 10
78 3.5.2. Multi-value Parameters . . . . . . . . . . . . . . . 11
79 3.6. Values (RFC 5545, Section 3.3) . . . . . . . . . . . . . 11
80 3.6.1. Binary (RFC 5545, Section 3.3.1) . . . . . . . . . . 12
81 3.6.2. Boolean (RFC 5545, Section 3.3.2) . . . . . . . . . 12
82 3.6.3. Calendar User Address (RFC 5545, Section 3.3.3) . . . 12
83 3.6.4. Date (RFC 5545, Section 3.3.4) . . . . . . . . . . . 12
84 3.6.5. Date-Time (RFC 5545, Section 3.3.5) . . . . . . . . . 13
85 3.6.6. Duration (RFC 5545, Section 3.3.6) . . . . . . . . . 13
86 3.6.7. Float (RFC 5545, Section 3.3.7) . . . . . . . . . . . 14
87 3.6.8. Integer (RFC 5545, Section 3.3.8) . . . . . . . . . . 14
88 3.6.9. Period of Time (RFC 5545, Section 3.3.9) . . . . . . 14
89 3.6.10. Recurrence Rule (RFC 5545, Section 3.3.10) . . . . . 15
90 3.6.11. Text (RFC 5545, Section 3.3.11) . . . . . . . . . . . 16
91 3.6.12. Time (RFC 5545, Section 3.3.12) . . . . . . . . . . . 16
92 3.6.13. URI (RFC 5545, Section 3.3.13) . . . . . . . . . . . 17
93 3.6.14. UTC Offset (RFC 5545, Section 3.3.14) . . . . . . . . 17
94 3.7. Extensions . . . . . . . . . . . . . . . . . . . . . . . 17
95 4. Converting from jCal into iCalendar . . . . . . . . . . . . . 17
96 5. Handling Unrecognized Properties or Parameters . . . . . . . 18
97 5.1. Converting iCalendar into jCal . . . . . . . . . . . . . 18
98 5.2. Converting jCal into iCalendar . . . . . . . . . . . . . 19
99 5.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 19
100 6. Security Considerations . . . . . . . . . . . . . . . . . . . 20
101 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21
102 7.1. UNKNOWN iCalendar Value Data Type . . . . . . . . . . . . 22
103 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 23
104 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 23
105 9.1. Normative References . . . . . . . . . . . . . . . . . . 23
106 9.2. Informative References . . . . . . . . . . . . . . . . . 24
114Kewisch, et al. Standards Track [Page 2]
116RFC 7265 jCal May 2014
119 Appendix A. ABNF Schema . . . . . . . . . . . . . . . . . . . . 25
120 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 27
121 B.1. Example 1 . . . . . . . . . . . . . . . . . . . . . . . . 27
122 B.1.1. iCalendar Data . . . . . . . . . . . . . . . . . . . 27
123 B.1.2. jCal Data . . . . . . . . . . . . . . . . . . . . . . 27
124 B.2. Example 2 . . . . . . . . . . . . . . . . . . . . . . . . 28
125 B.2.1. iCalendar Data . . . . . . . . . . . . . . . . . . . 28
126 B.2.2. jCal Data . . . . . . . . . . . . . . . . . . . . . . 29
130 The iCalendar data format [RFC5545] is a widely deployed interchange
131 format for calendaring and scheduling data. While many applications
132 and services consume and generate calendar data, iCalendar is a
133 specialized format that requires its own parser/generator. In
134 contrast, JSON-based formats as defined in [RFC7159] are the native
135 format for JavaScript widgets and libraries, and it is appropriate to
136 have a standard form of calendar data that is easier to work with
139 The purpose of this specification is to define "jCal", a JSON format
140 for iCalendar data. jCal is defined as a straightforward mapping into
141 JSON from iCalendar, so that iCalendar data can be converted to JSON,
142 and then back to iCalendar, without losing any semantic meaning in
143 the data. Anyone creating jCal calendar data according to this
144 specification will know that their data can be converted to a valid
145 iCalendar representation as well.
147 The key design considerations are essentially the same as those for
150 Round-tripping (converting an iCalendar instance to jCal and back)
151 will give the same semantic result as the starting point. For
152 example, all components, properties, and property parameters are
153 guaranteed to be preserved.
155 Ordering of elements and case of property and parameter names will
156 not necessarily be preserved.
158 The iCalendar data semantics are to be preserved, allowing a
159 simple consumer to easily browse the data in jCal. A full
160 understanding of iCalendar is still required in order to modify
161 and/or fully comprehend the calendar data.
163 Extensions to the underlying iCalendar specification must not lead
164 to requiring an update to jCal.
170Kewisch, et al. Standards Track [Page 3]
172RFC 7265 jCal May 2014
1752. Conventions Used in This Document
177 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
178 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
179 document are to be interpreted as described in [RFC2119]. The
180 underlying format used for jCal is JSON. Consequently, the terms
181 "object" and "array" as well as the four primitive types (strings,
182 numbers, booleans, and null) are to be interpreted as described in
183 Section 1 of [RFC7159].
185 Some examples in this document contain "partial" JSON documents used
186 for illustrative purposes. In these examples, three periods "..."
187 are used to indicate a portion of the document that has been removed
1903. Converting from iCalendar to jCal
192 This section describes how iCalendar data is converted to jCal using
193 a simple mapping between the iCalendar data model and JSON elements.
194 Aside from the formal description in this section, an informative
195 ABNF is specified in Appendix A.
197 In [RFC5545], an iCalendar object comprises a set of "components",
198 "properties", "parameters", and "values". The top level of iCalendar
199 data typically contains a stream of iCalendar objects, each of which
200 can be considered a "component". A "component" can contain other
201 "components" or "properties". A "property" has a "value" and a set
202 of zero or more "parameters". Each of these entities have a
203 representation in jCal, defined in the following sections. The
204 representation of an iCalendar object in JSON will be named "jCal
205 object" throughout this document.
209 iCalendar uses a line-folding mechanism to limit lines of data to a
210 maximum line length (typically 75 octets) to ensure the maximum
211 likelihood of preserving data integrity as it is transported via
212 various means (e.g., email) -- see Section 3.1 of [RFC5545].
214 iCalendar data uses an "escape" character sequence for text values
215 and property parameter values. See Sections 3.1 and 3.3 of [RFC5545]
216 as well as [RFC6868].
218 There is a subtle difference in the number representations between
219 JSON and iCalendar. While in iCalendar, a number may have leading
220 zeros, as well as a leading plus sign; this is not the case in JSON.
221 Numbers should be represented in whatever way needed for the
226Kewisch, et al. Standards Track [Page 4]
228RFC 7265 jCal May 2014
231 When converting from iCalendar to jCal: First, iCalendar lines MUST
232 be unfolded. Afterwards, any iCalendar escaping MUST be unescaped.
233 Finally, JSON escaping, as described in Section 7 of [RFC7159], MUST
234 be applied. The reverse order applies when converting from jCal to
235 iCalendar, which is further described in Section 4.
237 iCalendar uses a base64 encoding for binary data. However, it does
238 not restrict the encoding from being applied to non-binary value
239 types. So, the following rules are applied when processing a
240 property with the "ENCODING" property parameter set to "BASE64":
242 o If the property value type is "BINARY", the base64 encoding MUST
245 o If the value type is not "BINARY", the "ENCODING" property
246 parameter MUST be removed, and the value MUST be base64 decoded.
248 When base64 encoding is used, it MUST conform to Section 4 of
249 [RFC4648], which is the base64 method used in [RFC5545].
251 One key difference in the formatting of values used in iCalendar and
252 jCal is that in jCal, the specification uses date/time values aligned
253 with the extended format of [ISO.8601.2004], which is more commonly
254 used in Internet applications that make use of the JSON format. The
255 sections of this document describing the various date and time
256 formats contain more information on the use of the complete
257 representation, reduced accuracy, or truncated representation.
2593.2. iCalendar Stream and Objects (RFC 5545, Section 3.4)
261 At the top level of the iCalendar object model is an "iCalendar
262 stream". This stream encompasses multiple "iCalendar objects". As
263 the typical use case is transporting a single iCalendar object, there
264 is no defined equivalent to an "iCalendar stream" in jCal. To
265 transport multiple jCal objects in a stream, a simple JSON array can
271 [ /* Add jCal properties in place of this comment */ ],
272 [ /* Add jCal components in place of this comment */ ]
282Kewisch, et al. Standards Track [Page 5]
284RFC 7265 jCal May 2014
2873.3. Components (RFC 5545, Section 3.6)
289 Each iCalendar component, delimited by "BEGIN" and "END", will be
290 converted to a fixed-length array with three fields that have a
293 1. A string with the name of the iCalendar component, but in
296 2. An array of jCal properties as described in Section 3.4.
298 3. An array of jCal components, representing the sub-components of
299 the component in question.
301 This mapping applies to the top level iCalendar objects, as well as
302 individual sub-components in the same way. The iCalendar to jCal
303 component mapping is valid for both current iCalendar components and
304 any new iCalendar components added in the future. Conversion is to
305 be done in the same way.
307 While the grouping of properties and sub-components does not retain
308 the original order specified in the iCalendar data, the semantics of
309 a component are preserved.
314 [ /* Add jCal properties in place of this comment */ ],
315 [ /* Add jCal components in place of this comment */ ]
3183.4. Properties (RFC 5545, Sections 3.7 and 3.8)
320 iCalendar properties, whether they apply to the "VCALENDAR" object or
321 to a component, are handled in a consistent way in the jCal format.
323 In jCal, each individual iCalendar property MUST be represented by an
324 array with three fixed elements, followed by one or more additional
325 elements, depending on if the property is a multi-valued property as
326 described in Section 3.1.2 of [RFC5545].
338Kewisch, et al. Standards Track [Page 6]
340RFC 7265 jCal May 2014
343 The array consists of the following fixed elements:
345 1. The name of the property, as a lowercase string. The iCalendar
346 format specifies that property names are case insensitive and
347 recommends that they be rendered in uppercase. In jCal, they
348 MUST be in lowercase.
350 2. An object containing the parameters as described in Section 3.5.
351 If the property has no parameters, an empty object is used to
354 3. The type identifier string of the value, in lowercase. Due to
355 special casing of certain properties as described in
356 Section 3.4.1, it is important that parsers check both the type
357 identifier and the value data type and do not rely on assumptions
358 based on the property name.
360 The remaining elements of the array are used for one or more values
361 of the property. For single-valued properties, the array has exactly
362 four elements; for multi-valued properties, as described in
363 Section 3.1.2 of [RFC5545], each value is another element, and there
364 can be any number of additional elements.
366 In the following example, the "categories" property is multi-valued
367 and has two values, while the summary property is single-valued:
373 ["summary", {}, "text", "Meeting with Fred"],
374 ["categories", {}, "text", "Meetings", "Work"]
377 [ /* sub-components */ ]
394Kewisch, et al. Standards Track [Page 7]
396RFC 7265 jCal May 2014
3993.4.1. Special Cases for Properties
401 This section describes some properties that have special handling
402 when converting to jCal.
4043.4.1.1. GEO Property (RFC 5545, Section 3.8.1.6)
406 In iCalendar, the "GEO" property value is defined as a semicolon-
407 separated list of two "FLOAT" values, the first representing latitude
408 and the second longitude.
410 In jCal, the value for the "geo" property value is represented as an
411 array of two values. The first value of the property represents the
412 latitude; the second value represents the longitude.
414 When converting from jCal to iCalendar, be careful to use a semicolon
415 as the separator between the two values as required by [RFC5545].
417 When converting from jCal to iCalendar, the two values MUST be
418 converted using a semicolon as the separator character.
424 ["geo", {}, "float", [ 37.386013, -122.082932 ] ]
4303.4.1.2. REQUEST-STATUS Property (RFC 5545, Section 3.8.8.3)
432 In iCalendar, the "REQUEST-STATUS" property value is defined as a
433 semicolon-separated list of two or three "TEXT" values. The first
434 represents a code, the second a description, and the third any
437 In jCal, the value for the "request-status" property value is
438 represented as an array with two or three values. The first array
439 element corresponds to the code, the second element corresponds to
440 the description, and the third element corresponds to the additional
441 data. Each value is represented using a string value. If there is
442 no additional data in the iCalendar value, the last element of the
443 array SHOULD NOT be present.
445 When converting from jCal to iCalendar, the two or three values MUST
446 be converted using a semicolon as the separator character.
450Kewisch, et al. Standards Track [Page 8]
452RFC 7265 jCal May 2014
459 REQUEST-STATUS:2.0;Success
460 REQUEST-STATUS:3.7;Invalid calendar user;ATTENDEE:
461 mailto:jsmith@example.com
469 ["request-status", {}, "text", ["2.0", "Success"] ],
470 ["request-status", {}, "text",
473 "Invalid calendar user",
474 "ATTENDEE:mailto:jsmith@example.org"
4823.5. Parameters (RFC 5545, Section 3.2)
484 Property parameters are represented as a JSON object where each key-
485 value pair represents the iCalendar parameter name and its value.
486 The name of the parameter MUST be in lowercase; the original case of
487 the parameter value MUST be preserved. For example, the "PARTSTAT"
488 property parameter is represented in jCal by the "partstat" key. Any
489 new iCalendar parameters added in the future will be converted in the
506Kewisch, et al. Standards Track [Page 9]
508RFC 7265 jCal May 2014
517 "partstat": "ACCEPTED",
519 "role": "REQ-PARTICIPANT"
522 "mailto:jsmith@example.org"
524 ["summary", {}, "text", "Meeting"],
5303.5.1. VALUE Parameter
532 iCalendar defines a "VALUE" property parameter (Section 3.2.20 of
533 [RFC5545]). This property parameter MUST NOT be added to the
534 parameters object. Instead, the value type is signaled through the
535 type identifier in the third element of the array describing the
536 property. When converting a property from iCalendar to jCal, the
537 value type is determined as follows:
539 1. If the property has a "VALUE" parameter, that parameter's value
540 is used as the value type.
542 2. If the property has no "VALUE" parameter but has a default value
543 type, the default value type is used.
545 3. If the property has no "VALUE" parameter and has no default value
546 type, "unknown" is used.
548 Converting from jCal into iCalendar is done as follows:
550 1. If the property's value type is "unknown", no "VALUE" parameter
553 2. If the property's value type is the default type for that
554 property, no "VALUE" parameter is included.
556 3. Otherwise, a "VALUE" parameter is included, and the value type is
557 used as the parameter value.
562Kewisch, et al. Standards Track [Page 10]
564RFC 7265 jCal May 2014
567 See Section 5 for information on handling unknown value types.
5693.5.2. Multi-value Parameters
571 In [RFC5545], some parameters allow using a COMMA-separated list of
572 values. To ease processing in jCal, the value of such parameters
573 MUST be represented in an array containing the separated values. The
574 array elements MUST be string values. Single-value parameters can be
575 represented using either a single string value or an array with one
576 string element. A jCal parser MUST be able to understand both value
577 data types. Examples of such parameters are the iCalendar
578 "DELEGATED-FROM" and "DELEGATED-TO" parameters; more such parameters
579 may be added in extensions.
581 The iCalendar specification requires encapsulation between DQUOTE
582 characters if a parameter value contains a colon, a semicolon, or a
583 comma. These extra DQUOTE characters do not belong to the actual
584 parameter value, and hence are not included when the parameter is
591 "delegated-to": ["mailto:jdoe@example.org",
592 "mailto:jqpublic@example.org"]
595 "mailto:jsmith@example.org"
602 "delegated-to": "mailto:jdoe@example.org"
605 "mailto:jsmith@example.org"
6083.6. Values (RFC 5545, Section 3.3)
610 The following subsections specify how iCalendar property value data
611 types, which are defined in the subsections of [RFC5545],
612 Section 3.3, are represented in jCal.
618Kewisch, et al. Standards Track [Page 11]
620RFC 7265 jCal May 2014
6233.6.1. Binary (RFC 5545, Section 3.3.1)
625 Description: iCalendar "BINARY" property values are represented by a
626 property with the type identifier "binary". The value element is
627 a JSON string, encoded with base64 encoding as specified in
628 Section 4 of [RFC4648].
632 ["attach", {}, "binary", "SGVsbG8gV29ybGQh"]
6343.6.2. Boolean (RFC 5545, Section 3.3.2)
636 Description: iCalendar "BOOLEAN" property values are represented by
637 a property with the type identifier "boolean". The value is a
642 ["x-non-smoking", {}, "boolean", true]
6443.6.3. Calendar User Address (RFC 5545, Section 3.3.3)
646 Description: iCalendar "CAL-ADDRESS" property values are represented
647 by a property with the type identifier "cal-address". The value
648 is a JSON string with the URI as described in [RFC3986].
652 ["attendee", {}, "cal-address", "mailto:kewisch@example.com"]
6543.6.4. Date (RFC 5545, Section 3.3.4)
656 Description: iCalendar "DATE" property values are represented by a
657 property with the type identifier "date". The value elements are
658 JSON strings with the same date value specified by [RFC5545], but
659 represented using the extended format of the complete
660 representation specified in [ISO.8601.2004], Section 4.1.2.2.
661 Other variations, for example, representation with reduced
662 accuracy, MUST NOT be used.
666 ; year, month, and day rules are
667 ; defined in [ISO.8601.2004], Section 2.2.
668 date = year "-" month "-" day ;YYYY-MM-DD
674Kewisch, et al. Standards Track [Page 12]
676RFC 7265 jCal May 2014
681 ["dtstart", {}, "date", "2011-05-17"]
6833.6.5. Date-Time (RFC 5545, Section 3.3.5)
685 Description: iCalendar "DATE-TIME" property values are represented
686 by a property with the type identifier "date-time". The value
687 elements are JSON strings with the same date value specified by
688 [RFC5545], but represented using the extended format of the
689 complete representation specified in [ISO.8601.2004],
690 Section 4.3.2. Other variations, for example, representation with
691 reduced accuracy, MUST NOT be used. The same restrictions apply
692 with respect to leap seconds and time zone offsets as specified in
693 [RFC5545], Section 3.3.5.
697 ; year, month, day, hour, minute, and second rules are
698 ; defined in [ISO.8601.2004], Section 2.2.
699 ; The zone identifier is described in [ISO.8601.2004], Section 4.3.2.
700 date-complete = year "-" month "-" day ;YYYY-MM-DD
701 time-complete = hour ":" minute ":" second [zone] ; HH:MM:SS
702 datetime = date-complete "T" time-complete
706 ["dtstart", {}, "date-time", "2012-10-17T12:00:00"],
707 ["dtstamp", {}, "date-time", "2012-10-17T12:00:00Z"],
709 { "tzid": "Europe/Berlin" },
711 "2011-10-17T13:00:00"
7143.6.6. Duration (RFC 5545, Section 3.3.6)
716 Description: iCalendar "DURATION" property values are represented by
717 a property with the type identifier "duration". The value
718 elements are JSON strings with the same duration value specified
723 ["duration", {}, "duration", "P1D"]
730Kewisch, et al. Standards Track [Page 13]
732RFC 7265 jCal May 2014
7353.6.7. Float (RFC 5545, Section 3.3.7)
737 Description: iCalendar "FLOAT" property values are represented by a
738 property with the type identifier "float". The value elements are
739 JSON primitive number values.
743 ["x-grade", {}, "float", 1.3]
7453.6.8. Integer (RFC 5545, Section 3.3.8)
747 Description: vCard "INTEGER" property values are represented by a
748 property with the type identifier "integer". The value elements
749 are JSON primitive number values that MUST resolve to an integer
750 value in the range specified in [RFC5545], Section 3.3.8. Thus, a
751 fractional and/or exponential part are only allowed under limited
756 ["percent-complete", {}, "integer", 42]
7583.6.9. Period of Time (RFC 5545, Section 3.3.9)
760 Description: iCalendar "PERIOD" property values are represented by a
761 jCal property with the type identifier "period". The value
762 element is an array of JSON strings, with the first element
763 representing the start of the period and the second element
764 representing the end of the period. As in [RFC5545], the start of
765 the period is always formatted as a date-time value, and the end
766 of the period MUST be either a date-time or duration value. Any
767 date, date-time, or duration values contained in the period value
768 MUST be formatted in accordance to the rules for date, date-time,
769 or duration values specified in this document.
774 { "fbtype": "FREE" },
776 ["1997-03-08T16:00:00Z", "P1D"]
786Kewisch, et al. Standards Track [Page 14]
788RFC 7265 jCal May 2014
7913.6.10. Recurrence Rule (RFC 5545, Section 3.3.10)
793 Description: iCalendar "RECUR" property values are represented by a
794 property with the type identifier "recur". The value elements are
795 objects describing the structured data as specified by [RFC5545].
796 Each rule part is described by the combination of key and value.
797 The key specifies the name of the rule part and MUST be converted
798 to lowercase. The value of the rule part MUST be mapped by the
801 * The value of the "freq" and "wkst" rule parts MUST be a string
802 as specified in [RFC5545], with case preserved.
804 * The value of the "until" rule part MUST be a date or date-time
805 value formatted in accordance to the rules for date or date-
806 time specified in this document.
808 * The "count" and "interval" rule parts MUST be specified as a
809 single JSON number value.
811 * The following rule parts can have one or more numeric values:
812 "bysecond", "byminute", "byhour", "bymonthday", "byyearday",
813 "byweekno", "bymonth", and "bysetpos". If a rule part contains
814 multiple values, an array of numbers MUST be used for that rule
815 part. Single-valued rule parts can be represented by either
816 using a single number value, omitting the array completely, or
817 using an array with one number element. A jCal parser MUST be
818 able to understand both data types.
820 * Similarly, the "byday" rule part can have one or more string
821 values. If it contains multiple values, an array of strings
822 MUST be used. As before, a single-valued rule part can be
823 represented using either a single string value or an array with
824 one string element, both of which a jCal parser MUST be able to
835 "byday": [ "-1SU", "2MO" ],
842Kewisch, et al. Standards Track [Page 15]
844RFC 7265 jCal May 2014
855 "bymonthday": [ 1, 15, -1 ],
856 "until": "2013-10-01"
8603.6.11. Text (RFC 5545, Section 3.3.11)
862 Description: iCalendar "TEXT" property values are represented by a
863 property with the type identifier "text". The value elements are
868 ["comment", {}, "text", "hello, world"]
8703.6.12. Time (RFC 5545, Section 3.3.12)
872 Description: iCalendar "TIME" property values are represented by a
873 property with the type identifier "time". The value elements are
874 JSON strings with the same time value specified by [RFC5545], but
875 represented using the extended format of the complete
876 representation specified in [ISO.8601.2004], Section 4.2.2.2.
877 Other variations, for example, representation with reduced
878 accuracy, MUST NOT be used. The same restrictions apply with
879 respect to leap seconds, time fractions, and time zone offsets as
880 specified in [RFC5545], Section 3.3.12.
884 ; hour, minute, and second rules are
885 ; defined in [ISO.8601.2004], Section 2.2.
886 ; The zone identifier is described in [ISO.8601.2004], Section 4.3.2.
887 time-complete = hour ":" minute ":" second [zone] ; HH:MM:SS
891 ["x-time-local", {}, "time", "12:30:00"],
892 ["x-time-utc", {}, "time", "12:30:00Z"],
893 ["x-time-offset", { "tzid": "Europe/Berlin" }, "time", "12:30:00"]
898Kewisch, et al. Standards Track [Page 16]
900RFC 7265 jCal May 2014
9033.6.13. URI (RFC 5545, Section 3.3.13)
905 Description: iCalendar "URI" property values are represented by a
906 property with the type identifier "uri". The value elements are
907 JSON strings representing the URI.
911 ["tzurl", {}, "uri", "http://example.org/tz/Europe-Berlin.ics"]
9133.6.14. UTC Offset (RFC 5545, Section 3.3.14)
915 Description: iCalendar "UTC-OFFSET" property values are represented
916 by a property with the type identifier "utc-offset". The value
917 elements are JSON strings with the same UTC offset value specified
918 by [RFC5545], with the exception that the hour and minute
919 components are separated by a ":" character, for consistency with
920 the [ISO.8601.2004] time zone offset, extended format.
924 ["tzoffsetfrom", {}, "utc-offset", "-05:00"],
925 ["tzoffsetto", {}, "utc-offset", "+12:45"]
929 iCalendar extension properties and property parameters (those with an
930 "X-" prefix in their name) are handled in the same way as other
931 properties and property parameters: the property is represented by an
932 array, and the property parameter is represented by an object. The
933 property or parameter name uses the same name as for the iCalendar
934 extension, but in lowercase. For example, the "X-FOO" property in
935 iCalendar turns into the "x-foo" jCal property. See Section 5 for
936 how to deal with default values for unrecognized extension properties
937 or property parameters.
9394. Converting from jCal into iCalendar
941 Converting jCal to iCalendar reverses the process described in
942 Section 3. This section describes a few additional requirements for
945 When converting component, property, and property parameter names,
946 the names SHOULD be converted to uppercase. Although iCalendar names
947 are case insensitive, common practice is to keep them all uppercase
948 following the actual definitions in [RFC5545].
954Kewisch, et al. Standards Track [Page 17]
956RFC 7265 jCal May 2014
959 During conversion, JSON escaping MUST be unescaped. Afterwards,
960 iCalendar escaping, as defined by [RFC5545] and [RFC6868], MUST be
961 applied. Finally, long lines SHOULD be folded as described in
962 [RFC5545], Section 3.1.
964 Non-binary value types MUST NOT be base64 encoded.
966 When converting to iCalendar, the VALUE parameter MUST be added to
967 properties whose default value type is unknown, but do not have a
968 jCal type identifier "unknown". The VALUE parameter MAY be omitted
969 for properties using the default value type. The VALUE parameter
970 MUST be omitted for properties that have the jCal type identifier
9735. Handling Unrecognized Properties or Parameters
975 In iCalendar, properties can have one or more value types as
976 specified by their definition, with one of those values being defined
977 as the default. When a property uses its default value type, the
978 "VALUE" property parameter does not need to be specified on the
979 property. For example, the default value type for "DTSTART" is
980 "DATE-TIME", so "VALUE=DATE-TIME" need not be set as a property
981 parameter. However, "DTSTART" also allows a "DATE" value to be
982 specified, and if that is used, "VALUE=DATE" has to be set as a
985 When new properties are defined or "X-" properties used, an iCalendar
986 to jCal converter might not recognize them, and not know what the
987 appropriate default value types are, yet they need to be able to
988 preserve the values. A similar issue arises for unrecognized
991 In jCal, a new "unknown" property value type is introduced. Its
992 purpose is to allow preserving unknown property values when round-
993 tripping between jCal and iCalendar. To avoid collisions, this
994 specification reserves the UNKNOWN property value type in iCalendar.
995 It MUST NOT be used in any iCalendar as specified by [RFC5545], nor
996 any extensions to it. Thus, the type is registered to the iCalendar
997 Value Data Types registry in Section 7.1.
9995.1. Converting iCalendar into jCal
1001 Any property that does not include a "VALUE" property parameter and
1002 whose default value type is not known, MUST be converted to a
1003 primitive JSON string. The content of that string is the unprocessed
1004 value text. Also, value type MUST be set to "unknown".
1010Kewisch, et al. Standards Track [Page 18]
1012RFC 7265 jCal May 2014
1015 To correctly implement this format, it is critical that the type
1016 "unknown" be used if the default type is not known. If this
1017 requirement is ignored and, for example, "text" is used, additional
1018 escaping may occur, which breaks round-tripping values.
1020 Any unrecognized property parameter MUST be converted to a string
1021 value, with its content set to the property parameter value text, and
1022 treated as if it were a "TEXT" value.
10245.2. Converting jCal into iCalendar
1026 In jCal, the value type is always explicitly specified. It is
1027 converted to iCalendar using the iCalendar VALUE parameter, except in
1028 the following two cases:
1030 o If the value type specified in jCal matches the default value type
1031 in iCalendar, the VALUE parameter MAY be omitted.
1033 o If the value type specified in jCal is set to "unknown", the VALUE
1034 parameter MUST NOT be specified. The value MUST be taken over in
1035 iCalendar without processing.
1039 The following is an example of an unrecognized iCalendar property
1040 (that uses a "DATE-TIME" value as its default), and the equivalent
1041 jCal representation of that property.
1045 X-COMPLAINT-DEADLINE:20110512T120000Z
1049 ["x-complaint-deadline", {}, "unknown", "20110512T120000Z"]
1051 The following is an example of how to cope with jCal data where the
1052 parser was unable to identify the type. Note how the "unknown" value
1053 type is not added to the iCalendar data and escaping, aside from
1054 standard JSON string escaping, is not processed.
1058 ["x-coffee-data", {}, "unknown", "Stenophylla;Guinea\\,Africa"]
1062 X-COFFEE-DATA:Stenophylla;Guinea\,Africa
1066Kewisch, et al. Standards Track [Page 19]
1068RFC 7265 jCal May 2014
1071 The following is an example of a jCal property (where the
1072 corresponding iCalendar property uses an "INTEGER" value as its
1073 default) and the equivalent iCalendar representation of that
1078 ["percent-complete", {}, "integer", 95]
1084 The following is an example of an unrecognized iCalendar property
1085 parameter (that uses a "FLOAT" value as its default) specified on a
1086 recognized iCalendar property and the equivalent jCal representation
1087 of that property and property parameter.
1091 DTSTART;X-SLACK=30.3;VALUE=DATE:20110512
1095 ["dtstart", { "x-slack": "30.3" }, "date", "2011-05-12"]
10976. Security Considerations
1099 This specification defines how iCalendar data can be "translated"
1100 between two different data formats -- the original text format and
1101 JSON -- with a one-to-one mapping to ensure all the semantic data in
1102 one format (properties, parameters, and values) are preserved in the
1103 other. It does not change the semantic meaning of the underlying
1104 data itself, or impose or remove any security considerations that
1105 apply to the underlying data.
1107 The use of JSON as a format does have its own inherent security risks
1108 as discussed in Section 12 of [RFC7159]. Even though JSON is
1109 considered a safe subset of JavaScript, it should be kept in mind
1110 that a flaw in the parser processing JSON could still impose a
1111 threat, which doesn't arise with conventional iCalendar data.
1113 With this in mind, a parser for JSON data should be used for jCal
1114 that is aware of the security implications. For example, the use of
1115 JavaScript's eval() function is considered an unacceptable security
1116 risk, as described in Section 12 of [RFC7159]. A native parser with
1117 full awareness of the JSON format should be preferred.
1122Kewisch, et al. Standards Track [Page 20]
1124RFC 7265 jCal May 2014
1127 In addition, it is expected that this new format will result in
1128 iCalendar data being more widely disseminated (e.g., with use in web
1129 applications rather than just dedicated calendaring applications).
1131 In all cases, application developers have to conform to the semantics
1132 of the iCalendar data as defined by [RFC5545] and associated
1133 extensions, and all of the security considerations described in
1134 Section 7 of [RFC5545], or any associated extensions, are applicable.
11367. IANA Considerations
1138 This document defines a MIME media type for use with iCalendar in
1139 JSON data. This media type SHOULD be used for the transfer of
1140 calendaring data in JSON.
1142 Type name: application
1144 Subtype name: calendar+json
1146 Required parameters: none
1148 Optional parameters: "method", "component", and "optinfo" as defined
1149 for the text/calendar media type in [RFC5545], Section 8.1.
1151 Encoding considerations: Same as encoding considerations of
1152 application/json as specified in [RFC7159], Section 11.
1154 Security considerations: See Section 6.
1156 Interoperability considerations: This media type provides an
1157 alternative format for iCalendar data based on JSON.
1159 Published specification: This specification.
1161 Applications that use this media type: Applications that currently
1162 make use of the text/calendar media type can use this as an
1163 alternative. Similarly, applications that use the application/
1164 json media type to transfer calendaring data can use this to
1165 further specify the content.
1167 Fragment identifier considerations: N/A
1169 Additional information:
1171 Deprecated alias names for this type: N/A
1173 Magic number(s): N/A
1178Kewisch, et al. Standards Track [Page 21]
1180RFC 7265 jCal May 2014
1183 File extension(s): N/A
1185 Macintosh file type code(s): N/A
1187 Person & email address to contact for further information:
1190 Intended usage: COMMON
1192 Restrictions on usage: There are no restrictions on where this media
1195 Author: See the "Authors' Addresses" section of this document.
1197 Change controller: IETF
11997.1. UNKNOWN iCalendar Value Data Type
1201 IANA has added the following entry to the iCalendar Data Types
1206 Purpose: To allow preserving property values whose default value
1207 type is not known during round-tripping between jCal and
1210 Format definition: N/A
1212 Description: The UNKNOWN value data type is reserved for the
1213 exclusive use of the jCal format. Its use is described in
1214 Section 5 of this document.
1216 Example: As this registration serves as a reservation of the UNKNOWN
1217 type so that it is not used in iCalendar, there is no applicable
1218 iCalendar example. Examples of its usage in jCal can be found in
1221 IANA has made the "Status" column for this entry in the registry say,
1222 "Reserved - Do not use" and has made the "Reference" column refer to
1223 Section 5 of this document.
1234Kewisch, et al. Standards Track [Page 22]
1236RFC 7265 jCal May 2014
1241 The authors would like to thank the following for their valuable
1242 contributions: William Gill, Erwin Rehme, Dave Thewlis, Simon
1243 Perreault, Michael Angstadt, Peter Saint-Andre, Bert Greevenbosch,
1244 and Javier Godoy. This specification originated from the work of the
1245 XML-JSON technical committee of the Calendaring and Scheduling
12509.1. Normative References
1253 International Organization for Standardization, "Data
1254 elements and interchange formats -- Information
1255 interchange -- Representation of dates and times", ISO
1256 8601, December 2004,
1257 <http://www.iso.org/iso/catalogue_detail?csnumber=40874>.
1259 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1260 Requirement Levels", BCP 14, RFC 2119, March 1997.
1262 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
1263 Resource Identifier (URI): Generic Syntax", STD 66, RFC
1266 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
1267 Encodings", RFC 4648, October 2006.
1269 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
1270 Specifications: ABNF", STD 68, RFC 5234, January 2008.
1272 [RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling
1273 Core Object Specification (iCalendar)", RFC 5545,
1276 [RFC6321] Daboo, C., Douglass, M., and S. Lees, "xCal: The XML
1277 Format for iCalendar", RFC 6321, August 2011.
1279 [RFC6868] Daboo, C., "Parameter Value Encoding in iCalendar and
1280 vCard", RFC 6868, February 2013.
1282 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data
1283 Interchange Format", RFC 7159, March 2014.
1290Kewisch, et al. Standards Track [Page 23]
1292RFC 7265 jCal May 2014
12959.2. Informative References
1297 [calconnect-artifacts]
1298 The Calendaring and Scheduling Consortium, "Code Artifacts
1299 and Schemas", <http://www.calconnect.org/artifacts.shtml>.
1346Kewisch, et al. Standards Track [Page 24]
1348RFC 7265 jCal May 2014
1351Appendix A. ABNF Schema
1353 Below is an ABNF schema as per [RFC5234] for iCalendar in JSON. ABNF
1354 symbols not described here are taken from [RFC7159]. The schema is
1355 non-normative and given for reference only.
1357 Additional semantic restrictions apply, especially regarding the
1358 allowed properties and sub-components per component. Details on
1359 these restrictions can be found in this document and [RFC5545].
1361 Additional schemas may be available on the Internet at
1362 [calconnect-artifacts].
1364 ; A jCal object is a component with the component-name "vcalendar".
1365 ; Restrictions to which properties and sub-components may be
1366 ; specified are to be taken from [RFC5545].
1367 jcalobject = component
1369 ; A jCal component consists of the name string, properties array, and
1371 component = begin-array
1372 DQUOTE component-name DQUOTE value-separator
1373 properties-array value-separator
1377 components-array = begin-array
1378 [ component *(value-separator component) ]
1381 ; A jCal property consists of the name string, parameters object,
1382 ; type string, and one or more values as specified in this document.
1383 property = begin-array
1384 DQUOTE property-name DQUOTE value-separator
1385 params-object value-separator
1386 DQUOTE type-name DQUOTE
1387 property-value *(value-separator property-value)
1389 properties-array = begin-array
1390 [ property *(value-separator property) ]
1393 ; Property values depend on the type-name. Aside from the value types
1394 ; mentioned here, extensions may make use of other JSON value types.
1395 ; The non-terminal symbol structured-prop-value covers the special
1396 ; cases for GEO and REQUEST-STATUS.
1397 property-value = simple-prop-value / structured-prop-value
1398 simple-prop-value = string / number / true / false
1402Kewisch, et al. Standards Track [Page 25]
1404RFC 7265 jCal May 2014
1407 structured-prop-value =
1409 [ structured-element *(value-separator structured-element) ]
1411 structured-element = simple-prop-value
1413 ; The jCal params-object is a JSON object that follows the semantic
1414 ; guidelines described in this document.
1415 params-object = begin-object
1416 [ params-member *(value-separator params-member) ]
1418 params-member = DQUOTE param-name DQUOTE name-separator param-value
1419 param-value = string / param-multi
1420 param-multi = begin-array
1421 [ string *(value-separator string) ]
1424 ; The type MUST be a valid type as described by this document. New
1425 ; value types can be added by extensions.
1426 type-name = "binary" / "boolean" / "cal-address" / "date" /
1427 "date-time" / "duration" / "float" / "integer" /
1428 "period" / "recur" / "text" / "time" / "uri" /
1429 "utc-offset" / x-type
1432 ; Component, property, parameter, and type names MUST be lowercase.
1433 ; Additional semantic restrictions apply as described by this
1434 ; document and [RFC5545].
1435 component-name = lowercase-name
1436 property-name = lowercase-name
1437 param-name = lowercase-name
1438 x-type = lowercase-name
1439 lowercase-name = 1*(%x61-7A / DIGIT / "-")
1441 ; The following rules are defined in [RFC7159], as mentioned above:
1442 ; begin-array / end-array
1443 ; begin-object / end-object
1444 ; name-separator / value-separator
1445 ; string / number / true / false
1458Kewisch, et al. Standards Track [Page 26]
1460RFC 7265 jCal May 2014
1465 This section contains two examples of iCalendar objects with their
1466 jCal representation.
1470B.1.1. iCalendar Data
1474 PRODID:-//Example Inc.//Example Calendar//EN
1477 DTSTAMP:20080205T191224Z
1479 SUMMARY:Planning meeting
1480 UID:4088E990AD89CB3DBB484909
1488 ["calscale", {}, "text", "GREGORIAN"],
1489 ["prodid", {}, "text", "-//Example Inc.//Example Calendar//EN"],
1490 ["version", {}, "text", "2.0"]
1495 ["dtstamp", {}, "date-time", "2008-02-05T19:12:24Z"],
1496 ["dtstart", {}, "date", "2008-10-06"],
1497 ["summary", {}, "text", "Planning meeting"],
1498 ["uid", {}, "text", "4088E990AD89CB3DBB484909"]
1514Kewisch, et al. Standards Track [Page 27]
1516RFC 7265 jCal May 2014
1521B.2.1. iCalendar Data
1525 PRODID:-//Example Corp.//Example Client//EN
1527 LAST-MODIFIED:20040110T032845Z
1530 DTSTART:20000404T020000
1531 RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4
1537 DTSTART:20001026T020000
1538 RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
1545 DTSTAMP:20060206T001121Z
1546 DTSTART;TZID=US/Eastern:20060102T120000
1548 RRULE:FREQ=DAILY;COUNT=5
1549 RDATE;TZID=US/Eastern;VALUE=PERIOD:20060102T150000/PT2H
1551 DESCRIPTION:We are having a meeting all this week at 12 pm fo
1552 r one hour\, with an additional meeting on the first day 2 h
1553 ours long.\nPlease bring your own lunch for the 12 pm meetin
1555 UID:00959BC664CA650E933C892C@example.com
1558 DTSTAMP:20060206T001121Z
1559 DTSTART;TZID=US/Eastern:20060104T140000
1561 RECURRENCE-ID;TZID=US/Eastern:20060104T120000
1562 SUMMARY:Event #2 bis
1563 UID:00959BC664CA650E933C892C@example.com
1570Kewisch, et al. Standards Track [Page 28]
1572RFC 7265 jCal May 2014
1579 ["prodid", {}, "text", "-//Example Corp.//Example Client//EN"],
1580 ["version", {}, "text", "2.0"]
1585 ["last-modified", {}, "date-time", "2004-01-10T03:28:45Z"],
1586 ["tzid", {}, "text", "US/Eastern"]
1591 ["dtstart", {}, "date-time", "2000-04-04T02:00:00"],
1601 ["tzname", {}, "text", "EDT"],
1602 ["tzoffsetfrom", {}, "utc-offset", "-05:00"],
1603 ["tzoffsetto", {}, "utc-offset", "-04:00"]
1609 ["dtstart", {}, "date-time", "2000-10-26T02:00:00"],
1619 ["tzname", {}, "text", "EST"],
1620 ["tzoffsetfrom", {}, "utc-offset", "-04:00"],
1621 ["tzoffsetto", {}, "utc-offset", "-05:00"]
1626Kewisch, et al. Standards Track [Page 29]
1628RFC 7265 jCal May 2014
1637 ["dtstamp", {}, "date-time", "2006-02-06T00:11:21Z"],
1639 { "tzid": "US/Eastern" },
1641 "2006-01-02T12:00:00"
1643 ["duration", {}, "duration", "PT1H"],
1644 ["rrule", {}, "recur", { "freq": "DAILY", "count": 5 } ],
1646 { "tzid": "US/Eastern" },
1648 "2006-01-02T15:00:00/PT2H"
1650 ["summary", {}, "text", "Event #2"],
1654 // Note that comments and string concatenation are not
1655 // allowed per the JSON specification and is used here only
1656 // to avoid long lines.
1657 "We are having a meeting all this week at 12 pm for one " +
1658 "hour, with an additional meeting on the first day 2 " +
1659 "hours long.\nPlease bring your own lunch for the 12 pm " +
1662 ["uid", {}, "text", "00959BC664CA650E933C892C@example.com"]
1668 ["dtstamp", {}, "date-time", "2006-02-06T00:11:21Z"],
1670 { "tzid": "US/Eastern" },
1672 "2006-01-02T14:00:00"
1674 ["duration", {}, "duration", "PT1H"],
1676 { "tzid": "US/Eastern" },
1678 "2006-01-04T12:00:00"
1682Kewisch, et al. Standards Track [Page 30]
1684RFC 7265 jCal May 2014
1688 ["summary", {}, "text", "Event #2"],
1689 ["uid", {}, "text", "00959BC664CA650E933C892C@example.com"]
1700 650 Castro Street, Suite 300
1701 Mountain View, CA 94041
1704 EMail: mozilla@kewis.ch
1705 URI: http://www.mozilla.org/
1714 EMail: cyrus@daboo.name
1715 URI: http://www.apple.com/
1719 Rensselaer Polytechnic Institute
1724 EMail: douglm@rpi.edu
1725 URI: http://www.rpi.edu/
1738Kewisch, et al. Standards Track [Page 31]