One document matched: draft-ietf-jcardcal-jcal-00.xml
<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type="text/xsl" href="../../rfc2629.xslt"?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd'
[
<!ENTITY rfc2119 PUBLIC '' 'bibxml/reference.RFC.2119.xml'>
<!ENTITY rfc3986 PUBLIC '' 'bibxml/reference.RFC.3986.xml'>
<!ENTITY rfc4627 PUBLIC '' 'bibxml/reference.RFC.4627.xml'>
<!ENTITY rfc4648 PUBLIC '' 'bibxml/reference.RFC.4648.xml'>
<!ENTITY rfc5234 PUBLIC '' 'bibxml/reference.RFC.5234.xml'>
<!ENTITY rfc5545 PUBLIC '' 'bibxml/reference.RFC.5545.xml'>
<!ENTITY rfc6321 PUBLIC '' 'bibxml/reference.RFC.6321.xml'>
<!ENTITY I-D.sheffer-running-code PUBLIC '' 'bibxml3/reference.I-D.sheffer-running-code.xml'>
]>
<?rfc rfcedstyle="yes" ?>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<!-- default = 3 -->
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc strict="yes"?>
<!--<?rfc comments="yes"?> -->
<!--<?rfc inline="yes"?> -->
<rfc category='std' ipr='trust200902' docName='draft-ietf-jcardcal-jcal-00'>
<front>
<title abbrev="jCal">jCal: The JSON format for iCalendar</title>
<author initials="P." surname="Kewisch" fullname="Philipp Kewisch">
<organization abbrev="Mozilla">Mozilla Corporation</organization>
<address>
<postal>
<street>650 Castro Street, Suite 300</street>
<city>Mountain View</city>
<region>CA</region>
<code>94041</code>
<country>USA</country>
</postal>
<email>mozilla@kewis.ch</email>
<uri>http://www.mozilla.org/</uri>
</address>
</author>
<author initials="C." surname="Daboo" fullname="Cyrus Daboo">
<organization abbrev="Apple, Inc.">Apple Inc.</organization>
<address>
<postal>
<street>1 Infinite Loop</street>
<city>Cupertino</city>
<region>CA</region>
<code>95014</code>
<country>USA</country>
</postal>
<email>cyrus@daboo.name</email>
<uri>http://www.apple.com/</uri>
</address>
</author>
<author initials="M." surname="Douglass" fullname="Mike Douglass">
<organization abbrev="RPI">Rensselaer Polytechnic Institute</organization>
<address>
<postal>
<street>110 8th Street</street>
<city>Troy</city>
<region>NY</region>
<code>12180</code>
<country>USA</country>
</postal>
<email>douglm@rpi.edu</email>
<uri>http://www.rpi.edu/</uri>
</address>
</author>
<date />
<area>Applications</area>
<abstract>
<t>This specification defines "jCal", a JSON format for iCalendar data.</t>
</abstract>
</front>
<middle>
<section title='Introduction'>
<t>
The iCalendar data format <xref target='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 <xref target='RFC4627' /> 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.</t>
<t>
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.
</t>
<t>
The key design considerations are essentially the same as those for
<xref target='RFC6321' />, that is:
<list>
<t>
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, with the exception of those which have
default values.
</t>
<t>
Ordering of elements will not necessarily be preserved.
</t>
<t>
Preserve the semantics of the iCalendar data. While a simple consumer
can easily browse the calendar data in jCal, a full understanding of
iCalendar is still required in order to modify and/or fully
comprehend the calendar data.
</t>
<t>
Ability to handle many extensions to the underlying iCalendar
specification without requiring an update to this document.
</t>
</list>
</t>
</section>
<section title='Conventions Used in This Document'>
<t>
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
<xref target='RFC2119' />.
</t>
<t>
The underlying format used for jCal is JSON. Consequently, the terms
"object" and "array" as well as the four primitive types are to be
interpreted as described in Section 1 of <xref target="RFC4627"/>.
</t>
<t>
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.
</t>
</section>
<section title='Converting from iCalendar to jCal'>
<t>
This section describes how iCalendar data is converted to jCal using a
simple mapping between the iCalendar data model and JSON elements.
</t>
<section title="Pre-processing">
<t>
iCalendar uses a line folding mechanism to limit lines of data to a
maximum line length (typically 72 characters) to ensure maximum
likelihood of preserving data integrity as it is transported via
various means (e.g., email) - see Section 3.1 of <xref target='RFC5545'/>.
Prior to converting iCalendar data into jCal all folded lines MUST be
unfolded.
</t>
<t>
iCalendar data uses an "escape" character sequence for text values and
property parameter values. When such text elements are converted into
jCal the escaping MUST be removed.
</t>
<t>
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 MUST be applied when processing a property with
the "ENCODING" property parameter set to "BASE64":
<list style="symbols">
<t>
If the property value type is "BINARY", the base64 encoding MUST
be preserved.
</t>
<t>
If the value type is not "BINARY", the "ENCODING" property
parameter MUST be removed, and the value MUST be base64 decoded.
</t>
</list>
</t>
<t>
When base64 encoding and decoding is used, it MUST conform to Section
4 of <xref target='RFC4648'/>, which is the base64 method used in
<xref target='RFC5545'/>.
</t>
<t>
One key difference in the formatting of values used in iCalendar and
jCal is that in jCal the specification uses date/time and utc-offset
values aligned with the complete representation, extended format of
<xref target="ISO.8601.2004"/>.
</t>
</section>
<section title="iCalendar stream (RFC5545 section 3.4)">
<t>
At the top level of the iCalendar object model is an "iCalendar
stream". This stream encompasses multiple "iCalendar objects". In
jCal, the entire stream is represented by an array, where the first
element is the string "icalendar" and subsequent elements are
iCalendar objects represented as described in this document.
</t>
<t>
In the typical case where there is only one iCalendar object,
encapsulation inside an "icalendar" array MAY be omitted.
</t>
<t>
An iCalendar stream can contain one or more iCalendar objects. Each
iCalendar object, delimited by "BEGIN:VCALENDAR" and "END:VCALENDAR",
is represented by a fixed length array with three elements:
<list style="numbers">
<t>The string "vcalendar"</t>
<t>An array of jCal properties</t>
<t>An array of jCal components</t>
</list>
</t>
<t>
The representation of an iCalendar object in JSON will be named
"vcalendar component" throughout this document.
</t>
<t>
<figure>
<preamble>Example:</preamble>
<artwork><![CDATA[
["icalendar",
["vcalendar",
[ /* properties */ ],
[ /* components */ ]
],
["vcalendar",
[ /* properties */ ],
[ /* components */ ]
],
...
]
]]></artwork></figure>
</t>
<t>
iCalendar objects are comprised of a set of "components", "properties",
"parameters" and "values". A "component" can contain other "components"
or "properties". A "property" has a "value" and a set of zero or more
"parameters".
</t>
<t>
An iCalendar object may contain a mix of iCalendar component types,
for example vevent objects delimited by "BEGIN:VEVENT" and "END:VEVENT",
task objects delimited by "BEGIN:VTODO" and "END:VTODO".
</t>
</section>
<section anchor="components" title="Components (RFC5545 section 3.6)">
<t>
Each calendar component in the "VCALENDAR" object, delimited by
"BEGIN" and "END", will be converted to a fixed length array with
three fields that have a specific structure:
<list style="numbers">
<t>
A string with the name of the iCalendar component, but in
lowercase.
</t>
<t>
An array of jCal properties as described in
<xref target="properties"/>.
</t>
<t>
An array of jCal components, representing the sub-components of
the component in question.
</t>
</list>
</t>
<t>
While the grouping of properties and sub-components does not retain
the original order specified in the iCalendar stream, the semantics
of a component are preserved.
</t>
<t>
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.
</t>
<t>
<figure>
<preamble>Example:</preamble>
<artwork><![CDATA[
["vevent",
[ /* Array of jCal properties */ ],
[ /* Array of jCal sub-components */ ]
]
]]></artwork></figure>
</t>
</section>
<section anchor="properties" title="Properties (RFC5545 section 3.7 and 3.8)">
<t>
iCalendar properties, whether they apply to the "VCALENDAR" object
or to a component, are handled in a consistent way in the jCal format.
</t>
<t>
Each individual iCalendar property is represented in jCal by an array
with three fixed elements, followed by at one or more additional
elements, depending on if the property is a multi-value property as
described in Section 3.1.2 of <xref target="RFC5545"/>.
</t>
<t>
The array consists of the following fixed elements:
<list style="numbers">
<t>The name of the property as a string, but in lowercase.</t>
<t>
An object containing the parameters as described in
<xref target="parameters"/>.
</t>
<t>The type identifier string of the value, in lowercase.</t>
</list>
The remaining elements of the array are used for the value of the
property. For single-value properties, the array MUST have exactly
four elements, for multi-valued properties as described in
<xref target="multivalue"/> there can be any number of additional
elements.
</t>
<t>
The array describing the property can then be inserted into the array
designated for properties in any component, including the "vcalendar"
component described in <xref target="components"/>.
</t>
<t>
<figure>
<preamble>Example:</preamble>
<artwork><![CDATA[
["vevent",
[
["summary", {}, "text", "Meeting with Fred"],
["categories", {}, "text", "Meetings", "Work"]
...
],
[ /* sub-components */ ]
]
]]></artwork></figure>
</t>
<t>
The property parameters in the second element of the property array
associate a set of parameter names with their respective value.
Parameters are further described in <xref target="parameters"/>.
</t>
<t>
To allow for a cleaner implementation, the parameter object MUST be
present even if there are no parameters. In this case, an empty
object MUST be used.
</t>
<section title="Special Cases for Properties">
<t>
This section describes some properties that have special handling
when converting to jCal.
</t>
<section anchor="multivalue" title="Multi-valued Properties (RFC5545 Section 3.1.2)">
<t>
Various iCalendar properties defined in <xref target="RFC5545"/>,
for example the "CATEGORIES" property, are defined as multi-valued
properties. In jCal these properties are added as further members
of the array describing the property.
</t>
<t>
Note that additional multi-valued properties may be added in
extensions to the iCalendar format.
</t>
</section>
<section title="GEO Property (RFC5545 Section 3.8.1.6)">
<t>
In iCalendar, the "GEO" property value is defined as a semi-colon
separated list of two "FLOAT" values, the first representing
latitude and the second longitude.
</t>
<t>
In jCal, the value for the "geo" property is represented like a
multi-value property. The first value of the property represents
the latitude, the second value represents the longitude.
</t>
<t>
When converting from jCal to iCalendar, the two values MUST be
converted using a semi-colon as the separator character.
</t>
<t>
<figure>
<preamble>Example</preamble>
<artwork><![CDATA[
["vevent",
[
["geo", {}, "float", 37.386013, -122.082932 ]
...
],
...
]
]]></artwork></figure>
</t>
</section>
<section title="REQUEST-STATUS Property (RFC5545 Section 3.8.8.3)">
<t>
In iCalendar, the "REQUEST-STATUS" property value is defined as a
semi-colon separated list of two or three "TEXT" values. The first
represents a code, the second a description, and the third any
additional data.
</t>
<t>
In jCal, the value for the "request-status" property is
represented like a multi-value property. The first value of the
property corresponds to the code, the second value corresponds to
the description and the third value 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.
</t>
<t>
When converting from jCal to iCalendar, the two or three values
MUST be converted using a semi-colon as the separator character.
</t>
<t>
<figure>
<preamble>Example:</preamble>
<artwork><![CDATA[
["vevent":
[
["request-status", {}, "text", "2.0", "Success" ],
["request-status", {}, "text",
"3.7",
"Invalid Calendar User",
"ATTENDEE:mailto:jsmith@example.org"
],
...
],
...
]
]]></artwork></figure>
</t>
</section>
</section>
</section>
<section anchor="parameters" title="Parameters (RFC5545 section 3.2)">
<t>
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.
</t>
<t>
Each individual iCalendar property parameter is represented in jCal
by a key-value pair in the parameters object. The key uses the
same name as the iCalendar property parameter, but in lowercase. For
example, the "PARTSTAT" property parameter is represented in jCal by
the "partstat" key. The case of the parameter value MUST be
preserved.
</t>
<t>
<figure>
<preamble>Example:</preamble>
<artwork><![CDATA[
["vevent":
[
["attendee",
{
"partstat": "ACCEPTED",
"rsvp": "TRUE",
"role": "REQ-PARTICIPANT"
},
"cal-address",
"mailto:jsmith@example.org"
],
["summary", {}, "text", "Meeting"],
...
],
...
]
]]></artwork></figure>
</t>
<section title="VALUE parameter">
<t>
iCalendar defines a "VALUE" property parameter (Section 3.2.20 of
<xref target='RFC5545'/>). This property parameter MUST NOT be
added to the parameters object. Instead, the value type is always
explicitly mentioned in the third element of the array describing
the property. Thus, when converting from iCalendar to jCal, any
"VALUE" property parameters are skipped. When converting from
jCal into iCalendar, the appropriate "VALUE" property parameter MUST
be included in the iCalendar property if the value type is not the
default value type for that property.
</t>
</section>
<section title="Multi-value Parameters">
<t>
In <xref target='RFC5545'/>, some parameters allow using a
COMMA-separated list of values. To ease processing in jCal, the
value of a parameter with multiple values 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, but an array with one
element MAY also be used. An example for a such parameter is the
iCalendar "DELEGATED-FROM" and "DELEGATED-TO" parameter, more such
parameters may be added in extensions.
</t>
<t>
DQUOTE characters used to encapsulate the separated values MUST NOT
be added to the jCal parameter value.
</t>
<t>
<figure>
<preamble>Example 1:</preamble>
<artwork><![CDATA[
...
["attendee",
{
"delegated-to": ["mailto:jdoe@example.org",
"mailto:jqpublic@example.org"]
},
"cal-address",
"mailto:jsmith@example.org"
],
...
]]></artwork></figure>
</t>
<t>
<figure>
<preamble>Example 2:</preamble>
<artwork><![CDATA[
...
["attendee",
{
"delegated-to": "mailto:jdoe@example.org"
},
"cal-address",
"mailto:jsmith@example.org"
],
...
]]></artwork></figure>
</t>
</section>
</section>
<section anchor="values" title="Values (RFC5545 section 3.3)">
<t>
The type of an iCalendar value is explicitly mentioned in the third
element of the array describing a jCal property. The actual values of
the property can be found in the fourth and following elements of the
array.
</t>
<section title="Binary (RFC5545 section 3.3.1)">
<t><list style="hanging">
<t hangText="Description:">
iCalendar "BINARY" properties are represented by a property with
type identifier "binary". The value is base64 encoded data,
conforming to Section 4 of <xref target='RFC4648'/>, which is the
base64 method used in <xref target='RFC5545'/>.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["attach", {}, "binary", "SGVsbG8gV29ybGQh"],
...
]]></artwork></figure></t>
</list></t>
</section>
<section title="Boolean (RFC5545 section 3.3.2)">
<t><list style="hanging">
<t hangText="Description:">
iCalendar "BOOLEAN" properties are represented by a property with
the type identifier "boolean". The value is a boolean JSON value.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["x-non-smoking", {}, "boolean", true],
...
]]></artwork></figure></t>
</list></t>
</section>
<section title="Calendar User Address (RFC5545 section 3.3.3)">
<t><list style="hanging">
<t hangText="Description:">
iCalendar "CAL-ADDRESS" properties are represented by a property
with the type identifier "cal-address". The value is a string
with the URI as described in <xref target="RFC3986"/>.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["attendee", {}, "cal-address", "mailto:kewisch@example.com"],
...
]]></artwork></figure></t>
</list></t>
</section>
<section title="Date (RFC5545 section 3.3.4)">
<t><list style="hanging">
<t hangText="Description:">
iCalendar "DATE" properties are represented by a property with
the type identifier "date". The value is the same date value
specified by <xref target="RFC5545"/>, but formatted using the
<xref target="ISO.8601.2004"/> complete representation, extended
format. The textual format specifies a four-digit year, two-digit
month, and two-digit day of the month, separated by the "-"
character.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["dtstart", {}, "date", "2011-05-17"],
...
]]></artwork></figure></t>
</list></t>
</section>
<section title="Date-Time (RFC5545 section 3.3.5)">
<t><list style="hanging">
<t hangText="Description:">
iCalendar "DATE-TIME" properties are represented by a property
with the type identifier "date-time". The value is the same date
value specified by <xref target="RFC5545"/>, but formatted using
the <xref target="ISO.8601.2004"/> complete representation,
extended format. The same restrictions with respect to leap
seconds and timezone offsets as specified in <xref
target="RFC5545"/> Section 3.3.5 apply.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["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"
],
...
]]></artwork></figure></t>
</list></t>
</section>
<section title="Duration (RFC5545 section 3.3.6)">
<t><list style="hanging">
<t hangText="Description:">
iCalendar "DURATION" properties are represented by a property
with the type identifier "duration". The value is the same
duration value specified by <xref target="RFC5545"/> as a string.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["duration", {}, "duration", "P1D"],
...
]]></artwork></figure></t>
</list></t>
</section>
<section title="Float (RFC5545 section 3.3.7)">
<t><list style="hanging">
<t hangText="Description:">
iCalendar "FLOAT" properties are represented by a property with
the type identifier "float". The value is the floating point
number as a JSON primitive number value.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["x-grade", {}, "float", 1.3],
...
]]></artwork></figure></t>
</list></t>
</section>
<section title="Integer (RFC5545 section 3.3.8)">
<t><list style="hanging">
<t hangText="Description:">
iCalendar "INTEGER" properties are represented by a property with
the type identifier "integer". The value is the floating point
number as a JSON primitive number value.
</t>
<t hangText="Examples:"><figure><artwork><![CDATA[
...
["percent-complete", {}, "integer", 42],
...
]]></artwork></figure></t>
</list></t>
</section>
<section title="Period of Time (RFC5545 section 3.3.9)">
<t><list style="hanging">
<t hangText="Description:">
iCalendar "PERIOD" properties are represented by a jCal property
with the type identifier "period". The property value is an
array, with the first element representing the start of the
period and the second element representing the end of the period.
As in <xref target='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.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["freebusy",
{ "fbtype": "FREE" },
"period",
["1997-03-08T16:00:00Z", "P1D"]
],
...
]]></artwork></figure></t>
</list></t>
</section>
<section title="Recurrence Rule (RFC5545 section 3.3.10)">
<t><list style="hanging">
<t hangText="Description:">
iCalendar "RECUR" properties are represented by a property with
the type identifier "recur". The value is an object describing
the structured data as specified by <xref target='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:
<list style="symbols">
<t>
The value of the "freq" and "wskt" rule parts MUST be a
string as specified in <xref target='RFC5545'/>, with case
preserved.
</t>
<t>
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.
</t>
<t>
The "count" and "interval" rule parts MUST be specified as a
single number value.
</t>
<t>
The "bysecond", "byminute", "byhour", "bymonthday",
"byyearday", "byweekno", "bymonth" and "bysetpos" rule parts
MUST each be specified as an array with multiple number values.
Single-value rule parts SHOULD be represented using a single
string value, but an array with one element MAY also be used.
</t>
<t>
The "byday" rule part MUST be specified as an array with
multiple string values. A single-value "byday" rule part
SHOULD be represented using a single string value, but an
array with one element MAY also be used.
</t>
</list>
</t>
<t hangText="Example 1:"><figure><artwork><![CDATA[
...
["rrule",
{},
"recur",
{
"freq": "YEARLY",
"count": 5,
"byday": [ "-1SU", "2MO" ],
"bymonth": 10
}
],
...
]]></artwork></figure></t>
<t hangText="Example 2:"><figure><artwork><![CDATA[
...
["rrule",
{},
"recur",
{
"freq": "MONTHLY",
"interval": 2,
"bymonthday": [ 1, 15, -1 ],
"until": "2013-10-01"
}
],
...
]]></artwork></figure></t>
</list></t>
</section>
<section title="Text (RFC5545 section 3.3.11)">
<t><list style="hanging">
<t hangText="Description:">
iCalendar "TEXT" properties are represented by a property with
the type identifier "text". The value is the same text value
specified by <xref target='RFC5545'/> as a string.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["comment", {}, "text", "hello, world"],
...
]]></artwork></figure></t>
</list></t>
</section>
<section title="Time (RFC5545 section 3.3.12)">
<t><list style="hanging">
<t hangText="Description:">
iCalendar "TIME" propertes are represented by a property with the
type identifier "time". The value is the same date value
specified by <xref target="RFC5545"/>, but formatted using the
<xref target="ISO.8601.2004"/> complete representation, extended
format. The same restrictions with respect to leap seconds, time
fractions, and timezone offsets as specified in
<xref target="RFC5545"/> Section 3.3.12 apply.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["x-time-local", {}, "time", "12:30:00"],
["x-time-utc", {}, "time", "12:30:00Z"],
["x-time-offset", { "tzid": "Europe/Berlin" }, "time", "12:30:00"],
...
]]></artwork></figure></t>
</list></t>
</section>
<section title="URI (RFC5545 section 3.3.13)">
<t><list style="hanging">
<t hangText="Description:">
iCalendar "URI" properties are represented by a property with the
type identifier "uri". The value is a string with the URI.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["tzurl", {}, "uri", "http://example.org/tz/Europe-Berlin.ics"],
...
]]></artwork></figure></t>
</list></t>
</section>
<section title="UTC Offset (RFC5545 section 3.3.14)">
<t><list style="hanging">
<t hangText="Description:">
iCalendar "UTC-OFFSET" properties are represented by a property
with the type identifier "utc-offset". The value is a string with
the same UTC offset value specified by <xref target="RFC5545"/>,
with the exception that the hour and minute components are
separated by a ":" character, for consistency with the
<xref target="ISO.8601.2004"/> timezone offset, extended format.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["tzoffsetfrom", {}, "utc-offset", "-05:00"],
["tzoffsetto", {}, "utc-offset", "+12:45"],
..
]]></artwork></figure></t>
</list></t>
</section>
</section>
<section title="Extensions">
<t>
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, the property parameter 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 <xref target="unrecognized"/>
for how to deal with default values for unrecognized extension
properties or property parameters.
</t>
</section>
</section>
<section title="Converting from jCal into iCalendar">
<t>
When converting component, property and property parameter values, 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 <xref target="RFC5545"/>.
</t>
<t>
Backslash escaping and line folding MUST be applied to the resulting
iCalendar data as required by <xref target="RFC5545"/>.
</t>
<t>Non-binary value types MUST NOT be base64 encoded.</t>
<t>
jCal properties that do not specify the default type for the iCalendar
property MUST add a VALUE parameter when converting to iCalendar. jCal
properties that specify the default type SHOULD NOT add a VALUE
parameter.
</t>
</section>
<section title="Handling Unrecognized Properties or Parameters" anchor="unrecognized">
<t>
In iCalendar, properties have a default value type specified by their
definition, e.g. "SUMMARY"'s value type is "TEXT" and "DURATION"'s is
"DURATION". When a property uses its default value type, the "VALUE"
property parameter does not need to be specified on the property.
</t>
<t>
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. As a result, the following rules are applied when dealing
with unrecognized properties and property parameters:
<list style="symbols">
<t>When converting iCalendar into jCal:
<list style="symbols">
<t>
Any property that does not include a "VALUE" property parameter
and whose default value type is not known, MUST be converted to a
string object. The content of that string is the unprocessed
value text.
</t>
<t>
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.
</t>
</list>
</t>
<t>When converting jCal into iCalendar:
<list style="symbols">
<t>
Since jCal always explicitly specifies the value type, it can
always be converted to iCalendar using the VALUE parameter.
</t>
<t>
If the value type specified in jCal matches the default value
type in iCalendar, the VALUE parameter SHOULD be omitted.
</t>
</list>
</t>
</list>
</t>
<t>
Example: 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.
</t>
<figure><preamble>iCalendar:</preamble><artwork><![CDATA[
X-PROPERTY:20110512T120000Z
]]></artwork></figure>
<figure><preamble>jCal:</preamble><artwork><![CDATA[
...
["x-property", {}, "text", "20110512T120000Z"],
...
]]></artwork></figure>
<t>
Example: The following is an example of a jCal property (where the
corresponding iCalendar property uses a "INTEGER" value as its
default), and the equivalent iCalendar representation of that
property.
</t>
<figure><preamble>jCal:</preamble><artwork><![CDATA[
...
["percent-complete", {}, "integer", 95],
...
]]></artwork></figure>
<figure><preamble>iCalendar:</preamble><artwork><![CDATA[
PERCENT-COMPLETE:95
]]></artwork></figure>
<t>
Example: 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.
</t>
<figure><preamble>iCalendar:</preamble><artwork><![CDATA[
DTSTART;X-PARAM=30.3;VALUE=DATE:20110512
]]></artwork></figure>
<figure><preamble>jCal:</preamble><artwork><![CDATA[
...
["dtstart", { "x-param": "30.3" }, "date", "2011-05-12"],
...
]]></artwork></figure>
</section>
<section title="Implementation Status (to be removed prior to publication as an RFC)">
<t>
This section describes libraries known to implement this draft as per
<xref target='I-D.sheffer-running-code'/>.
<list style="numbers">
<t>
ICAL.js - Philipp Kewisch, James Lal. A JavaScript parser for iCalendar (rfc5545)
<list style="hanging">
<t hangText="Source:">https://github.com/kewisch/ical.js/</t>
<t hangText="Maturity:">production</t>
<t hangText="Coverage:">All aspects of this draft, up to version 01. Includes an online validator. (as of rev 847c67c501, 2013-02-14)</t>
<t hangText="Licensing:">MPL, Mozilla Public License 2.0</t>
</list>
</t>
<t>
Py Calendar - Cyrus Daboo. iCalendar/vCard Library
<list style="hanging">
<t hangText="Source:">https://svn.calendarserver.org/repository/calendarserver/PyCalendar/branches/json/</t>
<t hangText="Maturity:">production</t>
<t hangText="Coverage:">All aspects of this draft, up to version 01.</t>
<t hangText="Licensing:">Apache License, Version 2.0</t>
</list>
</t>
</list>
</t>
<t>
Additionally, interoperability testing of this draft is an ongoing
effort under members of calconnect, the Calendaring and Scheduling
Consortium. CalDAV Vendors are looking into supporting this draft.
</t>
</section>
<section title="Security Considerations" anchor="security">
<t>
For security considerations specific to calendar data, see Section 7 of
<xref target="RFC5545"/>. Since this specification is a mapping from
iCalendar, no new security concerns are introduced related to calendar
data.
</t>
<t>
The use of JSON as a format does have security risks. Section 7 of
<xref target="RFC4627"/> discusses these risks.
</t>
</section>
<section title="IANA Considerations">
<t>
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.
<list style="hanging">
<t hangText="Type name:">application</t>
<t hangText="Subtype name:">calendar+json</t>
<t hangText="Required parameters:">none</t>
<t hangText="Optional parameters:">
method, component and optinfo as defined for the text/calendar
media type in <xref target="RFC5545"/>.
</t>
<t hangText="Encoding considerations:">
Same as encoding considerations of application/json as specified in
<xref target="RFC4627"/>.
</t>
<t hangText="Security considerations:">See <xref target="security"/>.</t>
<t hangText="Interoperability considerations:">
This media type provides an alternative format for iCalendar data
based on JSON.
</t>
<t hangText="Published specification:">This specification.</t>
<t hangText="Applications which 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.
</t>
<t hangText="Person & email address to contact for further information:">calsify@ietf.org</t>
<t hangText="Intended usage:">COMMON</t>
<t hangText="Restrictions on usage:">
There are no restrictions on where this media type can be used.
</t>
<t hangText="Author:">
See the "Author's Address" section of this document.
</t>
<t hangText="Change controller:">IETF</t>
</list>
</t>
</section>
<section title="Acknowledgments">
<t>
The authors would like to thank the following for their valuable
contributions: William Gill, Erwin Rehme, and Dave Thewlis. This
specification originated from the work of the XML-JSON technical
committee of the Calendaring and Scheduling Consortium.
</t>
</section>
</middle>
<back>
<references title="Normative References">
&rfc2119;
&rfc5234;
&rfc4648;
&rfc5545;
&rfc6321;
&rfc3986;
<reference anchor="ISO.8601.2004">
<front>
<title>
"Data elements and interchange formats -- Information interchange
-- Representation of dates and times"
</title>
<author>
<organization>International Organization for Standardization</organization>
</author>
<date year="2004" month="12"/>
</front>
<seriesInfo name="ISO" value="8601"/>
</reference>
</references>
<references title="Informative References">
&rfc4627;
&I-D.sheffer-running-code;
<reference anchor="calconnect-artifacts"
target="http://www.calconnect.org/artifacts.shtml">
<front>
<title>Code Artifacts and Schemas</title>
<author>
<organization>The Calendaring and Scheduling Consortium</organization>
</author>
</front>
</reference>
</references>
<section anchor="schema" title="ABNF Schema">
<t>
Below is an ABNF schema as per <xref target="RFC5234"/> for iCalendar
in JSON. ABNF Symbols not described here are taken from
<xref target="RFC4627"/>. The schema is non-normative and given for
reference only.
</t>
<t>
The numeric section numbers given in the comments refer to section in
<xref target="RFC5545"/>. 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 <xref target="RFC5545"/>.
</t>
<t>
Additional schemas may be available on the internet at
<xref target="calconnect-artifacts"/>.
</t>
<figure><artwork><![CDATA[
; An iCalendar Stream is an array with the first element being the
; string "icalendar". All remaining elements are jcalobjects.
jcalstream = begin-array
DQUOTE "icalendar" DQUOTE
*(value-separator jcalobject)
end-array
; 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
propery-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 = string / number / boolean
; The jCal params-object is a JSON object which 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
; 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 / "-")
]]></artwork></figure>
</section>
<section title="Examples">
<t>
This section contains two examples of iCalendar objects with their jCal
representation.
</t>
<section title="Example 1">
<section title="iCalendar Data">
<figure><artwork><![CDATA[
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
]]></artwork></figure>
</section>
<section title="jCal Data">
<figure><artwork><![CDATA[
["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"],
],
[]
]
]
]
]]></artwork></figure>
</section>
</section>
<section title="Example 2">
<section title="iCalendar Data">
<figure><artwork><![CDATA[
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@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@example.com
END:VEVENT
END:VCALENDAR
]]></artwork></figure>
</section>
<section title="jCal Data">
<figure><artwork><![CDATA[
["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"]
],
[]
]
]
],
["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 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@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"
],
["summary", {}, "text", "Event #2"],
["uid", {}, "text", "00959BC664CA650E933C892C@example.com"]
],
[]
]
]
]
]]></artwork></figure>
</section>
</section>
</section>
<section title='Change History (to be removed prior to publication as an RFC)'>
<t>
<list style="hanging">
<t hangText="draft-kewisch-et-al-icalendar-in-json-01">
<list style="symbols">
<t>
Added information on how to handle multi-value parameter. The
decision leads to a cleaner draft for a similar proposal for
vcard.
</t>
<t>
Removed the open discussion point section regarding the mime
media type in favor of adding one.
</t>
<t>
Minor corrections in wording and typo fixes.
</t>
</list>
</t>
<t hangText="draft-kewisch-et-al-icalendar-in-json-02">
<list style="symbols">
<t>
Added implementation status section.
</t>
<t>
Removed various text tables that just show a conversion from
uppercase to lowercase.
</t>
<t>
Changed value format for RECUR and PERIOD types
</t>
<t>
Minor corrections in wording and typo fixes.
</t>
</list>
</t>
<t hangText="draft-ietf-jcardcal-jcal-00">
<list style="symbols">
<t>
Pubication as a WG draft
</t>
</list>
</t>
</list>
</t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 02:48:11 |