Network Working Group R. Menderico, Ed.
Internet-Draft P. Schlup
Intended status: Informational L. Kristiansen
Expires: May 27, 2016 Google
November 24, 2015

v-event URI: An URI scheme for events.


This document defines the format of Uniform Resource Identifiers (URIs) for calendar events, allowing users to add these events to their calendar application from any source that defines them, like web sites and printed QR codes

Status of This Memo

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

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at

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

This Internet-Draft will expire on May 27, 2016.

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 ( 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.

1. Introduction

Calendar users currently often do not have the ability to quickly add an event to theirdefault calendar app, when encountering event data on a webpage, poster or mobile apps. In this sense events have fallen behind other real world entities, like e-mail [RFC6068] and geo coordinates [RFC5870] which allow for performing actions in default apps when encountering these entities anywhere. This recommendations document addresses the problem by proposing best practices when embedding and publishing calendar data. We believe that using a standardized URI scheme for event publishing will make populating of users’ calendars much simpler, will make developers’ lives easier and will increase calendar apps usage in general. A major additional benefit of URIs is sharing of events on physical media (for example via QR codes) or via URL.

2. Motivation and related work

2.1. Current event publishing practices

Many ways to add events to calendar apps have been developed due to the lack of standardization. While these solve the basic need of sharing events, it does so with limited reach, are harder to use and limit adoption by new providers. We will briefly mention four common ways: using a download link, hCalendar embedding, using VEVENTs in QR codes and provider specific buttons.

2.1.1. Publish a link to an iCalendar file

A simple way to publish an event i sto share a link that points to an iCalendar [RFC5545] file and provide a link to the user for downloading it. In an ideal world, a user would click on the link pointing to a file, the browser would recognize this link as a calendar file and redirect it to the proper calendar application, which would display the event information to the user, allowing simple edit actions, and saving it to the calendar.

There are many problems with this method. Files must be hosted in a server, which is not always feasible or easy, and need to be maintained separately from the web pages they are linked from. This poses unnecessary difficulty for blog and CMS users, especially when compared to linking to email addresses or other web pages.

Furthermore, ICS files might not be recognized by the browser or operating system, or the user might use a web-based calendar app instead of a native one. Files might also contain malware and pose additional risk, with some end users avoiding downloaded files altogether.

One additional problem is coupling of the file and the entity it represents. Currently the user needs to manually keep the event file and all the links and descriptions with the same information in the links about in sync. It is preferable to have this information close together. Ideally the same tools used to generate a page could be used to assure a link and the text information being displayed are synchronized.

2.1.2. Current QR code implementations

Several QR code readers ([ZXing][i-nigma]) support calendar events to be embedded in QR codes, but they have their own non-standard implementation, usually a single VEVENT iCalendar component. They work well on the mobile platform but rely on OS internals [CalendarContract] to add the event to the calendar.

While QR code does not dictate a format for calendar events, most readers implement the URI standard schemes and would benefit from this proposal.

2.1.3. hCalendar

hCalendar [hCalendar] is a microformat for events that can be used to annotate a web page or another document and indicate to readers that an event is present. While microformats are useful for parsing and styling, they are not meant to be used as links to an event and need to be used in conjunction with the external ICS file method or a proprietary browser extension. They usually require a complex interaction between the website and the calendar application to get it right. This also makes it not ideal for QR scanning, since the annotations were not designed to represent the whole content of a document. They are more appropriate as an annotation on a previously structured text.

2.1.4. Custom calendar application link

Several calendar systems provide a proprietary URL for event creation ([AddThisEvent][GoogleCalendar]). However, due to lack of standards, applications must implement and link to these separately. This burdens both content creators and web site users: content creators must maintain individual links for each calendar application provider, and end users must find and choose the appropriate one for their own case. This consumes precious space on the page and requires understanding of several APIs, making it difficult for a developer that wants to just publish a simple event. Furthermore, it's impossible to link to all calendar app providers, requiring a combination of this method with the ICS file hosting method.

2.2. Alternative implementations

Tthough not currently used by the most popular calendar applications, other implementations could theoretically converge into a standard. We will talk briefly about the calendar mime type in combination with RegisterContentHandler, data URI scheme and a custom URI scheme.

2.2.1. text/calendar MIME type in combination with RegisterContentHandler

One way to use iCal files and avoid downloading it would be registering a handler for calendar MIME [RFC6838] types (text/calendar [RFC5545]). Operating Systems know how to handle mime type properly, and are able to redirect it to the right application. Web browsers, on the other hand, still have limited capability to handle it. The method RegisterContentHandler [RegisterContentHandler] allows to send a given mime type file directly to a website, but so far has only been implemented by Mozilla and only supports atom/xml MIME type.

2.2.2. data URI

Data URIs [RFC2397] can be used to replace an external file in an HTML. One advantage is that it gets embedded into the HTML and removes the need of an external file, either a real file or emulated. Unfortunately, browsers treat these the same way they treat files, therefore they would still need to be downloaded or properly redirected to an application, and RegisterContentHandler would need to be implemented by browsers and QR readers before this approach can be used.

2.2.3. Custom URI scheme

A custom URI scheme for events would behave similar to e-mail [RFC6068] geo [RFC5870] and other schemes, where the resource (e-mail, geo, or in this case, the event) is properly identified and follows a specified protocol. An HTML page could publish an event using this scheme (as it would with any other link format) or a print page could embed it in an 2D-barcode. The user would have several options of handling it: opening his application of choice, or redirecting to a previously registered website [RegisterProtocolHandler]. Support for URI schemes is widespread, most Operating Systems and browsers support it and its associated APIs.

3. The v-event URI scheme

In this section we will propose a custom URI schema that could be implemented easily by any calendar application and developers alike. We will also discuss some of its special requirements and provide several examples

3.1. Syntax

	      v-event:[base64,] icalendar event

The v-event URI scheme syntax is based on both iCalendar [RFC5545] and data URI scheme [RFC2397], we intend to make it trivial for people used to iCalendar syntax to implement this scheme, and also make it consistent with other existing URI formats. The basic syntax for the URI is: [RFC3986], the whole URI needs to follow the percent encoding escaping. The iCalendar event can be either written as an escaped text or, if base64 is specified, converted to base64. Calendar applications MUST recognize both formats to be compliant with this URI scheme For the iCalendar the following restrictions apply:

3.2. URI Registration

The v-event URI will be registered with IANA as a provisional scheme, to allow all calendar applications to use it. The authors are not pursuing a permanent registration because they believe that this scheme may be deprecated in the future in favor of a DATA URI scheme, when browser implementations support that scheme with the same level regular URIs are supported.

The following are the fields required by RFC 7595 [RFC7595]

3.3. Examples

3.3.1. V-Event URI 101 - a simple example

		SUMMARY:James T. Kirk's birthday

In this first example, we will start with a simple event that follows all the recommendations above. This event starts on March 23rd, 2233, at midnight and finishes at 11:59 PM at the same day, in Eastern Time. It has been last modified on April 1st, 2015. From these, we have the following icalendar event:

3.3.2. Base 64 encoding


As mentioned before, calendar applications also need to be able to interpret base64 versions of the URIs, the example below represents the same event described in Section 3.3.1:

3.3.3. Source link
		SUMMARY:James T. Kirk's birthday

A source link should be added if the URI cannot fit all information about a given event or for any other reason you believe that an ICS file may better suit your needs. For the same example in Section 3.3.1, we can add the source URL ‘’ and we would obtain the following URIs:

3.3.4. QR code examples

A QR code containing the first example (Section 3.3.1) can be found at It has been generated using the ZXing barcode generator([ZXing]).

3.4. Application requirements and best practices

3.4.1. Event publisher

For event publishers, the following extra requirements must me met:

There are also some best practices that need to be followed by these publishers in regard to UID generation and the LAST-MODIFIED field, which are discussed in the following subsections. UID generation

According to RFC 5545 [RFC5545], every event MUST be published with an UID, so calendar applications can detect multiple occurrences of it and remove them. The UID MUST be a globally unique identifier, and the system generating the event must guarantee it is unique. The recommended way is to generate an id that is internal to a given system (for instance, a database incremental id, an UUID, or something similar) and append the domain name or IP address at the end, separating them by an @.

For example, all these are valid unique ids for domain that fit this recommendation and also RFC 5545 [RFC5545]:

3.4.2. Calendar applications requirements

For calendar data handlers, the following set of extra rules apply:

4. Security and privacy considerations

Below are some guidelines applications implementing v-event URI generators and parsers need to follow in order to avoid security and privacy issues.

5. Future work

As mentioned in section Section 2.2.2, the data URI scheme would be a nice fit for providing an uniform format for specifying events in the Web and printed media (QR and other formats), and we have only chosen another method because data support is currently limited.

We plan to update this document with a data URI compatible format as soon as its support is more widespread, allowing it to be used by native applications, browser applications and physical media with the same support currently available for regular URIs. The format specified here is compatible with data URI and minimal changes would be needed to convert from one format to another.

6. Acknowledgements

The authors would like to thank the members of CalConnect TC-EVENTPUB committee for its contributions to this document, particularly Dave Thewlis, Cyrus Daboo and Thomas Schaefer.

7. References

[AddThisEvent] AddThisEvent, "AddThisEvent", 2012.

Last checked in August 26, 2015

[CalConnect] CalConnect, "CalConnect: The Calendaring and Scheduling Consortium", January 2004.

Last checked in November 1, 2015

[CalendarContract] Google Inc., "Android Calendar Contract", October 2011.

Last checked in August 26, 2015

[CalDavExtensions] Daboo, C., "New Properties for iCalendar", April 2015.

Last checked in August 26, 2015

[GoogleCalendar] Google Inc., "Google Calendar", April 2006.

Last checked in August 26, 2015

[hCalendar] Çelik, T. and B. Suda, "hCalendar Microformat", June 2005.

Last checked in July 27, 2015

[i-nigma] 3GVision, "i-nigma", August 2015.

Last checked in August 27, 2015

[RFC2397] Masinter, L., "The "data" URL scheme", RFC 2397, DOI 10.17487/RFC2397, August 1998.
[RFC3986] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005.
[RFC4122] Leach, P., Mealling, M. and R. Salz, "A Universally Unique IDentifier (UUID) URN Namespace", RFC 4122, DOI 10.17487/RFC4122, July 2005.
[RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 5545, DOI 10.17487/RFC5545, September 2009.
[RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource Identifier for Geographic Locations ('geo' URI)", RFC 5870, DOI 10.17487/RFC5870, June 2010.
[RFC6068] Duerst, M., Masinter, L. and J. Zawinski, "The 'mailto' URI Scheme", RFC 6068, DOI 10.17487/RFC6068, October 2010.
[RFC6838] Freed, N., Klensin, J. and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013.
[tz] IANA, "Time Zone Database", 1986.

Last checked in August 27, 2015

[RFC7595] Thaler, D., Hansen, T. and T. Hardie, "Guidelines and Registration Procedures for URI Schemes", BCP 35, RFC 7595, DOI 10.17487/RFC7595, June 2015.
[ZXing] Owen, S., "ZXing Project", November 2007.

Last checked in July 27, 2015

Authors' Addresses

Raphael Menderico (editor) Google Inc. Brandschenkestrasse 110 Zurich, ZH 8002 CH EMail: URI:
Paulo Schlup Google Inc. Brandschenkestrasse 110 Zurich, ZH 8002 CH EMail: URI:
Lucia Kristiansen Google Inc. Brandschenkestrasse 110 Zurich, ZH 8002 CH EMail: URI:

Table of Contents