[CalendarServer-changes] [14834] CalendarServer/trunk/doc
source_changes at macosforge.org
source_changes at macosforge.org
Wed May 27 07:45:31 PDT 2015
Revision: 14834
http://trac.calendarserver.org//changeset/14834
Author: cdaboo at apple.com
Date: 2015-05-27 07:45:30 -0700 (Wed, 27 May 2015)
Log Message:
-----------
Mark CTag spec as deprecated. Add some recent RFCs.
Modified Paths:
--------------
CalendarServer/trunk/doc/Extensions/caldav-ctag.txt
CalendarServer/trunk/doc/Extensions/caldav-ctag.xml
Added Paths:
-----------
CalendarServer/trunk/doc/RFC/RFC7095-jCard.txt
CalendarServer/trunk/doc/RFC/RFC7265-jcal.txt
CalendarServer/trunk/doc/RFC/RFC7529-RSCALE.txt
Modified: CalendarServer/trunk/doc/Extensions/caldav-ctag.txt
===================================================================
--- CalendarServer/trunk/doc/Extensions/caldav-ctag.txt 2015-05-27 14:33:41 UTC (rev 14833)
+++ CalendarServer/trunk/doc/Extensions/caldav-ctag.txt 2015-05-27 14:45:30 UTC (rev 14834)
@@ -1,62 +1,48 @@
-Calendar Server Extension C. Daboo
+
+ C. Daboo
Apple
- May 3, 2007
+ May 27, 2015
Calendar Collection Entity Tag (CTag) in CalDAV
- caldav-ctag-02
+ caldav-ctag-03
Abstract
+ IMPORTANT: The feature defined by this specification is now
+ deprecated in favor of support for the WebDAV Sync REPORT as defined
+ by [RFC6578]. Clients MUST NOT rely on this feature to detect
+ changes to collections, instead they MUST support the WebDAV Sync
+ REPORT. Servers MUST support the WebDAV Sync REPORT to allow clients
+ to efficiently synchronize calendar collections. Whilst most modern
+ clients do support the WebDAV Sync REPORT, servers MAY continue to
+ support this specification by simply using the DAV:sync-token
+ property value for the getctag property value, in order to provide
+ backwards compatibility with old clients.
+
This specification defines an extension to CalDAV that provides a
fast way for a client to determine whether the contents of a calendar
collection may have changed.
-
Table of Contents
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
- 2. Conventions Used in This Document . . . . . . . . . . . . . . . 2
- 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
- 3.1. Server . . . . . . . . . . . . . . . . . . . . . . . . . . 3
- 3.2. Client . . . . . . . . . . . . . . . . . . . . . . . . . . 3
- 4. New features in CalDAV . . . . . . . . . . . . . . . . . . . . 3
- 4.1. getctag WebDAV Property . . . . . . . . . . . . . . . . . . 4
- 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 4
- 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5
- 7. Normative References . . . . . . . . . . . . . . . . . . . . . 5
- Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 5
- Appendix B. Change History . . . . . . . . . . . . . . . . . . . . 5
- Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 6
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 1
+ 2. Conventions Used in This Document . . . . . . . . . . . . . . 2
+ 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 3.1. Server . . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 3.2. Client . . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 4. New features in CalDAV . . . . . . . . . . . . . . . . . . . 3
+ 4.1. getctag WebDAV Property . . . . . . . . . . . . . . . . . 3
+ 5. Security Considerations . . . . . . . . . . . . . . . . . . . 4
+ 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4
+ 7. Normative References . . . . . . . . . . . . . . . . . . . . 4
+ Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 5
+ Appendix B. Change History . . . . . . . . . . . . . . . . . . . 5
+ Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 5
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo [Page 1]
-
- CalDAV Proxy May 2007
-
-
1. Introduction
In CalDAV [RFC4791] calendar data is stored in calendar collection
@@ -64,6 +50,14 @@
find out what has changed since the last time they examined it.
Currently that involves having to do a PROPFIND Depth:1 HTTP request,
or a CALDAV:calendar-query REPORT request. When a calendar
+
+
+
+Daboo Expires November 28, 2015 [Page 1]
+
+ CalDAV CTag May 2015
+
+
collection contains a large number of calendar resources those
operations become expensive on the server.
@@ -82,10 +76,9 @@
doing the full (Depth:1) poll of the collection to actually determine
which resources in the collection changed.
- This extension also defines CTag's on CalDAV scheduling
- [I-D.desruisseaux-caldav-sched] Inbox and Outbox collections.
+ This extension also defines CTag's on CalDAV scheduling [RFC6638]
+ Inbox and Outbox collections.
-
2. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
@@ -103,16 +96,6 @@
of an XML fragment, the string "CS:" will be prefixed to the element
type names respectively.
-
-
-
-
-
-Daboo [Page 2]
-
- CalDAV Proxy May 2007
-
-
3. Overview
3.1. Server
@@ -124,6 +107,13 @@
be unique over the lifetime of any calendar or scheduling Inbox or
Outbox collection at a specific URI.
+
+
+Daboo Expires November 28, 2015 [Page 2]
+
+ CalDAV CTag May 2015
+
+
Whenever a calendar resource is added to, modified or deleted from
the calendar collection, the value of the CS:getctag property MUST
change. Typically this change will occur when the DAV:getetag
@@ -138,8 +128,8 @@
collection that it intends to synchronize with.
When polling a calendar or scheduling Inbox or Outbox collection, the
- client issues a PROPFIND Depth:0 HTTP request, asking for the CS:
- getctag property to be returned.
+ client issues a PROPFIND Depth:0 HTTP request, asking for the
+ CS:getctag property to be returned.
If the returned value of CS:getctag property matches the one
currently cached for the calendar or scheduling Inbox or Outbox
@@ -151,24 +141,12 @@
Inbox or Outbox collection have changed. At that point the client
should re-issue the PROPFIND Depth:1 request to get the collection
changes in detail and the CS:getctag property value corresponding to
- the new state. The new CSgetctag property value should replace the
+ the new state. The new CS:getctag property value should replace the
one currently cached for that calendar or scheduling Inbox or Outbox
collection.
-
4. New features in CalDAV
-
-
-
-
-
-
-Daboo [Page 3]
-
- CalDAV Proxy May 2007
-
-
4.1. getctag WebDAV Property
Name: getctag
@@ -184,6 +162,14 @@
protected and SHOULD be returned by a PROPFIND DAV:allprop request
(as defined in Section 12.14.1 of [RFC2518]).
+
+
+
+Daboo Expires November 28, 2015 [Page 3]
+
+ CalDAV CTag May 2015
+
+
Description: The CS:getctag property allows clients to quickly
determine if the contents of a calendar or scheduling Inbox or
Outbox collection have changed since the last time a
@@ -202,7 +188,6 @@
<T:getctag xmlns:T="http://calendarserver.org/ns/"
>ABCD-GUID-IN-THIS-COLLECTION-20070228T122324010340</T:getctag>
-
5. Security Considerations
The CS:getctag property value changes whenever any resource in the
@@ -215,28 +200,12 @@
resources in a calendar collection, but it does not expose any
details about them.
-
-
-
-
-
-Daboo [Page 4]
-
- CalDAV Proxy May 2007
-
-
6. IANA Considerations
This document does not require any actions on the part of IANA.
-
7. Normative References
- [I-D.desruisseaux-caldav-sched]
- Desruisseaux, B., "Scheduling Extensions to CalDAV",
- draft-desruisseaux-caldav-sched-03 (work in progress),
- January 2007.
-
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
@@ -245,42 +214,54 @@
WEBDAV", RFC 2518, February 1999.
[RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web
- Distributed Authoring and Versioning (WebDAV) Access
- Control Protocol", RFC 3744, May 2004.
+ Distributed Authoring and Versioning (WebDAV)
+ Access Control Protocol", RFC 3744, May 2004.
+
+
+
+
+Daboo Expires November 28, 2015 [Page 4]
+
+ CalDAV CTag May 2015
+
+
[RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
"Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
March 2007.
+ [RFC6578] Daboo, C. and A. Quillaud, "Collection Synchronization for
+ Web Distributed Authoring and Versioning (WebDAV)", RFC
+ 6578, March 2012.
+ [RFC6638] Daboo, C. and B. Desruisseaux, "Scheduling Extensions to
+ CalDAV", RFC 6638, June 2012.
+
Appendix A. Acknowledgments
This specification is the result of discussions between the Apple
calendar server and client teams.
-
Appendix B. Change History
- Changes from -01:
+ Changes in -03:
+ 1. Added deprecation warning.
+
+ 2. Updated references.
+
+ Changes in -02:
+
1. Updated to RFC4791 reference.
2. Added text indicating that ctag applies to schedule Inbox and
Outbox as well.
- Changes from -00:
+ Changes in -01:
1. Relaxed requirement so that any type of change to a child
resource can trigger a CTag change (similar behavior to ETag).
-
-
-
-Daboo [Page 5]
-
- CalDAV Proxy May 2007
-
-
Author's Address
Cyrus Daboo
@@ -296,41 +277,4 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo [Page 6]
-
+Daboo Expires November 28, 2015 [Page 5]
Modified: CalendarServer/trunk/doc/Extensions/caldav-ctag.xml
===================================================================
--- CalendarServer/trunk/doc/Extensions/caldav-ctag.xml 2015-05-27 14:33:41 UTC (rev 14833)
+++ CalendarServer/trunk/doc/Extensions/caldav-ctag.xml 2015-05-27 14:45:30 UTC (rev 14834)
@@ -4,7 +4,8 @@
<!ENTITY rfc2518 PUBLIC '' 'bibxml/reference.RFC.2518.xml'>
<!ENTITY rfc3744 PUBLIC '' 'bibxml/reference.RFC.3744.xml'>
<!ENTITY rfc4791 PUBLIC '' 'bibxml/reference.RFC.4791.xml'>
-<!ENTITY I-D.desruisseaux-caldav-sched PUBLIC '' 'bibxml3/reference.I-D.desruisseaux-caldav-sched.xml'>
+<!ENTITY rfc6578 PUBLIC '' 'bibxml/reference.RFC.6578.xml'>
+<!ENTITY rfc6638 PUBLIC '' 'bibxml/reference.RFC.6638.xml'>
]>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
@@ -16,9 +17,9 @@
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc private="Calendar Server Extension"?>
-<rfc ipr="none" docName='caldav-ctag-02'>
+<rfc ipr="none" docName='caldav-ctag-03'>
<front>
- <title abbrev="CalDAV Proxy">Calendar Collection Entity Tag (CTag) in CalDAV</title>
+ <title abbrev="CalDAV CTag">Calendar Collection Entity Tag (CTag) in CalDAV</title>
<author initials="C." surname="Daboo" fullname="Cyrus Daboo">
<organization abbrev="Apple">
Apple Inc.
@@ -35,9 +36,12 @@
<uri>http://www.apple.com/</uri>
</address>
</author>
- <date year='2007'/>
+ <date />
<abstract>
<t>
+ IMPORTANT: The feature defined by this specification is now deprecated in favor of support for the WebDAV Sync REPORT as defined by <xref target="RFC6578" />. Clients MUST NOT rely on this feature to detect changes to collections, instead they MUST support the WebDAV Sync REPORT. Servers MUST support the WebDAV Sync REPORT to allow clients to efficiently synchronize calendar collections. Whilst most modern clients do support the WebDAV Sync REPORT, servers MAY continue to support this specification by simply using the DAV:sync-token property value for the getctag property value, in order to provide backwards compatibility with old clients.
+ </t>
+ <t>
This specification defines an extension to CalDAV that provides a fast way for a client to determine whether the contents of a calendar collection may have changed.
</t>
</abstract>
@@ -54,7 +58,7 @@
To improve on performance, this specification defines a new "calendar collection entity tag" (CTag) WebDAV property that is defined on calendar collections. When the calendar collection changes, the CTag value changes. Thus a client can cache the CTag at some point in time, then poll the collection only (i.e. PROPFIND Depth:0 HTTP requests) and determine if a change has happened based on the returned CTag value. If there is a change, it can then fall back to doing the full (Depth:1) poll of the collection to actually determine which resources in the collection changed.
</t>
<t>
- This extension also defines CTag's on <xref target="I-D.desruisseaux-caldav-sched">CalDAV scheduling</xref> Inbox and Outbox collections.
+ This extension also defines CTag's on <xref target="RFC6638">CalDAV scheduling</xref> Inbox and Outbox collections.
</t>
</section>
<section title='Conventions Used in This Document'>
@@ -153,7 +157,8 @@
&rfc2518;
&rfc3744;
&rfc4791;
- &I-D.desruisseaux-caldav-sched;
+ &rfc6578;
+ &rfc6638;
</references>
<!--
<references title='Informative References'>
@@ -165,13 +170,19 @@
</t>
</section>
<section title='Change History'>
- <t>Changes from -01:
+ <t>Changes in -03:
<list style='numbers'>
+ <t>Added deprecation warning.</t>
+ <t>Updated references.</t>
+ </list>
+ </t>
+ <t>Changes in -02:
+ <list style='numbers'>
<t>Updated to RFC4791 reference.</t>
<t>Added text indicating that ctag applies to schedule Inbox and Outbox as well.</t>
</list>
</t>
- <t>Changes from -00:
+ <t>Changes in -01:
<list style='numbers'>
<t>Relaxed requirement so that any type of change to a child resource can trigger a CTag change (similar behavior to ETag).</t>
</list>
Added: CalendarServer/trunk/doc/RFC/RFC7095-jCard.txt
===================================================================
--- CalendarServer/trunk/doc/RFC/RFC7095-jCard.txt (rev 0)
+++ CalendarServer/trunk/doc/RFC/RFC7095-jCard.txt 2015-05-27 14:45:30 UTC (rev 14834)
@@ -0,0 +1,1627 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) P. Kewisch
+Request for Comments: 7095 Mozilla
+Category: Standards Track January 2014
+ISSN: 2070-1721
+
+
+ jCard: The JSON Format for vCard
+
+Abstract
+
+ This specification defines "jCard", a JSON format for vCard data.
+ The vCard data format is a text format for representing and
+ exchanging information about individuals and other entities, for
+ example, telephone numbers, email addresses, structured names, and
+ delivery addresses. JSON is a lightweight, text-based, language-
+ independent data interchange format commonly used in Internet
+ applications.
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 5741.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ http://www.rfc-editor.org/info/rfc7095.
+
+Copyright Notice
+
+ Copyright (c) 2014 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
+ (http://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.
+
+
+
+
+
+Kewisch Standards Track [Page 1]
+
+RFC 7095 jCard January 2014
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 2. Conventions Used in This Document . . . . . . . . . . . . . . 3
+ 3. Converting from vCard to jCard . . . . . . . . . . . . . . . 4
+ 3.1. Pre-processing . . . . . . . . . . . . . . . . . . . . . 4
+ 3.2. jCard Object and Syntactic Entities (RFC 6350, Sections
+ 6.1.1 and 6.1.2) . . . . . . . . . . . . . . . . . . . . 5
+ 3.3. Properties (RFC 6350, Section 6) . . . . . . . . . . . . 5
+ 3.3.1. Special Cases for Properties . . . . . . . . . . . . 7
+ 3.3.1.1. The VERSION Property . . . . . . . . . . . . . . 7
+ 3.3.1.2. Grouping of Properties . . . . . . . . . . . . . 7
+ 3.3.1.3. Structured Property Values . . . . . . . . . . . 8
+ 3.4. Parameters (RFC 6350, Section 5) . . . . . . . . . . . . 10
+ 3.4.1. VALUE Parameter . . . . . . . . . . . . . . . . . . . 10
+ 3.4.2. Multi-Valued Parameters . . . . . . . . . . . . . . . 11
+ 3.5. Values (RFC 6350, Section 4) . . . . . . . . . . . . . . 11
+ 3.5.1. Text (RFC 6350, Section 4.1) . . . . . . . . . . . . 12
+ 3.5.2. URI (RFC 6350, Section 4.2) . . . . . . . . . . . . . 12
+ 3.5.3. Date (RFC 6350, Section 4.3.1) . . . . . . . . . . . 12
+ 3.5.4. Time (RFC 6350, Section 4.3.2) . . . . . . . . . . . 13
+ 3.5.5. Date-Time (RFC 6350, Section 4.3.3) . . . . . . . . . 14
+ 3.5.6. Date and/or Time (RFC 6350, Section 4.3.4) . . . . . 16
+ 3.5.7. Timestamp (RFC 6350, Section 4.3.5) . . . . . . . . . 16
+ 3.5.8. Boolean (RFC 6350, Section 4.4) . . . . . . . . . . . 17
+ 3.5.9. Integer (RFC 6350, Section 4.5) . . . . . . . . . . . 17
+ 3.5.10. Float (RFC 6350, Section 4.6) . . . . . . . . . . . . 17
+ 3.5.11. UTC Offset (RFC 6350, Section 4.7) . . . . . . . . . 18
+ 3.5.12. Language Tag (RFC 6350, Section 4.8) . . . . . . . . 18
+ 3.6. Extensions (RFC 6350, Section 6.10) . . . . . . . . . . . 18
+ 4. Converting from jCard into vCard . . . . . . . . . . . . . . 19
+ 5. Handling Unrecognized Properties or Parameters . . . . . . . 19
+ 5.1. Converting vCard into jCard . . . . . . . . . . . . . . . 19
+ 5.2. Converting jCard into vCard . . . . . . . . . . . . . . . 20
+ 5.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 20
+ 6. Security Considerations . . . . . . . . . . . . . . . . . . . 21
+ 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22
+ 7.1. GROUP vCard Parameter . . . . . . . . . . . . . . . . . . 23
+ 7.2. UNKNOWN vCard Value Data Type . . . . . . . . . . . . . . 24
+ 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24
+ 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 24
+ 9.1. Normative References . . . . . . . . . . . . . . . . . . 24
+ 9.2. Informative References . . . . . . . . . . . . . . . . . 25
+ Appendix A. ABNF Syntax . . . . . . . . . . . . . . . . . . . . 26
+ Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 27
+ B.1. Example: vCard of the Author of RFC 6350 . . . . . . . . 27
+ B.1.1. vCard Data . . . . . . . . . . . . . . . . . . . . . 27
+ B.1.2. jCard Data . . . . . . . . . . . . . . . . . . . . . 28
+
+
+
+Kewisch Standards Track [Page 2]
+
+RFC 7095 jCard January 2014
+
+
+1. Introduction
+
+ The vCard data format [RFC6350] provides for the capture and exchange
+ of information normally stored within an address book or directory
+ application. The vCard format has gone through multiple revisions,
+ most recently vCard 4.
+
+ As certain similarities exist between vCard and the iCalendar data
+ format [RFC5545], there is also an effort to define a JSON-based data
+ format for calendar information called jCal [JCAL] that parallels the
+ format defined in this specification. The term "JSON" describes the
+ JavaScript Object Notation defined in [RFC4627].
+
+ The purpose of this specification is to define "jCard", a JSON format
+ for vCard data. One main advantage to using a JSON-based format over
+ the classic vCard format is easier processing for JavaScript-based
+ widgets and libraries, especially in the scope of web-based
+ applications.
+
+ The key design considerations are essentially the same as those for
+ [JCAL] and [RFC6321], that is:
+
+ Round-tripping (converting a vCard instance to jCard and back)
+ will give the same semantic result as the starting point. For
+ example, all components, properties, and property parameters are
+ guaranteed to be preserved.
+
+ The Ordering of elements and the case of property and parameter
+ names will not necessarily be preserved.
+
+ The vCard data semantics are to be preserved, allowing a simple
+ consumer to easily browse the data in jCard. A full understanding
+ of vCard is still required in order to modify and/or fully
+ comprehend the directory data.
+
+ Extensions to the underlying vCard specification must not lead to
+ requiring an update to jCard.
+
+2. Conventions Used in This Document
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in [RFC2119].
+
+ The underlying format used for jCard is JSON. Consequently, the
+ terms "object" and "array" as well as the four primitive types
+ (strings, numbers, booleans, and null) are to be interpreted as
+ described in Section 1 of [RFC4627].
+
+
+
+Kewisch Standards Track [Page 3]
+
+RFC 7095 jCard January 2014
+
+
+ Some examples in this document contain "partial" JSON documents used
+ for illustrative purposes. In these examples, three periods "..."
+ are used to indicate a portion of the document that has been removed
+ for compactness.
+
+3. Converting from vCard to jCard
+
+ This section describes how vCard objects are converted to jCard using
+ a simple mapping between the vCard data model and JSON elements.
+
+ In [RFC6350], vCard objects are comprised of a set of "properties",
+ "parameters", and "values". The top level of a vCard object contains
+ "properties". A "property" has a "value" and a set of zero or more
+ "parameters". Each of these entities has a representation in jCard,
+ defined in the following sections. The representation of a vCard
+ object in JSON will be named "jCard object" throughout this document.
+
+3.1. Pre-processing
+
+ vCard uses a line-folding mechanism to limit lines of data to a
+ maximum line length (typically 75 octets) to ensure maximum
+ likelihood of preserving data integrity as it is transported via
+ various means (e.g., email) -- see Section 3.2 of [RFC6350].
+
+ vCard data uses an "escape" character sequence for text values and
+ property parameter values. See Section 3.4 of [RFC6350] as well as
+ [RFC6868].
+
+ When converting from vCard to jCard, first vCard lines MUST be
+ unfolded. Afterwards, any vCard escaping MUST be unescaped.
+ Finally, JSON escaping (e.g., for control characters) MUST be
+ applied.
+
+ The reverse order applies when converting from jCard to vCard.
+ First, JSON escaping MUST be unescaped. Afterwards, vCard escaping
+ MUST be applied. Finally, long lines SHOULD be folded as described
+ in [RFC6350].
+
+ One key difference in the formatting of values used in vCard and
+ jCard is that in jCard the specification uses date/time values
+ aligned with the extended format of [ISO.8601.2004], which is more
+ commonly used in Internet applications that make use of the JSON
+ format. The sections of this document describing the various date
+ and time formats contain more information on the use of the complete
+ representation, reduced accuracy, or truncated representation.
+
+
+
+
+
+
+Kewisch Standards Track [Page 4]
+
+RFC 7095 jCard January 2014
+
+
+3.2. jCard Object and Syntactic Entities (RFC 6350, Sections 6.1.1 and
+ 6.1.2)
+
+ In Sections 6.1.1 and 6.1.2 of [RFC6350], the BEGIN and END
+ properties delimit a syntactic vCard entity. In jCard, each
+ syntactic entity is represented by an array with two elements and is
+ named "jCard object". The first element is the string "vcard", and
+ the second element is an array of jCard properties as described in
+ Section 3.3, belonging to the entity.
+
+ Although [RFC6350] defines BEGIN and END to be properties, they MUST
+ NOT appear as properties of the jCard. Instead, the jCard object is
+ sufficient to define a vCard entity. When converting from jCard to
+ vCard, the BEGIN and END properties MUST be added to enclose the
+ properties of the jCard object.
+
+ Example:
+
+ ["vcard", [
+ /* Add properties in place of this comment */
+ ]
+ ]
+
+ Consumers of this format wishing to define content that can represent
+ multiple jCard objects within the same JSON document can use a simple
+ JSON array, each element being a single jCard object.
+
+3.3. Properties (RFC 6350, Section 6)
+
+ Each individual vCard property is represented in jCard by an array
+ with three fixed elements, followed by one or more additional
+ elements, depending on if the property is a multi-valued property as
+ described in Section 3.3 of [RFC6350].
+
+ The array consists of the following fixed elements:
+
+ 1. The name of the property, as a lowercase string. The vCard
+ format specifies that property names are case insensitive and
+ recommends that they be rendered in uppercase. In jCard, they
+ MUST be in lowercase.
+
+ 2. An object containing the parameters as described in Section 3.4.
+ If the property has no parameters, an empty object is used to
+ represent that.
+
+
+
+
+
+
+
+Kewisch Standards Track [Page 5]
+
+RFC 7095 jCard January 2014
+
+
+ 3. The type identifier string of the value, in lowercase. It is
+ important that parsers check this to determine the data type of
+ the value and that they do not rely on assumptions. For example,
+ for structured values, the data type will be "array".
+
+ The remaining elements of the array are used for one or more values
+ of the property. For single-value properties, the array has exactly
+ four elements; for multi-valued properties, each value is another
+ element, and there can be any number of additional elements.
+
+ In the following example, the "categories" property is multi-valued
+ and has two values, while all other properties are single-valued:
+
+ ["vcard",
+ [
+ ["version", {}, "text", "4.0"],
+ ["fn", {}, "text", "John Doe"],
+ ["gender", {}, "text", "M"],
+ ["categories", {}, "text", "computers", "cameras"],
+ ...
+ ]
+ ]
+
+ As described in Section 3.3.1.3, a property value may be a structured
+ property value, in which case it is represented as an array
+ encapsulated in the array that represents the overall property.
+
+ Strictly speaking, this means that the property value is not
+ represented in the format indicated by the type identifier but by an
+ array instead. However, the values inside the encapsulated array are
+ of the format identified by the type identifier.
+
+ The above also holds for multi-valued properties, where some of the
+ values may be structured property values and therefore are
+ represented as an encapsulated array.
+
+ A special case is where a value in an encapsulated array consists of
+ multiple components itself, in which case it is represented as yet
+ another nested array, with elements matching the value type.
+ Section 3.3.1.3 describes this in more detail.
+
+ The above illustrates that it's important for the parser to check the
+ format of each property value, as it might either directly match the
+ value type, or it might be a structured value where nested
+ subelements match the value type.
+
+
+
+
+
+
+Kewisch Standards Track [Page 6]
+
+RFC 7095 jCard January 2014
+
+
+3.3.1. Special Cases for Properties
+
+ This section describes some properties that have special handling
+ when converting to jCard.
+
+3.3.1.1. The VERSION Property
+
+ The vCard format specification [RFC6350] defines the "VERSION"
+ property to be mandatory. The jCard "version" property MUST be
+ represented in the corresponding jCard component, with the same value
+ as in the vCard. vCards that conform to RFC 6350 will contain the
+ value "4.0".
+
+ Also in accordance to [RFC6350], the "version" property MUST be the
+ first element of the array containing the properties of a jCard.
+
+3.3.1.2. Grouping of Properties
+
+ In vCard [RFC6350], related properties can be grouped together using
+ a grouping construct. The grouping is accomplished by adding a
+ prefix (which consists of the group name followed by a dot) to the
+ property name.
+
+ In jCard, the same grouping is achieved through a "group" parameter
+ that holds the group name. In jCard, a property name therefore MUST
+ NOT be prefixed by a group name.
+
+ The "GROUP" parameter MUST NOT be used in vCard; as per [RFC6350], it
+ is merely registered to reserve the parameter, avoiding collisions.
+ Formal registration of the "GROUP" parameter is described in
+ Section 7.1.
+
+3.3.1.2.1. Group Conversion Rules
+
+ In jCard, the parameter's value is a single opaque string.
+ Conversion rules are as follows:
+
+ o From vCard to jCard, the group construct (see [RFC6350],
+ Section 3.3) is removed. In its place, the "group" parameter is
+ used. Its value is a string corresponding to the group name,
+ which is case insensitive both in vCard and jCard. The name's
+ case SHOULD be converted into lowercase.
+
+ o When converting from jCard to vCard, the value of the "group"
+ parameter followed by a dot is prefixed to the property name, and
+ the "group" parameter is discarded. The "GROUP" parameter MUST
+ NOT appear in the resulting vCard. Following the recommendations
+ in [RFC6350], the name's case SHOULD be converted into uppercase.
+
+
+
+Kewisch Standards Track [Page 7]
+
+RFC 7095 jCard January 2014
+
+
+ Example:
+
+ CONTACT.FN:Mr. John Q. Public\, Esq.
+
+ is equivalent to:
+
+ [ "fn", { "group": "CONTACT" }, "text", "Mr. John Q. Public, Esq." ]
+
+3.3.1.3. Structured Property Values
+
+ The vCard specification defines properties with structured values,
+ for example, "GENDER" or "ADR". In vCard, a structured text value
+ consists of one or multiple text components, delimited by the
+ SEMICOLON character. Its equivalent in jCard is a structured
+ property value, which is an array containing one element for each
+ text component, with empty/missing text components represented by
+ zero-length strings.
+
+ vCard Example:
+
+ ADR:;;123 Main Street;Any Town;CA;91921-1234;U.S.A.
+
+ jCard Example:
+
+ ["adr", {}, "text",
+ [
+ "", "", "123 Main Street",
+ "Any Town", "CA", "91921-1234", "U.S.A."
+ ]
+ ]
+
+ Some vCard properties, for example, ADR, also allow a structured
+ value element that itself has multiple values. In this case, the
+ element of the array describing the structured value is itself an
+ array with one element for each of the component's multiple values.
+
+ vCard Example:
+
+ ADR:;;My Street,Left Side,Second Shack;Hometown;PA;18252;U.S.A.
+
+
+
+
+
+
+
+
+
+
+
+
+Kewisch Standards Track [Page 8]
+
+RFC 7095 jCard January 2014
+
+
+ jCard Example:
+
+ ["adr", {}, "text",
+ [
+ "", "",
+ ["My Street", "Left Side", "Second Shack"],
+ "Hometown", "PA", "18252", "U.S.A."
+ ]
+ ]
+
+ In both cases, the array element values MUST have the primitive type
+ that matches the jCard type identifier. In [RFC6350], there are only
+ structured text values and thus only JSON strings are used. For
+ example, extensions may define structured number or boolean values,
+ where JSON number or boolean types MUST be used.
+
+ Although it is allowed for a structured property value to hold just
+ one component, it is RECOMMENDED to represent it as a single text
+ value instead, omitting the array completely. Nevertheless, a simple
+ implementation MAY choose to retain the array, with a single text
+ value as its element.
+
+ Similarly, structured values that consist of two text components with
+ one being optional (for example, "GENDER") can be represented as a
+ single text value. Therefore, parsers of jCard data SHOULD check
+ even known property values for structured information by considering
+ the JSON data type of the value, which can be an array or a primitive
+ value. This is especially important for languages where accessing
+ array members is done by the same construct as accessing characters
+ of a string.
+
+ Examples:
+
+ ["gender", {}, "text", ["F", "grrrl"] ],
+ ["gender", {}, "text", "M" ]
+
+ Per Section 6.3.1 of [RFC6350], the component separator MUST be
+ specified even if the component value is missing. Similarly, the
+ jCard array containing the structured data MUST contain all required
+ elements, even if they are empty.
+
+ vCard Example:
+
+ ADR;LABEL="123 Maple Ave\nSuite 901\nVancouver BC\nA1B 2C9\nCan
+ ada":;;;;;;
+
+
+
+
+
+
+Kewisch Standards Track [Page 9]
+
+RFC 7095 jCard January 2014
+
+
+ jCard Example:
+
+ ["adr",
+ {"label":"123 Maple Ave\nSuite 901\nVancouver BC\nA1B 2C9\nCanada"},
+ "text",
+ ["", "", "", "", "", "", ""]
+ ]
+
+3.4. Parameters (RFC 6350, Section 5)
+
+ Property parameters are represented as a JSON object where each key-
+ value pair represents the vCard parameter name and its value. The
+ name of the parameter MUST be in lowercase; the original case of the
+ parameter value MUST be preserved. For example, the "LANGUAGE"
+ property parameter is represented in jCard by the "language" key.
+ Any new vCard parameters added in the future will be converted in the
+ same way.
+
+ Example:
+
+ ["role", { "language": "tr" }, "text", "roca"],
+
+3.4.1. VALUE Parameter
+
+ vCard defines a "VALUE" property parameter (Section 5.2 of
+ [RFC6350]). This property parameter MUST NOT be added to the
+ parameters object. Instead, the value type is signaled through the
+ type identifier in the third element of the array describing the
+ property. When converting a property from vCard to jCard, the value
+ type is determined as follows:
+
+ 1. If the property has a "VALUE" parameter, that parameter's value
+ is used as the value type.
+
+ 2. If the property has no "VALUE" parameter but has a default value
+ type, the default value type is used.
+
+ 3. If the property has no "VALUE" parameter and has no default value
+ type, "unknown" is used.
+
+ Converting from jCard into vCard is done as follows:
+
+ 1. If the property's value type is "unknown", no "VALUE" parameter
+ is included.
+
+ 2. If the property's value type is the default type for that
+ property, no "VALUE" parameter is included.
+
+
+
+
+Kewisch Standards Track [Page 10]
+
+RFC 7095 jCard January 2014
+
+
+ 3. Otherwise, a "VALUE" parameter is included, and the value type is
+ used as the parameter value.
+
+ See Section 5 for information on handling unknown value types.
+
+3.4.2. Multi-Valued Parameters
+
+ In [RFC6350], some parameters allow using a comma-separated list of
+ values. To ease processing in jCard, the value for such parameters
+ MUST be represented in an array containing the separated values. The
+ array elements MUST be string values. Single-value parameters SHOULD
+ be represented using a single string value, although a more simple
+ implementation might prefer an array with one string element. An
+ example of such a parameter is the vCard "SORT-AS" parameter; more
+ such parameters may be added in extensions.
+
+ The vCard specification requires encapsulation between DQUOTE
+ characters if a parameter value contains a colon, a semicolon, or a
+ comma. These extra DQUOTE characters do not belong to the actual
+ parameter value and hence are not included when the parameter is
+ converted to jCard.
+
+ Example:
+
+ ["vcard",
+ [
+ ["version", {}, "text", "4.0"],
+ ["n",
+ { "sort-as": ["Harten", "Rene"] },
+ "text",
+ ["van der Harten", "Rene", "J.", "Sir", "R.D.O.N."]
+ ],
+ ["fn", {}, "text", "Rene van der Harten"]
+ ...
+ ]
+ ]
+
+3.5. Values (RFC 6350, Section 4)
+
+ The following subsections specify how vCard property value data types
+ (which are defined in Section 4 of [RFC6350]) are represented in
+ jCard.
+
+
+
+
+
+
+
+
+
+Kewisch Standards Track [Page 11]
+
+RFC 7095 jCard January 2014
+
+
+3.5.1. Text (RFC 6350, Section 4.1)
+
+ Description: vCard "TEXT" property values are represented by a
+ property with the type identifier "text". The value elements are
+ JSON strings. For details on structured text values, see
+ Section 3.3.1.3.
+
+ Example:
+
+ ["kind", {}, "text", "group"]
+
+3.5.2. URI (RFC 6350, Section 4.2)
+
+ Description: vCard "URI" property values are represented by a
+ property with the type identifier "uri". The value elements are
+ JSON strings.
+
+ Example:
+
+ ["source", {}, "uri", "ldap://ldap.example.com/cn=babs%20jensen"]
+
+3.5.3. Date (RFC 6350, Section 4.3.1)
+
+ Description: vCard "DATE" property values are represented by a
+ property with the type identifier "date". The value elements are
+ JSON strings with the same date value specified by [RFC6350], but
+ represented using the extended format specified in
+ [ISO.8601.2004], Section 4.1.2. If the complete representation is
+ not used, the same date format restrictions regarding reduced
+ accuracy, truncated representation, and expanded representation
+ noted in [RFC6350], Section 4.3.1 apply. Whenever the extended
+ format is not applicable, the basic format MUST be used.
+
+ ABNF syntax:
+
+ date-complete = year "-" month "-" day ;YYYY-MM-DD
+
+ date-noreduc = date-complete
+ / "--" month "-" day ; --MM-DD
+ / "---" day ; ---DDD
+
+ date = date-noreduc
+ / year; YYYY
+ / year "-" month ; YYYY-MM
+ / "--" month ; --MM
+
+
+
+
+
+
+Kewisch Standards Track [Page 12]
+
+RFC 7095 jCard January 2014
+
+
+ Examples:
+
+ ["bday", {}, "date", "1985-04-12"],
+ ["bday", {}, "date", "1985-04"],
+ ["bday", {}, "date", "1985"],
+ ["bday", {}, "date", "--04-12"],
+ ["bday", {}, "date", "---12"]
+
+ This table contains possible conversions between the vCard DATE
+ format and jCard date. This information is just an example and not a
+ formal specification of the syntax. The specification can be found
+ in [ISO.8601.2000] and [ISO.8601.2004].
+
+ +-----------+----------+------------+
+ | | vCard | jCard |
+ +-----------+----------+------------+
+ | Complete | 19850412 | 1985-04-12 |
+ | | | |
+ | Reduced | 1985-04 | 1985-04 |
+ | | | |
+ | Reduced | 1985 | 1985 |
+ | | | |
+ | Truncated | --0412 | --04-12 |
+ | | | |
+ | Truncated | --04 | --04 |
+ | | | |
+ | Truncated | ---12 | ---12 |
+ +-----------+----------+------------+
+
+3.5.4. Time (RFC 6350, Section 4.3.2)
+
+ Description: vCard "TIME" property values are represented by a
+ property with the type identifier "time". The value elements are
+ JSON strings with the same time value specified by [RFC6350], but
+ represented using the extended format specified in
+ [ISO.8601.2004], Section 4.2. If the complete representation is
+ not used, the same time format restrictions regarding reduced
+ accuracy, decimal fraction, and truncated representation noted in
+ [RFC6350], Section 4.3.2 apply. Whenever the extended format is
+ not applicable, the basic format MUST be used. The seconds value
+ of 60 MUST only be used to account for positive "leap" seconds,
+ and the midnight hour is always represented by 00, never 24.
+ Fractions of a second are not supported by this format. In jCard,
+ UTC offsets are permitted within a time value; note that this
+ differs from jCal [JCAL], where they are not permitted.
+
+
+
+
+
+
+Kewisch Standards Track [Page 13]
+
+RFC 7095 jCard January 2014
+
+
+ ABNF syntax:
+
+ time-notrunc = hour [":" minute [":" second]] [zone]
+
+ time = time-notrunc
+ / "-" minute ":" second [zone]; -mm:ss
+ / "-" minute [zone]; -mm
+ / "--" second [zone]; --ss
+
+ Examples:
+
+ ["x-time-local", {}, "time", "12:30:00"],
+ ["x-time-utc", {}, "time", "12:30:00Z"],
+ ["x-time-offset", {}, "time", "12:30:00-08:00"],
+ ["x-time-reduced", {}, "time", "23"],
+ ["x-time-truncated", {}, "time", "-30"]
+
+ This table contains possible conversions between the vCard TIME
+ format and jCard time. This information is just an example and not a
+ formal specification of the syntax. The specification can be found
+ in [ISO.8601.2000] and [ISO.8601.2004].
+
+ +-----------+--------+----------+
+ | | vCard | jCard |
+ +-----------+--------+----------+
+ | Complete | 232050 | 23:20:50 |
+ | | | |
+ | Reduced | 2320 | 23:20 |
+ | | | |
+ | Reduced | 23 | 23 |
+ | | | |
+ | Truncated | -2050 | -20:50 |
+ | | | |
+ | Truncated | -20 | -20 |
+ | | | |
+ | Truncated | --50 | --50 |
+ +-----------+--------+----------+
+
+ Also, all combinations may have any zone designator appended, as in
+ the complete representation.
+
+3.5.5. Date-Time (RFC 6350, Section 4.3.3)
+
+ Description: vCard "DATE-TIME" property values are represented by a
+ property with the type identifier "date-time". The value elements
+ are JSON strings with the same date value specified by [RFC6350],
+ but represented using the extended format specified in
+ [ISO.8601.2004], Section 4.3. If the complete representation is
+
+
+
+Kewisch Standards Track [Page 14]
+
+RFC 7095 jCard January 2014
+
+
+ not used, the same date and time format restrictions noted in
+ Sections 3.5.3 and 3.5.4 apply. Just as described in [RFC6350],
+ truncation of the date part is permitted.
+
+ Example:
+
+ ["anniversary", {}, "date-time", "2013-02-14T12:30:00"],
+ ["anniversary", {}, "date-time", "2013-01-10T19:00:00Z"],
+ ["anniversary", {}, "date-time", "2013-08-15T09:45:00+01:00"],
+ ["anniversary", {}, "date-time", "---15T09:45:00+01:00"]
+
+ This table contains possible conversions between the vCard DATE-TIME
+ format and jCard date-time. This information is just an example and
+ not a formal specification of the syntax. The specification can be
+ found in [ISO.8601.2000] and [ISO.8601.2004].
+
+ +----------------+----------------------+---------------------------+
+ | Representation | vCard | jCard |
+ +----------------+----------------------+---------------------------+
+ | Complete | 19850412T232050 | 1985-04-12T23:20:50 |
+ | | | |
+ | Complete | 19850412T232050Z | 1985-04-12T23:20:50Z |
+ | | | |
+ | Complete | 19850412T232050+0400 | 1985-04-12T23:20:50+04:00 |
+ | | | |
+ | Complete | 19850412T232050+04 | 1985-04-12T23:20:50+04 |
+ | | | |
+ | Reduced | 19850412T2320 | 1985-04-12T23:20 |
+ | | | |
+ | Reduced | 19850412T23 | 1985-04-12T23 |
+ | | | |
+ | Truncated and | --0412T2320 | --04-12T23:20 |
+ | Reduced | | |
+ | | | |
+ | Truncated and | --04T2320 | --04T23:20 |
+ | Reduced | | |
+ | | | |
+ | Truncated and | ---12T2320 | ---12T23:20 |
+ | Reduced | | |
+ | | | |
+ | Truncated and | --0412T2320 | --04-12T23:20 |
+ | Reduced | | |
+ | | | |
+ | Truncated and | --04T23 | --04T23 |
+ | Reduced | | |
+ +----------------+----------------------+---------------------------+
+
+
+
+
+
+Kewisch Standards Track [Page 15]
+
+RFC 7095 jCard January 2014
+
+
+ As specified in [ISO.8601.2000], the lower-order components may not
+ be omitted in the date part (reduced accuracy) and the higher-order
+ components may not be omitted in the time part (truncation). Also,
+ all combinations may have any zone designator appended, as in the
+ complete representation.
+
+3.5.6. Date and/or Time (RFC 6350, Section 4.3.4)
+
+ Description: vCard "DATE-AND-OR-TIME" property values are
+ represented by a property with the type identifier "date-and-or-
+ time". The value elements are either a date-time (Section 3.5.5),
+ a date (Section 3.5.3), or a time (Section 3.5.4) value. Just as
+ described in Section 4.3.4 of [RFC6350], a stand-alone time value
+ MUST always be preceded by a "T".
+
+ Example:
+
+ ["bday", {}, "date-and-or-time", "2013-02-14T12:30:00"],
+ ["bday", {}, "date-and-or-time", "---22T14:00"]
+ ["bday", {}, "date-and-or-time", "1985"],
+ ["bday", {}, "date-and-or-time", "T12:30"]
+
+3.5.7. Timestamp (RFC 6350, Section 4.3.5)
+
+ Description: vCard "TIMESTAMP" property values are represented by a
+ property with the type identifier "timestamp". The value elements
+ are JSON strings with the same timestamp value specified by
+ [RFC6350], but represented using the extended format and complete
+ representation specified in [ISO.8601.2004], Section 4.3.2.
+
+ Example:
+
+ ["rev", {}, "timestamp", "2013-02-14T12:30:00"],
+ ["rev", {}, "timestamp", "2013-02-14T12:30:00Z"],
+ ["rev", {}, "timestamp", "2013-02-14T12:30:00-05"],
+ ["rev", {}, "timestamp", "2013-02-14T12:30:00-05:00"]
+
+ This table contains possible conversions between the vCard TIMESTAMP
+ format and jCard timestamp. This information is just an example and
+ not a formal specification of the syntax. The specification can be
+ found in [ISO.8601.2000] and [ISO.8601.2004].
+
+
+
+
+
+
+
+
+
+
+Kewisch Standards Track [Page 16]
+
+RFC 7095 jCard January 2014
+
+
+ +----------------+----------------------+---------------------------+
+ | Representation | vCard | jCard |
+ +----------------+----------------------+---------------------------+
+ | Complete | 19850412T232050 | 1985-04-12T23:20:50 |
+ | | | |
+ | Complete | 19850412T232050Z | 1985-04-12T23:20:50Z |
+ | | | |
+ | Complete | 19850412T232050+0400 | 1985-04-12T23:20:50+04:00 |
+ | | | |
+ | Complete | 19850412T232050+04 | 1985-04-12T23:20:50+04 |
+ +----------------+----------------------+---------------------------+
+
+3.5.8. Boolean (RFC 6350, Section 4.4)
+
+ Description: vCard "BOOLEAN" property values are represented by a
+ property with the type identifier "boolean". The value element is
+ a JSON boolean value.
+
+ Example:
+
+ ["x-non-smoking", {}, "boolean", true]
+
+3.5.9. Integer (RFC 6350, Section 4.5)
+
+ Description: vCard "INTEGER" property values are represented by a
+ property with the type identifier "integer". The value elements
+ are JSON primitive number values.
+
+ Examples:
+
+ ["x-karma-points", {}, "integer", 42]
+
+ JSON allows decimals (e.g., 3.14) and exponents (e.g., 2e10) to be
+ used in numeric values. jCard does not prohibit this for "integer"
+ property values. However, since vCard does not support decimals or
+ exponents in integers, any decimals and exponents MUST be eliminated
+ when converting an "integer" value type property from jCard to vCard.
+
+3.5.10. Float (RFC 6350, Section 4.6)
+
+ Description: vCard "FLOAT" property values are represented by a
+ property with the type identifier "float". The value elements are
+ JSON primitive number values.
+
+ Example:
+
+ ["x-grade", {}, "float", 1.3]
+
+
+
+
+Kewisch Standards Track [Page 17]
+
+RFC 7095 jCard January 2014
+
+
+ JSON allows exponents (e.g., 2e10) to be used in numeric values.
+ jCard does not prohibit this for "float" property values. However,
+ since vCard does not support exponents in floats, any exponents MUST
+ be eliminated when converting a "float" value type property from
+ jCard to vCard.
+
+3.5.11. UTC Offset (RFC 6350, Section 4.7)
+
+ Description: vCard "UTC-OFFSET" property values are represented by a
+ property with the type identifier "utc-offset". The value
+ elements are JSON strings with the same UTC offset value specified
+ by [RFC6350], with the exception that the hour and minute
+ components are separated by a ":" character, for consistency with
+ the [ISO.8601.2004] timezone offset, extended format.
+
+ Example:
+
+ // Note: [RFC6350] mentions use of utc-offset
+ // for the TZ property as NOT RECOMMENDED
+ ["tz", {}, "utc-offset", "-05:00"]
+
+3.5.12. Language Tag (RFC 6350, Section 4.8)
+
+ Description: vCard "LANGUAGE-TAG" property values are represented by
+ a property with the type identifier "language-tag". The value
+ elements are JSON strings containing a single language-tag, as
+ defined in [RFC5646].
+
+ Example:
+
+ ["lang", {}, "language-tag", "de"]
+
+3.6. Extensions (RFC 6350, Section 6.10)
+
+ vCard extension properties and property parameters (those with an
+ "X-" prefix in their name) are handled in the same way as other
+ properties and property parameters: the property is represented by an
+ array, the property parameter represented by an object. The property
+ or parameter name uses the same name as for the vCard extension, but
+ in lowercase. For example, the "X-FOO" property in vCard turns into
+ the "x-foo" jCard property. See Section 5 for how to deal with
+ default values for unrecognized extension properties or property
+ parameters.
+
+
+
+
+
+
+
+
+Kewisch Standards Track [Page 18]
+
+RFC 7095 jCard January 2014
+
+
+4. Converting from jCard into vCard
+
+ When converting property and property parameter values, the names
+ SHOULD be converted to uppercase. Although vCard names are case
+ insensitive, common practice is to keep them all uppercase following
+ the actual definitions in [RFC6350].
+
+ Character escaping and line folding MUST be applied to the resulting
+ vCard data as required by [RFC6350] and [RFC6868].
+
+ When converting to vCard, the "VALUE" parameter MUST be added to
+ properties whose default value type is unknown but do not have a
+ jCard type identifier "unknown". The "VALUE" parameter MAY be
+ omitted for properties using the default value type. The "VALUE"
+ parameter MUST be omitted for properties that have the jCard type
+ identifier "unknown".
+
+5. Handling Unrecognized Properties or Parameters
+
+ In vCard, properties can have one or more value types as specified by
+ their definition, with one of those values being defined as the
+ default. When a property uses its default value type, the "VALUE"
+ property parameter does not need to be specified on the property.
+ For example, "BDAY"'s default value type is "date-and-or-time", so
+ "VALUE=date-and-or-time" need not be set as a property parameter.
+ However, "BDAY" also allows a "text" value to be specified, and if
+ that is used, "VALUE=text" has to be set as a property parameter.
+
+ When new properties are defined or "X-" properties used, a vCard-to-
+ jCard converter might not recognize them, and not know what the
+ appropriate default value types are, yet it needs to be able to
+ preserve the values. A similar issue arises for unrecognized
+ property parameters.
+
+ In jCard, a new "unknown" property value type is introduced. Its
+ purpose is to allow preserving unknown property values when round-
+ tripping between jCard and vCard. To avoid collisions, this
+ specification reserves the "UNKNOWN" property value type in vCard.
+ It MUST NOT be used in any vCard as specified by [RFC6350], nor any
+ extensions to it. The type is hence registered to the "vCard Value
+ Data Types" registry; see Section 7.2.
+
+5.1. Converting vCard into jCard
+
+ Any property that does not include a "VALUE" property parameter and
+ whose default value type is not known MUST be converted to a
+ primitive JSON string. The content of that string is the unprocessed
+ value text. Also, value type MUST be set to "unknown".
+
+
+
+Kewisch Standards Track [Page 19]
+
+RFC 7095 jCard January 2014
+
+
+ To correctly implement this format, it's critical to use the value
+ type "unknown" when the default value type is not known. If this
+ requirement is ignored and, for example, "text" is used, additional
+ escaping may occur that breaks round-tripping values.
+
+ Any unrecognized property parameter MUST be converted to a string
+ value, with its content set to the property parameter value text,
+ treated as if it were a "TEXT" value.
+
+5.2. Converting jCard into vCard
+
+ In jCard, the value type is always explicitly specified. It is
+ converted to vCard using the vCard "VALUE" parameter, except in the
+ following two cases:
+
+ o If the value type specified in jCard matches the default value
+ type in vCard, the "VALUE" parameter MAY be omitted.
+
+ o If the value type specified in jCard is set to "unknown", the
+ "VALUE" parameter MUST NOT be specified. The value MUST be taken
+ over in vCard without processing.
+
+5.3. Examples
+
+ The following is an example of an unrecognized vCard property (that
+ uses a "URI" value as its default), and the equivalent jCard
+ representation of that property.
+
+ vCard:
+
+ X-COMPLAINT-URI:mailto:abuse at example.org
+
+ jCard:
+
+ ["x-complaint-uri", {}, "unknown", "mailto:abuse at example.org"]
+
+ The following is an example of how to cope with jCard data where the
+ parser was unable to identify the value type. Note how the "unknown"
+ value type is not added to the vCard data, and escaping, aside from
+ standard JSON string escaping, is not processed.
+
+ jCard:
+
+ ["x-coffee-data", {}, "unknown", "Stenophylla;Guinea\\,Africa"]
+
+ vCard:
+
+ X-COFFEE-DATA:Stenophylla;Guinea\,Africa
+
+
+
+Kewisch Standards Track [Page 20]
+
+RFC 7095 jCard January 2014
+
+
+ There are no standard properties in [RFC6350] that have a default
+ type of integer. Consequently, this example uses the following
+ extended property that we treat as having a default type (namely,
+ integer) known to the parser in order to illustrate how a property
+ with a known default type would be transformed.
+
+ jCard:
+
+ ["x-karma-points", {}, "integer", 95]
+
+ vCard:
+
+ X-KARMA-POINTS:95
+
+ The following is an example of an unrecognized vCard property
+ parameter (that uses a "FLOAT" value as its default) specified on a
+ recognized vCard property, and the equivalent jCard representation of
+ that property and property parameter.
+
+ vCard:
+
+ GENDER;X-PROBABILITY=0.8:M
+
+ jCard:
+
+ ["gender", { "x-probability": "0.8" }, "text", "M"]
+
+6. Security Considerations
+
+ This specification defines how vCard data can be "translated" between
+ two different data formats -- the original text format and JSON --
+ with a one-to-one mapping to ensure all the semantic data in one
+ format (properties, parameters, and values) are preserved in the
+ other. It does not change the semantic meaning of the underlying
+ data itself, or impose or remove any security considerations that
+ apply to the underlying data.
+
+ The use of JSON as a format does have its own inherent security risks
+ as discussed in Section 7 of [RFC4627]. Even though JSON is
+ considered a safe subset of JavaScript, it should be kept in mind
+ that a flaw in the parser for JSON data could still impose a threat
+ that doesn't arise with conventional vCard data.
+
+ With this in mind when using jCard, the parser for JSON data should
+ be aware of the security implications. For example, the use of
+ JavaScript's eval() function is only allowed using the regular
+ expression in Section 6 of [RFC4627]. A native parser with full
+ awareness of the JSON format should be preferred.
+
+
+
+Kewisch Standards Track [Page 21]
+
+RFC 7095 jCard January 2014
+
+
+ In addition, it is expected that this new format will result in vCard
+ data being more widely disseminated (e.g., with use in web
+ applications rather than just dedicated "contact managers").
+
+ In all cases, application developers have to conform to the semantics
+ of the vCard data as defined by [RFC6350] and associated extensions,
+ and all of the security considerations described in Section 9 of
+ [RFC6350], or any associated extensions, are applicable.
+
+7. IANA Considerations
+
+ This document defines a MIME media type for use with vCard in JSON
+ data. This media type SHOULD be used for the transfer of calendaring
+ data in JSON.
+
+ Type name: application
+
+ Subtype name: vcard+json
+
+ Required parameters: none
+
+ Optional parameters: "version", as defined for the text/vcard media
+ type in [RFC6350], Section 10.1.
+
+ Encoding considerations: Same as encoding considerations of
+ application/json as specified in [RFC4627], Section 6.
+
+ Security considerations: See Section 6.
+
+ Interoperability considerations: This media type provides an
+ alternative format for vCard data based on JSON.
+
+ Published specification: This specification.
+
+ Applications which use this media type: Applications that currently
+ make use of the text/vcard media type can use this as an
+ alternative. Similarly, applications that use the application/
+ json media type to transfer directory data can use this to further
+ specify the content.
+
+ Fragment identifier considerations: N/A
+
+
+
+
+
+
+
+
+
+
+Kewisch Standards Track [Page 22]
+
+RFC 7095 jCard January 2014
+
+
+ Additional information:
+
+ Deprecated alias names for this type: N/A
+
+ Magic number(s): N/A
+
+ File extension(s): N/A
+
+ Macintosh file type code(s): N/A
+
+ Person & email address to contact for further information:
+ vcarddav at ietf.org
+
+ Intended usage: COMMON
+
+ Restrictions on usage: There are no restrictions on where this media
+ type can be used.
+
+ Author: See the "Author's Address" section of this document.
+
+ Change controller: IETF
+
+7.1. GROUP vCard Parameter
+
+ IANA has added the "GROUP" parameter to the "vCard Parameters"
+ registry, initialized in Section 10.3.2 of [RFC6350]. Usage of the
+ "GROUP" parameter is further described in Section 3.3.1.2 of this
+ document.
+
+ Namespace: <empty>
+
+ Parameter name: GROUP
+
+ Purpose: To simplify the jCard format.
+
+ Description: The "GROUP" parameter is reserved for the exclusive use
+ of the jCard format described in this document. It MUST NOT be
+ used in plain vCard [RFC6350], nor in xCard [RFC6351].
+
+ Format definition: When converting from jCard to vCard, the value of
+ the "GROUP" parameter is used as part of the property name.
+ Therefore, the value is restricted to characters allowed in
+ property names, namely ALPHA, DIGIT, and "-" characters. When
+ used, the "GROUP" parameter MUST NOT be empty.
+
+
+
+
+
+
+
+Kewisch Standards Track [Page 23]
+
+RFC 7095 jCard January 2014
+
+
+ Example: As this registration serves as a reservation of the "GROUP"
+ parameter so that it is not used in vCard, there is no applicable
+ vCard example. Examples of its usage in jCard can be found in
+ this document.
+
+7.2. UNKNOWN vCard Value Data Type
+
+ IANA has added the "UNKNOWN" value data type to the "vCard Value Data
+ Types" registry, initialized in Section 10.3.3 of [RFC6350]. Usage
+ of the "UNKNOWN" type is further described in Section 5 of this
+ document.
+
+ Value name: UNKNOWN
+
+ Purpose: To allow preserving property values whose default value
+ type is not known during round-tripping between jCard and vCard.
+
+ Format definition: (Not applicable)
+
+ Description: The "UNKNOWN" value data type is reserved for the
+ exclusive use of the jCard format. It MUST NOT be used in plain
+ vCard [RFC6350].
+
+ Example: As this registration serves as a reservation of the
+ "UNKNOWN" type so that it is not used in vCard, there is no
+ applicable vCard example. Examples of its usage in jCard can be
+ found in this document.
+
+8. Acknowledgments
+
+ The author would like to thank the following for their valuable
+ contributions: Cyrus Daboo, Mike Douglass, William Gill, Erwin Rehme,
+ Dave Thewlis, Simon Perreault, Michael Angstadt, Peter Saint-Andre,
+ Bert Greevenbosch, and Javier Godoy. This specification originated
+ from the work of the XML-JSON technical committee of the Calendaring
+ and Scheduling Consortium.
+
+9. References
+
+9.1. Normative References
+
+ [ISO.8601.2000]
+ International Organization for Standardization, "Data
+ elements and interchange formats -- Information
+ interchange -- Representation of dates and times", ISO
+ 8601, December 2000.
+
+
+
+
+
+Kewisch Standards Track [Page 24]
+
+RFC 7095 jCard January 2014
+
+
+ [ISO.8601.2004]
+ International Organization for Standardization, "Data
+ elements and interchange formats -- Information
+ interchange -- Representation of dates and times", ISO
+ 8601, December 2004.
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC4627] Crockford, D., "The application/json Media Type for
+ JavaScript Object Notation (JSON)", RFC 4627, July 2006.
+
+ [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
+ Specifications: ABNF", STD 68, RFC 5234, January 2008.
+
+ [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying
+ Languages", BCP 47, RFC 5646, September 2009.
+
+ [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350,
+ August 2011.
+
+ [RFC6868] Daboo, C., "Parameter Value Encoding in iCalendar and
+ vCard", RFC 6868, February 2013.
+
+9.2. Informative References
+
+ [JCAL] Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON
+ format for iCalendar", Work in Progress, December 2013.
+
+ [RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling
+ Core Object Specification (iCalendar)", RFC 5545,
+ September 2009.
+
+ [RFC6321] Daboo, C., Douglass, M., and S. Lees, "xCal: The XML
+ Format for iCalendar", RFC 6321, August 2011.
+
+ [RFC6351] Perreault, S., "xCard: vCard XML Representation", RFC
+ 6351, August 2011.
+
+ [calconnect-artifacts]
+ The Calendaring and Scheduling Consortium, "Code Artifacts
+ and Schemas", <http://www.calconnect.org/artifacts.shtml>.
+
+
+
+
+
+
+
+
+
+Kewisch Standards Track [Page 25]
+
+RFC 7095 jCard January 2014
+
+
+Appendix A. ABNF Syntax
+
+ Below is the ABNF syntax as per [RFC5234] for vCard in JSON. ABNF
+ symbols not described here are taken from [RFC4627]. The syntax is
+ non-normative and given for reference only.
+
+ The numeric section numbers given in the comments refer to sections
+ in [RFC6350]. Additional semantic restrictions apply, especially
+ regarding the allowed properties and subcomponents per component.
+ Details on these restrictions can be found in this document and
+ [RFC6350].
+
+ Additional ABNF syntax may be available on the Internet at
+ [calconnect-artifacts].
+
+ ; A jCard object uses the name "vcard" and a properties array.
+ ; Restrictions to which properties may be specified are to
+ ; be taken from RFC 6350.
+ jcardobject = begin-array
+ DQUOTE component-name DQUOTE value-separator
+ properties-array
+ end-array
+
+ ; A jCard property consists of the name string, parameters object,
+ ; type string, and one or more values as specified in this document.
+ property = begin-array
+ DQUOTE property-name DQUOTE value-separator
+ params-object value-separator
+ DQUOTE type-name DQUOTE
+ property-value *(value-separator property-value)
+ end-array
+ properties-array = begin-array
+ [ property *(value-separator property) ]
+ end-array
+
+ ; Property values depend on the type-name. Aside from the value types
+ ; mentioned here, extensions may make use of other JSON value types.
+ property-value = simple-prop-value / structured-prop-value
+ simple-prop-value = string / number / true / false
+ structured-prop-value =
+ begin-array
+ [ structured-element *(value-separator structured-element) ]
+ end-array
+
+ ; Each structured element may have multiple values if
+ ; semantically allowed.
+ structured-element = simple-prop-value / structured-multi-prop
+
+
+
+
+Kewisch Standards Track [Page 26]
+
+RFC 7095 jCard January 2014
+
+
+ structured-multi-prop =
+ begin-array
+ [ simple-prop-value *(value-separator simple-prop-value) ]
+ end-array
+
+ ; The jCard params-object is a JSON object that follows the semantic
+ ; guidelines described in this document.
+ params-object = begin-object
+ [ params-member *(value-separator params-member) ]
+ end-object
+ params-member = DQUOTE param-name DQUOTE name-separator param-value
+ param-value = string / param-multi
+ param-multi = begin-array
+ [ string *(value-separator string) ]
+ end-array
+
+ ; The type MUST be a valid type as described by this document. New
+ ; value types can be added by extensions.
+ type-name = "text" / "uri" / "date" / "time" / "date-time" /
+ "boolean" / "integer" / "float" / "utc-offset" /
+ "language-tag" / x-type
+
+ ; Property, parameter, and type names MUST be lowercase. Additional
+ ; semantic restrictions apply as described by this document and
+ ; RFC 6350.
+ component-name = lowercase-name
+ property-name = lowercase-name
+ param-name = lowercase-name
+ x-type = lowercase-name
+ lowercase-name = 1*(%x61-7A / DIGIT / "-")
+
+Appendix B. Examples
+
+ This section contains an example of a vCard object with its jCard
+ representation.
+
+B.1. Example: vCard of the Author of RFC 6350
+
+B.1.1. vCard Data
+
+ BEGIN:VCARD
+ VERSION:4.0
+ FN:Simon Perreault
+ N:Perreault;Simon;;;ing. jr,M.Sc.
+ BDAY:--0203
+ ANNIVERSARY:20090808T1430-0500
+ GENDER:M
+ LANG;PREF=1:fr
+
+
+
+Kewisch Standards Track [Page 27]
+
+RFC 7095 jCard January 2014
+
+
+ LANG;PREF=2:en
+ ORG;TYPE=work:Viagenie
+ ADR;TYPE=work:;Suite D2-630;2875 Laurier;
+ Quebec;QC;G1V 2M2;Canada
+ TEL;VALUE=uri;TYPE="work,voice";PREF=1:tel:+1-418-656-9254;ext=102
+ TEL;VALUE=uri;TYPE="work,cell,voice,video,text":tel:+1-418-262-6501
+ EMAIL;TYPE=work:simon.perreault at viagenie.ca
+ GEO;TYPE=work:geo:46.772673,-71.282945
+ KEY;TYPE=work;VALUE=uri:
+ http://www.viagenie.ca/simon.perreault/simon.asc
+ TZ:-0500
+ URL;TYPE=home:http://nomis80.org
+ END:VCARD
+
+B.1.2. jCard Data
+
+ ["vcard",
+ [
+ ["version", {}, "text", "4.0"],
+ ["fn", {}, "text", "Simon Perreault"],
+ ["n",
+ {},
+ "text",
+ ["Perreault", "Simon", "", "", ["ing. jr", "M.Sc."]]
+ ],
+ ["bday", {}, "date-and-or-time", "--02-03"],
+ ["anniversary",
+ {},
+ "date-and-or-time",
+ "2009-08-08T14:30:00-05:00"
+ ],
+ ["gender", {}, "text", "M"],
+ ["lang", { "pref": "1" }, "language-tag", "fr"],
+ ["lang", { "pref": "2" }, "language-tag", "en"],
+ ["org", { "type": "work" }, "text", "Viagenie"],
+ ["adr",
+ { "type": "work" },
+ "text",
+ [
+ "",
+ "Suite D2-630",
+ "2875 Laurier",
+ "Quebec",
+ "QC",
+ "G1V 2M2",
+ "Canada"
+ ]
+ ],
+
+
+
+Kewisch Standards Track [Page 28]
+
+RFC 7095 jCard January 2014
+
+
+ ["tel",
+ { "type": ["work", "voice"], "pref": "1" },
+ "uri",
+ "tel:+1-418-656-9254;ext=102"
+ ],
+ ["tel",
+ { "type": ["work", "cell", "voice", "video", "text"] },
+ "uri",
+ "tel:+1-418-262-6501"
+ ],
+ ["email",
+ { "type": "work" },
+ "text",
+ "simon.perreault at viagenie.ca"
+ ],
+ ["geo", { "type": "work" }, "uri", "geo:46.772673,-71.282945"],
+ ["key",
+ { "type": "work" },
+ "uri",
+ "http://www.viagenie.ca/simon.perreault/simon.asc"
+ ],
+ ["tz", {}, "utc-offset", "-05:00"],
+ ["url", { "type": "home" }, "uri", "http://nomis80.org"]
+ ]
+ ]
+
+Author's Address
+
+ Philipp Kewisch
+ Mozilla Corporation
+ 650 Castro Street, Suite 300
+ Mountain View, CA 94041
+ USA
+
+ EMail: mozilla at kewis.ch
+ URI: http://www.mozilla.org/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Kewisch Standards Track [Page 29]
+
Added: CalendarServer/trunk/doc/RFC/RFC7265-jcal.txt
===================================================================
--- CalendarServer/trunk/doc/RFC/RFC7265-jcal.txt (rev 0)
+++ CalendarServer/trunk/doc/RFC/RFC7265-jcal.txt 2015-05-27 14:45:30 UTC (rev 14834)
@@ -0,0 +1,1739 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) P. Kewisch
+Request for Comments: 7265 Mozilla
+Category: Standards Track C. Daboo
+ISSN: 2070-1721 Apple, Inc.
+ M. Douglass
+ RPI
+ May 2014
+
+
+ jCal: The JSON Format for iCalendar
+
+Abstract
+
+ This specification defines "jCal", a JSON format for iCalendar data.
+ The iCalendar data format is a text format for capturing and
+ exchanging information normally stored within a calendaring and
+ scheduling application, for example, tasks and events. JSON is a
+ lightweight, text-based, language-independent data interchange format
+ commonly used in Internet applications.
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 5741.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ http://www.rfc-editor.org/info/rfc7265.
+
+Copyright Notice
+
+ Copyright (c) 2014 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
+ (http://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.
+
+
+
+Kewisch, et al. Standards Track [Page 1]
+
+RFC 7265 jCal May 2014
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 2. Conventions Used in This Document . . . . . . . . . . . . . . 4
+ 3. Converting from iCalendar to jCal . . . . . . . . . . . . . . 4
+ 3.1. Pre-processing . . . . . . . . . . . . . . . . . . . . . 4
+ 3.2. iCalendar Stream and Objects (RFC 5545, Section 3.4) . . 5
+ 3.3. Components (RFC 5545, Section 3.6) . . . . . . . . . . . 6
+ 3.4. Properties (RFC 5545, Sections 3.7 and 3.8) . . . . . . . 6
+ 3.4.1. Special Cases for Properties . . . . . . . . . . . . 8
+ 3.4.1.1. GEO Property (RFC 5545, Section 3.8.1.6) . . . . 8
+ 3.4.1.2. REQUEST-STATUS Property (RFC 5545, Section
+ 3.8.8.3) . . . . . . . . . . . . . . . . . . . . 8
+ 3.5. Parameters (RFC 5545, Section 3.2) . . . . . . . . . . . 9
+ 3.5.1. VALUE Parameter . . . . . . . . . . . . . . . . . . . 10
+ 3.5.2. Multi-value Parameters . . . . . . . . . . . . . . . 11
+ 3.6. Values (RFC 5545, Section 3.3) . . . . . . . . . . . . . 11
+ 3.6.1. Binary (RFC 5545, Section 3.3.1) . . . . . . . . . . 12
+ 3.6.2. Boolean (RFC 5545, Section 3.3.2) . . . . . . . . . 12
+ 3.6.3. Calendar User Address (RFC 5545, Section 3.3.3) . . . 12
+ 3.6.4. Date (RFC 5545, Section 3.3.4) . . . . . . . . . . . 12
+ 3.6.5. Date-Time (RFC 5545, Section 3.3.5) . . . . . . . . . 13
+ 3.6.6. Duration (RFC 5545, Section 3.3.6) . . . . . . . . . 13
+ 3.6.7. Float (RFC 5545, Section 3.3.7) . . . . . . . . . . . 14
+ 3.6.8. Integer (RFC 5545, Section 3.3.8) . . . . . . . . . . 14
+ 3.6.9. Period of Time (RFC 5545, Section 3.3.9) . . . . . . 14
+ 3.6.10. Recurrence Rule (RFC 5545, Section 3.3.10) . . . . . 15
+ 3.6.11. Text (RFC 5545, Section 3.3.11) . . . . . . . . . . . 16
+ 3.6.12. Time (RFC 5545, Section 3.3.12) . . . . . . . . . . . 16
+ 3.6.13. URI (RFC 5545, Section 3.3.13) . . . . . . . . . . . 17
+ 3.6.14. UTC Offset (RFC 5545, Section 3.3.14) . . . . . . . . 17
+ 3.7. Extensions . . . . . . . . . . . . . . . . . . . . . . . 17
+ 4. Converting from jCal into iCalendar . . . . . . . . . . . . . 17
+ 5. Handling Unrecognized Properties or Parameters . . . . . . . 18
+ 5.1. Converting iCalendar into jCal . . . . . . . . . . . . . 18
+ 5.2. Converting jCal into iCalendar . . . . . . . . . . . . . 19
+ 5.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 19
+ 6. Security Considerations . . . . . . . . . . . . . . . . . . . 20
+ 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21
+ 7.1. UNKNOWN iCalendar Value Data Type . . . . . . . . . . . . 22
+ 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 23
+ 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 23
+ 9.1. Normative References . . . . . . . . . . . . . . . . . . 23
+ 9.2. Informative References . . . . . . . . . . . . . . . . . 24
+
+
+
+
+
+
+
+Kewisch, et al. Standards Track [Page 2]
+
+RFC 7265 jCal May 2014
+
+
+ Appendix A. ABNF Schema . . . . . . . . . . . . . . . . . . . . 25
+ Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 27
+ B.1. Example 1 . . . . . . . . . . . . . . . . . . . . . . . . 27
+ B.1.1. iCalendar Data . . . . . . . . . . . . . . . . . . . 27
+ B.1.2. jCal Data . . . . . . . . . . . . . . . . . . . . . . 27
+ B.2. Example 2 . . . . . . . . . . . . . . . . . . . . . . . . 28
+ B.2.1. iCalendar Data . . . . . . . . . . . . . . . . . . . 28
+ B.2.2. jCal Data . . . . . . . . . . . . . . . . . . . . . . 29
+
+1. Introduction
+
+ The iCalendar data format [RFC5545] is a widely deployed interchange
+ format for calendaring and scheduling data. While many applications
+ and services consume and generate calendar data, iCalendar is a
+ specialized format that requires its own parser/generator. In
+ contrast, JSON-based formats as defined in [RFC7159] are the native
+ format for JavaScript widgets and libraries, and it is appropriate to
+ have a standard form of calendar data that is easier to work with
+ than iCalendar.
+
+ The purpose of this specification is to define "jCal", a JSON format
+ for iCalendar data. jCal is defined as a straightforward mapping into
+ JSON from iCalendar, so that iCalendar data can be converted to JSON,
+ and then back to iCalendar, without losing any semantic meaning in
+ the data. Anyone creating jCal calendar data according to this
+ specification will know that their data can be converted to a valid
+ iCalendar representation as well.
+
+ The key design considerations are essentially the same as those for
+ [RFC6321], that is:
+
+ Round-tripping (converting an iCalendar instance to jCal and back)
+ will give the same semantic result as the starting point. For
+ example, all components, properties, and property parameters are
+ guaranteed to be preserved.
+
+ Ordering of elements and case of property and parameter names will
+ not necessarily be preserved.
+
+ The iCalendar data semantics are to be preserved, allowing a
+ simple consumer to easily browse the data in jCal. A full
+ understanding of iCalendar is still required in order to modify
+ and/or fully comprehend the calendar data.
+
+ Extensions to the underlying iCalendar specification must not lead
+ to requiring an update to jCal.
+
+
+
+
+
+Kewisch, et al. Standards Track [Page 3]
+
+RFC 7265 jCal May 2014
+
+
+2. Conventions Used in This Document
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in [RFC2119]. The
+ underlying format used for jCal is JSON. Consequently, the terms
+ "object" and "array" as well as the four primitive types (strings,
+ numbers, booleans, and null) are to be interpreted as described in
+ Section 1 of [RFC7159].
+
+ Some examples in this document contain "partial" JSON documents used
+ for illustrative purposes. In these examples, three periods "..."
+ are used to indicate a portion of the document that has been removed
+ for compactness.
+
+3. Converting from iCalendar to jCal
+
+ This section describes how iCalendar data is converted to jCal using
+ a simple mapping between the iCalendar data model and JSON elements.
+ Aside from the formal description in this section, an informative
+ ABNF is specified in Appendix A.
+
+ In [RFC5545], an iCalendar object comprises a set of "components",
+ "properties", "parameters", and "values". The top level of iCalendar
+ data typically contains a stream of iCalendar objects, each of which
+ can be considered a "component". A "component" can contain other
+ "components" or "properties". A "property" has a "value" and a set
+ of zero or more "parameters". Each of these entities have a
+ representation in jCal, defined in the following sections. The
+ representation of an iCalendar object in JSON will be named "jCal
+ object" throughout this document.
+
+3.1. Pre-processing
+
+ iCalendar uses a line-folding mechanism to limit lines of data to a
+ maximum line length (typically 75 octets) to ensure the maximum
+ likelihood of preserving data integrity as it is transported via
+ various means (e.g., email) -- see Section 3.1 of [RFC5545].
+
+ iCalendar data uses an "escape" character sequence for text values
+ and property parameter values. See Sections 3.1 and 3.3 of [RFC5545]
+ as well as [RFC6868].
+
+ There is a subtle difference in the number representations between
+ JSON and iCalendar. While in iCalendar, a number may have leading
+ zeros, as well as a leading plus sign; this is not the case in JSON.
+ Numbers should be represented in whatever way needed for the
+ underlying format.
+
+
+
+Kewisch, et al. Standards Track [Page 4]
+
+RFC 7265 jCal May 2014
+
+
+ When converting from iCalendar to jCal: First, iCalendar lines MUST
+ be unfolded. Afterwards, any iCalendar escaping MUST be unescaped.
+ Finally, JSON escaping, as described in Section 7 of [RFC7159], MUST
+ be applied. The reverse order applies when converting from jCal to
+ iCalendar, which is further described in Section 4.
+
+ iCalendar uses a base64 encoding for binary data. However, it does
+ not restrict the encoding from being applied to non-binary value
+ types. So, the following rules are applied when processing a
+ property with the "ENCODING" property parameter set to "BASE64":
+
+ o If the property value type is "BINARY", the base64 encoding MUST
+ be preserved.
+
+ o If the value type is not "BINARY", the "ENCODING" property
+ parameter MUST be removed, and the value MUST be base64 decoded.
+
+ When base64 encoding is used, it MUST conform to Section 4 of
+ [RFC4648], which is the base64 method used in [RFC5545].
+
+ One key difference in the formatting of values used in iCalendar and
+ jCal is that in jCal, the specification uses date/time values aligned
+ with the extended format of [ISO.8601.2004], which is more commonly
+ used in Internet applications that make use of the JSON format. The
+ sections of this document describing the various date and time
+ formats contain more information on the use of the complete
+ representation, reduced accuracy, or truncated representation.
+
+3.2. iCalendar Stream and Objects (RFC 5545, Section 3.4)
+
+ At the top level of the iCalendar object model is an "iCalendar
+ stream". This stream encompasses multiple "iCalendar objects". As
+ the typical use case is transporting a single iCalendar object, there
+ is no defined equivalent to an "iCalendar stream" in jCal. To
+ transport multiple jCal objects in a stream, a simple JSON array can
+ be used.
+
+ Example:
+
+ ["vcalendar",
+ [ /* Add jCal properties in place of this comment */ ],
+ [ /* Add jCal components in place of this comment */ ]
+ ]
+
+
+
+
+
+
+
+
+Kewisch, et al. Standards Track [Page 5]
+
+RFC 7265 jCal May 2014
+
+
+3.3. Components (RFC 5545, Section 3.6)
+
+ Each iCalendar component, delimited by "BEGIN" and "END", will be
+ converted to a fixed-length array with three fields that have a
+ specific structure:
+
+ 1. A string with the name of the iCalendar component, but in
+ lowercase.
+
+ 2. An array of jCal properties as described in Section 3.4.
+
+ 3. An array of jCal components, representing the sub-components of
+ the component in question.
+
+ This mapping applies to the top level iCalendar objects, as well as
+ individual sub-components in the same way. The iCalendar to jCal
+ component mapping is valid for both current iCalendar components and
+ any new iCalendar components added in the future. Conversion is to
+ be done in the same way.
+
+ While the grouping of properties and sub-components does not retain
+ the original order specified in the iCalendar data, the semantics of
+ a component are preserved.
+
+ Example:
+
+ ["vevent",
+ [ /* Add jCal properties in place of this comment */ ],
+ [ /* Add jCal components in place of this comment */ ]
+ ]
+
+3.4. Properties (RFC 5545, Sections 3.7 and 3.8)
+
+ iCalendar properties, whether they apply to the "VCALENDAR" object or
+ to a component, are handled in a consistent way in the jCal format.
+
+ In jCal, each individual iCalendar property MUST be represented by an
+ array with three fixed elements, followed by one or more additional
+ elements, depending on if the property is a multi-valued property as
+ described in Section 3.1.2 of [RFC5545].
+
+
+
+
+
+
+
+
+
+
+
+Kewisch, et al. Standards Track [Page 6]
+
+RFC 7265 jCal May 2014
+
+
+ The array consists of the following fixed elements:
+
+ 1. The name of the property, as a lowercase string. The iCalendar
+ format specifies that property names are case insensitive and
+ recommends that they be rendered in uppercase. In jCal, they
+ MUST be in lowercase.
+
+ 2. An object containing the parameters as described in Section 3.5.
+ If the property has no parameters, an empty object is used to
+ represent that.
+
+ 3. The type identifier string of the value, in lowercase. Due to
+ special casing of certain properties as described in
+ Section 3.4.1, it is important that parsers check both the type
+ identifier and the value data type and do not rely on assumptions
+ based on the property name.
+
+ The remaining elements of the array are used for one or more values
+ of the property. For single-valued properties, the array has exactly
+ four elements; for multi-valued properties, as described in
+ Section 3.1.2 of [RFC5545], each value is another element, and there
+ can be any number of additional elements.
+
+ In the following example, the "categories" property is multi-valued
+ and has two values, while the summary property is single-valued:
+
+ Example:
+
+ ["vevent",
+ [
+ ["summary", {}, "text", "Meeting with Fred"],
+ ["categories", {}, "text", "Meetings", "Work"]
+ ...
+ ],
+ [ /* sub-components */ ]
+ ]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Kewisch, et al. Standards Track [Page 7]
+
+RFC 7265 jCal May 2014
+
+
+3.4.1. Special Cases for Properties
+
+ This section describes some properties that have special handling
+ when converting to jCal.
+
+3.4.1.1. GEO Property (RFC 5545, Section 3.8.1.6)
+
+ In iCalendar, the "GEO" property value is defined as a semicolon-
+ separated list of two "FLOAT" values, the first representing latitude
+ and the second longitude.
+
+ In jCal, the value for the "geo" property value is represented as an
+ array of two values. The first value of the property represents the
+ latitude; the second value represents the longitude.
+
+ When converting from jCal to iCalendar, be careful to use a semicolon
+ as the separator between the two values as required by [RFC5545].
+
+ When converting from jCal to iCalendar, the two values MUST be
+ converted using a semicolon as the separator character.
+
+ Example
+
+ ["vevent",
+ [
+ ["geo", {}, "float", [ 37.386013, -122.082932 ] ]
+ ...
+ ],
+ ...
+ ]
+
+3.4.1.2. REQUEST-STATUS Property (RFC 5545, Section 3.8.8.3)
+
+ In iCalendar, the "REQUEST-STATUS" property value is defined as a
+ semicolon-separated list of two or three "TEXT" values. The first
+ represents a code, the second a description, and the third any
+ additional data.
+
+ In jCal, the value for the "request-status" property value is
+ represented as an array with two or three values. The first array
+ element corresponds to the code, the second element corresponds to
+ the description, and the third element corresponds to the additional
+ data. Each value is represented using a string value. If there is
+ no additional data in the iCalendar value, the last element of the
+ array SHOULD NOT be present.
+
+ When converting from jCal to iCalendar, the two or three values MUST
+ be converted using a semicolon as the separator character.
+
+
+
+Kewisch, et al. Standards Track [Page 8]
+
+RFC 7265 jCal May 2014
+
+
+ iCalendar Example:
+
+ BEGIN:VEVENT
+ ...
+ REQUEST-STATUS:2.0;Success
+ REQUEST-STATUS:3.7;Invalid calendar user;ATTENDEE:
+ mailto:jsmith at example.com
+ ...
+ END:VEVENT
+
+ jCal Example:
+
+ ["vevent":
+ [
+ ["request-status", {}, "text", ["2.0", "Success"] ],
+ ["request-status", {}, "text",
+ [
+ "3.7",
+ "Invalid calendar user",
+ "ATTENDEE:mailto:jsmith at example.org"
+ ]
+ ],
+ ...
+ ],
+ ...
+ ]
+
+3.5. Parameters (RFC 5545, Section 3.2)
+
+ Property parameters are represented as a JSON object where each key-
+ value pair represents the iCalendar parameter name and its value.
+ The name of the parameter MUST be in lowercase; the original case of
+ the parameter value MUST be preserved. For example, the "PARTSTAT"
+ property parameter is represented in jCal by the "partstat" key. Any
+ new iCalendar parameters added in the future will be converted in the
+ same way.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Kewisch, et al. Standards Track [Page 9]
+
+RFC 7265 jCal May 2014
+
+
+ Example:
+
+ ["vevent":
+ [
+ ["attendee",
+ {
+ "partstat": "ACCEPTED",
+ "rsvp": "TRUE",
+ "role": "REQ-PARTICIPANT"
+ },
+ "cal-address",
+ "mailto:jsmith at example.org"
+ ],
+ ["summary", {}, "text", "Meeting"],
+ ...
+ ],
+ ...
+ ]
+
+3.5.1. VALUE Parameter
+
+ iCalendar defines a "VALUE" property parameter (Section 3.2.20 of
+ [RFC5545]). This property parameter MUST NOT be added to the
+ parameters object. Instead, the value type is signaled through the
+ type identifier in the third element of the array describing the
+ property. When converting a property from iCalendar to jCal, the
+ value type is determined as follows:
+
+ 1. If the property has a "VALUE" parameter, that parameter's value
+ is used as the value type.
+
+ 2. If the property has no "VALUE" parameter but has a default value
+ type, the default value type is used.
+
+ 3. If the property has no "VALUE" parameter and has no default value
+ type, "unknown" is used.
+
+ Converting from jCal into iCalendar is done as follows:
+
+ 1. If the property's value type is "unknown", no "VALUE" parameter
+ is included.
+
+ 2. If the property's value type is the default type for that
+ property, no "VALUE" parameter is included.
+
+ 3. Otherwise, a "VALUE" parameter is included, and the value type is
+ used as the parameter value.
+
+
+
+
+Kewisch, et al. Standards Track [Page 10]
+
+RFC 7265 jCal May 2014
+
+
+ See Section 5 for information on handling unknown value types.
+
+3.5.2. Multi-value Parameters
+
+ In [RFC5545], some parameters allow using a COMMA-separated list of
+ values. To ease processing in jCal, the value of such parameters
+ MUST be represented in an array containing the separated values. The
+ array elements MUST be string values. Single-value parameters can be
+ represented using either a single string value or an array with one
+ string element. A jCal parser MUST be able to understand both value
+ data types. Examples of such parameters are the iCalendar
+ "DELEGATED-FROM" and "DELEGATED-TO" parameters; more such parameters
+ may be added in extensions.
+
+ The iCalendar specification requires encapsulation between DQUOTE
+ characters if a parameter value contains a colon, a semicolon, or a
+ comma. These extra DQUOTE characters do not belong to the actual
+ parameter value, and hence are not included when the parameter is
+ converted to jCal.
+
+ Example 1:
+
+ ["attendee",
+ {
+ "delegated-to": ["mailto:jdoe at example.org",
+ "mailto:jqpublic at example.org"]
+ },
+ "cal-address",
+ "mailto:jsmith at example.org"
+ ]
+
+ Example 2:
+
+ ["attendee",
+ {
+ "delegated-to": "mailto:jdoe at example.org"
+ },
+ "cal-address",
+ "mailto:jsmith at example.org"
+ ]
+
+3.6. Values (RFC 5545, Section 3.3)
+
+ The following subsections specify how iCalendar property value data
+ types, which are defined in the subsections of [RFC5545],
+ Section 3.3, are represented in jCal.
+
+
+
+
+
+Kewisch, et al. Standards Track [Page 11]
+
+RFC 7265 jCal May 2014
+
+
+3.6.1. Binary (RFC 5545, Section 3.3.1)
+
+ Description: iCalendar "BINARY" property values are represented by a
+ property with the type identifier "binary". The value element is
+ a JSON string, encoded with base64 encoding as specified in
+ Section 4 of [RFC4648].
+
+ Example:
+
+ ["attach", {}, "binary", "SGVsbG8gV29ybGQh"]
+
+3.6.2. Boolean (RFC 5545, Section 3.3.2)
+
+ Description: iCalendar "BOOLEAN" property values are represented by
+ a property with the type identifier "boolean". The value is a
+ JSON boolean value.
+
+ Example:
+
+ ["x-non-smoking", {}, "boolean", true]
+
+3.6.3. Calendar User Address (RFC 5545, Section 3.3.3)
+
+ Description: iCalendar "CAL-ADDRESS" property values are represented
+ by a property with the type identifier "cal-address". The value
+ is a JSON string with the URI as described in [RFC3986].
+
+ Example:
+
+ ["attendee", {}, "cal-address", "mailto:kewisch at example.com"]
+
+3.6.4. Date (RFC 5545, Section 3.3.4)
+
+ Description: iCalendar "DATE" property values are represented by a
+ property with the type identifier "date". The value elements are
+ JSON strings with the same date value specified by [RFC5545], but
+ represented using the extended format of the complete
+ representation specified in [ISO.8601.2004], Section 4.1.2.2.
+ Other variations, for example, representation with reduced
+ accuracy, MUST NOT be used.
+
+ ABNF Schema:
+
+ ; year, month, and day rules are
+ ; defined in [ISO.8601.2004], Section 2.2.
+ date = year "-" month "-" day ;YYYY-MM-DD
+
+
+
+
+
+Kewisch, et al. Standards Track [Page 12]
+
+RFC 7265 jCal May 2014
+
+
+ Example:
+
+ ["dtstart", {}, "date", "2011-05-17"]
+
+3.6.5. Date-Time (RFC 5545, Section 3.3.5)
+
+ Description: iCalendar "DATE-TIME" property values are represented
+ by a property with the type identifier "date-time". The value
+ elements are JSON strings with the same date value specified by
+ [RFC5545], but represented using the extended format of the
+ complete representation specified in [ISO.8601.2004],
+ Section 4.3.2. Other variations, for example, representation with
+ reduced accuracy, MUST NOT be used. The same restrictions apply
+ with respect to leap seconds and time zone offsets as specified in
+ [RFC5545], Section 3.3.5.
+
+ ABNF Schema:
+
+ ; year, month, day, hour, minute, and second rules are
+ ; defined in [ISO.8601.2004], Section 2.2.
+ ; The zone identifier is described in [ISO.8601.2004], Section 4.3.2.
+ date-complete = year "-" month "-" day ;YYYY-MM-DD
+ time-complete = hour ":" minute ":" second [zone] ; HH:MM:SS
+ datetime = date-complete "T" time-complete
+
+ Examples:
+
+ ["dtstart", {}, "date-time", "2012-10-17T12:00:00"],
+ ["dtstamp", {}, "date-time", "2012-10-17T12:00:00Z"],
+ ["dtend",
+ { "tzid": "Europe/Berlin" },
+ "date-time",
+ "2011-10-17T13:00:00"
+ ]
+
+3.6.6. Duration (RFC 5545, Section 3.3.6)
+
+ Description: iCalendar "DURATION" property values are represented by
+ a property with the type identifier "duration". The value
+ elements are JSON strings with the same duration value specified
+ by [RFC5545].
+
+ Example:
+
+ ["duration", {}, "duration", "P1D"]
+
+
+
+
+
+
+Kewisch, et al. Standards Track [Page 13]
+
+RFC 7265 jCal May 2014
+
+
+3.6.7. Float (RFC 5545, Section 3.3.7)
+
+ Description: iCalendar "FLOAT" property values are represented by a
+ property with the type identifier "float". The value elements are
+ JSON primitive number values.
+
+ Example:
+
+ ["x-grade", {}, "float", 1.3]
+
+3.6.8. Integer (RFC 5545, Section 3.3.8)
+
+ Description: vCard "INTEGER" property values are represented by a
+ property with the type identifier "integer". The value elements
+ are JSON primitive number values that MUST resolve to an integer
+ value in the range specified in [RFC5545], Section 3.3.8. Thus, a
+ fractional and/or exponential part are only allowed under limited
+ circumstances.
+
+ Examples:
+
+ ["percent-complete", {}, "integer", 42]
+
+3.6.9. Period of Time (RFC 5545, Section 3.3.9)
+
+ Description: iCalendar "PERIOD" property values are represented by a
+ jCal property with the type identifier "period". The value
+ element is an array of JSON strings, with the first element
+ representing the start of the period and the second element
+ representing the end of the period. As in [RFC5545], the start of
+ the period is always formatted as a date-time value, and the end
+ of the period MUST be either a date-time or duration value. Any
+ date, date-time, or duration values contained in the period value
+ MUST be formatted in accordance to the rules for date, date-time,
+ or duration values specified in this document.
+
+ Example:
+
+ ["freebusy",
+ { "fbtype": "FREE" },
+ "period",
+ ["1997-03-08T16:00:00Z", "P1D"]
+ ]
+
+
+
+
+
+
+
+
+Kewisch, et al. Standards Track [Page 14]
+
+RFC 7265 jCal May 2014
+
+
+3.6.10. Recurrence Rule (RFC 5545, Section 3.3.10)
+
+ Description: iCalendar "RECUR" property values are represented by a
+ property with the type identifier "recur". The value elements are
+ objects describing the structured data as specified by [RFC5545].
+ Each rule part is described by the combination of key and value.
+ The key specifies the name of the rule part and MUST be converted
+ to lowercase. The value of the rule part MUST be mapped by the
+ following rules:
+
+ * The value of the "freq" and "wkst" rule parts MUST be a string
+ as specified in [RFC5545], with case preserved.
+
+ * The value of the "until" rule part MUST be a date or date-time
+ value formatted in accordance to the rules for date or date-
+ time specified in this document.
+
+ * The "count" and "interval" rule parts MUST be specified as a
+ single JSON number value.
+
+ * The following rule parts can have one or more numeric values:
+ "bysecond", "byminute", "byhour", "bymonthday", "byyearday",
+ "byweekno", "bymonth", and "bysetpos". If a rule part contains
+ multiple values, an array of numbers MUST be used for that rule
+ part. Single-valued rule parts can be represented by either
+ using a single number value, omitting the array completely, or
+ using an array with one number element. A jCal parser MUST be
+ able to understand both data types.
+
+ * Similarly, the "byday" rule part can have one or more string
+ values. If it contains multiple values, an array of strings
+ MUST be used. As before, a single-valued rule part can be
+ represented using either a single string value or an array with
+ one string element, both of which a jCal parser MUST be able to
+ understand.
+
+ Example 1:
+
+ ["rrule",
+ {},
+ "recur",
+ {
+ "freq": "YEARLY",
+ "count": 5,
+ "byday": [ "-1SU", "2MO" ],
+ "bymonth": 10
+ }
+ ]
+
+
+
+Kewisch, et al. Standards Track [Page 15]
+
+RFC 7265 jCal May 2014
+
+
+ Example 2:
+
+ ["rrule",
+ {},
+ "recur",
+ {
+ "freq": "MONTHLY",
+ "interval": 2,
+ "bymonthday": [ 1, 15, -1 ],
+ "until": "2013-10-01"
+ }
+ ]
+
+3.6.11. Text (RFC 5545, Section 3.3.11)
+
+ Description: iCalendar "TEXT" property values are represented by a
+ property with the type identifier "text". The value elements are
+ JSON strings.
+
+ Example:
+
+ ["comment", {}, "text", "hello, world"]
+
+3.6.12. Time (RFC 5545, Section 3.3.12)
+
+ Description: iCalendar "TIME" property values are represented by a
+ property with the type identifier "time". The value elements are
+ JSON strings with the same time value specified by [RFC5545], but
+ represented using the extended format of the complete
+ representation specified in [ISO.8601.2004], Section 4.2.2.2.
+ Other variations, for example, representation with reduced
+ accuracy, MUST NOT be used. The same restrictions apply with
+ respect to leap seconds, time fractions, and time zone offsets as
+ specified in [RFC5545], Section 3.3.12.
+
+ ABNF Schema:
+
+ ; hour, minute, and second rules are
+ ; defined in [ISO.8601.2004], Section 2.2.
+ ; The zone identifier is described in [ISO.8601.2004], Section 4.3.2.
+ time-complete = hour ":" minute ":" second [zone] ; HH:MM:SS
+
+ Example:
+
+ ["x-time-local", {}, "time", "12:30:00"],
+ ["x-time-utc", {}, "time", "12:30:00Z"],
+ ["x-time-offset", { "tzid": "Europe/Berlin" }, "time", "12:30:00"]
+
+
+
+
+Kewisch, et al. Standards Track [Page 16]
+
+RFC 7265 jCal May 2014
+
+
+3.6.13. URI (RFC 5545, Section 3.3.13)
+
+ Description: iCalendar "URI" property values are represented by a
+ property with the type identifier "uri". The value elements are
+ JSON strings representing the URI.
+
+ Example:
+
+ ["tzurl", {}, "uri", "http://example.org/tz/Europe-Berlin.ics"]
+
+3.6.14. UTC Offset (RFC 5545, Section 3.3.14)
+
+ Description: iCalendar "UTC-OFFSET" property values are represented
+ by a property with the type identifier "utc-offset". The value
+ elements are JSON strings with the same UTC offset value specified
+ by [RFC5545], with the exception that the hour and minute
+ components are separated by a ":" character, for consistency with
+ the [ISO.8601.2004] time zone offset, extended format.
+
+ Example:
+
+ ["tzoffsetfrom", {}, "utc-offset", "-05:00"],
+ ["tzoffsetto", {}, "utc-offset", "+12:45"]
+
+3.7. Extensions
+
+ iCalendar extension properties and property parameters (those with an
+ "X-" prefix in their name) are handled in the same way as other
+ properties and property parameters: the property is represented by an
+ array, and the property parameter is represented by an object. The
+ property or parameter name uses the same name as for the iCalendar
+ extension, but in lowercase. For example, the "X-FOO" property in
+ iCalendar turns into the "x-foo" jCal property. See Section 5 for
+ how to deal with default values for unrecognized extension properties
+ or property parameters.
+
+4. Converting from jCal into iCalendar
+
+ Converting jCal to iCalendar reverses the process described in
+ Section 3. This section describes a few additional requirements for
+ conversion.
+
+ When converting component, property, and property parameter names,
+ the names SHOULD be converted to uppercase. Although iCalendar names
+ are case insensitive, common practice is to keep them all uppercase
+ following the actual definitions in [RFC5545].
+
+
+
+
+
+Kewisch, et al. Standards Track [Page 17]
+
+RFC 7265 jCal May 2014
+
+
+ During conversion, JSON escaping MUST be unescaped. Afterwards,
+ iCalendar escaping, as defined by [RFC5545] and [RFC6868], MUST be
+ applied. Finally, long lines SHOULD be folded as described in
+ [RFC5545], Section 3.1.
+
+ Non-binary value types MUST NOT be base64 encoded.
+
+ When converting to iCalendar, the VALUE parameter MUST be added to
+ properties whose default value type is unknown, but do not have a
+ jCal type identifier "unknown". The VALUE parameter MAY be omitted
+ for properties using the default value type. The VALUE parameter
+ MUST be omitted for properties that have the jCal type identifier
+ "unknown".
+
+5. Handling Unrecognized Properties or Parameters
+
+ In iCalendar, properties can have one or more value types as
+ specified by their definition, with one of those values being defined
+ as the default. When a property uses its default value type, the
+ "VALUE" property parameter does not need to be specified on the
+ property. For example, the default value type for "DTSTART" is
+ "DATE-TIME", so "VALUE=DATE-TIME" need not be set as a property
+ parameter. However, "DTSTART" also allows a "DATE" value to be
+ specified, and if that is used, "VALUE=DATE" has to be set as a
+ property parameter.
+
+ When new properties are defined or "X-" properties used, an iCalendar
+ to jCal converter might not recognize them, and not know what the
+ appropriate default value types are, yet they need to be able to
+ preserve the values. A similar issue arises for unrecognized
+ property parameters.
+
+ In jCal, a new "unknown" property value type is introduced. Its
+ purpose is to allow preserving unknown property values when round-
+ tripping between jCal and iCalendar. To avoid collisions, this
+ specification reserves the UNKNOWN property value type in iCalendar.
+ It MUST NOT be used in any iCalendar as specified by [RFC5545], nor
+ any extensions to it. Thus, the type is registered to the iCalendar
+ Value Data Types registry in Section 7.1.
+
+5.1. Converting iCalendar into jCal
+
+ Any property that does not include a "VALUE" property parameter and
+ whose default value type is not known, MUST be converted to a
+ primitive JSON string. The content of that string is the unprocessed
+ value text. Also, value type MUST be set to "unknown".
+
+
+
+
+
+Kewisch, et al. Standards Track [Page 18]
+
+RFC 7265 jCal May 2014
+
+
+ To correctly implement this format, it is critical that the type
+ "unknown" be used if the default type is not known. If this
+ requirement is ignored and, for example, "text" is used, additional
+ escaping may occur, which breaks round-tripping values.
+
+ Any unrecognized property parameter MUST be converted to a string
+ value, with its content set to the property parameter value text, and
+ treated as if it were a "TEXT" value.
+
+5.2. Converting jCal into iCalendar
+
+ In jCal, the value type is always explicitly specified. It is
+ converted to iCalendar using the iCalendar VALUE parameter, except in
+ the following two cases:
+
+ o If the value type specified in jCal matches the default value type
+ in iCalendar, the VALUE parameter MAY be omitted.
+
+ o If the value type specified in jCal is set to "unknown", the VALUE
+ parameter MUST NOT be specified. The value MUST be taken over in
+ iCalendar without processing.
+
+5.3. Examples
+
+ The following is an example of an unrecognized iCalendar property
+ (that uses a "DATE-TIME" value as its default), and the equivalent
+ jCal representation of that property.
+
+ iCalendar:
+
+ X-COMPLAINT-DEADLINE:20110512T120000Z
+
+ jCal:
+
+ ["x-complaint-deadline", {}, "unknown", "20110512T120000Z"]
+
+ The following is an example of how to cope with jCal data where the
+ parser was unable to identify the type. Note how the "unknown" value
+ type is not added to the iCalendar data and escaping, aside from
+ standard JSON string escaping, is not processed.
+
+ jCal:
+
+ ["x-coffee-data", {}, "unknown", "Stenophylla;Guinea\\,Africa"]
+
+ iCalendar:
+
+ X-COFFEE-DATA:Stenophylla;Guinea\,Africa
+
+
+
+Kewisch, et al. Standards Track [Page 19]
+
+RFC 7265 jCal May 2014
+
+
+ The following is an example of a jCal property (where the
+ corresponding iCalendar property uses an "INTEGER" value as its
+ default) and the equivalent iCalendar representation of that
+ property.
+
+ jCal:
+
+ ["percent-complete", {}, "integer", 95]
+
+ iCalendar:
+
+ PERCENT-COMPLETE:95
+
+ The following is an example of an unrecognized iCalendar property
+ parameter (that uses a "FLOAT" value as its default) specified on a
+ recognized iCalendar property and the equivalent jCal representation
+ of that property and property parameter.
+
+ iCalendar:
+
+ DTSTART;X-SLACK=30.3;VALUE=DATE:20110512
+
+ jCal:
+
+ ["dtstart", { "x-slack": "30.3" }, "date", "2011-05-12"]
+
+6. Security Considerations
+
+ This specification defines how iCalendar data can be "translated"
+ between two different data formats -- the original text format and
+ JSON -- with a one-to-one mapping to ensure all the semantic data in
+ one format (properties, parameters, and values) are preserved in the
+ other. It does not change the semantic meaning of the underlying
+ data itself, or impose or remove any security considerations that
+ apply to the underlying data.
+
+ The use of JSON as a format does have its own inherent security risks
+ as discussed in Section 12 of [RFC7159]. Even though JSON is
+ considered a safe subset of JavaScript, it should be kept in mind
+ that a flaw in the parser processing JSON could still impose a
+ threat, which doesn't arise with conventional iCalendar data.
+
+ With this in mind, a parser for JSON data should be used for jCal
+ that is aware of the security implications. For example, the use of
+ JavaScript's eval() function is considered an unacceptable security
+ risk, as described in Section 12 of [RFC7159]. A native parser with
+ full awareness of the JSON format should be preferred.
+
+
+
+
+Kewisch, et al. Standards Track [Page 20]
+
+RFC 7265 jCal May 2014
+
+
+ In addition, it is expected that this new format will result in
+ iCalendar data being more widely disseminated (e.g., with use in web
+ applications rather than just dedicated calendaring applications).
+
+ In all cases, application developers have to conform to the semantics
+ of the iCalendar data as defined by [RFC5545] and associated
+ extensions, and all of the security considerations described in
+ Section 7 of [RFC5545], or any associated extensions, are applicable.
+
+7. IANA Considerations
+
+ This document defines a MIME media type for use with iCalendar in
+ JSON data. This media type SHOULD be used for the transfer of
+ calendaring data in JSON.
+
+ Type name: application
+
+ Subtype name: calendar+json
+
+ Required parameters: none
+
+ Optional parameters: "method", "component", and "optinfo" as defined
+ for the text/calendar media type in [RFC5545], Section 8.1.
+
+ Encoding considerations: Same as encoding considerations of
+ application/json as specified in [RFC7159], Section 11.
+
+ Security considerations: See Section 6.
+
+ Interoperability considerations: This media type provides an
+ alternative format for iCalendar data based on JSON.
+
+ Published specification: This specification.
+
+ Applications that use this media type: Applications that currently
+ make use of the text/calendar media type can use this as an
+ alternative. Similarly, applications that use the application/
+ json media type to transfer calendaring data can use this to
+ further specify the content.
+
+ Fragment identifier considerations: N/A
+
+ Additional information:
+
+ Deprecated alias names for this type: N/A
+
+ Magic number(s): N/A
+
+
+
+
+Kewisch, et al. Standards Track [Page 21]
+
+RFC 7265 jCal May 2014
+
+
+ File extension(s): N/A
+
+ Macintosh file type code(s): N/A
+
+ Person & email address to contact for further information:
+ calsify at ietf.org
+
+ Intended usage: COMMON
+
+ Restrictions on usage: There are no restrictions on where this media
+ type can be used.
+
+ Author: See the "Authors' Addresses" section of this document.
+
+ Change controller: IETF
+
+7.1. UNKNOWN iCalendar Value Data Type
+
+ IANA has added the following entry to the iCalendar Data Types
+ registry:
+
+ Value name: UNKNOWN
+
+ Purpose: To allow preserving property values whose default value
+ type is not known during round-tripping between jCal and
+ iCalendar.
+
+ Format definition: N/A
+
+ Description: The UNKNOWN value data type is reserved for the
+ exclusive use of the jCal format. Its use is described in
+ Section 5 of this document.
+
+ Example: As this registration serves as a reservation of the UNKNOWN
+ type so that it is not used in iCalendar, there is no applicable
+ iCalendar example. Examples of its usage in jCal can be found in
+ this document.
+
+ IANA has made the "Status" column for this entry in the registry say,
+ "Reserved - Do not use" and has made the "Reference" column refer to
+ Section 5 of this document.
+
+
+
+
+
+
+
+
+
+
+Kewisch, et al. Standards Track [Page 22]
+
+RFC 7265 jCal May 2014
+
+
+8. Acknowledgments
+
+ The authors would like to thank the following for their valuable
+ contributions: William Gill, Erwin Rehme, Dave Thewlis, Simon
+ Perreault, Michael Angstadt, Peter Saint-Andre, Bert Greevenbosch,
+ and Javier Godoy. This specification originated from the work of the
+ XML-JSON technical committee of the Calendaring and Scheduling
+ Consortium.
+
+9. References
+
+9.1. Normative References
+
+ [ISO.8601.2004]
+ International Organization for Standardization, "Data
+ elements and interchange formats -- Information
+ interchange -- Representation of dates and times", ISO
+ 8601, December 2004,
+ <http://www.iso.org/iso/catalogue_detail?csnumber=40874>.
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
+ Resource Identifier (URI): Generic Syntax", STD 66, RFC
+ 3986, January 2005.
+
+ [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
+ Encodings", RFC 4648, October 2006.
+
+ [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
+ Specifications: ABNF", STD 68, RFC 5234, January 2008.
+
+ [RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling
+ Core Object Specification (iCalendar)", RFC 5545,
+ September 2009.
+
+ [RFC6321] Daboo, C., Douglass, M., and S. Lees, "xCal: The XML
+ Format for iCalendar", RFC 6321, August 2011.
+
+ [RFC6868] Daboo, C., "Parameter Value Encoding in iCalendar and
+ vCard", RFC 6868, February 2013.
+
+ [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data
+ Interchange Format", RFC 7159, March 2014.
+
+
+
+
+
+
+Kewisch, et al. Standards Track [Page 23]
+
+RFC 7265 jCal May 2014
+
+
+9.2. Informative References
+
+ [calconnect-artifacts]
+ The Calendaring and Scheduling Consortium, "Code Artifacts
+ and Schemas", <http://www.calconnect.org/artifacts.shtml>.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Kewisch, et al. Standards Track [Page 24]
+
+RFC 7265 jCal May 2014
+
+
+Appendix A. ABNF Schema
+
+ Below is an ABNF schema as per [RFC5234] for iCalendar in JSON. ABNF
+ symbols not described here are taken from [RFC7159]. The schema is
+ non-normative and given for reference only.
+
+ Additional semantic restrictions apply, especially regarding the
+ allowed properties and sub-components per component. Details on
+ these restrictions can be found in this document and [RFC5545].
+
+ Additional schemas may be available on the Internet at
+ [calconnect-artifacts].
+
+ ; A jCal object is a component with the component-name "vcalendar".
+ ; Restrictions to which properties and sub-components may be
+ ; specified are to be taken from [RFC5545].
+ jcalobject = component
+
+ ; A jCal component consists of the name string, properties array, and
+ ; component array
+ component = begin-array
+ DQUOTE component-name DQUOTE value-separator
+ properties-array value-separator
+ components-array
+ end-array
+
+ components-array = begin-array
+ [ component *(value-separator component) ]
+ end-array
+
+ ; A jCal property consists of the name string, parameters object,
+ ; type string, and one or more values as specified in this document.
+ property = begin-array
+ DQUOTE property-name DQUOTE value-separator
+ params-object value-separator
+ DQUOTE type-name DQUOTE
+ property-value *(value-separator property-value)
+ end-array
+ properties-array = begin-array
+ [ property *(value-separator property) ]
+ end-array
+
+ ; Property values depend on the type-name. Aside from the value types
+ ; mentioned here, extensions may make use of other JSON value types.
+ ; The non-terminal symbol structured-prop-value covers the special
+ ; cases for GEO and REQUEST-STATUS.
+ property-value = simple-prop-value / structured-prop-value
+ simple-prop-value = string / number / true / false
+
+
+
+Kewisch, et al. Standards Track [Page 25]
+
+RFC 7265 jCal May 2014
+
+
+ structured-prop-value =
+ begin-array
+ [ structured-element *(value-separator structured-element) ]
+ end-array
+ structured-element = simple-prop-value
+
+ ; The jCal params-object is a JSON object that follows the semantic
+ ; guidelines described in this document.
+ params-object = begin-object
+ [ params-member *(value-separator params-member) ]
+ end-object
+ params-member = DQUOTE param-name DQUOTE name-separator param-value
+ param-value = string / param-multi
+ param-multi = begin-array
+ [ string *(value-separator string) ]
+ end-array
+
+ ; The type MUST be a valid type as described by this document. New
+ ; value types can be added by extensions.
+ type-name = "binary" / "boolean" / "cal-address" / "date" /
+ "date-time" / "duration" / "float" / "integer" /
+ "period" / "recur" / "text" / "time" / "uri" /
+ "utc-offset" / x-type
+
+
+ ; Component, property, parameter, and type names MUST be lowercase.
+ ; Additional semantic restrictions apply as described by this
+ ; document and [RFC5545].
+ component-name = lowercase-name
+ property-name = lowercase-name
+ param-name = lowercase-name
+ x-type = lowercase-name
+ lowercase-name = 1*(%x61-7A / DIGIT / "-")
+
+ ; The following rules are defined in [RFC7159], as mentioned above:
+ ; begin-array / end-array
+ ; begin-object / end-object
+ ; name-separator / value-separator
+ ; string / number / true / false
+
+
+
+
+
+
+
+
+
+
+
+
+Kewisch, et al. Standards Track [Page 26]
+
+RFC 7265 jCal May 2014
+
+
+Appendix B. Examples
+
+ This section contains two examples of iCalendar objects with their
+ jCal representation.
+
+B.1. Example 1
+
+B.1.1. iCalendar Data
+
+ BEGIN:VCALENDAR
+ CALSCALE:GREGORIAN
+ PRODID:-//Example Inc.//Example Calendar//EN
+ VERSION:2.0
+ BEGIN:VEVENT
+ DTSTAMP:20080205T191224Z
+ DTSTART:20081006
+ SUMMARY:Planning meeting
+ UID:4088E990AD89CB3DBB484909
+ END:VEVENT
+ END:VCALENDAR
+
+B.1.2. jCal Data
+
+ ["vcalendar",
+ [
+ ["calscale", {}, "text", "GREGORIAN"],
+ ["prodid", {}, "text", "-//Example Inc.//Example Calendar//EN"],
+ ["version", {}, "text", "2.0"]
+ ],
+ [
+ ["vevent",
+ [
+ ["dtstamp", {}, "date-time", "2008-02-05T19:12:24Z"],
+ ["dtstart", {}, "date", "2008-10-06"],
+ ["summary", {}, "text", "Planning meeting"],
+ ["uid", {}, "text", "4088E990AD89CB3DBB484909"]
+ ],
+ []
+ ]
+ ]
+ ]
+
+
+
+
+
+
+
+
+
+
+Kewisch, et al. Standards Track [Page 27]
+
+RFC 7265 jCal May 2014
+
+
+B.2. Example 2
+
+B.2.1. iCalendar Data
+
+ BEGIN:VCALENDAR
+ VERSION:2.0
+ PRODID:-//Example Corp.//Example Client//EN
+ BEGIN:VTIMEZONE
+ LAST-MODIFIED:20040110T032845Z
+ TZID:US/Eastern
+ BEGIN:DAYLIGHT
+ DTSTART:20000404T020000
+ RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4
+ TZNAME:EDT
+ TZOFFSETFROM:-0500
+ TZOFFSETTO:-0400
+ END:DAYLIGHT
+ BEGIN:STANDARD
+ DTSTART:20001026T020000
+ RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
+ TZNAME:EST
+ TZOFFSETFROM:-0400
+ TZOFFSETTO:-0500
+ END:STANDARD
+ END:VTIMEZONE
+ BEGIN:VEVENT
+ DTSTAMP:20060206T001121Z
+ DTSTART;TZID=US/Eastern:20060102T120000
+ DURATION:PT1H
+ RRULE:FREQ=DAILY;COUNT=5
+ RDATE;TZID=US/Eastern;VALUE=PERIOD:20060102T150000/PT2H
+ SUMMARY:Event #2
+ DESCRIPTION:We are having a meeting all this week at 12 pm fo
+ r one hour\, with an additional meeting on the first day 2 h
+ ours long.\nPlease bring your own lunch for the 12 pm meetin
+ gs.
+ UID:00959BC664CA650E933C892C at example.com
+ END:VEVENT
+ BEGIN:VEVENT
+ DTSTAMP:20060206T001121Z
+ DTSTART;TZID=US/Eastern:20060104T140000
+ DURATION:PT1H
+ RECURRENCE-ID;TZID=US/Eastern:20060104T120000
+ SUMMARY:Event #2 bis
+ UID:00959BC664CA650E933C892C at example.com
+ END:VEVENT
+ END:VCALENDAR
+
+
+
+
+Kewisch, et al. Standards Track [Page 28]
+
+RFC 7265 jCal May 2014
+
+
+B.2.2. jCal Data
+
+ ["vcalendar",
+ [
+ ["prodid", {}, "text", "-//Example Corp.//Example Client//EN"],
+ ["version", {}, "text", "2.0"]
+ ],
+ [
+ ["vtimezone",
+ [
+ ["last-modified", {}, "date-time", "2004-01-10T03:28:45Z"],
+ ["tzid", {}, "text", "US/Eastern"]
+ ],
+ [
+ ["daylight",
+ [
+ ["dtstart", {}, "date-time", "2000-04-04T02:00:00"],
+ ["rrule",
+ {},
+ "recur",
+ {
+ "freq": "YEARLY",
+ "byday": "1SU",
+ "bymonth": 4
+ }
+ ],
+ ["tzname", {}, "text", "EDT"],
+ ["tzoffsetfrom", {}, "utc-offset", "-05:00"],
+ ["tzoffsetto", {}, "utc-offset", "-04:00"]
+ ],
+ []
+ ],
+ ["standard",
+ [
+ ["dtstart", {}, "date-time", "2000-10-26T02:00:00"],
+ ["rrule",
+ {},
+ "recur",
+ {
+ "freq": "YEARLY",
+ "byday": "1SU",
+ "bymonth": 10
+ }
+ ],
+ ["tzname", {}, "text", "EST"],
+ ["tzoffsetfrom", {}, "utc-offset", "-04:00"],
+ ["tzoffsetto", {}, "utc-offset", "-05:00"]
+ ],
+
+
+
+Kewisch, et al. Standards Track [Page 29]
+
+RFC 7265 jCal May 2014
+
+
+ []
+ ]
+ ]
+ ],
+ ["vevent",
+ [
+ ["dtstamp", {}, "date-time", "2006-02-06T00:11:21Z"],
+ ["dtstart",
+ { "tzid": "US/Eastern" },
+ "date-time",
+ "2006-01-02T12:00:00"
+ ],
+ ["duration", {}, "duration", "PT1H"],
+ ["rrule", {}, "recur", { "freq": "DAILY", "count": 5 } ],
+ ["rdate",
+ { "tzid": "US/Eastern" },
+ "period",
+ "2006-01-02T15:00:00/PT2H"
+ ],
+ ["summary", {}, "text", "Event #2"],
+ ["description",
+ {},
+ "text",
+ // Note that comments and string concatenation are not
+ // allowed per the JSON specification and is used here only
+ // to avoid long lines.
+ "We are having a meeting all this week at 12 pm for one " +
+ "hour, with an additional meeting on the first day 2 " +
+ "hours long.\nPlease bring your own lunch for the 12 pm " +
+ "meetings."
+ ],
+ ["uid", {}, "text", "00959BC664CA650E933C892C at example.com"]
+ ],
+ []
+ ],
+ ["vevent",
+ [
+ ["dtstamp", {}, "date-time", "2006-02-06T00:11:21Z"],
+ ["dtstart",
+ { "tzid": "US/Eastern" },
+ "date-time",
+ "2006-01-02T14:00:00"
+ ],
+ ["duration", {}, "duration", "PT1H"],
+ ["recurrence-id",
+ { "tzid": "US/Eastern" },
+ "date-time",
+ "2006-01-04T12:00:00"
+
+
+
+Kewisch, et al. Standards Track [Page 30]
+
+RFC 7265 jCal May 2014
+
+
+ ],
+ ["summary", {}, "text", "Event #2"],
+ ["uid", {}, "text", "00959BC664CA650E933C892C at example.com"]
+ ],
+ []
+ ]
+ ]
+ ]
+
+Authors' Addresses
+
+ Philipp Kewisch
+ Mozilla Corporation
+ 650 Castro Street, Suite 300
+ Mountain View, CA 94041
+ USA
+
+ EMail: mozilla at kewis.ch
+ URI: http://www.mozilla.org/
+
+
+ Cyrus Daboo
+ Apple Inc.
+ 1 Infinite Loop
+ Cupertino, CA 95014
+ USA
+
+ EMail: cyrus at daboo.name
+ URI: http://www.apple.com/
+
+
+ Mike Douglass
+ Rensselaer Polytechnic Institute
+ 110 8th Street
+ Troy, NY 12180
+ USA
+
+ EMail: douglm at rpi.edu
+ URI: http://www.rpi.edu/
+
+
+
+
+
+
+
+
+
+
+
+
+Kewisch, et al. Standards Track [Page 31]
+
Added: CalendarServer/trunk/doc/RFC/RFC7529-RSCALE.txt
===================================================================
--- CalendarServer/trunk/doc/RFC/RFC7529-RSCALE.txt (rev 0)
+++ CalendarServer/trunk/doc/RFC/RFC7529-RSCALE.txt 2015-05-27 14:45:30 UTC (rev 14834)
@@ -0,0 +1,1179 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) C. Daboo
+Request for Comments: 7529 Apple Inc.
+Updates: 5545, 6321, 7265 G. Yakushev
+Category: Standards Track Google Inc.
+ISSN: 2070-1721 May 2015
+
+
+ Non-Gregorian Recurrence Rules in the Internet Calendaring and
+ Scheduling Core Object Specification (iCalendar)
+
+Abstract
+
+ This document defines extensions to the Internet Calendaring and
+ Scheduling Core Object Specification (iCalendar) (RFC 5545) to
+ support use of non-Gregorian recurrence rules. It also defines how
+ Calendaring Extensions to WebDAV (CalDAV) (RFC 4791) servers and
+ clients can be extended to support these new recurrence rules.
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 5741.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ http://www.rfc-editor.org/info/rfc7529.
+
+Copyright Notice
+
+ Copyright (c) 2015 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
+ (http://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.
+
+
+
+
+
+Daboo & Yakushev Standards Track [Page 1]
+
+RFC 7529 iCalendar RSCALE Extension May 2015
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 2. Conventions Used in This Document . . . . . . . . . . . . . . 3
+ 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4
+ 4. Extended RRULE Property . . . . . . . . . . . . . . . . . . . 6
+ 4.1. Skipping Invalid Dates . . . . . . . . . . . . . . . . . 6
+ 4.2. Handling Leap Months . . . . . . . . . . . . . . . . . . 9
+ 4.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 10
+ 5. Registering Calendar Systems . . . . . . . . . . . . . . . . 13
+ 6. Compatibility . . . . . . . . . . . . . . . . . . . . . . . . 13
+ 7. Use with iTIP . . . . . . . . . . . . . . . . . . . . . . . . 14
+ 8. Use with xCal . . . . . . . . . . . . . . . . . . . . . . . . 15
+ 9. Use with jCal . . . . . . . . . . . . . . . . . . . . . . . . 15
+ 10. Use with CalDAV . . . . . . . . . . . . . . . . . . . . . . . 16
+ 10.1. CALDAV:supported-rscale-set Property . . . . . . . . . . 17
+ 11. Security Considerations . . . . . . . . . . . . . . . . . . . 18
+ 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 18
+ 12.1. Normative References . . . . . . . . . . . . . . . . . . 18
+ 12.2. Informative References . . . . . . . . . . . . . . . . . 19
+ Appendix A. xCal RELAX NG Schema Update . . . . . . . . . . . . 20
+ Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 21
+ Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21
+
+1. Introduction
+
+ The iCalendar [RFC5545] data format is in widespread use to represent
+ calendar data. iCalendar represents dates and times using the
+ Gregorian calendar system only. It does provide a way to use non-
+ Gregorian calendar systems via a "CALSCALE" property, but this has
+ never been used. However, there is a need to support at least non-
+ Gregorian recurrence patterns to cover anniversaries, and many local,
+ religious, or civil holidays based on non-Gregorian dates.
+
+ There are several disadvantages to using the existing "CALSCALE"
+ property in iCalendar for implementing non-Gregorian calendars:
+
+ 1. The "CALSCALE" property exists in the top-level "VCALENDAR"
+ objects and thus applies to all components within that object.
+ In today's multi-cultural society, that restricts the ability to
+ mix events from different calendar systems within the same
+ iCalendar object, e.g., it would prevent having both the
+ Gregorian New Year and Chinese New Year in the same iCalendar
+ object.
+
+ 2. Time zone and daylight saving time rules are typically published
+ using Gregorian calendar dates and rules (e.g., "the 3rd Sunday
+ in March") and are thus converted to iCalendar "VTIMEZONE"
+
+
+
+Daboo & Yakushev Standards Track [Page 2]
+
+RFC 7529 iCalendar RSCALE Extension May 2015
+
+
+ components using Gregorian dates and recurrence rules. This
+ results in the problem whereby one component (the "VTIMEZONE") is
+ fixed to the Gregorian calendar system, and another (a "VEVENT")
+ wants to use a different non-Gregorian calendar scale; thus, the
+ single top-level "CALSCALE" property is again inadequate.
+
+ This specification solves these issues by allowing the "CALSCALE" to
+ remain set to Gregorian but redefining the "RRULE" recurrence rule
+ property to accept new items, including one that allows non-Gregorian
+ calendar systems to be used. With this, all the "DATE", "DATE-TIME",
+ and "PERIOD" values in the iCalendar object would remain specified
+ using the Gregorian calendar system, but repeating patterns in other
+ calendar systems could be defined. It is then up to calendar user
+ agents and servers to map between Gregorian and non-Gregorian
+ calendar systems in order to expand out recurrence instances. The
+ non-Gregorian recurrence rules can be used in any iCalendar component
+ that allows the "RRULE" property to be specified, including
+ "VTIMEZONE" components (to allow for possible future use of non-
+ Gregorian rules in published daylight saving time data).
+
+ This specification does not itself define calendar systems; rather,
+ it utilizes the calendar system registry defined by the Unicode
+ Consortium in their Common Locale Data Repository (CLDR) project
+ [UNICODE.CLDR], as implemented in the Unicode (International
+ Components for Unicode (ICU)) Library [UNICODE.ICU].
+
+ This specification makes the following updates:
+
+ It updates iCalendar [RFC5545], the XML format for iCalendar
+ (xCal) [RFC6321], and the JSON format for iCalendar (jCal)
+ [RFC7265], to extend the "RRULE" property definition.
+
+ It clarifies use of the iCalendar Transport-Independent
+ Interoperability Protocol (iTIP) [RFC5546] to specify how the
+ extended "RRULE" property should be handled in iTIP messages.
+
+ It extends CalDAV [RFC4791] to specify how the extended "RRULE"
+ property can be supported by CalDAV servers and clients.
+
+2. Conventions Used in This Document
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
+ "OPTIONAL" in this document are to be interpreted as described in
+ [RFC2119].
+
+
+
+
+
+
+Daboo & Yakushev Standards Track [Page 3]
+
+RFC 7529 iCalendar RSCALE Extension May 2015
+
+
+ The notation used in this memo is the ABNF notation of [RFC5234] as
+ used by iCalendar [RFC5545]. Any syntax elements shown below that
+ are not explicitly defined in this specification come from iCalendar
+ [RFC5545], iTIP [RFC5546], and CalDAV [RFC4791].
+
+ When XML element types in the namespaces "DAV:" and
+ "urn:ietf:params:xml:ns:caldav" are referenced in this document
+ outside of the context of an XML fragment, the string "DAV:" and
+ "CALDAV:" will be prefixed to the element type names, respectively.
+
+ When a Gregorian calendar date is shown in text, it will use the
+ format "YYYYMMDD", where "YYYY" is the 4-digit year, "MM" the 2-digit
+ month, and "DD" the 2-digit day (this is the same format used in
+ iCalendar [RFC5545]). The Chinese calendar will be used as an
+ example of a non-Gregorian calendar for illustrative purposes. When
+ a Chinese calendar date is shown in text, it will use the format
+ "{C}YYYYMM[L]DD" -- i.e., the same format as Gregorian but with a
+ "{C}" prefix, and an optional "L" character after the month element
+ to indicate a leap month. Similarly, {E} and {H} are used in other
+ examples as prefixes for Ethiopic (Amete Mihret) and Hebrew dates,
+ respectively. The "{}" prefix is used for purely illustrative
+ purposes and never appears in actual dates used in iCalendar or
+ related specifications. Note that the Chinese calendar years shown
+ in the examples are based on the Unicode (ICU) [UNICODE.ICU]
+ library's Chinese calendar epoch. While there are several different
+ Chinese calendar epochs in common use, the choice of one over another
+ does not impact the actual calculation of the Gregorian equivalent
+ dates, provided conversion is always done using the same epoch.
+
+3. Overview
+
+ In the Gregorian calendar system, each year is composed of a fixed
+ number of months (12), with each month having a fixed number of days
+ (between 30 and 31), except for the second month (February), which
+ contains either 28 or 29 days (the latter in a leap year). Weeks are
+ composed of 7 days, with day names Monday, Tuesday, Wednesday,
+ Thursday, Friday, Saturday, and Sunday. Years can have either 365 or
+ 366 days (the latter in a leap year). The number of whole weeks in a
+ year is 52 (though the [ISO.8601.2004] week numbering scheme used by
+ iCalendar [RFC5545] can have a numeric count up to 53).
+
+ In iCalendar, the "RECUR" value type defines various fields used to
+ express a recurrence pattern, and those fields are given limits based
+ on those of the Gregorian calendar system. Since other calendar
+ systems can have different limits and other behaviors that need to be
+ accounted for, the maximum values for the elements in the "RECUR"
+ value are not covered by this specification.
+
+
+
+
+Daboo & Yakushev Standards Track [Page 4]
+
+RFC 7529 iCalendar RSCALE Extension May 2015
+
+
+ To generate a set of recurring instances in a non-Gregorian calendar
+ system, the following principles are used:
+
+ 1. iCalendar data continues to use the "GREGORIAN" calendar system,
+ so all "DATE", "DATE-TIME", and "PERIOD" values continue to use
+ the Gregorian format and limits.
+
+ 2. The "RRULE" property is extended to include an "RSCALE" element
+ in its value that specifies the calendar system to use for the
+ recurrence pattern. The existing elements of the "RRULE" value
+ type are used, but modified to support different upper limits,
+ based on the "RSCALE" value, as well as a modification to month
+ numbers to allow a leap month to be specified. Existing
+ requirements for the use of "RRULE" all still apply (e.g., the
+ "RRULE" has to match the "DTSTART" value of the master instance).
+ Other recurrence properties such as "RECURRENCE-ID", "RDATE", and
+ "EXDATE" continue to use the Gregorian date format as "CALSCALE"
+ is unchanged.
+
+ When generating instances, the following procedure might be used:
+
+ 1. Convert the "DTSTART" property value of the master recurring
+ component into the date and time components for the calendar
+ system specified by the "RSCALE" element in the "RRULE" value.
+ This provides the "seed" value for generating subsequent
+ recurrence instances.
+
+ 2. Iteratively generate instances using the "RRULE" value applied to
+ the year, month, and day components of the date in the new
+ calendar system.
+
+ 3. For each generated instance, convert the dates and times back
+ from the non-Gregorian form into Gregorian and use those values
+ for other properties such as "RECURRENCE-ID".
+
+ Consider the following example for an event representing the Chinese
+ New Year:
+
+ DTSTART;VALUE=DATE:20130210
+ RRULE:RSCALE=CHINESE;FREQ=YEARLY
+ SUMMARY:Chinese New Year
+
+ To generate instances, first the "DTSTART" value "20130210" is
+ converted into the Chinese calendar system giving "{C}46500101".
+ Next, the year component is incremented by one to give "{C}46510101",
+ and that is then converted back into Gregorian as "20140131".
+ Additional instances are generated by iteratively increasing the year
+ component in the Chinese date and converting back to Gregorian.
+
+
+
+Daboo & Yakushev Standards Track [Page 5]
+
+RFC 7529 iCalendar RSCALE Extension May 2015
+
+
+4. Extended RRULE Property
+
+ This specification extends the existing "RRULE" iCalendar property
+ value to include a new "RSCALE" element that can be used to indicate
+ the calendar system used for generating the recurrence pattern.
+
+ When "RSCALE" is present, the other changes to "RRULE" are:
+
+ 1. Elements that include numeric values (e.g., "BYYEARDAY") have
+ numeric ranges defined by the "RSCALE" value (i.e., in some
+ calendar systems there might be more than 366 days in a year).
+
+ 2. Month numbers can include an "L" suffix to indicate that the
+ specified month is a leap month in the corresponding calendar
+ system (see Section 4.2).
+
+ 3. A "SKIP" element is added to define how "missing" instances are
+ handled (see Section 4.1).
+
+ The syntax for the "RECUR" value is modified in the following
+ fashion:
+
+ ; recur-rule-part is extended from RFC 5545
+ recur-rule-part =/ ("RSCALE" "=" rscale)
+ / ("SKIP" "=" skip)
+
+ rscale = (iana-token ; A CLDR-registered calendar system
+ ; name.
+ / x-name) ; A non-standard, experimental
+ ; calendar system name.
+ ; Names are case insensitive,
+ ; but uppercase values are preferred.
+
+ skip = ("OMIT" / "BACKWARD" / "FORWARD")
+ ; Optional, with default value "OMIT", and
+ ; MUST NOT be present unless "RSCALE" is present.
+
+ monthnum = 1*2DIGIT ["L"]
+ ; Existing element modified to include a leap
+ ; month indicator suffix.
+
+4.1. Skipping Invalid Dates
+
+ In every calendar system, only certain combinations of day-of-month
+ and month values are valid for a given year, e.g., in the Gregorian
+ calendar system, January 31st is valid but February 31st is not.
+ Similarly, February 29th is valid in a leap year but invalid in a
+ non-leap year. Other calendar systems can also include leap months
+
+
+
+Daboo & Yakushev Standards Track [Page 6]
+
+RFC 7529 iCalendar RSCALE Extension May 2015
+
+
+ (see Section 4.2), which vary from year to year. This poses a
+ problem for recurring events where the frequency of recurrence might
+ give rise to an invalid date. For example, a recurring event that
+ starts on January 31st and is set to repeat monthly will generate
+ invalid dates for months with fewer than 31 days. The iCalendar
+ [RFC5545] specification requires recurrence rule generators to ignore
+ any invalid dates generated when iterating the rule. However, that
+ behavior might be surprising to a calendar user born on a leap day
+ and whose birthday event only appears on their calendar every four
+ years. There are common conventions used by humans to determine what
+ to do in such cases, but those conventions can differ from calendar
+ system to calendar system, as well as within the same calendar
+ system, depending on the nature of the event. Typically, humans will
+ expect the "missing" events to be moved to an earlier or later
+ (valid) date.
+
+ This specification introduces a new "RRULE" element, "SKIP", for use
+ only when the "RSCALE" element is present. The "SKIP" element allows
+ the calendar user agent to specify new options for handling invalid
+ dates.
+
+ "SKIP=OMIT": this is the default option and corresponds to the
+ existing iCalendar behavior of simply ignoring the invalid date.
+
+ "SKIP=BACKWARD": when this option is set, a date with an invalid
+ month is changed to the previous (valid) month. A date with an
+ invalid day-of-month is changed to the previous (valid)
+ day-of-month.
+
+ "SKIP=FORWARD": when this option is set, a date with an invalid
+ month is changed to the next (valid) month. A date with an
+ invalid day-of-month is changed to the next (valid) day-of-month.
+
+ Note that for both "BACKWARD" and "FORWARD", if the month is changed
+ and results in an invalid day-of-month, then the skip behavior will
+ be reapplied as per the day-of-month rules, according to the
+ processing order defined below.
+
+ The month and day-of-month skip behavior is only applied at specific
+ points during the processing of an "RRULE" as determined by the order
+ in which any "BYxxx" elements are processed. The order is as follows
+ (based on the "RRULE" element processing order defined in
+ Section 3.3.10 of [RFC5545]):
+
+ o BYMONTH
+
+ o SKIP (for invalid month only)
+
+
+
+
+Daboo & Yakushev Standards Track [Page 7]
+
+RFC 7529 iCalendar RSCALE Extension May 2015
+
+
+ o BYWEEKNO
+
+ o BYYEARDAY
+
+ o BYMONTHDAY
+
+ o SKIP (for invalid day)
+
+ o BYDAY
+
+ o BYHOUR
+
+ o BYMINUTE
+
+ o BYSECOND
+
+ o BYSETPOS
+
+ o COUNT
+
+ o UNTIL
+
+ It is often possible to avoid having to deal with invalid dates by
+ determining the real intent of a human user, e.g., a human creating a
+ monthly recurring event that starts on January 31st likely intends
+ the event to occur on the last day of every month, in which case that
+ could be encoded into an "RRULE" by using the "BYMONTHDAY=-1"
+ element.
+
+ Only a few types of recurrence patterns are likely to need the use of
+ "SKIP". The following is a list of some situations where it might be
+ needed:
+
+ 1. The start date of the recurrence is a leap day in the specified
+ calendar system.
+
+ 2. The start date of the recurrence is in a leap month in the
+ specified calendar system.
+
+ 3. The start date of the recurrence has a day-of-month value greater
+ than the smallest day-of-month value for any month in any year in
+ the specified calendar system.
+
+ 4. A "BYMONTHDAY" element in an "RRULE" has a day-of-month value
+ greater than the smallest day-of-month value for any month in any
+ year in the specified calendar system.
+
+
+
+
+
+Daboo & Yakushev Standards Track [Page 8]
+
+RFC 7529 iCalendar RSCALE Extension May 2015
+
+
+ 5. A "BYMONTH" element in an "RRULE" has a value corresponding to a
+ leap month in the specified calendar system.
+
+ 6. A combination of a "BYMONTHDAY" element and a "BYMONTH" element
+ in an "RRULE" has a value corresponding to a leap day in the
+ specified calendar system.
+
+ 7. A "BYYEARDAY" element in an "RRULE" has an absolute value greater
+ than the smallest number of days in any year in the specified
+ calendar system.
+
+ 8. A "BYWEEKNO" element in an "RRULE" has an absolute value greater
+ than the smallest number of weeks in any year in the specified
+ calendar system.
+
+ Examples of using "SKIP" for some common use cases appear in
+ Section 4.3.
+
+4.2. Handling Leap Months
+
+ Leap months can occur in different calendar systems. For such
+ calendar systems, the following rules are applied for "identifying"
+ months:
+
+ 1. Numeric values 1 through N are used to identify regular, non-
+ leap, months (where N is the number of months in a regular, non-
+ leap, year).
+
+ 2. The suffix "L" is added to the regular month number to indicate a
+ leap month that follows the regular month, e.g., "5L" is a leap
+ month that follows the 5th regular month in the year.
+
+ Care has to be taken when mapping the month identifiers used here
+ with those of any underlying calendar system library being used. In
+ particular, the Hebrew calendar system used by Unicode (ICU)
+ [UNICODE.ICU] uses a month number scheme of 1 through 13, with month
+ 6 being the leap month, and in non-leap years, month 6 is skipped.
+ Thus, ICU months 1 through 5 map to iCalendar months 1 through 5, ICU
+ month 6 maps to iCalendar month "5L", and ICU months 7 through 13 map
+ to iCalendar months 6 through 12.
+
+
+
+
+
+
+
+
+
+
+
+Daboo & Yakushev Standards Track [Page 9]
+
+RFC 7529 iCalendar RSCALE Extension May 2015
+
+
+4.3. Examples
+
+4.3.1. Chinese New Year
+
+ Consider the following set of iCalendar properties (from the example
+ above):
+
+ DTSTART;VALUE=DATE:20130210
+ RRULE:RSCALE=CHINESE;FREQ=YEARLY
+ SUMMARY:Chinese New Year
+
+ These define a recurring event for the Chinese New Year, with the
+ first instance being the one in Gregorian year 2013.
+
+ The Chinese date corresponding to the first instance is
+ "{C}46500101". The table below shows the initial instance and the
+ next four, each of which is determined by adding the appropriate
+ amount to the year component of the Chinese date. Also shown is the
+ conversion back to the Gregorian date:
+
+ +--------------+--------------------------+
+ | Chinese Date | Gregorian Date |
+ +--------------+--------------------------+
+ | {C}46500101 | 20130210 - DTSTART value |
+ | {C}46510101 | 20140131 |
+ | {C}46520101 | 20150219 |
+ | {C}46530101 | 20160208 |
+ | {C}46540101 | 20170128 |
+ +--------------+--------------------------+
+
+4.3.2. Ethiopic 13th Month
+
+ Consider the following set of iCalendar properties:
+
+ DTSTART;VALUE=DATE:20130906
+ RRULE:RSCALE=ETHIOPIC;FREQ=MONTHLY;BYMONTH=13
+ SUMMARY:First day of 13th month
+
+ These define a recurring event for the first day of the 13th month,
+ with the first instance being the one in Gregorian year 2013. While
+ there are a number of alternative ways of writing the "RRULE" above
+ to achieve the same pattern of recurring dates, the one above was
+ chosen to illustrate a "BYMONTH" value exceeding the limit of 12,
+ previously described in iCalendar (Section 3.3.10 of [RFC5545]).
+
+
+
+
+
+
+
+Daboo & Yakushev Standards Track [Page 10]
+
+RFC 7529 iCalendar RSCALE Extension May 2015
+
+
+ The Ethiopic date corresponding to the first instance is
+ "{E}20051301". The table below shows the initial instance and the
+ next four, each of which is determined by adding the appropriate
+ amount to the year component of the Ethiopic date. Also shown is the
+ conversion back to the Gregorian date:
+
+ +---------------+--------------------------+
+ | Ethiopic Date | Gregorian Date |
+ +---------------+--------------------------+
+ | {E}20051301 | 20130906 - DTSTART value |
+ | {E}20061301 | 20140906 |
+ | {E}20071301 | 20150906 |
+ | {E}20081301 | 20160906 |
+ | {E}20091301 | 20170906 |
+ +---------------+--------------------------+
+
+ Note that in this example, the value of the "BYMONTH" component in
+ the "RRULE" matches the Ethiopic month value and not the Gregorian
+ month.
+
+4.3.3. Hebrew Anniversary Starting in a Leap Month
+
+ Consider the following set of iCalendar properties:
+
+ DTSTART;VALUE=DATE:20140208
+ RRULE:RSCALE=HEBREW;FREQ=YEARLY;BYMONTH=5L;BYMONTHDAY=8;SKIP=FORWARD
+ SUMMARY:Anniversary
+
+ These define a recurring event for the 8th day of the Hebrew month of
+ Adar I (the leap month identified by "5L"), with the first instance
+ being the one in Gregorian year 2014.
+
+ The Hebrew date corresponding to the first instance is
+ "{H}577405L08", which is a leap month in year 5774. The table below
+ shows the initial instance and the next four, each of which is
+ determined by adding the appropriate amount to the year component of
+ the Hebrew date, taking into account that only year 5776 is a leap
+ year. Thus, in other years the Hebrew month component is adjusted
+ forward to month 6. Also shown is the conversion back to the
+ Gregorian date:
+
+
+
+
+
+
+
+
+
+
+
+Daboo & Yakushev Standards Track [Page 11]
+
+RFC 7529 iCalendar RSCALE Extension May 2015
+
+
+ +--------------+--------------------------+
+ | Hebrew Date | Gregorian Date |
+ +--------------+--------------------------+
+ | {H}577405L08 | 20140208 - DTSTART value |
+ | {H}57750608 | 20150227 |
+ | {H}577605L08 | 20160217 |
+ | {H}57770608 | 20170306 |
+ | {H}57780608 | 20180223 |
+ +--------------+--------------------------+
+
+4.3.4. Gregorian Leap Day with SKIP
+
+ Consider the following set of iCalendar properties:
+
+ DTSTART;VALUE=DATE:20120229
+ RRULE:FREQ=YEARLY
+ SUMMARY:Anniversary
+
+ These define a recurring event for the 29th of February, 2012, in the
+ standard iCalendar calendar scale -- Gregorian. The standard
+ iCalendar behavior is that non-existent dates in a recurrence set are
+ ignored. Thus, the properties above would only generate instances in
+ leap years (2016, 2020, etc.), which is likely not what users expect.
+ The new "RSCALE" option defined by this specification provides the
+ "SKIP" element, which can be used to "fill in" the missing instances
+ in an appropriate fashion. The set of iCalendar properties below
+ does that:
+
+ DTSTART;VALUE=DATE:20120229
+ RRULE:RSCALE=GREGORIAN;FREQ=YEARLY;SKIP=FORWARD
+ SUMMARY:Anniversary
+
+ With these properties, the "missing" instances in non-leap years now
+ appear on the 1st of March in those years:
+
+ +-------------------------------+----------------------------+
+ | Instances (with SKIP=FORWARD) | Instances (without RSCALE) |
+ +-------------------------------+----------------------------+
+ | 20120229 | 20120229 - DTSTART value |
+ | 20130301 | |
+ | 20140301 | |
+ | 20150301 | |
+ | 20160229 | 20160229 |
+ | 20170301 | |
+ +-------------------------------+----------------------------+
+
+
+
+
+
+
+Daboo & Yakushev Standards Track [Page 12]
+
+RFC 7529 iCalendar RSCALE Extension May 2015
+
+
+5. Registering Calendar Systems
+
+ This specification uses the Unicode Consortium's registry of calendar
+ systems [UNICODE.CLDR] to define valid values for the "RSCALE"
+ element of an "RRULE". Note that the underscore character "_" is
+ never used in CLDR-based calendar system names. New values can be
+ added to this registry following Unicode Consortium rules. It is
+ expected that many implementations of non-Gregorian calendars will
+ use software libraries provided by Unicode (ICU) [UNICODE.ICU], and
+ hence it makes sense to reuse their registry rather than creating a
+ new one. "RSCALE" values are case insensitive, but uppercase is
+ preferred.
+
+ CLDR supports the use of "alias" values as alternative names for
+ specific calendar systems. These alias values can be used as
+ "RSCALE" values and are treated the same as the equivalent CLDR
+ calendar system they are an alias for.
+
+ When using the CLDR data, calendar agents SHOULD take into account
+ the "deprecated" value and use the alternative "preferred" calendar
+ system. In particular, the "islamicc" calendar system is considered
+ deprecated in favor of the "islamic-civil" calendar system.
+
+6. Compatibility
+
+ For calendar user agents that do not support the "RSCALE" element, or
+ do not support the calendar system specified by the "RSCALE" element
+ value, the following behaviors are possible when processing iCalendar
+ data:
+
+ 1. The calendar user agent can reject the entire iCalendar object
+ within which at least one iCalendar component uses the
+ unrecognized "RSCALE" element or element value.
+
+ 2. The calendar user agent can reject just the iCalendar components
+ containing an unrecognized "RSCALE" element or element value.
+ Note that any overridden components associated with those
+ rejected components MUST also be rejected (i.e., any other
+ components with the same "UID" property value as the one with the
+ unrecognized "RSCALE" element or element value).
+
+ 3. The calendar user agent can fall back to a non-recurring behavior
+ for the iCalendar component containing the unrecognized "RSCALE"
+ element or element value (effectively ignoring the "RRULE"
+ property). However, any overridden components SHOULD be rejected
+ as they would represent "orphaned" instances that would seem to
+ be out of place.
+
+
+
+
+Daboo & Yakushev Standards Track [Page 13]
+
+RFC 7529 iCalendar RSCALE Extension May 2015
+
+
+ In general, the best choice for a calendar user agent would be option
+ (2) above, as it would be the least disruptive choice. Note that
+ when processing iTIP [RFC5546] messages, the manner of the rejection
+ is covered as discussed in the next section.
+
+7. Use with iTIP
+
+ iTIP [RFC5546] defines how iCalendar data can be sent between
+ calendar user agents to schedule calendar components between calendar
+ users. It is often not possible to know the capabilities of a
+ calendar user agent to which an iTIP message is being sent, but iTIP
+ defines fallback behavior in such cases.
+
+ For calendar user agents that do not support the "RSCALE" element,
+ the following can occur when iTIP messages containing an "RSCALE"
+ element are received:
+
+ The receiving calendar user agent can reject the entire iTIP
+ message and return an iTIP reply with a "REQUEST-STATUS" property
+ set to the "3.1" status code (as per Section 3.6.14 of [RFC5546]).
+
+ The receiving calendar user agent can fall back to a non-recurring
+ behavior for the calendar component (effectively ignoring the
+ "RRULE" property) and return an iTIP reply with a "REQUEST-STATUS"
+ property set to the "2.3", "2.5", "2.8", or "2.10" status codes
+ (as per Sections 3.6.4, 3.6.6, 3.6.9, or 3.6.11, respectively, of
+ [RFC5546]).
+
+ For calendar user agents that support the "RSCALE" element but do not
+ support the calendar system specified by the "RSCALE" element value,
+ the following can occur:
+
+ The iTIP message SHOULD be rejected, returning a "REQUEST-STATUS"
+ property set to the "3.1" status code (as per Section 3.6.14 of
+ [RFC5546]).
+
+ If the iTIP message is accepted and the calendar component treated
+ as non-recurring, an iTIP reply with a "REQUEST-STATUS" property
+ set to the "2.8" or "2.10" status codes (as per Sections 3.6.9 or
+ 3.6.11, respectively, of [RFC5546]) SHOULD be returned.
+
+ As noted in Section 6, the best choice is to reject the entire iTIP
+ message.
+
+
+
+
+
+
+
+
+Daboo & Yakushev Standards Track [Page 14]
+
+RFC 7529 iCalendar RSCALE Extension May 2015
+
+
+8. Use with xCal
+
+ xCal [RFC6321] defines how iCalendar data is represented in XML.
+ This specification extends the <recur> XML element in Section 3.6.10
+ of [RFC6321] in the following manner:
+
+ 1. A new <rscale> XML element is defined as a child element of
+ <recur>. The content of this element MUST be a string whose
+ value is the "RSCALE" element value of the "RRULE", with case
+ preserved.
+
+ 2. A new <skip> XML element is defined as a child element of
+ <recur>. The content of this element MUST be a string whose
+ value is the "SKIP" element value of the "RRULE", with case
+ preserved.
+
+ 3. The <bymonth> XML element is redefined to support either numeric
+ or string values as its content (as per Section 4.2).
+
+ Extensions to the RELAX NG schema in Appendix A of [RFC6321] are
+ defined in Appendix A of this document.
+
+ Example: the iCalendar "RRULE" property:
+
+ RRULE:RSCALE=GREGORIAN;FREQ=YEARLY;SKIP=FORWARD
+
+ would be represented in XML as:
+
+ <rrule>
+ <recur>
+ <rscale>GREGORIAN</rscale>
+ <freq>YEARLY</freq>
+ <skip>FORWARD</skip>
+ </recur>
+ </rrule>
+
+9. Use with jCal
+
+ jCal [RFC7265] defines how iCalendar data is represented in JSON.
+ This specification extends the "recur" JSON object defined in
+ Section 3.6.10 of [RFC7265] in the following manner:
+
+ 1. A new "rscale" child member is defined. This MUST be a string
+ whose value is the "RSCALE" element value of the "RRULE", with
+ case preserved.
+
+
+
+
+
+
+Daboo & Yakushev Standards Track [Page 15]
+
+RFC 7529 iCalendar RSCALE Extension May 2015
+
+
+ 2. A new "skip" child member is defined. This MUST be a string
+ whose value is the "SKIP" element value of the "RRULE", with case
+ preserved.
+
+ 3. The "bymonth" child member is redefined to support either numeric
+ or string values. If the "BYMONTH" element value is an integer,
+ then a numeric JSON value MUST be used. If the "BYMONTH" element
+ value is an integer with the "L" suffix (as per Section 4.2),
+ then a JSON string value MUST be used.
+
+ Example: the iCalendar "RRULE" property:
+
+ RRULE:RSCALE=GREGORIAN;FREQ=YEARLY;SKIP=FORWARD
+
+ would be represented in JSON as:
+
+ [
+ "rrule",
+ {},
+ "recur",
+ {
+ "rscale": "GREGORIAN",
+ "freq": "YEARLY",
+ "skip": "FORWARD"
+ }
+ ]
+
+10. Use with CalDAV
+
+ The CalDAV [RFC4791] calendar access protocol allows clients and
+ servers to exchange iCalendar data. In addition, CalDAV clients are
+ able to query calendar data stored on the server, including time-
+ based queries. Since an "RSCALE" element value determines the time
+ ranges for recurring instances in a calendar component, CalDAV
+ servers need to support it to interoperate with clients also using
+ the "RSCALE" element.
+
+ A CalDAV server advertises a CALDAV:supported-rscale-set Web
+ Distributed Authoring and Versioning (WebDAV) property on calendar
+ home or calendar collections if it supports use of the "RSCALE"
+ element as described in this specification. The server can advertise
+ a specific set of supported calendar systems by including one or more
+ CALDAV:supported-rscale XML elements within the
+ CALDAV:supported-rscale-set XML element. If no
+ CALDAV:supported-rscale XML elements are included in the WebDAV
+ property, then clients can try any calendar system value but need to
+ be prepared for a failure when attempting to store the calendar data.
+
+
+
+
+Daboo & Yakushev Standards Track [Page 16]
+
+RFC 7529 iCalendar RSCALE Extension May 2015
+
+
+ Clients MUST NOT attempt to store iCalendar data containing "RSCALE"
+ elements if the CALDAV:supported-rscale-set WebDAV property is not
+ advertised by the server.
+
+ The server SHOULD return an HTTP 403 response with a DAV:error
+ element containing a CALDAV:supported-rscale XML element, if a client
+ attempts to store iCalendar data with an "RSCALE" element value not
+ supported by the server.
+
+ It is possible for an "RSCALE" value to be present in calendar data
+ on the server being accessed by a client that does not support an
+ "RSCALE" element or its specified value. It is expected that
+ existing clients, unaware of "RSCALE", will fail gracefully by
+ ignoring the calendar component, while still processing other
+ calendar data on the server (as per option (2) in Section 6).
+
+10.1. CALDAV:supported-rscale-set Property
+
+ Name: supported-rscale-set
+
+ Namespace: urn:ietf:params:xml:ns:caldav
+
+ Purpose: Enumerates the set of supported iCalendar "RSCALE" element
+ values supported by the server.
+
+ Protected: This property MUST be protected and SHOULD NOT be
+ returned by a PROPFIND allprop request (as defined in Section 14.2
+ of [RFC4918]).
+
+ Description: See above.
+
+ Definition:
+
+ <!ELEMENT supported-rscale-set (supported-rscale*)>
+ <!ELEMENT supported-rscale (#PCDATA)>
+ <!-- PCDATA value: string - case insensitive but
+ uppercase preferred -->
+
+ Example:
+
+ <C:supported-rscale-set
+ xmlns:C="urn:ietf:params:xml:ns:caldav">
+ <C:supported-rscale>GREGORIAN</C:supported-rscale>
+ <C:supported-rscale>CHINESE</C:supported-rscale>
+ <C:supported-rscale>ISLAMIC-CIVIL</C:supported-rscale>
+ <C:supported-rscale>HEBREW</C:supported-rscale>
+ <C:supported-rscale>ETHIOPIC</C:supported-rscale>
+ </C:supported-rscale-set>
+
+
+
+Daboo & Yakushev Standards Track [Page 17]
+
+RFC 7529 iCalendar RSCALE Extension May 2015
+
+
+11. Security Considerations
+
+ This specification does not introduce any additional security
+ concerns beyond those described in [RFC5545], [RFC5546], and
+ [RFC4791].
+
+12. References
+
+12.1. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997,
+ <http://www.rfc-editor.org/info/rfc2119>.
+
+ [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
+ "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
+ March 2007, <http://www.rfc-editor.org/info/rfc4791>.
+
+ [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed
+ Authoring and Versioning (WebDAV)", RFC 4918, June 2007,
+ <http://www.rfc-editor.org/info/rfc4918>.
+
+ [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
+ Specifications: ABNF", STD 68, RFC 5234, January 2008,
+ <http://www.rfc-editor.org/info/rfc5234>.
+
+ [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and
+ Scheduling Core Object Specification (iCalendar)", RFC
+ 5545, September 2009,
+ <http://www.rfc-editor.org/info/rfc5545>.
+
+ [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent
+ Interoperability Protocol (iTIP)", RFC 5546, December
+ 2009, <http://www.rfc-editor.org/info/rfc5546>.
+
+ [RFC6321] Daboo, C., Douglass, M., and S. Lees, "xCal: The XML
+ Format for iCalendar", RFC 6321, August 2011,
+ <http://www.rfc-editor.org/info/rfc6321>.
+
+ [RFC7265] Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON
+ Format for iCalendar", RFC 7265, May 2014,
+ <http://www.rfc-editor.org/info/rfc7265>.
+
+ [UNICODE.CLDR]
+ The Unicode Consortium, "CLDR calendar.xml Data", Unicode
+ Consortium CLDR,
+ <http://www.unicode.org/repos/cldr/tags/latest/common/
+ bcp47/calendar.xml>.
+
+
+
+Daboo & Yakushev Standards Track [Page 18]
+
+RFC 7529 iCalendar RSCALE Extension May 2015
+
+
+12.2. Informative References
+
+ [ISO.8601.2004]
+ International Organization for Standardization, "Data
+ elements and interchange formats - Information interchange
+ - Representation of dates and times", ISO Standard 8601,
+ December 2004.
+
+ [UNICODE.ICU]
+ "International Components for Unicode", April 2014,
+ <http://site.icu-project.org>.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo & Yakushev Standards Track [Page 19]
+
+RFC 7529 iCalendar RSCALE Extension May 2015
+
+
+Appendix A. xCal RELAX NG Schema Update
+
+ The following changes are made to the RELAX NG schema defined in
+ Appendix A of [RFC6321].
+
+ # 3.3.10 RECUR
+ # This extension adds type-rscale and type-skip,
+ # and modifies type-bymonth
+
+ value-recur = element recur {
+ type-rscale?,
+ type-freq,
+ (type-until | type-count)?,
+ element interval {
+ xsd:positiveInteger
+ }?,
+ type-bysecond*,
+ type-byminute*,
+ type-byhour*,
+ type-byday*,
+ type-bymonthday*,
+ type-byyearday*,
+ type-byweekno*,
+ type-bymonth*,
+ type-bysetpos*,
+ element wkst { type-weekday }?,
+ type-skip?
+ }
+
+
+ type-rscale = element rscale {
+ xsd:string
+ }
+
+ type-bymonth = element bymonth {
+ xsd:positiveInteger |
+ xsd:string
+ }
+
+ type-skip = element skip {
+ "OMIT" |
+ "BACKWARD" |
+ "FORWARD"
+ }
+
+
+
+
+
+
+
+Daboo & Yakushev Standards Track [Page 20]
+
+RFC 7529 iCalendar RSCALE Extension May 2015
+
+
+Acknowledgments
+
+ Thanks to the following for feedback: Mark Davis, Mike Douglass,
+ Donald Eastlake, Peter Edberg, Marten Gajda, Philipp Kewisch, Barry
+ Leiba, Jonathan Lennox, Ken Murchison, Arnaud Quillaud, Dave Thewlis,
+ and Umaoka Yoshito.
+
+ This specification originated from work at the Calendaring and
+ Scheduling Consortium, which has helped with the development and
+ testing of implementations.
+
+Authors' Addresses
+
+ Cyrus Daboo
+ Apple Inc.
+ 1 Infinite Loop
+ Cupertino, CA 95014
+ United States
+
+ EMail: cyrus at daboo.name
+ URI: http://www.apple.com/
+
+
+ Gregory Yakushev
+ Google Inc.
+ Brandschenkestrasse 100
+ 8002 Zurich
+ Switzerland
+
+ EMail: gyakushev at yahoo.com
+ URI: http://www.google.com/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo & Yakushev Standards Track [Page 21]
+
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.macosforge.org/pipermail/calendarserver-changes/attachments/20150527/bfb885bb/attachment-0001.html>
More information about the calendarserver-changes
mailing list