diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..b284020 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,82 @@ + +[build-system] +requires = ["setuptools"] +build-backend = "setuptools.build_meta" + +[project] +name = "vobject" +authors = [ + {name = "Jeffrey Harris", email = "jeffrey@osafoundation.org"}, +] +maintainers = [ + {name = "David Arnold", email = "d+vobject@pobox.com"}, +] +description = "A full-featured Python package for parsing and creating iCalendar and vCard files" +readme = "README.md" +requires-python = "== 2.7, >= 3.8" +keywords = ["vobject", "icalendar", "vcard", "vcalendar", "ics", "vcs", "vcf", "hcalendar"] +license = {file = "LICENSE-2.0.txt"} +classifiers = [ + # Convert 0.9.x to "6 - Mature" once v1.0 is out + "Development Status :: 5 - Production/Stable", + "Environment :: Console", + "Intended Audience :: Developers", + "License :: OSI Approved :: Apache Software License", + "Natural Language :: English", + "Operating System :: OS Independent", + "Programming Language :: Python", + "Programming Language :: Python :: 2.7", + "Programming Language :: Python :: 3.8", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Topic :: Text Processing", + "Topic :: Software Development :: Libraries", + "Topic :: Software Development :: Libraries :: Python Modules", +] +dependencies = [ + "python-dateutil >= 2.4.0", + "six >= 1.16.0", +] +dynamic = ["version"] + +[project.scripts] +ics_diff = "vobject.ics_diff:main" +change_tz = "vobject.change_tz:main" + +[project.urls] +Homepage = "https://py-vobject.github.io" +Repository = "https://github.com/py-vobject/vobject" +Issues = "https://github.com/py-vobject/vobject/issues" +Changelog = "https://github/com/py-vobject/vobject/blob/master/CHANGELOG.md" + +[tool.setuptools] +packages = ["vobject"] + +[tool.setuptools.dynamic] +version = {attr = "vobject.__version__"} + +[tool.pylint.format] +max-line-length = "88" +disable = ["C0103", "C0301"] + +[tool.isort] +profile = "black" +multi_line_output = 3 + +[tool.flake8] +# Note: requires 'flake8.pyproject' module installed +max-line-length = 80 +extend-ignore = ["B950", "E203", "E266", "E501", "E701", "W503"] +exclude = [".git", "__pycache__", "venv*"] +per_file_ignores = [ + "*/__init__.py: F401", +] + +[tool.distutils.bdist_wheel] +# Request creation of a universal wheel (ie. py2.py3-none-any) +universal = true + +[tool.black] +target-version = ["py27", "py37", "py38", "py39", "py310"] diff --git a/requirements-dev.txt b/requirements-dev.txt index 28af6eb..8633e6e 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -1,6 +1,15 @@ +black[python2]==21.12b0 +build +click==8.0.2 coverage +flake8 +flake8-bugbear +flake8-pyproject +pylint python-dateutil >= 2.4.0 setuptools +sphinx +twine wheel pre-commit black diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index c648b1c..0000000 --- a/requirements.txt +++ /dev/null @@ -1 +0,0 @@ -python-dateutil >= 2.4.0 diff --git a/setup.py b/setup.py deleted file mode 100755 index 76bd4f3..0000000 --- a/setup.py +++ /dev/null @@ -1,62 +0,0 @@ -""" -VObject: module for reading vCard and vCalendar files - -Description ------------ - -Parses iCalendar and vCard files into Python data structures, decoding the -relevant encodings. Also serializes vobject data structures to iCalendar, vCard, -or (experimentally) hCalendar unicode strings. - -Requirements ------------- - -Requires python 2.7 or later, dateutil 2.4.0 or later and six. - -Recent changes --------------- - - Revert too-strict serialization of timestamp values - broke too many other - implementations - -For older changes, see - - http://py-vobject.github.io/vobject/#release-history or - - http://vobject.skyhouseconsulting.com/history.html -""" - -from setuptools import find_packages, setup - -doclines = (__doc__ or "").splitlines() - -setup( - name="vobject", - version="0.9.7", - author="Jeffrey Harris", - author_email="jeffrey@osafoundation.org", - maintainer="David Arnold", - maintainer_email="davida@pobox.com", - license="Apache", - zip_safe=True, - url="http://py-vobject.github.io/vobject/", - download_url="https://github.com/py-vobject/vobject/tarball/0.9.7", - bugtrack_url="https://github.com/py-vobject/vobject/issues", - entry_points={"console_scripts": ["ics_diff = vobject.ics_diff:main", "change_tz = vobject.change_tz:main"]}, - include_package_data=True, - install_requires=["python-dateutil >= 2.4.0", "six"], - platforms=["any"], - packages=find_packages(), - description="A full-featured Python package for parsing and creating " "iCalendar and vCard files", - long_description="\n".join(doclines[2:]), - keywords=["vobject", "icalendar", "vcard", "ics", "vcs", "hcalendar"], - test_suite="tests", - classifiers=""" - Development Status :: 5 - Production/Stable - Environment :: Console - Intended Audience :: Developers - License :: OSI Approved :: Apache Software License - Natural Language :: English - Operating System :: OS Independent - Programming Language :: Python - Programming Language :: Python :: 2.7 - Programming Language :: Python :: 3 - Topic :: Text Processing""".strip().splitlines(), -) diff --git a/specs/rfc2425-mime-directory.txt b/specs/rfc2425-mime-directory.txt new file mode 100644 index 0000000..2e37e24 --- /dev/null +++ b/specs/rfc2425-mime-directory.txt @@ -0,0 +1,1851 @@ + + + + + + +Network Working Group T. Howes +Request for Comments: 2425 M. Smith +Category: Standards Track Netscape Communications Corp. + F. Dawson + Lotus Development Corporation + September 1998 + + + A MIME Content-Type for Directory Information + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1998). All Rights Reserved. + +1. Abstract + + This document defines a MIME Content-Type for holding directory + information. The definition is independent of any particular + directory service or protocol. The text/directory Content-Type is + defined for holding a variety of directory information, for example, + name, or email address, or logo. The text/directory Content-Type can + also be used as the root body part in a multipart/related Content- + Type for handling more complicated situations, especially those in + which non-textual information that already has a natural MIME + representation, for example, a photograph or sound, is to be + represented. + + The text/directory Content-Type defines a general framework and + format for holding directory information in a simple "type:value" + form. We refer to "type" in this context meaning a property or + attribute with which the value is associated. Mechanisms are defined + to specify alternate languages, encodings and other meta-information. + This document also defines the procedure by which particular formats, + called profiles, for carrying application-specific information within + a text/directory Content-Type can be defined and registered, and the + conventions such formats must follow. It is expected that other + documents will be produced that define such formats for various + applications (e.g., white pages). + + + + + +Howes, et. al. Standards Track [Page 1] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + + 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 [RFC-2119]. + +2. Table of Contents + + Status of the Memo................................................ 1 + Copyright Notice.................................................. 1 + 1. Abstract...................................................... 1 + 2. Table of Contents............................................. 2 + 3. Need for a MIME Directory Type................................ 3 + 4. Overview...................................................... 4 + 5. The text/directory Content-Type............................... 4 + 5.1. MIME media type name........................................ 4 + 5.2. MIME subtype name........................................... 5 + 5.3. Required parameters......................................... 5 + 5.4. Optional parameters......................................... 5 + 5.5. Encoding considerations..................................... 5 + 5.6. Security considerations..................................... 6 + 5.7. Interoperability considerations............................. 6 + 5.8. Published specification..................................... 6 + 5.8.1. Line delimiting and folding............................... 6 + 5.8.2. ABNF content-type definition.............................. 7 + 5.8.3. Pre-defined Parameters.................................... 9 + 5.8.4. Pre-defined Value Types...................................11 + 5.9. Applications which use this media type......................14 + 5.10. Additional information.....................................14 + 5.11. Person & email address to contact for further information..14 + 5.12. Intended usage.............................................14 + 5.13. Author/Change controller...................................15 + 6. Predefined Types..............................................15 + 6.1. SOURCE Type Definition......................................15 + 6.2. NAME Type Definition........................................16 + 6.3. PROFILE Type Definition.....................................16 + 6.4. BEGIN Type Definition.......................................17 + 6.5. END Type Definition.........................................17 + 7. Use of the multipart/related Content-Type.....................18 + 8. Examples.......................................................18 + 8.1. Example 1...................................................19 + 8.2. Example 2...................................................19 + 8.3. Example 3...................................................20 + 8.4. Example 4...................................................21 + 9. Registration of new profiles..................................22 + 9.1. Define the profile..........................................22 + 9.2. Post the profile definition.................................23 + 9.3. Allow a comment period......................................23 + 9.4. Submit the profile for approval.............................23 + 10. Profile Change Control.......................................23 + + + +Howes, et. al. Standards Track [Page 2] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + + 11. Registration of new types....................................24 + 11.1. Define the type............................................24 + 11.2. Post the type definition...................................25 + 11.3. Allow a comment period.....................................25 + 11.4. Submit the type for approval...............................25 + 12. Type Change Control..........................................25 + 13. Registration of new parameters...............................26 + 13.1. Define the parameter.......................................26 + 13.2. Post the parameter definition..............................27 + 13.3. Allow a comment period.....................................27 + 13.4. Submit the parameter for approval..........................27 + 14. Parameter Change Control.....................................28 + 15. Registration of new value types..............................28 + 15.1. Define the value type......................................28 + 15.2. Post the value type definition.............................29 + 15.3. Allow a comment period.....................................29 + 15.4. Submit the value type for approval.........................29 + 16. Security Considerations......................................30 + 17. Acknowledgements..............................................30 + 18. References....................................................30 + 19. Authors' Addresses...........................................32 + 20. Full Copyright Statement......................................33 + +3. Need for a MIME Directory Type + + For purposes of this document, a directory is a special-purpose + database that contains typed information. A directory usually + supports both read and search of the information it contains, and can + support creation and modification of the information as well. + Directory information is usually accessed far more often than it is + updated. Directories can be local or global in scope. They can be + distributed or centralized. The information they contain can be + replicated, with weak or strong consistency requirements. + + There are several situations in which users of Internet mail might + wish to exchange directory information: the email analogy of a + "business card" exchange; the conveyance of directory information to + a user having only email access to the Internet; the provision of + machine-parseable address information when purchasing goods or + services over the Internet; etc. As MIME [RFC-2045, RFC-2046] is + used increasingly by other protocols, most notably HTTP, it can also + be useful for these protocols to carry directory information in MIME + format. Such a format, for example, could be used to represent URC + (uniform resource characteristics) information about resources on the + World Wide Web, or to provide a rudimentary directory service over + HTTP. + + + + + +Howes, et. al. Standards Track [Page 3] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + +4. Overview + + The scheme defined here for representing directory information in a + MIME Content-Type has two parts. First, the text/directory Content- + Type is defined for use in holding directory information within a + single body part, for example name, title, or email address. In its + simplest form, the format uses a "type:value" approach, which should + be easily parseable by existing MIME implementations and + understandable by users. More complicated situations can be + represented also. This document defines the general form the + information in the Content-Type should have, and the procedure by + which specific types and values (properties) for particular + applications can be defined. The framework is general enough to + handle information from any number of end directory services, + including LDAP [RFC-1777, RFC-1778], WHOIS++ [RFC-1835], and X.500 + [X500]. + + Directory entries can include far more than just textual information. + Some such information (e.g., an image or sound) overlaps with + predefined MIME Content-Types. In these cases it can be desirable to + include the information in its well-known MIME format. This situation + is handled by using a multipart/related Content-Type as defined in + [RFC-2112]. The root component of this type is a text/directory body + part specifying any in-line information, and for information + contained in other Content-Types, the Content-IDs (in URI form) of + those parts. + + In some applications, it can be useful to include a pointer (e.g, a + URI) to some directory information rather than the information + itself. This document defines a general mechanism for accomplishing + this. + +5. The text/directory Content-Type + + The text/directory Content-Type is used to hold basic directory + information and URIs referencing other information, including other + MIME body parts holding supplementary or non-textual directory + information, such as an image or sound. It is defined as follows, + using the MIME media type registration template from [RFC-2048]. + + To: ietf-types@uninett.no + Subject: Registration of MIME media type text/directory + +5.1. MIME media type name + + MIME media type name: text + + + + + +Howes, et. al. Standards Track [Page 4] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + +5.2. MIME subtype name + + MIME subtype name: directory + +5.3. Required parameters + + Required parameters: charset + + The "charset" parameter is as defined in [RFC-2046] for other body + parts. It is used to identify the default character set used within + the body part. + +5.4. Optional parameters + + Optional parameters: profile + + The "profile" parameter is used to convey the type(s) of entity(ies) + to which the directory information pertains and the likely set of + information associated with the entity(ies). It is intended only as a + guide to applications interpreting the information contained within + the body part. It SHOULD NOT be used to exclude or require particular + pieces of information unless a profile definition specifically calls + for this behavior. Unless specifically forbidden by a particular + profile definition, a text/directory content type can contain + arbitrary attribute/value pairs. + + The value of the "profile" parameter is defined as follows. Profile + names are case insensitive (i.e., the profile name "vCard" is the + same as "VCARD" and "vcard" and "vcArD"). + + profile = x-name / iana-token + + x-name = "x-" 1*(ALPHA / DIGIT / "-") + ; Names beginning with "x-" or "X-" are + ; reserved for experimental use not intended for released + ; products, or for use in bilateral agreements. + + iana-token = + +5.5. Encoding considerations + + The default encoding is 8bit. Otherwise, as specified by the + Content-Transfer-Encoding header field. + + + + + + +Howes, et. al. Standards Track [Page 5] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + +5.6. Security considerations + + Directory information can be public or it can be protected from + unauthorized access by the directory service in which it resides. + Once the information leaves its native service, there can be no + guarantee that the same care will be taken by all services handling + the information. Furthermore, this specification defines no access + control mechanism by which information can be protected, or by which + access control information can be conveyed. Note that the integrity + and privacy of a text/directory body part can be protected by + enclosing it within an appropriate MIME-based security mechanism. + +5.7. Interoperability considerations + + In order to make sense of directory information, applications must + share a common understanding of the types of information contained + within the Content-Type (the directory schema). This schema + information is not defined in this document, but rather in companion + documents (e.g., [MIME-VCARD]) that follow the requirements specified + in this document, or in bilateral agreements between communicating + parties. + +5.8. Published specification + + The text/directory Content-Type contains directory information, + typically pertaining to a single directory entity or group of + entities. The content consists of one or more lines in the format + given below. + +5.8.1. Line delimiting and folding + + Individual lines within the MIME text/directory Content Type body are + delimited by the [RFC-822] line break, which is a CRLF sequence + (ASCII decimal 13, followed by ASCII decimal 10). Long logical lines + of text can be split into a multiple-physical-line representation + using the following folding technique. + + A logical line MAY be continued on the next physical line anywhere + between two characters by inserting a CRLF immediately followed by a + single white space character (space, ASCII decimal 32, or horizontal + tab, ASCII decimal 9). At least one character must be present on the + folded line. Any sequence of CRLF followed immediately by a single + white space character is ignored (removed) when processing the + content type. For example the line: + + DESCRIPTION:This is a long description that exists on a long line. + + Can be represented as: + + + +Howes, et. al. Standards Track [Page 6] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + + DESCRIPTION:This is a long description + that exists on a long line. + + It could also be represented as: + + DESCRIPTION:This is a long descrip + tion that exists o + n a long line. + + The process of moving from this folded multiple-line representation + of a type definition to its single line representation is called + unfolding. Unfolding is accomplished by regarding CRLF immediately + followed by a white space character (namely HTAB ASCII decimal 9 or + SPACE ASCII decimal 32) as equivalent to no characters at all (i.e., + the CRLF and single white space character are removed). + +5.8.2. ABNF content-type definition + + The following ABNF uses the notation of RFC 2234, which also defines + CRLF, WSP, DQUOTE, VCHAR, ALPHA, and DIGIT. After the unfolding of + any folded lines as described above, the syntax for a line of this + content type is as follows: + + contentline = [group "."] name *(";" param) ":" value CRLF + ; When parsing a content line, folded lines MUST first + ; be unfolded according to the unfolding procedure + ; described above. + ; When generating a content line, lines longer than 75 + ; characters SHOULD be folded according to the folding + ; procedure described above. + + group = 1*(ALPHA / DIGIT / "-") + + name = x-name / iana-token + + iana-token = 1*(ALPHA / DIGIT / "-") + ; identifier registered with IANA + + x-name = "x-" 1*(ALPHA / DIGIT / "-") + ; Names that begin with "x-" or "X-" are + ; reserved for experimental use, not intended for released + ; products, or for use in bilateral agreements. + + param = param-name "=" param-value *("," param-value) + + param-name = x-name / iana-token + + param-value = ptext / quoted-string + + + +Howes, et. al. Standards Track [Page 7] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + + ptext = *SAFE-CHAR + + value = *VALUE-CHAR + / valuespec ; valuespec defined in section 5.8.4 + + quoted-string = DQUOTE *QSAFE-CHAR DQUOTE + + NON-ASCII = %x80-FF + ; use restricted by charset parameter + ; on outer MIME object (UTF-8 preferred) + + QSAFE-CHAR = WSP / %x21 / %x23-7E / NON-ASCII + ; Any character except CTLs, DQUOTE + + SAFE-CHAR = WSP / %x21 / %x23-2B / %x2D-39 / %x3C-7E / NON-ASCII + ; Any character except CTLs, DQUOTE, ";", ":", "," + + VALUE-CHAR = WSP / VCHAR / NON-ASCII + ; any textual character + + A line that begins with a white space character is a continuation of + the previous line, as described above. The white space character and + immediately preceeding CRLF should be discarded when reconstructing + the original line. Note that this line-folding convention differs + from that found in RFC 822, in that the sequence found + anywhere in the content indicates a continued line and should be + removed. + + Various type names and the format of the corresponding values are + defined as specified in Section 11. Specifications MAY impose + ordering on the type constructs within a body part, though none is + required by default. The various x-name constructs are used for + bilaterally-agreed upon type names, parameter names and parameter + values, or for use in experimental settings. + + Type names and parameter names are case insensitive (e.g., the type + name "fn" is the same as "FN" and "Fn"). Parameter values MAY be case + sensitive or case insensitive, depending on their definition. + + The group construct is used to group related attributes together. + The group name is a syntactic convention used to indicate that all + type names prefaced with the same group name SHOULD be grouped + together when displayed by an application. It has no other + significance. Implementations that do not understand or support + grouping MAY simply strip off any text before a "." to the left of + the type name and present the types and values as normal. + + + + + +Howes, et. al. Standards Track [Page 8] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + + Each attribute defined in the text/directory body MAY have multiple + values, if allowed in the definition of the profile in which the + attribute is used. The general rule for encoding multi-valued items + is to simply create a new content line for each value (including the + type name). However, it should be noted that some value types + support encoding multiple values in a single content line by + separating the values with a comma ",". This approach has been taken + for several of the content types defined below (date, time, integer, + float), for space-saving reasons. + +5.8.3. Pre-defined Parameters + + The following parameters and value types are defined for general use. + + predefined-param = encodingparm + / valuetypeparm + / languageparm + / contextparm + + encodingparm = "encoding" "=" encodingtype + + encodingtype = "b" ; from RFC 2047 + / iana-token ; registered as described in + ; section 15 of this document + + valuetypeparm = "value" "=" valuetype + + valuetype = "uri" ; genericurl from secion 5 of RFC 1738 + / "text" + / "date" + / "time" + / "date-time" ; date time + / "integer" + / "boolean" + / "float" + / x-name + / iana-token ; registered as described in + ; section 15 of this document + + languageparm = "language" "=" Language-Tag + ; Language-Tag is defined in section 2 of RFC 1766 + + contextparm = "context" "=" context + + context = x-name + / iana-token + + + + + +Howes, et. al. Standards Track [Page 9] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + + The "language" type parameter is used to identify data in multiple + languages. There is no concept of "default" language, except as + specified by any "Content-Language" MIME header parameter that is + present. The value of the "language" type parameter is a language + tag as defined in Section 2 of [RFC-1766]. + + The "context" type parameter is used to identify a context (e.g., a + protocol) used in interpreting the value. This is used, for example, + in the "source" type, defined below. + + The "encoding" type parameter is used to specify an alternate + encoding for a value. If the value contains a CRLF, it must be + encoded, since CRLF is used to separate lines in the content-type + itself. Currently, only the "b" encoding is supported. + + The "b" encoding can also be useful for binary values that are mixed + with other text information in the body part (e.g., a certificate). + Using a per-value "b" encoding in this case leaves the other + information in a more readable form. The encoded base 64 value can be + split across multiple physical lines in the content type by using the + line folding technique described above. + + The Content-Transfer-Encoding header field is used to specify the + encoding used for the body part as a whole. The "encoding" type + parameter is used to specify an encoding for a particular value + (e.g., a certificate). In this case, the Content-Transfer-Encoding + header might specify "8bit", while the one certificate value might + specify an encoding of "b" via an "encoding=b" type parameter. + + The Content-Transfer-Encoding and the encodings of individual types + given by the "encoding" type parameter are independent of one + another. When encoding a text/directory body part for transmission, + individual type encodings are performed first, then the entire body + part is encoded according to the Content-Transfer-Encoding. When + decoding a text/directory body part, the Content-Transfer-Encoding is + decoded first, and then any individual types with an "encoding" type + parameter are decoded. + + The "value" parameter is optional, and is used to identify the value + type (data type) and format of the value. The use of these + predefined formats is encouraged even if the value parameter is not + explicity used. By defining a standard set of value types and their + formats, existing parsing and processing code can be leveraged. + + Including the value type explicitly as part of each property provides + an extra hint to keep parsing simple and support more generalized + applications. For example a search engine would not have to know the + particular value types for all of the items for which it is + + + +Howes, et. al. Standards Track [Page 10] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + + searching. Because the value type is explicit in the definition, the + search engine could look for dates in any item type and provide + results that can still be interpreted. + +5.8.4. Pre-defined Value Types + + The format for values corresponding to the predefined valuetype + specifications given above are defined. + + valuespec = text-list + / genericurl ; from section 5 of RFC 1738 + / date-list + / time-list + / date-time-list + / boolean + / integer-list + / float-list + / iana-valuespec + + text-list = *TEXT-LIST-CHAR *("," *TEXT-LIST-CHAR) + + TEXT-LIST-CHAR = "\\" / "\," / "\n" + / + ; Backslashes, newlines, and commas must be encoded. + ; \n or \N can be used to encode a newline. + + date-list = date *("," date) + + time-list = time *("," time) + + date-time-list = date "T" time *("," date "T" time) + + boolean = "TRUE" / "FALSE" + + integer-list = integer *("," integer) + + integer = [sign] 1*DIGIT + + float-list = float *("," float) + + float = [sign] 1*DIGIT ["." 1*DIGIT] + + sign = "+" / "-" + + date = date-fullyear ["-"] date-month ["-"] date-mday + + date-fullyear = 4 DIGIT + + + + +Howes, et. al. Standards Track [Page 11] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + + date-month = 2 DIGIT ;01-12 + + date-mday = 2 DIGIT ;01-28, 01-29, 01-30, 01-31 + ;based on month/year + + time = time-hour [":"] time-minute [":"] time-second [time-secfrac] + [time-zone] + + time-hour = 2 DIGIT ;00-23 + + time-minute = 2 DIGIT ;00-59 + + time-second = 2 DIGIT ;00-60 (leap second) + + time-secfrac = "," 1*DIGIT + + time-zone = "Z" / time-numzone + + time-numzome = sign time-hour [":"] time-minute + + iana-valuespec = + + Some specific notes on the value types and formats: + + "text": The "text" value type should be used to identify values that + contain human-readable text. The character set and language in which + the text is represented is controlled by the charset content-header + and the language type parameter and content-header. + + Examples for "text": + this is a text value + this is one value,this is another + this is a single value\, with a comma encoded + + A formatted text line break in a text value type MUST be represented + as the character sequence backslash (ASCII decimal 92) followed by a + Latin small letter n (ASCII decimal 110) or a Latin capital letter N + (ASCII decimal 78), that is "\n" or "\N". + + For example a multiple line DESCRIPTION value of: + + Mythical Manager + Hyjinx Software Division + BabsCo, Inc. + + could be represented as: + + + +Howes, et. al. Standards Track [Page 12] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + + DESCRIPTION:Mythical Manager\nHyjinx Software Division\n + BabsCo\, Inc.\n + + demonstrating the \n literal formatted line break technique, the + CRLF-followed-by-space line folding technique, and the backslash + escape technique. + + "uri": The "uri" value type should be used to identify values that + are referenced by a URI (including a Content-ID URI), instead of + encoded in-line. These value references might be used if the value is + too large, or otherwise undesirable to include directly. The format + for the URI is as defined in RFC 1738. + + Examples for "uri": + http://www.foobar.com/my/picture.jpg + ldap://ldap.foobar.com/cn=babs%20jensen + + "date", "time", and "date-time": Each of these value types is based + on a subset of the definitions in ISO 8601 standard. Profiles MAY + place further restrictions on "date" and "time" values. Multiple + "date" and "time" values can be specified using the comma-separated + notation, unless restricted by a profile. + + Examples for "date": + 1985-04-12 + 1996-08-05,1996-11-11 + 19850412 + + Examples for "time": + 10:22:00 + 102200 + 10:22:00.33 + 10:22:00.33Z + 10:22:33,11:22:00 + 10:22:00-08:00 + + Examples for "date-time": + 1996-10-22T14:00:00Z + 1996-08-11T12:34:56Z + 19960811T123456Z + 1996-10-22T14:00:00Z,1996-08-11T12:34:56Z + + "boolean": The "boolean" value type is used to express boolen values. + These values are case insensitive. + + Examples: TRUE + false + True + + + +Howes, et. al. Standards Track [Page 13] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + + "integer": The "integer" value type is used to express signed + integers in decimal format. If sign is not specified, the value is + assumed positive "+". Multiple "integer" values can be specified + using the comma-separated notation, unless restricted by a profile. + + Examples: 1234567890 + -1234556790 + +1234556790,432109876 + + "float": The "float" value type is used to express real numbers. If + sign is not specified, the value is assumed positive "+". Multiple + "float" values can be specified using the comma-separated notation, + unless restricted by a profile. + + Examples: 20.30 + 1000000.0000001 + 1.333,3.14 + +5.9. Applications which use this media type + + Applications which use this media type: Various + +5.10. Additional information + + Additional information: None + +5.11. Person & email address to contact for further information + + Tim Howes + Netscape Communications Corp. + 501 East Middlefield Rd. + Mountain View, CA 94041 + USA + howes@netscape.com + +1 415 937 3419 + +5.12. Intended usage + + Intended usage: COMMON + + + + + + + + + + + + +Howes, et. al. Standards Track [Page 14] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + +5.13. Author/Change controller + + Tim Howes + Netscape Communications Corp. + 501 East Middlefield Rd. + Mountain View, CA 94041 + USA + howes@netscape.com + +1 415 937 3419 + + Mark Smith + Netscape Communications Corp. + 501 East Middlefield Rd. + Mountain View, CA 94041 + USA + mcs@netscape.com + +1 415 937 3477 + + Frank Dawson + Lotus Development Corporation + 6544 Battleford Drive + Raleigh, NC 27613-3502 + USA + frank_dawson@lotus.com + +1-919-676-9515 + +6. Predefined Types + + The following types are generally useful regardless of the profile + being carried and are defined below using the text/directory MIME + type registration template defined in Section 11.1 of this document. + These types MAY be included in any profile, unless explicitly + forbidden in the profile definition. + +6.1. SOURCE Type Definition + + To: ietf-mime-direct@imc.org + Subject: Registration of text/directory MIME type SOURCE + + Type name: SOURCE + + Type purpose: To identify the source of directory information + contained in the content type. + + Type encoding: 8bit + + Type valuetype: uri + + + + +Howes, et. al. Standards Track [Page 15] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + + Type special notes: The SOURCE type is used to provide the means by + which applications knowledgable in the given directory service + protocol can obtain additional or more up-to-date information from + the directory service. It contains a URI as defined in [RFC-1738] + and/or other information referencing the directory entity or entities + to which the information pertains. When directory information is + available from more than one source, the sending entity can pick what + it considers to be the best source, or multiple SOURCE types can be + included. The interpretation of the value for a SOURCE type can + depend on the setting of the CONTEXT type parameter. The value of the + CONTEXT type parameter MUST be compatible with the value of the uri + prefix. + + Type example: + SOURCE;CONTEXT=LDAP:ldap://ldap.host/cn=Babs%20Jensen, + %20o=Babsco,%20c=US + +6.2. NAME Type Definition + + To: ietf-mime-direct@imc.org + Subject: Registration of text/directory MIME type NAME + + Type name: NAME + + Type purpose: To identify the displayable name of the directory + entity to which information in the content type pertains. + + Type encoding: 8bit + + Type valuetype: text + + Type special notes: The NAME type is used to convey the display name + of the entity to which the directory information pertains. + + Type example: + NAME:Babs Jensen's Contact Information + +6.3. PROFILE Type Definition + + To: ietf-mime-direct@imc.org + Subject: Registration of text/directory MIME type PROFILE + + Type name: PROFILE + + Type purpose: To identify the type of directory entity to which + information in the content type pertains. + + Type encoding: 8bit + + + +Howes, et. al. Standards Track [Page 16] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + + Type valuetype: A profile name, registered as described in Section 9 + of this document or bilaterally agreed upon as described in Section + 5. + + Type special notes: The PROFILE type is used to convey the type of + the entity to which the directory information in the rest of the body + part pertains. It should be the same as the "profile" header + parameter, if present. + + Type example: + PROFILE:vCard + +6.4. BEGIN Type Definition + + To: ietf-mime-direct@imc.org + Subject: Registration of text/directory MIME type BEGIN + + Type name: BEGIN + + Type purpose: To denote the beginning of a syntactic entity within a + text/directory content-type. + + Type encoding: 8bit + + Type valuetype: text, containing a profile name, registered as + described in Section 9 of this document or bilaterally-agreed upon as + described in Section 5. + + Type special notes: The BEGIN type is used in conjunction with the + END type to delimit a profile containing a related set of properties + within an text/directory content-type. This construct can be used + instead of or in addition to wrapping separate sets of information + inside additional MIME headers. It is provided for applications that + wish to define content that can contain multiple entities within the + same text/directory content-type or to define content that can be + identifiable outside of a MIME environment. + + Type example: + BEGIN:VCARD + +6.5. END Type Definition + + To: ietf-mime-direct@imc.org + Subject: Registration of text/directory MIME type END + + Type name: END + + + + + +Howes, et. al. Standards Track [Page 17] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + + Type purpose: To denote the end of a syntactic entity within a + text/directory content-type. + + Type encoding: 8bit + + Type valuetype: text, containing a profile name, registered as + described in Section 9 of this document or bilaterally-agreed upon as + described in Section 5. + + Type special notes: The END type is used in conjunction with the + BEGIN type to delimit a profile containing a related set of + properties within an text/directory content-type. This construct can + be used instead of or in addition to wrapping separate sets of + information inside additional MIME headers. It is provided for + applications that wish to define content that can contain multiple + entities within the same text/directory content-type or to define + content that can be identifiable outside of a MIME environment. + + Type example: + END: VCARD + +7. Use of the multipart/related Content-Type + + The multipart/related Content-Type can be used to hold directory + information comprised of both text and non-text information or + directory information that already has a natural MIME representation. + The root body part within the multipart/related body part is + specified as defined in [RFC-2112] by a "start" parameter, or it is + the first body part in the absence of such a parameter. The root + body part must have a Content-Type of "text/directory". This part + holds inline information and makes reference to subsequent body parts + holding additional text or non-text directory information via their + Content-ID URIs as explained in Section 5. + + The body parts referred to do not have to be in any particular order, + except as noted above for the root body part. + +8. Examples + + The following examples are for illustrative purposes only and are not + part of the definition. + + + + + + + + + + +Howes, et. al. Standards Track [Page 18] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + +8.1. Example 1 + + The first example illustrates simple use of the text/directory + Content-Type. Note that no "profile" parameter is given, so an + application may not know what kind of directory entity the + information applies to. Note also the use of both hypothetical + official and bilaterally agreed upon types. + + From: Whomever@wherever.com + To: Someone@somewhere.com + Subject: whatever + MIME-Version: 1.0 + Message-ID: + Content-Type: text/directory + Content-ID: + + cn:Babs Jensen + cn:Barbara J Jensen + sn:Jensen + email:babs@umich.edu + phone:+1 313 747-4454 + x-id:1234567890 + +8.2. Example 2 + + The next example illustrates the use of the Quoted-Printable transfer + encoding defined in [RFC 2045] to include non-ASCII character in some + of the information returned, and the use of the optional "name" and + "source" types. It also illustrates the use of an "encoding" type + parameter to encode a certificate value in "b". A "vCard" profile + [MIME- VCARD] is used for the example. + +Content-Type: text/directory; + charset="iso-8859-1"; + profile="vCard" +Content-ID: +Content-Transfer-Encoding: Quoted-Printable + +begin:VCARD +source:ldap://cn=bjorn%20Jensen, o=university%20of%20Michigan, c=US +name:Bjorn Jensen +fn:Bj=F8rn Jensen +n:Jensen;Bj=F8rn +email;type=internet:bjorn@umich.edu +tel;type=work,voice,msg:+1 313 747-4454 +key;type=x509;encoding=B:dGhpcyBjb3VsZCBiZSAKbXkgY2VydGlmaWNhdGUK +end:VCARD + + + + +Howes, et. al. Standards Track [Page 19] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + +8.3. Example 3 + + The next example illustrates the use of multi-valued type parameters, + the "language" type parameter, the "value" type parameter, folding of + long lines, the \n encoding for formatted lines, attribute grouping, + and the inline "b" encoding. A "vCard" profile [MIME-VCARD] is used + for the example. + +Content-Type: text/directory; profile="vcard"; charset=iso-8859-1 +Content-ID: +Content-Transfer-Encoding: Quoted-Printable + +begin:vcard +source:ldap://cn=Meister%20Berger,o=Universitaet%20Goerlitz,c=DE +name:Meister Berger +fn:Meister Berger +n:Berger;Meister +bday;value=date:1963-09-21 +o:Universit=E6t G=F6rlitz +title:Mayor +title;language=de;value=text:Burgermeister +note:The Mayor of the great city of + Goerlitz in the great country of Germany. +email;internet:mb@goerlitz.de +home.tel;type=fax,voice,msg:+49 3581 123456 +home.label:Hufenshlagel 1234\n + 02828 Goerlitz\n + Deutschland +key;type=X509;encoding=b:MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQ + AwdzELMAkGA1UEBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zI + ENvcnBvcmF0aW9uMRwwGgYDVQQLExNJbmZvcm1hdGlvbiBTeXN0ZW1zMRwwGgYDVQQD + ExNyb290Y2EubmV0c2NhcGUuY29tMB4XDTk3MDYwNjE5NDc1OVoXDTk3MTIwMzE5NDc + 1OVowgYkxCzAJBgNVBAYTAlVTMSYwJAYDVQQKEx1OZXRzY2FwZSBDb21tdW5pY2F0aW + 9ucyBDb3JwLjEYMBYGA1UEAxMPVGltb3RoeSBBIEhvd2VzMSEwHwYJKoZIhvcNAQkBF + hJob3dlc0BuZXRzY2FwZS5jb20xFTATBgoJkiaJk/IsZAEBEwVob3dlczBcMA0GCSqG + SIb3DQEBAQUAA0sAMEgCQQC0JZf6wkg8pLMXHHCUvMfL5H6zjSk4vTTXZpYyrdN2dXc + oX49LKiOmgeJSzoiFKHtLOIboyludF90CgqcxtwKnAgMBAAGjNjA0MBEGCWCGSAGG+E + IBAQQEAwIAoDAfBgNVHSMEGDAWgBT84FToB/GV3jr3mcau+hUMbsQukjANBgkqhkiG9 + w0BAQQFAAOBgQBexv7o7mi3PLXadkmNP9LcIPmx93HGp0Kgyx1jIVMyNgsemeAwBM+M + SlhMfcpbTrONwNjZYW8vJDSoi//yrZlVt9bJbs7MNYZVsyF1unsqaln4/vy6Uawfg8V + UMk1U7jt8LYpo4YULU7UZHPYVUaSgVttImOHZIKi4hlPXBOhcUQ== +end:vcard + + + + + + + + + +Howes, et. al. Standards Track [Page 20] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + +8.4. Example 4 + + The final example illustrates the use of the multipart/related + Content-Type to include non-textual directory data via the "uri" + encoding to refer to other body parts within the same message, or to + external values. Note that no "profile" parameter is given, so an + application may not know what kind of directory entity the + information applies to. Note also the use of both hypothetical + official and bilaterally agreed upon types. + +Content-Type: multipart/related; + boundary=woof; + type="text/directory"; + start="" +Content-ID: + +--woof +Content-Type: text/directory; charset="iso-8859-1" +Content-ID: +Content-Transfer-Encoding: Quoted-Printable + +source:ldap://cn=Bjorn%20Jensen,o=University%20of%20Michigan,c=US +cn:Bj=F8rn Jensen +sn:Jensen +email:bjorn@umich.edu +image;value=uri:cid:id6@host.com +image;value=uri;format=jpeg:ftp://some.host/some/path.jpg +sound;value=uri:cid:id7@host.com +phone:+1 313 747-4454 + +--woof +Content-Type: image/jpeg +Content-ID: + +<...image data...> + +--woof +Content-Type: message/external-body; + name="myvoice.au"; + site="myhost.com"; + access-type=ANON-FTP; + directory="pub/myname"; + mode="image" + +Content-Type: audio/basic +Content-ID: + +--woof-- + + + +Howes, et. al. Standards Track [Page 21] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + +9. Registration of new profiles + + This section defines procedures by which new profiles are registered + with the IANA and made available to the Internet community. Note that + non-IANA profiles can be used by bilateral agreement, provided the + associated profile names follow the "X-" convention defined above. + + The procedures defined here are designed to allow public comment and + review of new profiles, while posing only a small impediment to the + definition of new profiles. + + Registration of a new profile is accomplished by the following steps. + +9.1. Define the profile + + A profile is defined by completing the following template. + + To: ietf-mime-direct@imc.org + Subject: Registration of text/directory MIME profile XXX + + Profile name: + + Profile purpose: + + Profile types: + + Profile special notes (optional): + + Intended usage: (one of COMMON, LIMITED USE or OBSOLETE) + + The explanation of what goes in each field in the template follows. + + Profile name: The name of the profile as it will appear in the + text/directory MIME Content-Type "profile" header parameter, or the + predefined "profile" type name. + + Profile purpose: The purpose of the profile (e.g., to represent + information about people, printers, documents, etc.). Give a short + but clear description. + + Profile types: The list of types associated with the profile. This + list of types is to be expected but not required in the profile, + unless otherwise noted in the profile definition. Other types not + mentioned in the profile definition MAY also be present. Note that + any new types referenced by the profile MUST be defined separately as + described in Section 10. + + + + + +Howes, et. al. Standards Track [Page 22] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + + Profile special notes: Any special notes about the profile, how it is + to be used, etc. This section of the template can also be used to + define an ordering on the types that appear in the Content-Type, if + such an ordering is required. + +9.2. Post the profile definition + + The profile description must be posted to the new profile discussion + list, ietf-mime-direct@imc.org + +9.3. Allow a comment period + + Discussion on the new profile must be allowed to take place on the + list for a minimum of two weeks. Consensus must be reached on the + profile before proceeding to step 4. + +9.4. Submit the profile for approval + + Once the two-week comment period has elapsed, and the proposer is + convinced consensus has been reached on the profile, the registration + application should be submitted to the Profile Reviewer for approval. + The Profile Reviewer is appointed by the Application Area Directors + and can either accept or reject the profile registration. An accepted + registration is passed on by the Profile Reviewer to the IANA for + inclusion in the official IANA profile registry. The registration may + be rejected for any of the following reasons. 1) Insufficient comment + period; 2) Consensus not reached; 3) Technical deficiencies raised on + the list or elsewhere have not been addressed. The Profile Reviewer's + decision to reject a profile can be appealed by the proposer to the + IESG, or the objections raised can be addressed by the proposer and + the profile resubmitted. + +10. Profile Change Control + + Existing profiles can be changed using the same process by which they + were registered. + + Define the change + + Post the change + + Allow a comment period + + Submit the changed profile for approval + + + + + + + +Howes, et. al. Standards Track [Page 23] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + + Note that the original author or any other interested party can + propose a change to an existing profile, but that such changes should + only be proposed when there are serious omissions or errors in the + published specification. The Profile Reviewer can object to a change + if it is not backwards compatible, but is not required to do so. + + Profile definitions can never be deleted from the IANA registry, but + profiles which are no longer believed to be useful can be declared + OBSOLETE by a change to their "intended use" field. + +11. Registration of new types + + This section defines procedures by which new types are registered + with the IANA. Note that non-IANA types can be used by bilateral + agreement, provided the associated types names follow the "X-" + convention defined above. + + The procedures defined here are designed to allow public comment and + review of new types, while posing only a small impediment to the + definition of new types. + + Registration of a new type is accomplished by the following steps. + +11.1. Define the type + + A type is defined by completing the following template. + + To: ietf-mime-direct@imc.org + Subject: Registration of text/directory MIME type XXX + + Type name: + + Type purpose: + + Type encoding: + + Type valuetype: + + Type special notes (optional): + + Intended usage: (one of COMMON, LIMITED USE or OBSOLETE) + + The meaning of each field in the template is as follows. + + Type name: The name of the type, as it will appear in the body of an + text/directory MIME Content-Type "type: value" line to the left of + the colon ":". + + + + +Howes, et. al. Standards Track [Page 24] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + + Type purpose: The purpose of the type (e.g., to represent a name, + postal address, IP address, etc.). Give a short but clear + description. + + Type encoding: The default encoding a value of the type must have in + the body of a text/directory MIME Content-Type. + + Type valuetype: The format a value of the type must have in the body + of a text/directory MIME Content-Type. This description must be + precise and must not violate the general encoding rules defined in + section 5 of this document. + + Type special notes: Any special notes about the type, how it is to be + used, etc. + +11.2. Post the type definition + + The type description must be posted to the new type discussion list, + ietf-mime-direct@imc.org + +11.3. Allow a comment period + + Discussion on the new type must be allowed to take place on the list + for a minimum of two weeks. Consensus must be reached on the type + before proceeding to step 4. + +11.4. Submit the type for approval + + Once the two-week comment period has elapsed, and the proposer is + convinced consensus has been reached on the type, the registration + application should be submitted to the Profile Reviewer for approval. + The Profile Reviewer is appointed by the Application Area Directors + and can either accept or reject the type registration. An accepted + registration is passed on by the Profile Reviewer to the IANA for + inclusion in the official IANA profile registry. The registration can + be rejected for any of the following reasons. 1) Insufficient comment + period; 2) Consensus not reached; 3) Technical deficiencies raised on + the list or elsewhere have not been addressed. The Profile + Reviewer's decision to reject a type can be appealed by the proposer + to the IESG, or the objections raised can be addressed by the + proposer and the type resubmitted. + + + + + + + + + + +Howes, et. al. Standards Track [Page 25] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + +12. Type Change Control + + Existing types can be changed using the same process by which they + were registered. + + Define the change + + Post the change + + Allow a comment period + + Submit the type for approval + + Note that the original author or any other interested party can + propose a change to an existing type, but that such changes should + only be proposed when there are serious omissions or errors in the + published specification. The Profile Reviewer can object to a change + if it is not backwards compatible, but is not required to do so. + + Type definitions can never be deleted from the IANA registry, but + types which are nolonger believed to be useful can be declared + OBSOLETE by a change to their "intended use" field. + +13. Registration of new parameters + + This section defines procedures by which new parameters are + registered with the IANA and made available to the Internet + community. Note that non-IANA parameters can be used by bilateral + agreement, provided the associated parameters names follow the "X-" + convention defined above. + + The procedures defined here are designed to allow public comment and + review of new parameters, while posing only a small impediment to the + definition of new parameters. + + Registration of a new parameter is accomplished by the following + steps. + +13.1. Define the parameter + + A parameter is defined by completing the following template. + + To: ietf-mime-direct@imc.org + Subject: Registration of text/directory MIME type parameter XXX + + Parameter name: + + Parameter purpose: + + + +Howes, et. al. Standards Track [Page 26] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + + Parameter values: + + Parameter special notes (optional): + + Intended usage: (one of COMMON, LIMITED USE or OBSOLETE) + + The explanation of what goes in each field in the template follows. + + Parameter name: The name of the parameter as it will appear in the + text/directory MIME Content-Type. + + Parameter purpose: The purpose of the parameter (e.g., to represent + the format of an image, type of a phone number, etc.). Give a short + but clear description. If defining a general paramemter like "format" + or "type" keep in mind that other applications might wish to extend + its use. + + Parameter values: The list or description of values associated with + the parameter. + + Parameter special notes: Any special notes about the parameter, how + it is to be used, etc. + +13.2. Post the parameter definition + + The parameter description must be posted to the new parameter + discussion list, ietf-mime-direct@imc.org + +13.3. Allow a comment period + + Discussion on the new parameter must be allowed to take place on the + list for a minimum of two weeks. Consensus must be reached on the + parameter before proceeding to step 4. + +13.4. Submit the parameter for approval + + Once the two-week comment period has elapsed, and the proposer is + convinced consensus has been reached on the parameter, the + registration application should be submitted to the Profile Reviewer + for approval. The Profile Reviewer is appointed by the Application + Area Directors and can either accept or reject the parameter + registration. An accepted registration is passed on by the Profile + Reviewer to the IANA for inclusion in the official IANA parameter + registry. The registration can be rejected for any of the following + reasons. 1) Insufficient comment period; 2) Consensus not reached; 3) + Technical deficiencies raised on the list or elsewhere have not been + addressed. The Profile Reviewer's decision to reject a profile can be + appealed by the proposer to the IESG, or the objections raised can be + + + +Howes, et. al. Standards Track [Page 27] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + + addressed by the proposer and the parameter registration resubmitted. + +14. Parameter Change Control + + Existing parameters can be changed using the same process by which + they were registered. + + Define the change + + Post the change + + Allow a comment period + + Submit the parameter for approval + + Note that the original author or any other interested party can + propose a change to an existing parameter, but that such changes + should only be proposed when there are serious omissions or errors in + the published specification. The Profile Reviewer can object to a + change if it is not backwards compatible, but is not required to do + so. + + Parameter definitions can never be deleted from the IANA registry, + but parameters which are nolonger believed to be useful can be + declared OBSOLETE by a change to their "intended use" field. + +15. Registration of new value types + + This section defines procedures by which new value types are + registered with the IANA and made available to the Internet + community. Note that non-IANA value types can be used by bilateral + agreement, provided the associated value types names follow the "X-" + convention defined above. + + The procedures defined here are designed to allow public comment and + review of new value types, while posing only a small impediment to + the definition of new value types. + + Registration of a new value types is accomplished by the following + steps. + +15.1. Define the value type + + A value type is defined by completing the following template. + + To: ietf-mime-direct@imc.org + Subject: Registration of text/directory MIME value type XXX + + + + +Howes, et. al. Standards Track [Page 28] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + + value type name: + + value type purpose: + + value type format: + + value type special notes (optional): + + Intended usage: (one of COMMON, LIMITED USE or OBSOLETE) + + The explanation of what goes in each field in the template follows. + + value type name: The name of the value type as it will appear in the + text/directory MIME Content-Type. + + value type purpose: The purpose of the value type. Give a short but + clear description. + + value type format: The definition of the format for the value, + usually using ABNF grammar. + + value type special notes: Any special notes about the value type, how + it is to be used, etc. + +15.2. Post the value type definition + + The value type description must be posted to the new value type + discussion list, ietf-mime-direct@imc.org + +15.3. Allow a comment period + + Discussion on the new value type must be allowed to take place on the + list for a minimum of two weeks. Consensus must be reached before + proceeding to step 4. + +15.4. Submit the value type for approval + + Once the two-week comment period has elapsed, and the proposer is + convinced consensus has been reached on the value type, the + registration application should be submitted to the Profile Reviewer + for approval. The Profile Reviewer is appointed by the Application + Area Directors and can either accept or reject the value type + registration. An accepted registration should be passed on by the + Profile Reviewer to the IANA for inclusion in the official IANA value + type registry. The registration can be rejected for any of the + following reasons. 1) Insufficient comment period; 2) Consensus not + reached; 3) Technical deficiencies raised on the list or elsewhere + have not been addressed. The Profile Reviewer's decision to reject a + + + +Howes, et. al. Standards Track [Page 29] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + + profile can be appealed by the proposer to the IESG, or the + objections raised can be addressed by the proposer and the value type + registration resubmitted. + +16. Security Considerations + + Internet mail is subject to many well known security attacks, + including monitoring, replay, and forgery. Care should be taken by + any directory service in allowing information to leave the scope of + the service itself, where any access controls can no longer be + guaranteed. Applications should also take care to display directory + data in a "safe" environment (e.g., PostScript-valued types). + +17. Acknowledgements + + The registration procedures defined here were shamelessly lifted from + the MIME registration RFC. + + The many valuable comments contributed by members of the IETF ASID + working group are gratefully acknowledged, as are the contributions + of the Versit Consortium. Chris Newman was especially helpful in + navigating the intricacies of ABNF lore. + +18. References + + [RFC-1777] Yeong, W., Howes, T., and S. Kille, "Lightweight + Directory Access Protocol", RFC 1777, March 1995. + + [RFC-1778] Howes, T., Kille, S., Yeong, W., and C. Robbins, "The + String Representation of Standard Attribute Syntaxes", + RFC 1778, March 1995. + + [RFC-822] Crocker, D., "Standard for the Format of ARPA Internet + Text Messages", STD 11, RFC 822, August 1982. + + [RFC-2045] Borenstein, N., and N. Freed, "Multipurpose Internet + Mail Extensions (MIME) Part One: Format of Internet + Message Bodies", RFC 2045, November 1996. + + [RFC-2046] Moore, K., "Multipurpose Internet Mail Extensions (MIME) + Part Two: Media Types", RFC 2046, November 1996. + + [RFC-2048] Freed, N., Klensin, J., and J. Postel, "Multipurpose + Internet Mail Extensions (MIME) Part Four: Registration + Procedures", RFC 2048, November 1996. + + [RFC-1766] Alvestrand, H., "Tags for the Identification of + Languages", RFC 1766, March 1995. + + + +Howes, et. al. Standards Track [Page 30] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + + [RFC-2112] Levinson, E., "The MIME Multipart/Related Content-type", + RFC 2112, March 1997. + + [X500] "Information Processing Systems - Open Systems + Interconnection - The Directory: Overview of Concepts, + Models and Services", ISO/IEC JTC 1/SC21, International + Standard 9594-1, 1988. + + [RFC-1835] Deutsch, P., Schoultz, R., Faltstrom, P., and C. Weider, + "Architecture of the WHOIS++ service", RFC 1835, August + 1995. + + [RFC-1738] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform + Resource Locators (URL)", RFC 1738, December 1994. + + [MIME-VCARD] Dawson, F., and T. Howes, "VCard MIME Directory + Profile", RFC 2426, September 1998. + + [VCARD] Internet Mail Consortium, "vCard - The Electronic + Business Card", Version 2.1, + http://www.imc.com/pdi/vcard-21.txt, September, 1996. + + [RFC-2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC-2234] Crocker, D., and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997. + + + + + + + + + + + + + + + + + + + + + + + + +Howes, et. al. Standards Track [Page 31] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + +19. Authors' Addresses + + Tim Howes + Netscape Communications Corp. + 501 East Middlefield Rd. + Mountain View, CA 94041 + USA + + Phone: +1.415.937.3419 + EMail: howes@netscape.com + + + Mark Smith + Netscape Communications Corp. + 501 East Middlefield Rd. + Mountain View, CA 94041 + USA + + Phone: +1.415.937.3477 + EMail: mcs@netscape.com + + + Frank Dawson + Lotus Development Corporation + 6544 Battleford Drive + Raleigh, NC 27613 + USA + + Phone: +1-919-676-9515 + EMail: frank_dawson@lotus.com + + + + + + + + + + + + + + + + + + + + + +Howes, et. al. Standards Track [Page 32] + +RFC 2425 MIME Content-Type for Directory Information September 1998 + + +20. Full Copyright Statement + + Copyright (C) The Internet Society (1998). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + + + + + + + + + + + + + + + + + + + + + + + + +Howes, et. al. Standards Track [Page 33] + diff --git a/specs/rfc2426-vcard-3.0.txt b/specs/rfc2426-vcard-3.0.txt new file mode 100644 index 0000000..a393a67 --- /dev/null +++ b/specs/rfc2426-vcard-3.0.txt @@ -0,0 +1,2355 @@ + + + + + + +Network Working Group F. Dawson +Request for Comments: 2426 Lotus Development Corporation +Category: Standards Track T. Howes + Netscape Communications + September 1998 + + + vCard MIME Directory Profile + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1998). All Rights Reserved. + +Abstract + + This memo defines the profile of the MIME Content-Type [MIME-DIR] for + directory information for a white-pages person object, based on a + vCard electronic business card. The profile definition is independent + of any particular directory service or protocol. The profile is + defined for representing and exchanging a variety of information + about an individual (e.g., formatted and structured name and delivery + addresses, email address, multiple telephone numbers, photograph, + logo, audio clips, etc.). The directory information used by this + profile is based on the attributes for the person object defined in + the X.520 and X.521 directory services recommendations. The profile + also provides the method for including a [VCARD] representation of a + white-pages directory entry within the MIME Content-Type defined by + the [MIME-DIR] 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 [RFC 2119]. + + + + + + + + + + + +Dawson & Howes Standards Track [Page 1] + +RFC 2426 vCard MIME Directory Profile September 1998 + + +Table of Contents + + Overview.........................................................3 + 1. THE VCARD MIME DIRECTORY PROFILE REGISTRATION.................4 + 2. MIME DIRECTORY FEATURES.......................................5 + 2.1 PREDEFINED TYPE USAGE ......................................5 + 2.1.1 BEGIN and END Type ......................................5 + 2.1.2 NAME Type ...............................................5 + 2.1.3 PROFILE Type ............................................5 + 2.1.4 SOURCE Type .............................................5 + 2.2 PREDEFINED TYPE PARAMETER USAGE ............................6 + 2.3 PREDEFINED VALUE TYPE USAGE ................................6 + 2.4 EXTENSIONS TO THE PREDEFINED VALUE TYPES ...................6 + 2.4.1 BINARY ..................................................6 + 2.4.2 VCARD ...................................................6 + 2.4.3 PHONE-NUMBER ............................................7 + 2.4.4 UTC-OFFSET ..............................................7 + 2.5 STRUCTURED TYPE VALUES .....................................7 + 2.6 LINE DELIMITING AND FOLDING ................................8 + 3. VCARD PROFILE FEATURES........................................8 + 3.1 IDENTIFICATION TYPES .......................................8 + 3.1.1 FN Type Definition ......................................8 + 3.1.2 N Type Definition .......................................9 + 3.1.3 NICKNAME Type Definition ................................9 + 3.1.4 PHOTO Type Definition ..................................10 + 3.1.5 BDAY Type Definition ...................................11 + 3.2 DELIVERY ADDRESSING TYPES .................................11 + 3.2.1 ADR Type Definition ....................................11 + 3.2.2 LABEL Type Definition ..................................13 + 3.3 TELECOMMUNICATIONS ADDRESSING TYPES .......................13 + 3.3.1 TEL Type Definition ....................................14 + 3.3.2 EMAIL Type Definition ..................................15 + 3.3.3 MAILER Type Definition .................................15 + 3.4 GEOGRAPHICAL TYPES ........................................16 + 3.4.1 TZ Type Definition .....................................16 + 3.4.2 GEO Type Definition ....................................16 + 3.5 ORGANIZATIONAL TYPES ......................................17 + 3.5.1 TITLE Type Definition ..................................17 + 3.5.2 ROLE Type Definition ...................................18 + 3.5.3 LOGO Type Definition ...................................18 + 3.5.4 AGENT Type Definition ..................................19 + 3.5.5 ORG Type Definition ....................................20 + 3.6 EXPLANATORY TYPES .........................................20 + 3.6.1 CATEGORIES Type Definition .............................20 + 3.6.2 NOTE Type Definition ...................................21 + 3.6.3 PRODID Type Definition .................................21 + 3.6.4 REV Type Definition ....................................22 + 3.6.5 SORT-STRING Type Definition ............................22 + + + +Dawson & Howes Standards Track [Page 2] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + 3.6.6 SOUND Type Definition ..................................23 + 3.6.7 UID Type Definition ....................................24 + 3.6.8 URL Type Definition ....................................25 + 3.6.9 VERSION Type Definition ................................25 + 3.7 SECURITY TYPES ............................................25 + 3.7.1 CLASS Type Definition ..................................26 + 3.7.2 KEY Type Definition ....................................26 + 3.8 EXTENDED TYPES ............................................27 + 4. FORMAL GRAMMAR...............................................27 + 5. DIFFERENCES FROM VCARD V2.1..................................37 + 6. ACKNOWLEDGEMENTS.............................................39 + 7. AUTHORS' ADDRESSES...........................................39 + 8. SECURITY CONSIDERATIONS......................................39 + 9. REFERENCES...................................................40 + 10. FULL COPYRIGHT STATEMENT....................................42 + +Overview + + The [MIME-DIR] document defines a MIME Content-Type for holding + different kinds of directory information. The directory information + can be based on any of a number of directory schemas. This document + defines a [MIME-DIR] usage profile for conveying directory + information based on one such schema; that of the white-pages type of + person object. + + The schema is based on the attributes for the person object defined + in the X.520 and X.521 directory services recommendations. The schema + has augmented the basic attributes defined in the X.500 series + recommendation in order to provide for an electronic representation + of the information commonly found on a paper business card. This + schema was first defined in the [VCARD] document. Hence, this [MIME- + DIR] profile is referred to as the vCard MIME Directory Profile. + + A directory entry based on this usage profile can include traditional + directory, white-pages information such as the distinguished name + used to uniquely identify the entry, a formatted representation of + the name used for user-interface or presentation purposes, both the + structured and presentation form of the delivery address, various + telephone numbers and organizational information associated with the + entry. In addition, traditional paper business card information such + as an image of an organizational logo or identify photograph can be + included in this person object. + + The vCard MIME Directory Profile also provides support for + representing other important information about the person associated + with the directory entry. For instance, the date of birth of the + person; an audio clip describing the pronunciation of the name + associated with the directory entry, or some other application of the + + + +Dawson & Howes Standards Track [Page 3] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + digital sound; longitude and latitude geo-positioning information + related to the person associated with the directory entry; date and + time that the directory information was last updated; annotations + often written on a business card; Uniform Resource Locators (URL) for + a website; public key information. The profile also provides support + for non-standard extensions to the schema. This provides the + flexibility for implementations to augment the current capabilities + of the profile in a standardized way. More information about this + electronic business card format can be found in [VCARD]. + +1. The vCard Mime Directory Profile Registration + + This profile is identified by the following [MIME-DIR] registration + template information. Subsequent sections define the profile + definition. + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME profile VCARD + + Profile name: VCARD + + Profile purpose: To hold person object or white-pages type of + directory information. The person schema captured in the directory + entries is that commonly found in an electronic business card. + + Predefined MIME Directory value specifications used: uri, date, + date-time, float + + New value specifications: This profile places further constraints on + the [MIME-DIR] text value specification. In addition, it adds a + binary, phone-number, utc-offset and vcard value specifications. + + Predefined MIME Directory types used: SOURCE, NAME, PROFILE, BEGIN, + END. + + Predefined MIME Directory parameters used: ENCODING, VALUE, CHARSET, + LANGUAGE, CONTEXT. + + New types: FN, N, NICKNAME, PHOTO, BDAY, ADR, LABEL, TEL, EMAIL, + MAILER, TZ, GEO, TITLE, ROLE, LOGO, AGENT, ORG, CATEGORIES, NOTE, + PRODID, REV, SORT-STRING, SOUND, URL, UID, VERSION, CLASS, KEY + + New parameters: TYPE + + Profile special notes: The vCard object MUST contain the FN, N and + VERSION types. The type-grouping feature of [MIME-DIR] is supported + by this profile to group related vCard properties about a directory + + + +Dawson & Howes Standards Track [Page 4] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + entry. For example, vCard properties describing WORK or HOME related + characteristics can be grouped with a unique group label. + + The profile permits the use of non-standard types (i.e., those + identified with the prefix string "X-") as a flexible method for + implementations to extend the functionality currently defined within + this profile. + +2. MIME Directory Features + + The vCard MIME Directory Profile makes use of many of the features + defined by [MIME-DIR]. The following sections either clarify or + extend the content-type definition of [MIME-DIR]. + +2.1 Predefined Type Usage + + The vCard MIME Directory Profile uses the following predefined types + from [MIME-DIR]. + +2.1.1 BEGIN and END Type + + The content entity MUST begin with the BEGIN type with a value of + "VCARD". The content entity MUST end with the END type with a value + of "VCARD". + +2.1.2 NAME Type + + If the NAME type is present, then its value is the displayable, + presentation text associated with the source for the vCard, as + specified in the SOURCE type. + +2.1.3 PROFILE Type + + If the PROFILE type is present, then its value MUST be "VCARD". + +2.1.4 SOURCE Type + + If the SOURCE type is present, then its value provides information + how to find the source for the vCard. + + + + + + + + + + + + +Dawson & Howes Standards Track [Page 5] + +RFC 2426 vCard MIME Directory Profile September 1998 + + +2.2 Predefined Type Parameter Usage + + The vCard MIME Directory Profile uses the following predefined type + parameters as defined by [MIME-DIR]. + + - LANGUAGE + + - ENCODING + + - VALUE + +2.3 Predefined VALUE Type Usage + + The predefined data type values specified in [MIME-DIR] MUST NOT be + repeated in COMMA separated value lists except within the N, + NICKNAME, ADR and CATEGORIES value types. + + The text value type defined in [MIME-DIR] is further restricted such + that any SEMI-COLON character (ASCII decimal 59) in the value MUST be + escaped with the BACKSLASH character (ASCII decimal 92). + +2.4 Extensions To The Predefined VALUE Types + + The predefined data type values specified in [MIME-DIR] have been + extended by the vCard profile to include a number of value types that + are specific to this profile. + +2.4.1 BINARY + + The "binary" value type specifies that the type value is inline, + encoded binary data. This value type can be specified in the PHOTO, + LOGO, SOUND, and KEY types. + + If inline encoded binary data is specified, the ENCODING type + parameter MUST be used to specify the encoding format. The binary + data MUST be encoded using the "B" encoding format. Long lines of + encoded binary data SHOULD BE folded to 75 characters using the + folding method defined in [MIME-DIR]. + + The value type is defined by the following notation: + + binary = + +2.4.2 VCARD + + The "vcard" value type specifies that the type value is another + vCard. This value type can be specified in the AGENT type. The value + type is defined by this specification. Since each of the type + + + +Dawson & Howes Standards Track [Page 6] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + declarations with in the vcard value type are being specified within + a text value themselves, they MUST be terminated with the backslash + escape sequence "\n" or "\N", instead of the normal newline character + sequence CRLF. In addition, any COMMA character (ASCII decimal 44), + SEMI-COLON character (ASCII decimal 59) and COLON character (ASCII + decimal 58) MUST be escaped with the BACKSLASH character (ASCII + decimal 92). For example, with the AGENT type a value would be + specified as: + + AGENT:BEGIN:VCARD\nFN:Joe Friday\nTEL:+1-919-555-7878\n + TITLE:Area Administrator\, Assistant\n EMAIL\;TYPE=INTERN\n + ET:jfriday@host.com\nEND:VCARD\n + +2.4.3 PHONE-NUMBER + + The "phone-number" value type specifies that the type value is a + telephone number. This value type can be specified in the TEL type. + The value type is a text value that has the special semantics of a + telephone number as defined in [CCITT E.163] and [CCITT X.121]. + +2.4.4 UTC-OFFSET + + The "utc-offset" value type specifies that the type value is a signed + offset from UTC. This value type can be specified in the TZ type. + + The value type is an offset from Coordinated Universal Time (UTC). It + is specified as a positive or negative difference in units of hours + and minutes (e.g., +hh:mm). The time is specified as a 24-hour clock. + Hour values are from 00 to 23, and minute values are from 00 to 59. + Hour and minutes are 2-digits with high order zeroes required to + maintain digit count. The extended format for ISO 8601 UTC offsets + MUST be used. The extended format makes use of a colon character as a + separator of the hour and minute text fields. + + The value is defined by the following notation: + + time-hour = 2DIGIT ;00-23 + time-minute = 2DIGIT ;00-59 + utc-offset = ("+" / "-") time-hour ":" time-minute + +2.5 Structured Type Values + + Compound type values are delimited by a field delimiter, specified by + the SEMI-COLON character (ASCII decimal 59). A SEMI-COLON in a + component of a compound property value MUST be escaped with a + BACKSLASH character (ASCII decimal 92). + + + + + +Dawson & Howes Standards Track [Page 7] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + Lists of values are delimited by a list delimiter, specified by the + COMMA character (ASCII decimal 44). A COMMA character in a value MUST + be escaped with a BACKSLASH character (ASCII decimal 92). + + This profile supports the type grouping mechanism defined in [MIME- + DIR]. Grouping of related types is a useful technique to communicate + common semantics concerning the properties of a vCard. + +2.6 Line Delimiting and Folding + + This profile supports the same line delimiting and folding methods + defined in [MIME-DIR]. Specifically, when parsing a content line, + folded lines must first be unfolded according to the unfolding + procedure described in [MIME-DIR]. After generating a content line, + lines longer than 75 characters SHOULD be folded according to the + folding procedure described in [MIME DIR]. + + Folding is done after any content encoding of a type value. Unfolding + is done before any decoding of a type value in a content line. + +3. vCard Profile Features + + The vCard MIME Directory Profile Type contains directory information, + typically pertaining to a single directory entry. The information is + described using an attribute schema that is tailored for capturing + personal contact information. The vCard can include attributes that + describe identification, delivery addressing, telecommunications + addressing, geographical, organizational, general explanatory and + security and access information about the particular object + associated with the vCard. + +3.1 Identification Types + + These types are used in the vCard profile to capture information + associated with the identification and naming of the person or + resource associated with the vCard. + +3.1.1 FN Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type FN + + Type name:FN + + Type purpose: To specify the formatted text corresponding to the name + of the object the vCard represents. + + + + +Dawson & Howes Standards Track [Page 8] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + Type encoding: 8bit + + Type value: A single text value. + + Type special notes: This type is based on the semantics of the X.520 + Common Name attribute. The property MUST be present in the vCard + object. + + Type example: + + FN:Mr. John Q. Public\, Esq. + +3.1.2 N Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type N + + Type name: N + + Type purpose: To specify the components of the name of the object the + vCard represents. + + Type encoding: 8bit + + Type value: A single structured text value. Each component can have + multiple values. + + Type special note: The structured type value corresponds, in + sequence, to the Family Name, Given Name, Additional Names, Honorific + Prefixes, and Honorific Suffixes. The text components are separated + by the SEMI-COLON character (ASCII decimal 59). Individual text + components can include multiple text values (e.g., multiple + Additional Names) separated by the COMMA character (ASCII decimal + 44). This type is based on the semantics of the X.520 individual name + attributes. The property MUST be present in the vCard object. + + Type example: + + N:Public;John;Quinlan;Mr.;Esq. + + N:Stevenson;John;Philip,Paul;Dr.;Jr.,M.D.,A.C.P. + +3.1.3 NICKNAME Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type NICKNAME + + + +Dawson & Howes Standards Track [Page 9] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + Type name: NICKNAME + + Type purpose: To specify the text corresponding to the nickname of + the object the vCard represents. + + Type encoding: 8bit + + Type value: One or more text values separated by a COMMA character + (ASCII decimal 44). + + Type special note: The nickname is the descriptive name given instead + of or in addition to the one belonging to a person, place, or thing. + It can also be used to specify a familiar form of a proper name + specified by the FN or N types. + + Type example: + + NICKNAME:Robbie + + NICKNAME:Jim,Jimmie + +3.1.4 PHOTO Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type PHOTO + + Type name: PHOTO + + Type purpose: To specify an image or photograph information that + annotates some aspect of the object the vCard represents. + + Type encoding: The encoding MUST be reset to "b" using the ENCODING + parameter in order to specify inline, encoded binary data. If the + value is referenced by a URI value, then the default encoding of 8bit + is used and no explicit ENCODING parameter is needed. + + Type value: A single value. The default is binary value. It can also + be reset to uri value. The uri value can be used to specify a value + outside of this MIME entity. + + Type special notes: The type can include the type parameter "TYPE" to + specify the graphic image format type. The TYPE parameter values MUST + be one of the IANA registered image formats or a non-standard image + format. + + + + + + +Dawson & Howes Standards Track [Page 10] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + Type example: + + PHOTO;VALUE=uri:http://www.abc.com/pub/photos + /jqpublic.gif + + + PHOTO;ENCODING=b;TYPE=JPEG:MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcN + AQEEBQAwdzELMAkGA1UEBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bm + ljYXRpb25zIENvcnBvcmF0aW9uMRwwGgYDVQQLExNJbmZvcm1hdGlvbiBTeXN0 + <...remainder of "B" encoded binary data...> + +3.1.5 BDAY Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type BDAY + + Type name: BDAY + + Type purpose: To specify the birth date of the object the vCard + represents. + + Type encoding: 8bit + + Type value: The default is a single date value. It can also be reset + to a single date-time value. + + Type examples: + + BDAY:1996-04-15 + + BDAY:1953-10-15T23:10:00Z + + BDAY:1987-09-27T08:30:00-06:00 + +3.2 Delivery Addressing Types + + These types are concerned with information related to the delivery + addressing or label for the vCard object. + +3.2.1 ADR Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type ADR + + Type name: ADR + + + + +Dawson & Howes Standards Track [Page 11] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + Type purpose: To specify the components of the delivery address for + the vCard object. + + Type encoding: 8bit + + Type value: A single structured text value, separated by the + SEMI-COLON character (ASCII decimal 59). + + Type special notes: The structured type value consists of a sequence + of address components. The component values MUST be specified in + their corresponding position. The structured type value corresponds, + in sequence, to the post office box; the extended address; the street + address; the locality (e.g., city); the region (e.g., state or + province); the postal code; the country name. When a component value + is missing, the associated component separator MUST still be + specified. + + The text components are separated by the SEMI-COLON character (ASCII + decimal 59). Where it makes semantic sense, individual text + components can include multiple text values (e.g., a "street" + component with multiple lines) separated by the COMMA character + (ASCII decimal 44). + + The type can include the type parameter "TYPE" to specify the + delivery address type. The TYPE parameter values can include "dom" to + indicate a domestic delivery address; "intl" to indicate an + international delivery address; "postal" to indicate a postal + delivery address; "parcel" to indicate a parcel delivery address; + "home" to indicate a delivery address for a residence; "work" to + indicate delivery address for a place of work; and "pref" to indicate + the preferred delivery address when more than one address is + specified. These type parameter values can be specified as a + parameter list (i.e., "TYPE=dom;TYPE=postal") or as a value list + (i.e., "TYPE=dom,postal"). This type is based on semantics of the + X.520 geographical and postal addressing attributes. The default is + "TYPE=intl,postal,parcel,work". The default can be overridden to some + other set of values by specifying one or more alternate values. For + example, the default can be reset to "TYPE=dom,postal,work,home" to + specify a domestic delivery address for postal delivery to a + residence that is also used for work. + + Type example: In this example the post office box and the extended + address are absent. + + ADR;TYPE=dom,home,postal,parcel:;;123 Main + Street;Any Town;CA;91921-1234 + + + + + +Dawson & Howes Standards Track [Page 12] + +RFC 2426 vCard MIME Directory Profile September 1998 + + +3.2.2 LABEL Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type LABEL + + Type name: LABEL + + Type purpose: To specify the formatted text corresponding to delivery + address of the object the vCard represents. + + Type encoding: 8bit + + Type value: A single text value. + + Type special notes: The type value is formatted text that can be used + to present a delivery address label for the vCard object. The type + can include the type parameter "TYPE" to specify delivery label type. + The TYPE parameter values can include "dom" to indicate a domestic + delivery label; "intl" to indicate an international delivery label; + "postal" to indicate a postal delivery label; "parcel" to indicate a + parcel delivery label; "home" to indicate a delivery label for a + residence; "work" to indicate delivery label for a place of work; and + "pref" to indicate the preferred delivery label when more than one + label is specified. These type parameter values can be specified as a + parameter list (i.e., "TYPE=dom;TYPE=postal") or as a value list + (i.e., "TYPE=dom,postal"). This type is based on semantics of the + X.520 geographical and postal addressing attributes. The default is + "TYPE=intl,postal,parcel,work". The default can be overridden to some + other set of values by specifying one or more alternate values. For + example, the default can be reset to "TYPE=intl,post,parcel,home" to + specify an international delivery label for both postal and parcel + delivery to a residential location. + + Type example: A multi-line address label. + + LABEL;TYPE=dom,home,postal,parcel:Mr.John Q. Public\, Esq.\n + Mail Drop: TNE QB\n123 Main Street\nAny Town\, CA 91921-1234 + \nU.S.A. + +3.3 Telecommunications Addressing Types + + These types are concerned with information associated with the + telecommunications addressing of the object the vCard represents. + + + + + + + +Dawson & Howes Standards Track [Page 13] + +RFC 2426 vCard MIME Directory Profile September 1998 + + +3.3.1 TEL Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type TEL + + Type name: TEL + + Type purpose: To specify the telephone number for telephony + communication with the object the vCard represents. + + Type encoding: 8bit + + Type value: A single phone-number value. + + Type special notes: The value of this type is specified in a + canonical form in order to specify an unambiguous representation of + the globally unique telephone endpoint. This type is based on the + X.500 Telephone Number attribute. + + The type can include the type parameter "TYPE" to specify intended + use for the telephone number. The TYPE parameter values can include: + "home" to indicate a telephone number associated with a residence, + "msg" to indicate the telephone number has voice messaging support, + "work" to indicate a telephone number associated with a place of + work, "pref" to indicate a preferred-use telephone number, "voice" to + indicate a voice telephone number, "fax" to indicate a facsimile + telephone number, "cell" to indicate a cellular telephone number, + "video" to indicate a video conferencing telephone number, "pager" to + indicate a paging device telephone number, "bbs" to indicate a + bulletin board system telephone number, "modem" to indicate a MODEM + connected telephone number, "car" to indicate a car-phone telephone + number, "isdn" to indicate an ISDN service telephone number, "pcs" to + indicate a personal communication services telephone number. The + default type is "voice". These type parameter values can be specified + as a parameter list (i.e., "TYPE=work;TYPE=voice") or as a value list + (i.e., "TYPE=work,voice"). The default can be overridden to another + set of values by specifying one or more alternate values. For + example, the default TYPE of "voice" can be reset to a WORK and HOME, + VOICE and FAX telephone number by the value list + "TYPE=work,home,voice,fax". + + Type example: + + TEL;TYPE=work,voice,pref,msg:+1-213-555-1234 + + + + + + +Dawson & Howes Standards Track [Page 14] + +RFC 2426 vCard MIME Directory Profile September 1998 + + +3.3.2 EMAIL Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type EMAIL + + Type name: EMAIL + + Type purpose: To specify the electronic mail address for + communication with the object the vCard represents. + + Type encoding: 8bit + + Type value: A single text value. + + Type special notes: The type can include the type parameter "TYPE" to + specify the format or preference of the electronic mail address. The + TYPE parameter values can include: "internet" to indicate an Internet + addressing type, "x400" to indicate a X.400 addressing type or "pref" + to indicate a preferred-use email address when more than one is + specified. Another IANA registered address type can also be + specified. The default email type is "internet". A non-standard value + can also be specified. + + Type example: + + EMAIL;TYPE=internet:jqpublic@xyz.dom1.com + + EMAIL;TYPE=internet:jdoe@isp.net + + EMAIL;TYPE=internet,pref:jane_doe@abc.com + +3.3.3 MAILER Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type MAILER + + Type name: MAILER + + Type purpose: To specify the type of electronic mail software that is + used by the individual associated with the vCard. + + Type encoding: 8bit + + Type value: A single text value. + + + + + +Dawson & Howes Standards Track [Page 15] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + Type special notes: This information can provide assistance to a + correspondent regarding the type of data representation which can be + used, and how they can be packaged. This property is based on the + private MIME type X-Mailer that is generally implemented by MIME user + agent products. + + Type example: + + MAILER:PigeonMail 2.1 + +3.4 Geographical Types + + These types are concerned with information associated with + geographical positions or regions associated with the object the + vCard represents. + +3.4.1 TZ Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type TZ + + Type name: TZ + + Type purpose: To specify information related to the time zone of the + object the vCard represents. + + Type encoding: 8bit + + Type value: The default is a single utc-offset value. It can also be + reset to a single text value. + + Type special notes: The type value consists of a single value. + + Type examples: + + TZ:-05:00 + + TZ;VALUE=text:-05:00; EST; Raleigh/North America + ;This example has a single value, not a structure text value. + +3.4.2 GEO Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type GEO + + Type name: GEO + + + +Dawson & Howes Standards Track [Page 16] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + Type purpose: To specify information related to the global + positioning of the object the vCard represents. + + Type encoding: 8bit + + Type value: A single structured value consisting of two float values + separated by the SEMI-COLON character (ASCII decimal 59). + + Type special notes: This type specifies information related to the + global position of the object associated with the vCard. The value + specifies latitude and longitude, in that order (i.e., "LAT LON" + ordering). The longitude represents the location east and west of the + prime meridian as a positive or negative real number, respectively. + The latitude represents the location north and south of the equator + as a positive or negative real number, respectively. The longitude + and latitude values MUST be specified as decimal degrees and should + be specified to six decimal places. This will allow for granularity + within a meter of the geographical position. The text components are + separated by the SEMI-COLON character (ASCII decimal 59). The simple + formula for converting degrees-minutes-seconds into decimal degrees + is: + + decimal = degrees + minutes/60 + seconds/3600. + + Type example: + + GEO:37.386013;-122.082932 + +3.5 Organizational Types + + These types are concerned with information associated with + characteristics of the organization or organizational units of the + object the vCard represents. + +3.5.1 TITLE Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type TITLE + + Type name: TITLE + + Type purpose: To specify the job title, functional position or + function of the object the vCard represents. + + Type encoding: 8bit + + Type value: A single text value. + + + +Dawson & Howes Standards Track [Page 17] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + Type special notes: This type is based on the X.520 Title attribute. + + Type example: + + TITLE:Director\, Research and Development + +3.5.2 ROLE Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type ROLE + + Type name: ROLE + + Type purpose: To specify information concerning the role, occupation, + or business category of the object the vCard represents. + + Type encoding: 8bit + + Type value: A single text value. + + Type special notes: This type is based on the X.520 Business Category + explanatory attribute. This property is included as an organizational + type to avoid confusion with the semantics of the TITLE type and + incorrect usage of that type when the semantics of this type is + intended. + + Type example: + + ROLE:Programmer + +3.5.3 LOGO Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type LOGO + + Type name: LOGO + + Type purpose: To specify a graphic image of a logo associated with + the object the vCard represents. + + Type encoding: The encoding MUST be reset to "b" using the ENCODING + parameter in order to specify inline, encoded binary data. If the + value is referenced by a URI value, then the default encoding of 8bit + is used and no explicit ENCODING parameter is needed. + + + + + +Dawson & Howes Standards Track [Page 18] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + Type value: A single value. The default is binary value. It can also + be reset to uri value. The uri value can be used to specify a value + outside of this MIME entity. + + Type special notes: The type can include the type parameter "TYPE" to + specify the graphic image format type. The TYPE parameter values MUST + be one of the IANA registered image formats or a non-standard image + format. + + Type example: + + LOGO;VALUE=uri:http://www.abc.com/pub/logos/abccorp.jpg + + LOGO;ENCODING=b;TYPE=JPEG:MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcN + AQEEBQAwdzELMAkGA1UEBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bm + ljYXRpb25zIENvcnBvcmF0aW9uMRwwGgYDVQQLExNJbmZvcm1hdGlvbiBTeXN0 + <...the remainder of "B" encoded binary data...> + +3.5.4 AGENT Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type AGENT + + Type name: AGENT + + Type purpose: To specify information about another person who will + act on behalf of the individual or resource associated with the + vCard. + + Type encoding: 8-bit + + Type value: The default is a single vcard value. It can also be reset + to either a single text or uri value. The text value can be used to + specify textual information. The uri value can be used to specify + information outside of this MIME entity. + + Type special notes: This type typically is used to specify an area + administrator, assistant, or secretary for the individual associated + with the vCard. A key characteristic of the Agent type is that it + represents somebody or something that is separately addressable. + + Type example: + + AGENT;VALUE=uri: + CID:JQPUBLIC.part3.960129T083020.xyzMail@host3.com + + + + + +Dawson & Howes Standards Track [Page 19] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + AGENT:BEGIN:VCARD\nFN:Susan Thomas\nTEL:+1-919-555- + 1234\nEMAIL\;INTERNET:sthomas@host.com\nEND:VCARD\n + +3.5.5 ORG Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type ORG + + Type name: ORG + + Type purpose: To specify the organizational name and units associated + with the vCard. + + Type encoding: 8bit + + Type value: A single structured text value consisting of components + separated the SEMI-COLON character (ASCII decimal 59). + + Type special notes: The type is based on the X.520 Organization Name + and Organization Unit attributes. The type value is a structured type + consisting of the organization name, followed by one or more levels + of organizational unit names. + + Type example: A type value consisting of an organizational name, + organizational unit #1 name and organizational unit #2 name. + + ORG:ABC\, Inc.;North American Division;Marketing + +3.6 Explanatory Types + + These types are concerned with additional explanations, such as that + related to informational notes or revisions specific to the vCard. + +3.6.1 CATEGORIES Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type CATEGORIES + + Type name: CATEGORIES + + Type purpose: To specify application category information about the + vCard. + + Type encoding: 8bit + + + + + +Dawson & Howes Standards Track [Page 20] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + Type value: One or more text values separated by a COMMA character + (ASCII decimal 44). + + Type example: + + CATEGORIES:TRAVEL AGENT + + CATEGORIES:INTERNET,IETF,INDUSTRY,INFORMATION TECHNOLOGY + +3.6.2 NOTE Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type NOTE + + Type name: NOTE + + Type purpose: To specify supplemental information or a comment that + is associated with the vCard. + + Type encoding: 8bit + + Type value: A single text value. + + Type special notes: The type is based on the X.520 Description + attribute. + + Type example: + + NOTE:This fax number is operational 0800 to 1715 + EST\, Mon-Fri. + +3.6.3 PRODID Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type PRODID + + Type name: PRODID + + Type purpose: To specify the identifier for the product that created + the vCard object. + + Type encoding: 8-bit + + Type value: A single text value. + + + + + +Dawson & Howes Standards Track [Page 21] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + Type special notes: Implementations SHOULD use a method such as that + specified for Formal Public Identifiers in ISO 9070 to assure that + the text value is unique. + + Type example: + + PRODID:-//ONLINE DIRECTORY//NONSGML Version 1//EN + +3.6.4 REV Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type REV + + Type name: REV + + Type purpose: To specify revision information about the current + vCard. + + Type encoding: 8-bit + + Type value: The default is a single date-time value. Can also be + reset to a single date value. + + Type special notes: The value distinguishes the current revision of + the information in this vCard for other renditions of the + information. + + Type example: + + REV:1995-10-31T22:27:10Z + + REV:1997-11-15 + +3.6.5 SORT-STRING Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type SORT-STRING + + Type Name: SORT-STRING + + Type purpose: To specify the family name or given name text to be + used for national-language-specific sorting of the FN and N types. + + Type encoding: 8bit + + Type value: A single text value. + + + +Dawson & Howes Standards Track [Page 22] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + Type special notes: The sort string is used to provide family name or + given name text that is to be used in locale- or national-language- + specific sorting of the formatted name and structured name types. + Without this information, sorting algorithms could incorrectly sort + this vCard within a sequence of sorted vCards. When this type is + present in a vCard, then this family name or given name value is used + for sorting the vCard. + + Type examples: For the case of family name sorting, the following + examples define common sort string usage with the FN and N types. + + FN:Rene van der Harten + N:van der Harten;Rene;J.;Sir;R.D.O.N. + SORT-STRING:Harten + + FN:Robert Pau Shou Chang + N:Pau;Shou Chang;Robert + SORT-STRING:Pau + + FN:Osamu Koura + N:Koura;Osamu + SORT-STRING:Koura + + FN:Oscar del Pozo + N:del Pozo Triscon;Oscar + SORT-STRING:Pozo + + FN:Chistine d'Aboville + N:d'Aboville;Christine + SORT-STRING:Aboville + +3.6.6 SOUND Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type SOUND + + Type name: SOUND + + Type purpose: To specify a digital sound content information that + annotates some aspect of the vCard. By default this type is used to + specify the proper pronunciation of the name type value of the vCard. + + Type encoding: The encoding MUST be reset to "b" using the ENCODING + parameter in order to specify inline, encoded binary data. If the + value is referenced by a URI value, then the default encoding of 8bit + is used and no explicit ENCODING parameter is needed. + + + + +Dawson & Howes Standards Track [Page 23] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + Type value: A single value. The default is binary value. It can also + be reset to uri value. The uri value can be used to specify a value + outside of this MIME entity. + + Type special notes: The type can include the type parameter "TYPE" to + specify the audio format type. The TYPE parameter values MUST be one + of the IANA registered audio formats or a non-standard audio format. + + Type example: + + SOUND;TYPE=BASIC;VALUE=uri:CID:JOHNQPUBLIC.part8. + 19960229T080000.xyzMail@host1.com + + SOUND;TYPE=BASIC;ENCODING=b:MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcN + AQEEBQAwdzELMAkGA1UEBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bm + ljYXRpb25zIENvcnBvcmF0aW9uMRwwGgYDVQQLExNJbmZvcm1hdGlvbiBTeXN0 + <...the remainder of "B" encoded binary data...> + +3.6.7 UID Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type UID + + Type name: UID + + Type purpose: To specify a value that represents a globally unique + identifier corresponding to the individual or resource associated + with the vCard. + + Type encoding: 8bit + + Type value: A single text value. + + Type special notes: The type is used to uniquely identify the object + that the vCard represents. + + The type can include the type parameter "TYPE" to specify the format + of the identifier. The TYPE parameter value should be an IANA + registered identifier format. The value can also be a non-standard + format. + + Type example: + + UID:19950401-080045-40000F192713-0052 + + + + + + +Dawson & Howes Standards Track [Page 24] + +RFC 2426 vCard MIME Directory Profile September 1998 + + +3.6.8 URL Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type URL + + Type name: URL + + Type purpose: To specify a uniform resource locator associated with + the object that the vCard refers to. + + Type encoding: 8bit + + Type value: A single uri value. + + Type example: + + URL:http://www.swbyps.restaurant.french/~chezchic.html + +3.6.9 VERSION Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type VERSION + + Type name: VERSION + + Type purpose: To specify the version of the vCard specification used + to format this vCard. + + Type encoding: 8bit + + Type value: A single text value. + + Type special notes: The property MUST be present in the vCard object. + The value MUST be "3.0" if the vCard corresponds to this + specification. + + Type example: + + VERSION:3.0 + +3.7 Security Types + + These types are concerned with the security of communication pathways + or access to the vCard. + + + + + +Dawson & Howes Standards Track [Page 25] + +RFC 2426 vCard MIME Directory Profile September 1998 + + +3.7.1 CLASS Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type CLASS + + Type name: CLASS + + Type purpose: To specify the access classification for a vCard + object. + + Type encoding: 8bit + + Type value: A single text value. + + Type special notes: An access classification is only one component of + the general security model for a directory service. The + classification attribute provides a method of capturing the intent of + the owner for general access to information described by the vCard + object. + + Type examples: + + CLASS:PUBLIC + + CLASS:PRIVATE + + CLASS:CONFIDENTIAL + +3.7.2 KEY Type Definition + + To: ietf-mime-directory@imc.org + + Subject: Registration of text/directory MIME type KEY + + Type name: KEY + + Type purpose: To specify a public key or authentication certificate + associated with the object that the vCard represents. + + Type encoding: The encoding MUST be reset to "b" using the ENCODING + parameter in order to specify inline, encoded binary data. If the + value is a text value, then the default encoding of 8bit is used and + no explicit ENCODING parameter is needed. + + Type value: A single value. The default is binary. It can also be + reset to text value. The text value can be used to specify a text + key. + + + +Dawson & Howes Standards Track [Page 26] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + Type special notes: The type can also include the type parameter TYPE + to specify the public key or authentication certificate format. The + parameter type should specify an IANA registered public key or + authentication certificate format. The parameter type can also + specify a non-standard format. + + Type example: + + KEY;ENCODING=b:MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQA + wdzELMAkGA1UEBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENbW11bmljYX + Rpb25zIENvcnBvcmF0aW9uMRwwGgYDVQQLExNJbmZvcm1hdGlvbiBTeXN0 + ZW1zMRwwGgYDVQQDExNyb290Y2EubmV0c2NhcGUuY29tMB4XDTk3MDYwNj + E5NDc1OVoXDTk3MTIwMzE5NDc1OVowgYkxCzAJBgNVBAYTAlVTMSYwJAYD + VQQKEx1OZXRzY2FwZSBDb21tdW5pY2F0aW9ucyBDb3JwLjEYMBYGA1UEAx + MPVGltb3RoeSBBIEhvd2VzMSEwHwYJKoZIhvcNAQkBFhJob3dlc0BuZXRz + Y2FwZS5jb20xFTATBgoJkiaJk/IsZAEBEwVob3dlczBcMA0GCSqGSIb3DQ + EBAQUAA0sAMEgCQQC0JZf6wkg8pLMXHHCUvMfL5H6zjSk4vTTXZpYyrdN2 + dXcoX49LKiOmgeJSzoiFKHtLOIboyludF90CgqcxtwKnAgMBAAGjNjA0MB + EGCWCGSAGG+EIBAQQEAwIAoDAfBgNVHSMEGDAWgBT84FToB/GV3jr3mcau + +hUMbsQukjANBgkqhkiG9w0BAQQFAAOBgQBexv7o7mi3PLXadkmNP9LcIP + mx93HGp0Kgyx1jIVMyNgsemeAwBM+MSlhMfcpbTrONwNjZYW8vJDSoi//y + rZlVt9bJbs7MNYZVsyF1unsqaln4/vy6Uawfg8VUMk1U7jt8LYpo4YULU7 + UZHPYVUaSgVttImOHZIKi4hlPXBOhcUQ== + +3.8 Extended Types + + The types defined by this document can be extended with private types + using the non-standard, private values mechanism defined in [RFC + 2045]. Non-standard, private types with a name starting with "X-" may + be defined bilaterally between two cooperating agents without outside + registration or standardization. + +4. Formal Grammar + + The following formal grammar is provided to assist developers in + building parsers for the vCard. + + This syntax is written according to the form described in RFC 2234, + but it references just this small subset of RFC 2234 literals: + + ;******************************************* + ; Commonly Used Literal Definition + ;******************************************* + + ALPHA = %x41-5A / %x61-7A + ; Latin Capital Letter A-Latin Capital Letter Z / + ; Latin Small Letter a-Latin Small Letter z + + + + +Dawson & Howes Standards Track [Page 27] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + CHAR = %x01-7F + ; Any C0 Controls and Basic Latin, excluding NULL from + ; Code Charts, pages 7-6 through 7-9 in [UNICODE] + + CR = %x0D + ; Carriage Return + + LF = %0A + ; Line Feed + + CRLF = CR LF + ; Internet standard newline + + ;CTL = %x00-1F / %x7F + ; Controls. Not used, but referenced in comments. + + DIGIT = %x30-39 + ; Digit Zero-Digit Nine + + DQUOTE = %x22 + ; Quotation Mark + + HTAB = %x09 + ; Horizontal Tabulation + + SP = %x20 + ; space + + VCHAR = %x21-7E + ; Visible (printing) characters + + WSP = SP / HTAB + ; White Space + + ;******************************************* + ; Basic vCard Definition + ;******************************************* + + vcard_entity = 1*(vcard) + + vcard = [group "."] "BEGIN" ":" "VCARD" 1*CRLF + 1*(contentline) + ;A vCard object MUST include the VERSION, FN and N types. + [group "."] "END" ":" "VCARD" 1*CRLF + + contentline = [group "."] name *(";" param ) ":" value CRLF + ; When parsing a content line, folded lines must first + ; be unfolded according to the unfolding procedure + + + +Dawson & Howes Standards Track [Page 28] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + ; described above. When generating a content line, lines + ; longer than 75 characters SHOULD be folded according to + ; the folding procedure described in [MIME DIR]. + + group = 1*(ALPHA / DIGIT / "-") + + name = iana-token / x-name + ; Parsing of the param and value is + ; based on the "name" or type identifier + ; as defined in ABNF sections below + + iana-token = 1*(ALPHA / DIGIT / "-") + ; vCard type or parameter identifier registered with IANA + + x-name = "X-" 1*(ALPHA / DIGIT / "-") + ; Reserved for non-standard use + + param = param-name "=" param-value *("," param-value) + + param-name = iana-token / x-name + + param-value = ptext / quoted-string + + ptext = *SAFE-CHAR + + value = *VALUE-CHAR + + quoted-string = DQUOTE QSAFE-CHAR DQUOTE + + NON-ASCII = %x80-FF + ; Use is restricted by CHARSET parameter + ; on outer MIME object (UTF-8 preferred) + + QSAFE-CHAR = WSP / %x21 / %x23-7E / NON-ASCII + ; Any character except CTLs, DQUOTE + + SAFE-CHAR = WSP / %x21 / %x23-2B / %x2D-39 / %x3C-7E / NON-ASCII + ; Any character except CTLs, DQUOTE, ";", ":", "," + + VALUE-CHAR = WSP / VCHAR / NON-ASCII + ; Any textual character + + ;******************************************* + ; vCard Type Definition + ; + ; Provides type-specific definitions for how the + ; "value" and "param" are defined. + ;******************************************* + + + +Dawson & Howes Standards Track [Page 29] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + ;For name="NAME" + param = "" + ; No parameters allowed + + value = text-value + + ;For name="PROFILE" + param = "" + ; No parameters allowed + + value = text-value + ; Value MUST be the case insensitive value "VCARD + + ;For name="SOURCE" + param = source-param + ; No parameters allowed + + value = uri + + source-param = ("VALUE" "=" "uri") + / ("CONTEXT" "=" "word") + ; Parameter value specifies the protocol context + ; for the uri value. + / (x-name "=" *SAFE-CHAR) + + ;For name="FN" + ;This type MUST be included in a vCard object. + param = text-param + ; Text parameters allowed + + value = text-value + + ;For name="N" + ;This type MUST be included in a vCard object. + + param = text-param + ; Text parameters allowed + + value = n-value + + n-value = 0*4(text-value *("," text-value) ";") + text-value *("," text-value) + ; Family; Given; Middle; Prefix; Suffix. + ; Example: Public;John;Quincy,Adams;Reverend Dr. III + + ;For name="NICKNAME" + param = text-param + ; Text parameters allowed + + + +Dawson & Howes Standards Track [Page 30] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + value = text-list + + ;For name="PHOTO" + param = img-inline-param + ; Only image parameters allowed + + param =/ img-refer-param + ; Only image parameters allowed + + value = img-inline-value + ; Value and parameter MUST match + + value =/ img-refer-value + ; Value and parameter MUST match + + ;For name="BDAY" + param = ("VALUE" "=" "date") + ; Only value parameter allowed + + param =/ ("VALUE" "=" "date-time") + ; Only value parameter allowed + + value = date-value + ; Value MUST match value type + + value =/ date-time-value + ; Value MUST match value type + + ;For name="ADR" + param = adr-param / text-param + ; Only adr and text parameters allowed + + value = adr-value + + ;For name="LABEL" + param = adr-param / text-param + ; Only adr and text parameters allowed + + value = text-value + + ;For name="TEL" + param = tel-param + ; Only tel parameters allowed + + value = phone-number-value + + tel-param = "TYPE" "=" tel-type *("," tel-type) + + + + +Dawson & Howes Standards Track [Page 31] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + tel-type = "HOME" / "WORK" / "PREF" / "VOICE" / "FAX" / "MSG" + / "CELL" / "PAGER" / "BBS" / "MODEM" / "CAR" / "ISDN" + / "VIDEO" / "PCS" / iana-token / x-name + ; Values are case insensitive + + ;For name="EMAIL" + param = email-param + ; Only email parameters allowed + + value = text-value + + email-param = "TYPE" "=" email-type ["," "PREF"] + ; Value is case insensitive + + email-type = "INTERNET" / "X400" / iana-token / "X-" word + ; Values are case insensitive + + ;For name="MAILER" + param = text-param + ; Only text parameters allowed + + value = text-value + + ;For name="TZ" + param = "" + ; No parameters allowed + + value = utc-offset-value + + ;For name="GEO" + param = "" + ; No parameters allowed + + value = float-value ";" float-value + + ;For name="TITLE" + param = text-param + ; Only text parameters allowed + + value = text-value + + ;For name="ROLE" + param = text-param + ; Only text parameters allowed + + value = text-value + + ;For name="LOGO" + + + +Dawson & Howes Standards Track [Page 32] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + param = img-inline-param / img-refer-param + ; Only image parameters allowed + + value = img-inline-value / img-refer-value + ; Value and parameter MUST match + + ;For name="AGENT" + param = agent-inline-param + + param =/ agent-refer-param + + value = agent-inline-value + ; Value and parameter MUST match + + value =/ agent-refer-value + ; Value and parameter MUST match + + agent-inline-param = "" + ; No parameters allowed + + agent-refer-param = "VALUE" "=" "uri" + ; Only value parameter allowed + + agent-inline-value = text-value + ; Value MUST be a valid vCard object + + agent-refer-value = uri + ; URI MUST refer to image content of given type + + ;For name="ORG" + + param = text-param + ; Only text parameters allowed + + value = org-value + + org-value = *(text-value ";") text-value + ; First is Organization Name, remainder are Organization Units. + + ;For name="CATEGORIES" + param = text-param + ; Only text parameters allowed + + value = text-list + + ;For name="NOTE" + param = text-param + ; Only text parameters allowed + + + +Dawson & Howes Standards Track [Page 33] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + value = text-value + + ;For name="PRODID" + param = "" + ; No parameters allowed + + value = text-value + + ;For name="REV" + param = ["VALUE" =" "date-time"] + ; Only value parameters allowed. Values are case insensitive. + + param =/ "VALUE" =" "date" + ; Only value parameters allowed. Values are case insensitive. + + value = date-time-value + + value =/ date-value + + ;For name="SORT-STRING" + param = text-param + ; Only text parameters allowed + + value = text-value + + ;For name="SOUND" + param = snd-inline-param + ; Only sound parameters allowed + + param =/ snd-refer-param + ; Only sound parameters allowed + + value = snd-line-value + ; Value MUST match value type + + value =/ snd-refer-value + ; Value MUST match value type + + snd-inline-value = binary-value CRLF + ; Value MUST be "b" encoded audio content + + snd-inline-param = ("VALUE" "=" "binary"]) + / ("ENCODING" "=" "b") + / ("TYPE" "=" *SAFE-CHAR) + ; Value MUST be an IANA registered audio type + + snd-refer-value = uri + ; URI MUST refer to audio content of given type + + + +Dawson & Howes Standards Track [Page 34] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + snd-refer-param = ("VALUE" "=" "uri") + / ("TYPE" "=" word) + ; Value MUST be an IANA registered audio type + + ;For name="UID" + param = "" + ; No parameters allowed + + value = text-value + + ;For name="URL" + param = "" + ; No parameters allowed + + value = uri + + ;For name="VERSION" + ;This type MUST be included in a vCard object. + param = "" + ; No parameters allowed + + value = text-value + ; Value MUST be "3.0" + + ;For name="CLASS" + param = "" + ; No parameters allowed + + value = "PUBLIC" / "PRIVATE" / "CONFIDENTIAL" + / iana-token / x-name + ; Value are case insensitive + + ;For name="KEY" + param = key-txt-param + ; Only value and type parameters allowed + + param =/ key-bin-param + ; Only value and type parameters allowed + + value = text-value + + value =/ binary-value + + key-txt-param = "TYPE" "=" keytype + + key-bin-param = ("TYPE" "=" keytype) + / ("ENCODING" "=" "b") + ; Value MUST be a "b" encoded key or certificate + + + +Dawson & Howes Standards Track [Page 35] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + keytype = "X509" / "PGP" / iana-token / x-name + ; Values are case insensitive + + ;For name="X-" non-standard type + param = text-param / (x-name "=" param-value) + ; Only text or non-standard parameters allowed + + value = text-value + + ;******************************************* + ; vCard Commonly Used Parameter Definition + ;******************************************* + + text-param = ("VALUE" "=" "ptext") + / ("LANGUAGE" "=" langval) + / (x-name "=" param-value) + + langval = + + img-inline-value = binary-value + ;Value MUST be "b" encoded image content + + img-inline-param + + img-inline-param = ("VALUE" "=" "binary") + / ("ENCODING" "=" "b") + / ("TYPE" "=" param-value + ;TYPE value MUST be an IANA registered image type + + img-refer-value = uri + ;URI MUST refer to image content of given type + + img-refer-param = ("VALUE" "=" "uri") + / ("TYPE" "=" param-value) + ;TYPE value MUST be an IANA registered image type + + adr-param = ("TYPE" "=" adr-type *("," adr-type)) + / (text-param) + + adr-type = "dom" / "intl" / "postal" / "parcel" / "home" + / "work" / "pref" / iana-type / x-name + + adr-value = 0*6(text-value ";") text-value + ; PO Box, Extended Address, Street, Locality, Region, Postal + ; Code, Country Name + + + + + + +Dawson & Howes Standards Track [Page 36] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + ;******************************************* + ; vCard Type Value Definition + ;******************************************* + + text-value-list = 1*text-value *("," 1*text-value) + + text-value = *(SAFE-CHAR / ":" / DQUOTE / ESCAPED-CHAR) + + ESCAPED-CHAR = "\\" / "\;" / "\," / "\n" / "\N") + ; \\ encodes \, \n or \N encodes newline + ; \; encodes ;, \, encodes , + + binary-value = + + date-value = + + time-value = + + date-time-value = + + phone-number-value = + + uri-value = + + utc-offset-value = ("+" / "-") time-hour ":" time-minute + time-hour = 2DIGIT ;00-23 + time-minute = 2DIGIT ;00-59 + +5. Differences From vCard v2.1 + + This specification has been reviewed by the IETF community. The + review process introduced a number of differences from the [VCARD] + version 2.1. These differences require that vCard objects conforming + to this specification have a different version number than a vCard + conforming to [VCARD]. The differences include the following: + + . The QUOTED-PRINTABLE inline encoding has been eliminated. + Only the "B" encoding of [RFC 2047] is an allowed value for + the ENCODING parameter. + + . The method for specifying CRLF character sequences in text + type values has been changed. The CRLF character sequence in + a text type value is specified with the backslash character + sequence "\n" or "\N". + + + + +Dawson & Howes Standards Track [Page 37] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + . Any COMMA or SEMICOLON in a text type value must be backslash + escaped. + + . VERSION value corresponding to this specification MUST be + "3.0". + + . The [MIME-DIR] predefined types of SOURCE, NAME and PROFILE + are allowed. + + . The [MIME-DIR] VALUE type parameter for value data typing is + allowed. In addition, there are extensions made to these type + values for additional value types used in this specification. + + . The [VCARD] CHARSET type parameter has been eliminated. + Character set can only be specified on the CHARSET parameter + on the Content-Type MIME header field. + + . The [VCARD] support for non-significant WSP character has + been eliminated. + + . The "TYPE=" prefix to parameter values is required. In + [VCARD] this was optional. + + . LOGO, PHOTO and SOUND multimedia formats MUST be either IANA + registered types or non-standard types. + + . Inline binary content must be "B" encoded and folded. A blank + line after the encoded binary content is no longer required. + + . TEL values can be identified as personal communication + services telephone numbers with the PCS type parameter value. + + . The CATEGORIES, CLASS, NICKNAME, PRODID and SORT-STRING types + have been added. + + . The VERSION, N and FN types MUST be specified in a vCard. + This identifies the version of the specification that the + object was formatted to. It also assures that every vCard + will include both a structured and formatted name that can be + used to identify the object. + + + + + + + + + + + +Dawson & Howes Standards Track [Page 38] + +RFC 2426 vCard MIME Directory Profile September 1998 + + +6. Acknowledgements + + The many valuable comments contributed by members of the IETF ASID + working group are gratefully acknowledged, as are the contributions + by Roland Alden, Stephen Bartlett, Alec Dun, Patrik Faltstrom, Daniel + Gurney, Bruce Johnston, Daniel Klaussen, Pete Miller, Keith Moore, + Vinod Seraphin, Michelle Watkins. Chris Newman was especially helpful + in navigating the intricacies of ABNF lore. + +7. Authors' Addresses + + BEGIN:vCard + VERSION:3.0 + FN:Frank Dawson + ORG:Lotus Development Corporation + ADR;TYPE=WORK,POSTAL,PARCEL:;;6544 Battleford Drive + ;Raleigh;NC;27613-3502;U.S.A. + TEL;TYPE=VOICE,MSG,WORK:+1-919-676-9515 + TEL;TYPE=FAX,WORK:+1-919-676-9564 + EMAIL;TYPE=INTERNET,PREF:Frank_Dawson@Lotus.com + EMAIL;TYPE=INTERNET:fdawson@earthlink.net + URL:http://home.earthlink.net/~fdawson + END:vCard + + + BEGIN:vCard + VERSION:3.0 + FN:Tim Howes + ORG:Netscape Communications Corp. + ADR;TYPE=WORK:;;501 E. Middlefield Rd.;Mountain View; + CA; 94043;U.S.A. + TEL;TYPE=VOICE,MSG,WORK:+1-415-937-3419 + TEL;TYPE=FAX,WORK:+1-415-528-4164 + EMAIL;TYPE=INTERNET:howes@netscape.com + END:vCard + +8. Security Considerations + + vCards can carry cryptographic keys or certificates, as described in + Section 3.7.2. + + Section 3.7.1 specifies a desired security classification policy for + a particular vCard. That policy is not enforced in any way. + + The vCard objects have no inherent authentication or privacy, but can + easily be carried by any security mechanism that transfers MIME + objects with authentication or privacy. In cases where threats of + "spoofed" vCard information is a concern, the vCard SHOULD BE + + + +Dawson & Howes Standards Track [Page 39] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + transported using one of these secure mechanisms. + + The information in a vCard may become out of date. In cases where the + vitality of data is important to an originator of a vCard, the "URL" + type described in section 3.6.8 SHOULD BE specified. In addition, the + "REV" type described in section 3.6.4 can be specified to indicate + the last time that the vCard data was updated. + +9. References + + [ISO 8601] ISO 8601:1988 - Data elements and interchange formats - + Information interchange - Representation of dates and + times - The International Organization for + Standardization, June, 1988. + + [ISO 8601 TC] ISO 8601, Technical Corrigendum 1 - Data elements and + interchange formats - Information interchange - + Representation of dates and times - The International + Organization for Standardization, May, 1991. + + [ISO 9070] ISO 9070, Information Processing - SGML support + facilities - Registration Procedures for Public Text + Owner Identifiers, April, 1991. + + [CCITT E.163] Recommendation E.163 - Numbering Plan for The + International Telephone Service, CCITT Blue Book, + Fascicle II.2, pp. 128-134, November, 1988. + + [CCITT X.121] Recommendation X.121 - International Numbering Plan for + Public Data Networks, CCITT Blue Book, Fascicle VIII.3, + pp. 317-332, November, 1988. + + [CCITT X.520] Recommendation X.520 - The Directory - Selected + Attribute Types, November 1988. + + [CCITT X.521] Recommendation X.521 - The Directory - Selected Object + Classes, November 1988. + + [MIME-DIR] Howes, T., Smith, M., and F. Dawson, "A MIME Content- + Type for Directory Information", RFC 2425, September + 1998. + + [RFC 1738] Berners-Lee, T., Masinter, L., and M. McCahill, + "Uniform Resource Locators (URL)", RFC 1738, December + 1994. + + [RFC 1766] Alvestrand, H., "Tags for the Identification of + Languages", RFC 1766, March 1995. + + + +Dawson & Howes Standards Track [Page 40] + +RFC 2426 vCard MIME Directory Profile September 1998 + + + [RFC 1872] Levinson, E., "The MIME Multipart/Related Content- + type", RFC 1872, December 1995. + + [RFC 2045] Freed, N., and N. Borenstein, "Multipurpose Internet + Mail Extensions (MIME) - Part One: Format of Internet + Message Bodies", RFC 2045, November 1996. + + [RFC 2046] Freed, N., and N. Borenstein, "Multipurpose Internet + Mail Extensions (MIME) - Part Two: Media Types", RFC + 2046, November 1996. + + [RFC 2047] Moore, K., "Multipurpose Internet Mail Extensions + (MIME) - Part Three: Message Header Extensions for + Non-ASCII Text", RFC 2047, November 1996. + + [RFC 2048] Freed, N., Klensin, J., and J. Postel, "Multipurpose + Internet Mail Extensions (MIME) - Part Four: + Registration Procedures", RFC 2048, January 1997. + + [RFC 2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC 2234] Crocker, D., and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997. + + [UNICODE] "The Unicode Standard - Version 2.0", The Unicode + Consortium, July 1996. + + [VCARD] Internet Mail Consortium, "vCard - The Electronic + Business Card Version 2.1", + http://www.imc.org/pdi/vcard-21.txt, September 18, + 1996. + + + + + + + + + + + + + + + + + + + +Dawson & Howes Standards Track [Page 41] + +RFC 2426 vCard MIME Directory Profile September 1998 + + +10. Full Copyright Statement + + Copyright (C) The Internet Society (1998). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + + + + + + + + + + + + + + + + + + + + + + + + +Dawson & Howes Standards Track [Page 42] + diff --git a/specs/rfc2445-icalendar-2.0.txt b/specs/rfc2445-icalendar-2.0.txt new file mode 100644 index 0000000..70a3bcd --- /dev/null +++ b/specs/rfc2445-icalendar-2.0.txt @@ -0,0 +1,8291 @@ + + + + + + +Network Working Group F. Dawson +Request for Comments: 2445 Lotus +Category: Standards Track D. Stenerson + Microsoft + November 1998 + + + Internet Calendaring and Scheduling Core Object Specification + (iCalendar) + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1998). All Rights Reserved. + +Abstract + + There is a clear need to provide and deploy interoperable calendaring + and scheduling services for the Internet. Current group scheduling + and Personal Information Management (PIM) products are being extended + for use across the Internet, today, in proprietary ways. This memo + has been defined to provide the definition of a common format for + openly exchanging calendaring and scheduling information across the + Internet. + + This memo is formatted as a registration for a MIME media type per + [RFC 2048]. However, the format in this memo is equally applicable + for use outside of a MIME message content type. + + The proposed media type value is 'text/calendar'. This string would + label a media type containing calendaring and scheduling information + encoded as text characters formatted in a manner outlined below. + + This MIME media type provides a standard content type for capturing + calendar event, to-do and journal entry information. It also can be + used to convey free/busy time information. The content type is + suitable as a MIME message entity that can be transferred over MIME + based email systems, using HTTP or some other Internet transport. In + + + + + + +Dawson & Stenerson Standards Track [Page 1] + +RFC 2445 iCalendar November 1998 + + + addition, the content type is useful as an object for interactions + between desktop applications using the operating system clipboard, + drag/drop or file systems capabilities. + + This memo is based on the earlier work of the vCalendar specification + for the exchange of personal calendaring and scheduling information. + In order to avoid confusion with this referenced work, this memo is + to be known as the iCalendar specification. + + This memo defines the format for specifying iCalendar object methods. + An iCalendar object method is a set of usage constraints for the + iCalendar object. For example, these methods might define scheduling + messages that request an event be scheduled, reply to an event + request, send a cancellation notice for an event, modify or replace + the definition of an event, provide a counter proposal for an + original event request, delegate an event request to another + individual, request free or busy time, reply to a free or busy time + request, or provide similar scheduling messages for a to-do or + journal entry calendar component. The iCalendar Transport-indendent + Interoperability Protocol (iTIP) defined in [ITIP] is one such + scheduling protocol. + +Table of Contents + + 1 Introduction.....................................................5 + 2 Basic Grammar and Conventions....................................6 + 2.1 Formatting Conventions .......................................7 + 2.2 Related Memos ................................................8 + 2.3 International Considerations .................................8 + 3 Registration Information.........................................8 + 3.1 Content Type .................................................8 + 3.2 Parameters ...................................................9 + 3.3 Content Header Fields .......................................10 + 3.4 Encoding Considerations .....................................10 + 3.5 Security Considerations .....................................10 + 3.6 Interoperability Considerations .............................11 + 3.7 Applications Which Use This Media Type ......................11 + 3.8 Additional Information ......................................11 + 3.9 Magic Numbers ...............................................11 + 3.10 File Extensions ............................................11 + 3.11 Contact for Further Information: ...........................12 + 3.12 Intended Usage .............................................12 + 3.13 Authors/Change Controllers .................................12 + 4 iCalendar Object Specification..................................13 + 4.1 Content Lines ...............................................13 + 4.1.1 List and Field Separators ................................16 + 4.1.2 Multiple Values ..........................................16 + 4.1.3 Binary Content ...........................................16 + + + +Dawson & Stenerson Standards Track [Page 2] + +RFC 2445 iCalendar November 1998 + + + 4.1.4 Character Set ............................................17 + 4.2 Property Parameters .........................................17 + 4.2.1 Alternate Text Representation ............................18 + 4.2.2 Common Name ..............................................19 + 4.2.3 Calendar User Type .......................................20 + 4.2.4 Delegators ...............................................20 + 4.2.5 Delegatees ...............................................21 + 4.2.6 Directory Entry Reference ................................21 + 4.2.7 Inline Encoding ..........................................22 + 4.2.8 Format Type ..............................................23 + 4.2.9 Free/Busy Time Type ......................................23 + 4.2.10 Language ................................................24 + 4.2.11 Group or List Membership ................................25 + 4.2.12 Participation Status ....................................25 + 4.2.13 Recurrence Identifier Range .............................27 + 4.2.14 Alarm Trigger Relationship ..............................27 + 4.2.15 Relationship Type .......................................28 + 4.2.16 Participation Role ......................................29 + 4.2.17 RSVP Expectation ........................................29 + 4.2.18 Sent By .................................................30 + 4.2.19 Time Zone Identifier ....................................30 + 4.2.20 Value Data Types ........................................32 + 4.3 Property Value Data Types ...................................32 + 4.3.1 Binary ...................................................33 + 4.3.2 Boolean ..................................................33 + 4.3.3 Calendar User Address ....................................34 + 4.3.4 Date .....................................................34 + 4.3.5 Date-Time ................................................35 + 4.3.6 Duration .................................................37 + 4.3.7 Float ....................................................38 + 4.3.8 Integer ..................................................38 + 4.3.9 Period of Time ...........................................39 + 4.3.10 Recurrence Rule .........................................40 + 4.3.11 Text ....................................................45 + 4.3.12 Time ....................................................47 + 4.3.13 URI .....................................................49 + 4.3.14 UTC Offset ..............................................49 + 4.4 iCalendar Object ............................................50 + 4.5 Property ....................................................51 + 4.6 Calendar Components .........................................51 + 4.6.1 Event Component ..........................................52 + 4.6.2 To-do Component ..........................................55 + 4.6.3 Journal Component ........................................56 + 4.6.4 Free/Busy Component ......................................58 + 4.6.5 Time Zone Component ......................................60 + 4.6.6 Alarm Component ..........................................67 + 4.7 Calendar Properties .........................................73 + 4.7.1 Calendar Scale ...........................................73 + + + +Dawson & Stenerson Standards Track [Page 3] + +RFC 2445 iCalendar November 1998 + + + 4.7.2 Method ...................................................74 + 4.7.3 Product Identifier .......................................75 + 4.7.4 Version ..................................................76 + 4.8 Component Properties ........................................77 + 4.8.1 Descriptive Component Properties .........................77 + 4.8.1.1 Attachment ...........................................77 + 4.8.1.2 Categories ...........................................78 + 4.8.1.3 Classification .......................................79 + 4.8.1.4 Comment ..............................................80 + 4.8.1.5 Description ..........................................81 + 4.8.1.6 Geographic Position ..................................82 + 4.8.1.7 Location .............................................84 + 4.8.1.8 Percent Complete .....................................85 + 4.8.1.9 Priority .............................................85 + 4.8.1.10 Resources ...........................................87 + 4.8.1.11 Status ..............................................88 + 4.8.1.12 Summary .............................................89 + 4.8.2 Date and Time Component Properties .......................90 + 4.8.2.1 Date/Time Completed ..................................90 + 4.8.2.2 Date/Time End ........................................91 + 4.8.2.3 Date/Time Due ........................................92 + 4.8.2.4 Date/Time Start ......................................93 + 4.8.2.5 Duration .............................................94 + 4.8.2.6 Free/Busy Time .......................................95 + 4.8.2.7 Time Transparency ....................................96 + 4.8.3 Time Zone Component Properties ...........................97 + 4.8.3.1 Time Zone Identifier .................................97 + 4.8.3.2 Time Zone Name .......................................98 + 4.8.3.3 Time Zone Offset From ................................99 + 4.8.3.4 Time Zone Offset To .................................100 + 4.8.3.5 Time Zone URL .......................................101 + 4.8.4 Relationship Component Properties .......................102 + 4.8.4.1 Attendee ............................................102 + 4.8.4.2 Contact .............................................104 + 4.8.4.3 Organizer ...........................................106 + 4.8.4.4 Recurrence ID .......................................107 + 4.8.4.5 Related To ..........................................109 + 4.8.4.6 Uniform Resource Locator ............................110 + 4.8.4.7 Unique Identifier ...................................111 + 4.8.5 Recurrence Component Properties .........................112 + 4.8.5.1 Exception Date/Times ................................112 + 4.8.5.2 Exception Rule ......................................114 + 4.8.5.3 Recurrence Date/Times ...............................115 + 4.8.5.4 Recurrence Rule .....................................117 + 4.8.6 Alarm Component Properties ..............................126 + 4.8.6.1 Action ..............................................126 + 4.8.6.2 Repeat Count ........................................126 + 4.8.6.3 Trigger .............................................127 + + + +Dawson & Stenerson Standards Track [Page 4] + +RFC 2445 iCalendar November 1998 + + + 4.8.7 Change Management Component Properties ..................129 + 4.8.7.1 Date/Time Created ...................................129 + 4.8.7.2 Date/Time Stamp .....................................130 + 4.8.7.3 Last Modified .......................................131 + 4.8.7.4 Sequence Number .....................................131 + 4.8.8 Miscellaneous Component Properties ......................133 + 4.8.8.1 Non-standard Properties .............................133 + 4.8.8.2 Request Status ......................................134 + 5 iCalendar Object Examples......................................136 + 6 Recommended Practices..........................................140 + 7 Registration of Content Type Elements..........................141 + 7.1 Registration of New and Modified iCalendar Object Methods ..141 + 7.2 Registration of New Properties .............................141 + 7.2.1 Define the property .....................................142 + 7.2.2 Post the Property definition ............................143 + 7.2.3 Allow a comment period ..................................143 + 7.2.4 Submit the property for approval ........................143 + 7.3 Property Change Control ....................................143 + 8 References.....................................................144 + 9 Acknowledgments................................................145 + 10 Authors' and Chairs' Addresses................................146 + 11 Full Copyright Statement......................................148 + +1 Introduction + + The use of calendaring and scheduling has grown considerably in the + last decade. Enterprise and inter-enterprise business has become + dependent on rapid scheduling of events and actions using this + information technology. However, the longer term growth of + calendaring and scheduling, is currently limited by the lack of + Internet standards for the message content types that are central to + these knowledgeware applications. This memo is intended to progress + the level of interoperability possible between dissimilar calendaring + and scheduling applications. This memo defines a MIME content type + for exchanging electronic calendaring and scheduling information. The + Internet Calendaring and Scheduling Core Object Specification, or + iCalendar, allows for the capture and exchange of information + normally stored within a calendaring and scheduling application; such + as a Personal Information Manager (PIM) or a Group Scheduling + product. + + The iCalendar format is suitable as an exchange format between + applications or systems. The format is defined in terms of a MIME + content type. This will enable the object to be exchanged using + several transports, including but not limited to SMTP, HTTP, a file + system, desktop interactive protocols such as the use of a memory- + based clipboard or drag/drop interactions, point-to-point + asynchronous communication, wired-network transport, or some form of + + + +Dawson & Stenerson Standards Track [Page 5] + +RFC 2445 iCalendar November 1998 + + + unwired transport such as infrared might also be used. + + The memo also provides for the definition of iCalendar object methods + that will map this content type to a set of messages for supporting + calendaring and scheduling operations such as requesting, replying + to, modifying, and canceling meetings or appointments, to-dos and + journal entries. The iCalendar object methods can be used to define + other calendaring and scheduling operations such a requesting for and + replying with free/busy time data. Such a scheduling protocol is + defined in the iCalendar Transport-independent Interoperability + Protocol (iTIP) defined in [ITIP]. + + The memo also includes a formal grammar for the content type based on + the Internet ABNF defined in [RFC 2234]. This ABNF is required for + the implementation of parsers and to serve as the definitive + reference when ambiguities or questions arise in interpreting the + descriptive prose definition of the memo. + +2 Basic Grammar and Conventions + + 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 interoperated as described in + [RFC 2119]. + + This memo makes use of both a descriptive prose and a more formal + notation for defining the calendaring and scheduling format. + + The notation used in this memo is the ABNF notation of [RFC 2234]. + Readers intending on implementing this format defined in this memo + should be familiar with this notation in order to properly interpret + the specifications of this memo. + + All numeric and hexadecimal values used in this memo are given in + decimal notation. + + All names of properties, property parameters, enumerated property + values and property parameter values are case-insensitive. However, + all other property values are case-sensitive, unless otherwise + stated. + + Note: All indented editorial notes, such as this one, are + intended to provide the reader with additional information. The + information is not essential to the building of an + implementation conformant with this memo. The information is + provided to highlight a particular feature or characteristic of + the memo. + + + + +Dawson & Stenerson Standards Track [Page 6] + +RFC 2445 iCalendar November 1998 + + + The format for the iCalendar object is based on the syntax of the + [RFC 2425] content type. While the iCalendar object is not a profile + of the [RFC 2425] content type, it does reuse a number of the + elements from the [RFC 2425] specification. + +2.1 Formatting Conventions + + The mechanisms defined in this memo are defined in prose. Many of the + terms used to describe these have common usage that is different than + the standards usage of this memo. In order to reference within this + memo elements of the calendaring and scheduling model, core object + (this memo) or interoperability protocol [ITIP] some formatting + conventions have been used. Calendaring and scheduling roles are + referred to in quoted-strings of text with the first character of + each word in upper case. For example, "Organizer" refers to a role of + a "Calendar User" within the scheduling protocol defined by [ITIP]. + Calendar components defined by this memo are referred to with + capitalized, quoted-strings of text. All calendar components start + with the letter "V". For example, "VEVENT" refers to the event + calendar component, "VTODO" refers to the to-do calendar component + and "VJOURNAL" refers to the daily journal calendar component. + Scheduling methods defined by [ITIP] are referred to with + capitalized, quoted-strings of text. For example, "REQUEST" refers to + the method for requesting a scheduling calendar component be created + or modified, "REPLY" refers to the method a recipient of a request + uses to update their status with the "Organizer" of the calendar + component. + + The properties defined by this memo are referred to with capitalized, + quoted-strings of text, followed by the word "property". For example, + "ATTENDEE" property refers to the iCalendar property used to convey + the calendar address of a calendar user. Property parameters defined + by this memo are referred to with lowercase, quoted-strings of text, + followed by the word "parameter". For example, "value" parameter + refers to the iCalendar property parameter used to override the + default data type for a property value. Enumerated values defined by + this memo are referred to with capitalized text, either alone or + followed by the word "value". For example, the "MINUTELY" value can + be used with the "FREQ" component of the "RECUR" data type to specify + repeating components based on an interval of one minute or more. + + + + + + + + + + + +Dawson & Stenerson Standards Track [Page 7] + +RFC 2445 iCalendar November 1998 + + +2.2 Related Memos + + Implementers will need to be familiar with several other memos that, + along with this memo, form a framework for Internet calendaring and + scheduling standards. This memo, [ICAL], specifies a core + specification of objects, data types, properties and property + parameters. + + [ITIP] - specifies an interoperability protocol for scheduling + between different implementations; + + [IMIP] specifies an Internet email binding for [ITIP]. + + This memo does not attempt to repeat the specification of concepts or + definitions from these other memos. Where possible, references are + made to the memo that provides for the specification of these + concepts or definitions. + +2.3 International Considerations + + In the rest of this document, descriptions of characters are of the + form "character name (codepoint)", where "codepoint" is from the US- + ASCII character set. The "character name" is the authoritative + description; (codepoint) is a reference to that character in US-ASCII + or US-ASCII compatible sets (for example the ISO-8859-x family, UTF- + 8, ISO-2022-xx, KOI8-R). If a non-US-ASCII compatible character set + is used, appropriate code-point from that character set MUST be + chosen instead. Use of non-US-ASCII-compatible character sets is NOT + recommended. + +3 Registration Information + + The Calendaring and Scheduling Core Object Specification is intended + for use as a MIME content type. However, the implementation of the + memo is in no way limited solely as a MIME content type. + +3.1 Content Type + + The following text is intended to register this memo as the MIME + content type "text/calendar". + + To: ietf-types@uninett.no + + Subject: Registration of MIME content type text/calendar. + + MIME media type name: text + + MIME subtype name: calendar + + + +Dawson & Stenerson Standards Track [Page 8] + +RFC 2445 iCalendar November 1998 + + +3.2 Parameters + + Required parameters: none + + Optional parameters: charset, method, component and optinfo + + The "charset" parameter is defined in [RFC 2046] for other body + parts. It is used to identify the default character set used within + the body part. + + The "method" parameter is used to convey the iCalendar object method + or transaction semantics for the calendaring and scheduling + information. It also is an identifier for the restricted set of + properties and values that the iCalendar object consists of. The + parameter is to be used as a guide for applications interpreting the + information contained within the body part. It SHOULD NOT be used to + exclude or require particular pieces of information unless the + identified method definition specifically calls for this behavior. + Unless specifically forbidden by a particular method definition, a + text/calendar content type can contain any set of properties + permitted by the Calendaring and Scheduling Core Object + Specification. The "method" parameter MUST be the same value as that + specified in the "METHOD" component property in the iCalendar object. + If one is present, the other MUST also be present. + + The value for the "method" parameter is defined as follows: + + method = 1*(ALPHA / DIGIT / "-") + ; IANA registered iCalendar object method + + The "component" parameter conveys the type of iCalendar calendar + component within the body part. If the iCalendar object contains more + than one calendar component type, then multiple component parameters + MUST be specified. + + The value for the "component" parameter is defined as follows: + + component = ("VEVENT" / "VTODO" / "VJOURNAL" / "VFREEBUSY" + / "VTIMEZONE" / x-name / iana-token) + + The "optinfo" parameter conveys optional information about the + iCalendar object within the body part. This parameter can only + specify semantics already specified by the iCalendar object and that + can be otherwise determined by parsing the body part. In addition, + the optional information specified by this parameter MUST be + consistent with that information specified by the iCalendar object. + For example, it can be used to convey the "Attendee" response status + to a meeting request. The parameter value consists of a string value. + + + +Dawson & Stenerson Standards Track [Page 9] + +RFC 2445 iCalendar November 1998 + + + The parameter can be specified multiple times. + + This parameter MAY only specify semantics already specified by the + iCalendar object and that can be otherwise determined by parsing the + body part. + + The value for the "optinfo" parameter is defined as follows: + + optinfo = infovalue / qinfovalue + + infovalue = iana-token / x-name + + qinfovalue = DQUOTE (infovalue) DQUOTE + +3.3 Content Header Fields + + Optional content header fields: Any header fields defined by [RFC + 2045]. + +3.4 Encoding Considerations + + This MIME content type can contain 8bit characters, so the use of + quoted-printable or BASE64 MIME content-transfer-encodings might be + necessary when iCalendar objects are transferred across protocols + restricted to the 7bit repertoire. Note that a text valued property + in the content entity can also have content encoding of special + characters using a BACKSLASH character (US-ASCII decimal 92) + escapement technique. This means that content values can end up + encoded twice. + +3.5 Security Considerations + + SPOOFING - - In this memo, the "Organizer" is the only person + authorized to make changes to an existing "VEVENT", "VTODO", + "VJOURNAL" calendar component and redistribute the updates to the + "Attendees". An iCalendar object that maliciously changes or cancels + an existing "VEVENT", "VTODO" or "VJOURNAL" or "VFREEBUSY" calendar + component might be constructed by someone other than the "Organizer" + and sent to the "Attendees". In addition in this memo, other than the + "Organizer", an "Attendee" of a "VEVENT", "VTODO", "VJOURNAL" + calendar component is the only other person authorized to update any + parameter associated with their "ATTENDEE" property and send it to + the "Organizer". An iCalendar object that maliciously changes the + "ATTENDEE" parameters can be constructed by someone other than the + real "Attendee" and sent to the "Organizer". + + + + + + +Dawson & Stenerson Standards Track [Page 10] + +RFC 2445 iCalendar November 1998 + + + PROCEDURAL ALARMS - - An iCalendar object can be created that + contains a "VEVENT" and "VTODO" calendar component with "VALARM" + calendar components. The "VALARM" calendar component can be of type + PROCEDURE and can have an attachment containing some sort of + executable program. Implementations that incorporate these types of + alarms are subject to any virus or malicious attack that might occur + as a result of executing the attachment. + + ATTACHMENTS - - An iCalendar object can include references to Uniform + Resource Locators that can be programmed resources. + + Implementers and users of this memo should be aware of the network + security implications of accepting and parsing such information. In + addition, the security considerations observed by implementations of + electronic mail systems should be followed for this memo. + +3.6 Interoperability Considerations + + This MIME content type is intended to define a common format for + conveying calendaring and scheduling information between different + systems. It is heavily based on the earlier [VCAL] industry + specification. + +3.7 Applications Which Use This Media Type + + This content-type is designed for widespread use by Internet + calendaring and scheduling applications. In addition, applications in + the workflow and document management area might find this content- + type applicable. The [ITIP] and [IMIP] Internet protocols directly + use this content-type also. Future work on an Internet calendar + access protocol will utilize this content-type too. + +3.8 Additional Information + + This memo defines this content-type. + +3.9 Magic Numbers + + None. + +3.10 File Extensions + + The file extension of "ics" is to be used to designate a file + containing (an arbitrary set of) calendaring and scheduling + information consistent with this MIME content type. + + + + + + +Dawson & Stenerson Standards Track [Page 11] + +RFC 2445 iCalendar November 1998 + + + The file extension of "ifb" is to be used to designate a file + containing free or busy time information consistent with this MIME + content type. + + Macintosh file type codes: The file type code of "iCal" is to be used + in Apple MacIntosh operating system environments to designate a file + containing calendaring and scheduling information consistent with + this MIME media type. + + The file type code of "iFBf" is to be used in Apple MacIntosh + operating system environments to designate a file containing free or + busy time information consistent with this MIME media type. + +3.11 Contact for Further Information: + + Frank Dawson + 6544 Battleford Drive + Raleigh, NC 27613-3502 + 919-676-9515 (Telephone) + 919-676-9564 (Data/Facsimile) + Frank_Dawson@Lotus.com (Internet Mail) + + Derik Stenerson + One Microsoft Way + Redmond, WA 98052-6399 + 425-936-5522 (Telephone) + 425-936-7329 (Facsimile) + deriks@microsoft.com (Internet Mail) + +3.12 Intended Usage + + COMMON + +3.13 Authors/Change Controllers + + Frank Dawson + 6544 Battleford Drive + Raleigh, NC 27613-3502 + 919-676-9515 (Telephone) + 919-676-9564 (Data/Facsimile) + Frank_Dawson@Lotus.com (Internet Mail) + + Derik Stenerson + One Microsoft Way + Redmond, WA 98052-6399 + 425-936-5522 (Telephone) + 425-936-7329 (Facsimile) + deriks@microsoft.com (Internet Mail) + + + +Dawson & Stenerson Standards Track [Page 12] + +RFC 2445 iCalendar November 1998 + + +4 iCalendar Object Specification + + The following sections define the details of a Calendaring and + Scheduling Core Object Specification. This information is intended to + be an integral part of the MIME content type registration. In + addition, this information can be used independent of such content + registration. In particular, this memo has direct applicability for + use as a calendaring and scheduling exchange format in file-, memory- + or network-based transport mechanisms. + +4.1 Content Lines + + The iCalendar object is organized into individual lines of text, + called content lines. Content lines are delimited by a line break, + which is a CRLF sequence (US-ASCII decimal 13, followed by US-ASCII + decimal 10). + + Lines of text SHOULD NOT be longer than 75 octets, excluding the line + break. Long content lines SHOULD be split into a multiple line + representations using a line "folding" technique. That is, a long + line can be split between any two characters by inserting a CRLF + immediately followed by a single linear white space character (i.e., + SPACE, US-ASCII decimal 32 or HTAB, US-ASCII decimal 9). Any sequence + of CRLF followed immediately by a single linear white space character + is ignored (i.e., removed) when processing the content type. + + For example the line: + + DESCRIPTION:This is a long description that exists on a long line. + + Can be represented as: + + DESCRIPTION:This is a lo + ng description + that exists on a long line. + + The process of moving from this folded multiple line representation + to its single line representation is called "unfolding". Unfolding is + accomplished by removing the CRLF character and the linear white + space character that immediately follows. + + When parsing a content line, folded lines MUST first be unfolded + according to the unfolding procedure described above. When generating + a content line, lines longer than 75 octets SHOULD be folded + according to the folding procedure described above. + + + + + + +Dawson & Stenerson Standards Track [Page 13] + +RFC 2445 iCalendar November 1998 + + + The content information associated with an iCalendar object is + formatted using a syntax similar to that defined by [RFC 2425]. That + is, the content information consists of CRLF-separated content lines. + + The following notation defines the lines of content in an iCalendar + object: + + contentline = name *(";" param ) ":" value CRLF + ; This ABNF is just a general definition for an initial parsing + ; of the content line into its property name, parameter list, + ; and value string + + ; When parsing a content line, folded lines MUST first + ; be unfolded according to the unfolding procedure + ; described above. When generating a content line, lines + ; longer than 75 octets SHOULD be folded according to + ; the folding procedure described above. + + name = x-name / iana-token + + iana-token = 1*(ALPHA / DIGIT / "-") + ; iCalendar identifier registered with IANA + + x-name = "X-" [vendorid "-"] 1*(ALPHA / DIGIT / "-") + ; Reservered for experimental use. Not intended for use in + ; released products. + + vendorid = 3*(ALPHA / DIGIT) ;Vendor identification + + param = param-name "=" param-value + *("," param-value) + ; Each property defines the specific ABNF for the parameters + ; allowed on the property. Refer to specific properties for + ; precise parameter ABNF. + + param-name = iana-token / x-token + + param-value = paramtext / quoted-string + + paramtext = *SAFE-CHAR + + value = *VALUE-CHAR + + quoted-string = DQUOTE *QSAFE-CHAR DQUOTE + + NON-US-ASCII = %x80-F8 + ; Use restricted by charset parameter + ; on outer MIME object (UTF-8 preferred) + + + +Dawson & Stenerson Standards Track [Page 14] + +RFC 2445 iCalendar November 1998 + + + QSAFE-CHAR = WSP / %x21 / %x23-7E / NON-US-ASCII + ; Any character except CTLs and DQUOTE + + SAFE-CHAR = WSP / %x21 / %x23-2B / %x2D-39 / %x3C-7E + / NON-US-ASCII + ; Any character except CTLs, DQUOTE, ";", ":", "," + + VALUE-CHAR = WSP / %x21-7E / NON-US-ASCII + ; Any textual character + + CR = %x0D + ; carriage return + + LF = %x0A + ; line feed + + CRLF = CR LF + ; Internet standard newline + + CTL = %x00-08 / %x0A-1F / %x7F + ; Controls + + ALPHA = %x41-5A / %x61-7A ; A-Z / a-z + + DIGIT = %x30-39 + ; 0-9 + + DQUOTE = %x22 + ; Quotation Mark + + WSP = SPACE / HTAB + + SPACE = %x20 + + HTAB = %x09 + + The property value component of a content line has a format that is + property specific. Refer to the section describing each property for + a definition of this format. + + All names of properties, property parameters, enumerated property + values and property parameter values are case-insensitive. However, + all other property values are case-sensitive, unless otherwise + stated. + + + + + + + +Dawson & Stenerson Standards Track [Page 15] + +RFC 2445 iCalendar November 1998 + + +4.1.1 List and Field Separators + + Some properties and parameters allow a list of values. Values in a + list of values MUST be separated by a COMMA character (US-ASCII + decimal 44). There is no significance to the order of values in a + list. For those parameter values (such as those that specify URI + values) that are specified in quoted-strings, the individual quoted- + strings are separated by a COMMA character (US-ASCII decimal 44). + + Some property values are defined in terms of multiple parts. These + structured property values MUST have their value parts separated by a + SEMICOLON character (US-ASCII decimal 59). + + Some properties allow a list of parameters. Each property parameter + in a list of property parameters MUST be separated by a SEMICOLON + character (US-ASCII decimal 59). + + Property parameters with values containing a COLON, a SEMICOLON or a + COMMA character MUST be placed in quoted text. + + For example, in the following properties a SEMICOLON is used to + separate property parameters from each other, and a COMMA is used to + separate property values in a value list. + + ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT:MAILTO: + jsmith@host.com + + RDATE;VALUE=DATE:19970304,19970504,19970704,19970904 + +4.1.2 Multiple Values + + Some properties defined in the iCalendar object can have multiple + values. The general rule for encoding multi-valued items is to simply + create a new content line for each value, including the property + name. However, it should be noted that some properties support + encoding multiple values in a single property by separating the + values with a COMMA character (US-ASCII decimal 44). Individual + property definitions should be consulted for determining whether a + specific property allows multiple values and in which of these two + forms. + +4.1.3 Binary Content + + Binary content information in an iCalendar object SHOULD be + referenced using a URI within a property value. That is the binary + content information SHOULD be placed in an external MIME entity that + can be referenced by a URI from within the iCalendar object. In + applications where this is not feasible, binary content information + + + +Dawson & Stenerson Standards Track [Page 16] + +RFC 2445 iCalendar November 1998 + + + can be included within an iCalendar object, but only after first + encoding it into text using the "BASE64" encoding method defined in + [RFC 2045]. Inline binary contact SHOULD only be used in applications + whose special circumstances demand that an iCalendar object be + expressed as a single entity. A property containing inline binary + content information MUST specify the "ENCODING" property parameter. + Binary content information placed external to the iCalendar object + MUST be referenced by a uniform resource identifier (URI). + + The following example specifies an "ATTACH" property that references + an attachment external to the iCalendar object with a URI reference: + + ATTACH:http://xyz.com/public/quarterly-report.doc + + The following example specifies an "ATTACH" property with inline + binary encoded content information: + + ATTACH;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY: + MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U + EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE + <...remainder of "BASE64" encoded binary data...> + +4.1.4 Character Set + + There is not a property parameter to declare the character set used + in a property value. The default character set for an iCalendar + object is UTF-8 as defined in [RFC 2279]. + + The "charset" Content-Type parameter can be used in MIME transports + to specify any other IANA registered character set. + +4.2 Property Parameters + + A property can have attributes associated with it. These "property + parameters" contain meta-information about the property or the + property value. Property parameters are provided to specify such + information as the location of an alternate text representation for a + property value, the language of a text property value, the data type + of the property value and other attributes. + + Property parameter values that contain the COLON (US-ASCII decimal + 58), SEMICOLON (US-ASCII decimal 59) or COMMA (US-ASCII decimal 44) + character separators MUST be specified as quoted-string text values. + Property parameter values MUST NOT contain the DOUBLE-QUOTE (US-ASCII + decimal 22) character. The DOUBLE-QUOTE (US-ASCII decimal 22) + character is used as a delimiter for parameter values that contain + restricted characters or URI text. For example: + + + + +Dawson & Stenerson Standards Track [Page 17] + +RFC 2445 iCalendar November 1998 + + + DESCRIPTION;ALTREP="http://www.wiz.org":The Fall'98 Wild Wizards + Conference - - Las Vegas, NV, USA + + Property parameter values that are not in quoted strings are case + insensitive. + + The general property parameters defined by this memo are defined by + the following notation: + + parameter = altrepparam ; Alternate text representation + / cnparam ; Common name + / cutypeparam ; Calendar user type + / delfromparam ; Delegator + / deltoparam ; Delegatee + / dirparam ; Directory entry + / encodingparam ; Inline encoding + / fmttypeparam ; Format type + / fbtypeparam ; Free/busy time type + / languageparam ; Language for text + / memberparam ; Group or list membership + / partstatparam ; Participation status + / rangeparam ; Recurrence identifier range + / trigrelparam ; Alarm trigger relationship + / reltypeparam ; Relationship type + / roleparam ; Participation role + / rsvpparam ; RSVP expectation + / sentbyparam ; Sent by + / tzidparam ; Reference to time zone object + / valuetypeparam ; Property value data type + / ianaparam + ; Some other IANA registered iCalendar parameter. + / xparam + ; A non-standard, experimental parameter. + + ianaparam = iana-token "=" param-value *("," param-value) + + xparam =x-name "=" param-value *("," param-value) + +4.2.1 Alternate Text Representation + + Parameter Name: ALTREP + + Purpose: To specify an alternate text representation for the property + value. + + Format Definition: The property parameter is defined by the following + notation: + + + + +Dawson & Stenerson Standards Track [Page 18] + +RFC 2445 iCalendar November 1998 + + + altrepparam = "ALTREP" "=" DQUOTE uri DQUOTE + + Description: The parameter specifies a URI that points to an + alternate representation for a textual property value. A property + specifying this parameter MUST also include a value that reflects the + default representation of the text value. The individual URI + parameter values MUST each be specified in a quoted-string. + + Example: + + DESCRIPTION;ALTREP="CID:":Project + XYZ Review Meeting will include the following agenda items: (a) + Market Overview, (b) Finances, (c) Project Management + + The "ALTREP" property parameter value might point to a "text/html" + content portion. + + Content-Type:text/html + Content-Id: + + +

Project XYZ Review Meeting will include the following + agenda items:

  1. Market + Overview
  2. Finances
  3. Project Management

+ + +4.2.2 Common Name + + Parameter Name: CN + + Purpose: To specify the common name to be associated with the + calendar user specified by the property. + + Format Definition: The property parameter is defined by the following + notation: + + cnparam = "CN" "=" param-value + + Description: This parameter can be specified on properties with a + CAL-ADDRESS value type. The parameter specifies the common name to be + associated with the calendar user specified by the property. The + parameter value is text. The parameter value can be used for display + text to be associated with the calendar address specified by the + property. + + + + + + + +Dawson & Stenerson Standards Track [Page 19] + +RFC 2445 iCalendar November 1998 + + + Example: + + ORGANIZER;CN="John Smith":MAILTO:jsmith@host.com + +4.2.3 Calendar User Type + + Parameter Name: CUTYPE + + Purpose: To specify the type of calendar user specified by the + property. + + Format Definition: The property parameter is defined by the following + notation: + + cutypeparam = "CUTYPE" "=" + ("INDIVIDUAL" ; An individual + / "GROUP" ; A group of individuals + / "RESOURCE" ; A physical resource + / "ROOM" ; A room resource + / "UNKNOWN" ; Otherwise not known + / x-name ; Experimental type + / iana-token) ; Other IANA registered + ; type + ; Default is INDIVIDUAL + + Description: This parameter can be specified on properties with a + CAL-ADDRESS value type. The parameter identifies the type of calendar + user specified by the property. If not specified on a property that + allows this parameter, the default is INDIVIDUAL. + + Example: + + ATTENDEE;CUTYPE=GROUP:MAILTO:ietf-calsch@imc.org + +4.2.4 Delegators + + Parameter Name: DELEGATED-FROM + + Purpose: To specify the calendar users that have delegated their + participation to the calendar user specified by the property. + + Format Definition: The property parameter is defined by the following + notation: + + delfromparam = "DELEGATED-FROM" "=" DQUOTE cal-address DQUOTE + *("," DQUOTE cal-address DQUOTE) + + + + + +Dawson & Stenerson Standards Track [Page 20] + +RFC 2445 iCalendar November 1998 + + + Description: This parameter can be specified on properties with a + CAL-ADDRESS value type. This parameter can be specified on a property + that has a value type of calendar address. This parameter specifies + those calendar uses that have delegated their participation in a + group scheduled event or to-do to the calendar user specified by the + property. The value MUST be a MAILTO URI as defined in [RFC 1738]. + The individual calendar address parameter values MUST each be + specified in a quoted-string. + + Example: + + ATTENDEE;DELEGATED-FROM="MAILTO:jsmith@host.com":MAILTO: + jdoe@host.com + +4.2.5 Delegatees + + Parameter Name: DELEGATED-TO + + Purpose: To specify the calendar users to whom the calendar user + specified by the property has delegated participation. + + Format Definition: The property parameter is defined by the following + notation: + + deltoparam = "DELEGATED-TO" "=" DQUOTE cal-address DQUOTE + *("," DQUOTE cal-address DQUOTE) + + Description: This parameter can be specified on properties with a + CAL-ADDRESS value type. This parameter specifies those calendar users + whom have been delegated participation in a group scheduled event or + to-do by the calendar user specified by the property. The value MUST + be a MAILTO URI as defined in [RFC 1738]. The individual calendar + address parameter values MUST each be specified in a quoted-string. + + Example: + + ATTENDEE;DELEGATED-TO="MAILTO:jdoe@host.com","MAILTO:jqpublic@ + host.com":MAILTO:jsmith@host.com + +4.2.6 Directory Entry Reference + + Parameter Name: DIR + + Purpose: To specify reference to a directory entry associated with + the calendar user specified by the property. + + Format Definition: The property parameter is defined by the following + notation: + + + +Dawson & Stenerson Standards Track [Page 21] + +RFC 2445 iCalendar November 1998 + + + dirparam = "DIR" "=" DQUOTE uri DQUOTE + + Description: This parameter can be specified on properties with a + CAL-ADDRESS value type. The parameter specifies a reference to the + directory entry associated with the calendar user specified by the + property. The parameter value is a URI. The individual URI parameter + values MUST each be specified in a quoted-string. + + Example: + + ORGANIZER;DIR="ldap://host.com:6666/o=eDABC%20Industries,c=3DUS?? + (cn=3DBJim%20Dolittle)":MAILTO:jimdo@host1.com + +4.2.7 Inline Encoding + + Parameter Name: ENCODING + + Purpose: To specify an alternate inline encoding for the property + value. + + Format Definition: The property parameter is defined by the following + notation: + + encodingparam = "ENCODING" "=" + ("8BIT" + ; "8bit" text encoding is defined in [RFC 2045] + / "BASE64" + ; "BASE64" binary encoding format is defined in [RFC 2045] + / iana-token + ; Some other IANA registered iCalendar encoding type + / x-name) + ; A non-standard, experimental encoding type + + Description: The property parameter identifies the inline encoding + used in a property value. The default encoding is "8BIT", + corresponding to a property value consisting of text. The "BASE64" + encoding type corresponds to a property value encoded using the + "BASE64" encoding defined in [RFC 2045]. + + If the value type parameter is ";VALUE=BINARY", then the inline + encoding parameter MUST be specified with the value + ";ENCODING=BASE64". + + + + + + + + + +Dawson & Stenerson Standards Track [Page 22] + +RFC 2445 iCalendar November 1998 + + + Example: + + ATTACH;FMTYPE=IMAGE/JPEG;ENCODING=BASE64;VALUE=BINARY:MIICajC + CAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1UEBhMCVVMxLDA + qBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIENvcnBvcmF0aW9uMRw + <...remainder of "BASE64" encoded binary data...> + +4.2.8 Format Type + + Parameter Name: FMTTYPE + + Purpose: To specify the content type of a referenced object. + + Format Definition: The property parameter is defined by the following + notation: + + fmttypeparam = "FMTTYPE" "=" iana-token + ; A IANA registered content type + / x-name + ; A non-standard content type + + Description: This parameter can be specified on properties that are + used to reference an object. The parameter specifies the content type + of the referenced object. For example, on the "ATTACH" property, a + FTP type URI value does not, by itself, necessarily convey the type + of content associated with the resource. The parameter value MUST be + the TEXT for either an IANA registered content type or a non-standard + content type. + + Example: + + ATTACH;FMTTYPE=application/binary:ftp://domain.com/pub/docs/ + agenda.doc + +4.2.9 Free/Busy Time Type + + Parameter Name: FBTYPE + + Purpose: To specify the free or busy time type. + + Format Definition: The property parameter is defined by the following + notation: + + fbtypeparam = "FBTYPE" "=" ("FREE" / "BUSY" + / "BUSY-UNAVAILABLE" / "BUSY-TENTATIVE" + / x-name + ; Some experimental iCalendar data type. + / iana-token) + + + +Dawson & Stenerson Standards Track [Page 23] + +RFC 2445 iCalendar November 1998 + + + ; Some other IANA registered iCalendar data type. + + Description: The parameter specifies the free or busy time type. The + value FREE indicates that the time interval is free for scheduling. + The value BUSY indicates that the time interval is busy because one + or more events have been scheduled for that interval. The value + BUSY-UNAVAILABLE indicates that the time interval is busy and that + the interval can not be scheduled. The value BUSY-TENTATIVE indicates + that the time interval is busy because one or more events have been + tentatively scheduled for that interval. If not specified on a + property that allows this parameter, the default is BUSY. + + Example: The following is an example of this parameter on a FREEBUSY + property. + + FREEBUSY;FBTYPE=BUSY:19980415T133000Z/19980415T170000Z + +4.2.10 Language + + Parameter Name: LANGUAGE + + Purpose: To specify the language for text values in a property or + property parameter. + + Format Definition: The property parameter is defined by the following + notation: + + languageparam = "LANGUAGE" "=" language + + language = + + Description: This parameter can be specified on properties with a + text value type. The parameter identifies the language of the text in + the property or property parameter value. The value of the "language" + property parameter is that defined in [RFC 1766]. + + For transport in a MIME entity, the Content-Language header field can + be used to set the default language for the entire body part. + Otherwise, no default language is assumed. + + Example: + + SUMMARY;LANGUAGE=us-EN:Company Holiday Party + + LOCATION;LANGUAGE=en:Germany + LOCATION;LANGUAGE=no:Tyskland + + + + + +Dawson & Stenerson Standards Track [Page 24] + +RFC 2445 iCalendar November 1998 + + + The following example makes use of the Quoted-Printable encoding in + order to represent non-ASCII characters. + + LOCATION;LANGUAGE=da:K=F8benhavn + LOCATION;LANGUAGE=en:Copenhagen + +4.2.11 Group or List Membership + + Parameter Name: MEMBER + + Purpose: To specify the group or list membership of the calendar user + specified by the property. + + Format Definition: The property parameter is defined by the following + notation: + + memberparam = "MEMBER" "=" DQUOTE cal-address DQUOTE + *("," DQUOTE cal-address DQUOTE) + + Description: This parameter can be specified on properties with a + CAL-ADDRESS value type. The parameter identifies the groups or list + membership for the calendar user specified by the property. The + parameter value either a single calendar address in a quoted-string + or a COMMA character (US-ASCII decimal 44) list of calendar + addresses, each in a quoted-string. The individual calendar address + parameter values MUST each be specified in a quoted-string. + + Example: + + ATTENDEE;MEMBER="MAILTO:ietf-calsch@imc.org":MAILTO:jsmith@host.com + + ATTENDEE;MEMBER="MAILTO:projectA@host.com","MAILTO:projectB@host. + com":MAILTO:janedoe@host.com + +4.2.12 Participation Status + + Parameter Name: PARTSTAT + + Purpose: To specify the participation status for the calendar user + specified by the property. + + Format Definition: The property parameter is defined by the following + notation: + + partstatparam = "PARTSTAT" "=" + ("NEEDS-ACTION" ; Event needs action + / "ACCEPTED" ; Event accepted + / "DECLINED" ; Event declined + + + +Dawson & Stenerson Standards Track [Page 25] + +RFC 2445 iCalendar November 1998 + + + / "TENTATIVE" ; Event tentatively + ; accepted + / "DELEGATED" ; Event delegated + / x-name ; Experimental status + / iana-token) ; Other IANA registered + ; status + ; These are the participation statuses for a "VEVENT". Default is + ; NEEDS-ACTION + partstatparam /= "PARTSTAT" "=" + ("NEEDS-ACTION" ; To-do needs action + / "ACCEPTED" ; To-do accepted + / "DECLINED" ; To-do declined + / "TENTATIVE" ; To-do tentatively + ; accepted + / "DELEGATED" ; To-do delegated + / "COMPLETED" ; To-do completed. + ; COMPLETED property has + ;date/time completed. + / "IN-PROCESS" ; To-do in process of + ; being completed + / x-name ; Experimental status + / iana-token) ; Other IANA registered + ; status + ; These are the participation statuses for a "VTODO". Default is + ; NEEDS-ACTION + + partstatparam /= "PARTSTAT" "=" + ("NEEDS-ACTION" ; Journal needs action + / "ACCEPTED" ; Journal accepted + / "DECLINED" ; Journal declined + / x-name ; Experimental status + / iana-token) ; Other IANA registered + ; status + ; These are the participation statuses for a "VJOURNAL". Default is + ; NEEDS-ACTION + + Description: This parameter can be specified on properties with a + CAL-ADDRESS value type. The parameter identifies the participation + status for the calendar user specified by the property value. The + parameter values differ depending on whether they are associated with + a group scheduled "VEVENT", "VTODO" or "VJOURNAL". The values MUST + match one of the values allowed for the given calendar component. If + not specified on a property that allows this parameter, the default + value is NEEDS-ACTION. + + Example: + + ATTENDEE;PARTSTAT=DECLINED:MAILTO:jsmith@host.com + + + +Dawson & Stenerson Standards Track [Page 26] + +RFC 2445 iCalendar November 1998 + + +4.2.13 Recurrence Identifier Range + + Parameter Name: RANGE + + Purpose: To specify the effective range of recurrence instances from + the instance specified by the recurrence identifier specified by the + property. + + Format Definition: The property parameter is defined by the following + notation: + + rangeparam = "RANGE" "=" ("THISANDPRIOR" + ; To specify all instances prior to the recurrence identifier + / "THISANDFUTURE") + ; To specify the instance specified by the recurrence identifier + ; and all subsequent recurrence instances + + Description: The parameter can be specified on a property that + specifies a recurrence identifier. The parameter specifies the + effective range of recurrence instances that is specified by the + property. The effective range is from the recurrence identified + specified by the property. If this parameter is not specified an + allowed property, then the default range is the single instance + specified by the recurrence identifier value of the property. The + parameter value can be "THISANDPRIOR" to indicate a range defined by + the recurrence identified value of the property and all prior + instances. The parameter value can also be "THISANDFUTURE" to + indicate a range defined by the recurrence identifier and all + subsequent instances. + + Example: + + RECURRENCE-ID;RANGE=THISANDPRIOR:19980401T133000Z + +4.2.14 Alarm Trigger Relationship + + Parameter Name: RELATED + + Purpose: To specify the relationship of the alarm trigger with + respect to the start or end of the calendar component. + + Format Definition: The property parameter is defined by the following + notation: + + trigrelparam = "RELATED" "=" + ("START" ; Trigger off of start + / "END") ; Trigger off of end + + + + +Dawson & Stenerson Standards Track [Page 27] + +RFC 2445 iCalendar November 1998 + + + Description: The parameter can be specified on properties that + specify an alarm trigger with a DURATION value type. The parameter + specifies whether the alarm will trigger relative to the start or end + of the calendar component. The parameter value START will set the + alarm to trigger off the start of the calendar component; the + parameter value END will set the alarm to trigger off the end of the + calendar component. If the parameter is not specified on an allowable + property, then the default is START. + + Example: + + TRIGGER;RELATED=END:PT5M + +4.2.15 Relationship Type + + Parameter Name: RELTYPE + + Purpose: To specify the type of hierarchical relationship associated + with the calendar component specified by the property. + + Format Definition: The property parameter is defined by the following + notation: + + reltypeparam = "RELTYPE" "=" + ("PARENT" ; Parent relationship. Default. + / "CHILD" ; Child relationship + / "SIBLING ; Sibling relationship + / iana-token ; Some other IANA registered + ; iCalendar relationship type + / x-name) ; A non-standard, experimental + ; relationship type + + Description: This parameter can be specified on a property that + references another related calendar. The parameter specifies the + hierarchical relationship type of the calendar component referenced + by the property. The parameter value can be PARENT, to indicate that + the referenced calendar component is a superior of calendar + component; CHILD to indicate that the referenced calendar component + is a subordinate of the calendar component; SIBLING to indicate that + the referenced calendar component is a peer of the calendar + component. If this parameter is not specified on an allowable + property, the default relationship type is PARENT. + + Example: + + RELATED-TO;RELTYPE=SIBLING:<19960401-080045-4000F192713@host.com> + + + + + +Dawson & Stenerson Standards Track [Page 28] + +RFC 2445 iCalendar November 1998 + + +4.2.16 Participation Role + + Parameter Name: ROLE + + Purpose: To specify the participation role for the calendar user + specified by the property. + + Format Definition: The property parameter is defined by the following + notation: + + roleparam = "ROLE" "=" + ("CHAIR" ; Indicates chair of the + ; calendar entity + / "REQ-PARTICIPANT" ; Indicates a participant whose + ; participation is required + / "OPT-PARTICIPANT" ; Indicates a participant whose + ; participation is optional + / "NON-PARTICIPANT" ; Indicates a participant who is + ; copied for information + ; purposes only + / x-name ; Experimental role + / iana-token) ; Other IANA role + ; Default is REQ-PARTICIPANT + + Description: This parameter can be specified on properties with a + CAL-ADDRESS value type. The parameter specifies the participation + role for the calendar user specified by the property in the group + schedule calendar component. If not specified on a property that + allows this parameter, the default value is REQ-PARTICIPANT. + + Example: + + ATTENDEE;ROLE=CHAIR:MAILTO:mrbig@host.com + +4.2.17 RSVP Expectation + + Parameter Name: RSVP + + Purpose: To specify whether there is an expectation of a favor of a + reply from the calendar user specified by the property value. + + Format Definition: The property parameter is defined by the following + notation: + + rsvpparam = "RSVP" "=" ("TRUE" / "FALSE") + ; Default is FALSE + + + + + +Dawson & Stenerson Standards Track [Page 29] + +RFC 2445 iCalendar November 1998 + + + Description: This parameter can be specified on properties with a + CAL-ADDRESS value type. The parameter identifies the expectation of a + reply from the calendar user specified by the property value. This + parameter is used by the "Organizer" to request a participation + status reply from an "Attendee" of a group scheduled event or to-do. + If not specified on a property that allows this parameter, the + default value is FALSE. + + Example: + + ATTENDEE;RSVP=TRUE:MAILTO:jsmith@host.com + +4.2.18 Sent By + + Parameter Name: SENT-BY + + Purpose: To specify the calendar user that is acting on behalf of the + calendar user specified by the property. + + Format Definition: The property parameter is defined by the following + notation: + + sentbyparam = "SENT-BY" "=" DQUOTE cal-address DQUOTE + + Description: This parameter can be specified on properties with a + CAL-ADDRESS value type. The parameter specifies the calendar user + that is acting on behalf of the calendar user specified by the + property. The parameter value MUST be a MAILTO URI as defined in [RFC + 1738]. The individual calendar address parameter values MUST each be + specified in a quoted-string. + + Example: + + ORGANIZER;SENT-BY:"MAILTO:sray@host.com":MAILTO:jsmith@host.com + +4.2.19 Time Zone Identifier + + Parameter Name: TZID + + Purpose: To specify the identifier for the time zone definition for a + time component in the property value. + + Format Definition: This property parameter is defined by the + following notation: + + tzidparam = "TZID" "=" [tzidprefix] paramtext CRLF + + tzidprefix = "/" + + + +Dawson & Stenerson Standards Track [Page 30] + +RFC 2445 iCalendar November 1998 + + + Description: The parameter MUST be specified on the "DTSTART", + "DTEND", "DUE", "EXDATE" and "RDATE" properties when either a DATE- + TIME or TIME value type is specified and when the value is not either + a UTC or a "floating" time. Refer to the DATE-TIME or TIME value type + definition for a description of UTC and "floating time" formats. This + property parameter specifies a text value which uniquely identifies + the "VTIMEZONE" calendar component to be used when evaluating the + time portion of the property. The value of the TZID property + parameter will be equal to the value of the TZID property for the + matching time zone definition. An individual "VTIMEZONE" calendar + component MUST be specified for each unique "TZID" parameter value + specified in the iCalendar object. + + The parameter MUST be specified on properties with a DATE-TIME value + if the DATE-TIME is not either a UTC or a "floating" time. + + The presence of the SOLIDUS character (US-ASCII decimal 47) as a + prefix, indicates that this TZID represents a unique ID in a globally + defined time zone registry (when such registry is defined). + + Note: This document does not define a naming convention for time + zone identifiers. Implementers may want to use the naming + conventions defined in existing time zone specifications such as + the public-domain Olson database [TZ]. The specification of + globally unique time zone identifiers is not addressed by this + document and is left for future study. + + The following are examples of this property parameter: + + DTSTART;TZID=US-Eastern:19980119T020000 + + DTEND;TZID=US-Eastern:19980119T030000 + + The TZID property parameter MUST NOT be applied to DATE-TIME or TIME + properties whose time values are specified in UTC. + + The use of local time in a DATE-TIME or TIME value without the TZID + property parameter is to be interpreted as a local time value, + regardless of the existence of "VTIMEZONE" calendar components in the + iCalendar object. + + For more information see the sections on the data types DATE-TIME and + TIME. + + + + + + + + +Dawson & Stenerson Standards Track [Page 31] + +RFC 2445 iCalendar November 1998 + + +4.2.20 Value Data Types + + Parameter Name: VALUE + + Purpose: To explicitly specify the data type format for a property + value. + + Format Definition: The "VALUE" property parameter is defined by the + following notation: + + valuetypeparam = "VALUE" "=" valuetype + + valuetype = ("BINARY" + / "BOOLEAN" + / "CAL-ADDRESS" + / "DATE" + / "DATE-TIME" + / "DURATION" + / "FLOAT" + / "INTEGER" + / "PERIOD" + / "RECUR" + / "TEXT" + / "TIME" + / "URI" + / "UTC-OFFSET" + / x-name + ; Some experimental iCalendar data type. + / iana-token) + ; Some other IANA registered iCalendar data type. + + Description: The parameter specifies the data type and format of the + property value. The property values MUST be of a single value type. + For example, a "RDATE" property cannot have a combination of DATE- + TIME and TIME value types. + + If the property's value is the default value type, then this + parameter need not be specified. However, if the property's default + value type is overridden by some other allowable value type, then + this parameter MUST be specified. + +4.3 Property Value Data Types + + The properties in an iCalendar object are strongly typed. The + definition of each property restricts the value to be one of the + value data types, or simply value types, defined in this section. The + value type for a property will either be specified implicitly as the + default value type or will be explicitly specified with the "VALUE" + + + +Dawson & Stenerson Standards Track [Page 32] + +RFC 2445 iCalendar November 1998 + + + parameter. If the value type of a property is one of the alternate + valid types, then it MUST be explicitly specified with the "VALUE" + parameter. + +4.3.1 Binary + + Value Name: BINARY + + Purpose: This value type is used to identify properties that contain + a character encoding of inline binary data. For example, an inline + attachment of an object code might be included in an iCalendar + object. + + Formal Definition: The value type is defined by the following + notation: + + binary = *(4b-char) [b-end] + ; A "BASE64" encoded character string, as defined by [RFC 2045]. + + b-end = (2b-char "==") / (3b-char "=") + + b-char = ALPHA / DIGIT / "+" / "/" + + Description: Property values with this value type MUST also include + the inline encoding parameter sequence of ";ENCODING=BASE64". That + is, all inline binary data MUST first be character encoded using the + "BASE64" encoding method defined in [RFC 2045]. No additional content + value encoding (i.e., BACKSLASH character encoding) is defined for + this value type. + + Example: The following is an abridged example of a "BASE64" encoded + binary value data. + + ATTACH;VALUE=BINARY;ENCODING=BASE64:MIICajCCAdOgAwIBAgICBEUwDQY + JKoZIhvcNAQEEBQAwdzELMAkGA1UEBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlI + ENvbW11bmljYXRpb25zIENvcnBvcmF0aW9uMRwwGgYDVQQLExNJbmZv + <...remainder of "BASE64" encoded binary data...> + +4.3.2 Boolean + + Value Name: BOOLEAN + + Purpose: This value type is used to identify properties that contain + either a "TRUE" or "FALSE" Boolean value. + + Formal Definition: The value type is defined by the following + notation: + + + + +Dawson & Stenerson Standards Track [Page 33] + +RFC 2445 iCalendar November 1998 + + + boolean = "TRUE" / "FALSE" + + Description: These values are case insensitive text. No additional + content value encoding (i.e., BACKSLASH character encoding) is + defined for this value type. + + Example: The following is an example of a hypothetical property that + has a BOOLEAN value type: + + GIBBERISH:TRUE + +4.3.3 Calendar User Address + + Value Name: CAL-ADDRESS + + Purpose: This value type is used to identify properties that contain + a calendar user address. + + Formal Definition: The value type is as defined by the following + notation: + + cal-address = uri + + Description: The value is a URI as defined by [RFC 1738] or any other + IANA registered form for a URI. When used to address an Internet + email transport address for a calendar user, the value MUST be a + MAILTO URI, as defined by [RFC 1738]. No additional content value + encoding (i.e., BACKSLASH character encoding) is defined for this + value type. + + Example: + + ATTENDEE:MAILTO:jane_doe@host.com + +4.3.4 Date + + Value Name: DATE + + Purpose: This value type is used to identify values that contain a + calendar date. + + Formal Definition: The value type is defined by the following + notation: + + date = date-value + + date-value = date-fullyear date-month date-mday + date-fullyear = 4DIGIT + + + +Dawson & Stenerson Standards Track [Page 34] + +RFC 2445 iCalendar November 1998 + + + date-month = 2DIGIT ;01-12 + date-mday = 2DIGIT ;01-28, 01-29, 01-30, 01-31 + ;based on month/year + + Description: If the property permits, multiple "date" values are + specified as a COMMA character (US-ASCII decimal 44) separated list + of values. The format for the value type is expressed as the [ISO + 8601] complete representation, basic format for a calendar date. The + textual format specifies a four-digit year, two-digit month, and + two-digit day of the month. There are no separator characters between + the year, month and day component text. + + No additional content value encoding (i.e., BACKSLASH character + encoding) is defined for this value type. + + Example: The following represents July 14, 1997: + + 19970714 + +4.3.5 Date-Time + + Value Name: DATE-TIME + + Purpose: This value type is used to identify values that specify a + precise calendar date and time of day. + + Formal Definition: The value type is defined by the following + notation: + + date-time = date "T" time ;As specified in the date and time + ;value definitions + + Description: If the property permits, multiple "date-time" values are + specified as a COMMA character (US-ASCII decimal 44) separated list + of values. No additional content value encoding (i.e., BACKSLASH + character encoding) is defined for this value type. + + The "DATE-TIME" data type is used to identify values that contain a + precise calendar date and time of day. The format is based on the + [ISO 8601] complete representation, basic format for a calendar date + and time of day. The text format is a concatenation of the "date", + followed by the LATIN CAPITAL LETTER T character (US-ASCII decimal + 84) time designator, followed by the "time" format. + + The "DATE-TIME" data type expresses time values in three forms: + + The form of date and time with UTC offset MUST NOT be used. For + example, the following is not valid for a date-time value: + + + +Dawson & Stenerson Standards Track [Page 35] + +RFC 2445 iCalendar November 1998 + + + DTSTART:19980119T230000-0800 ;Invalid time format + + FORM #1: DATE WITH LOCAL TIME + + The date with local time form is simply a date-time value that does + not contain the UTC designator nor does it reference a time zone. For + example, the following represents Janurary 18, 1998, at 11 PM: + + DTSTART:19980118T230000 + + Date-time values of this type are said to be "floating" and are not + bound to any time zone in particular. They are used to represent the + same hour, minute, and second value regardless of which time zone is + currently being observed. For example, an event can be defined that + indicates that an individual will be busy from 11:00 AM to 1:00 PM + every day, no matter which time zone the person is in. In these + cases, a local time can be specified. The recipient of an iCalendar + object with a property value consisting of a local time, without any + relative time zone information, SHOULD interpret the value as being + fixed to whatever time zone the ATTENDEE is in at any given moment. + This means that two ATTENDEEs, in different time zones, receiving the + same event definition as a floating time, may be participating in the + event at different actual times. Floating time SHOULD only be used + where that is the reasonable behavior. + + In most cases, a fixed time is desired. To properly communicate a + fixed time in a property value, either UTC time or local time with + time zone reference MUST be specified. + + The use of local time in a DATE-TIME value without the TZID property + parameter is to be interpreted as floating time, regardless of the + existence of "VTIMEZONE" calendar components in the iCalendar object. + + FORM #2: DATE WITH UTC TIME + + The date with UTC time, or absolute time, is identified by a LATIN + CAPITAL LETTER Z suffix character (US-ASCII decimal 90), the UTC + designator, appended to the time value. For example, the following + represents January 19, 1998, at 0700 UTC: + + DTSTART:19980119T070000Z + + The TZID property parameter MUST NOT be applied to DATE-TIME + properties whose time values are specified in UTC. + + FORM #3: DATE WITH LOCAL TIME AND TIME ZONE REFERENCE + + + + + +Dawson & Stenerson Standards Track [Page 36] + +RFC 2445 iCalendar November 1998 + + + The date and local time with reference to time zone information is + identified by the use the TZID property parameter to reference the + appropriate time zone definition. TZID is discussed in detail in the + section on Time Zone. For example, the following represents 2 AM in + New York on Janurary 19, 1998: + + DTSTART;TZID=US-Eastern:19980119T020000 + + Example: The following represents July 14, 1997, at 1:30 PM in New + York City in each of the three time formats, using the "DTSTART" + property. + + DTSTART:19970714T133000 ;Local time + DTSTART:19970714T173000Z ;UTC time + DTSTART;TZID=US-Eastern:19970714T133000 ;Local time and time + ; zone reference + + A time value MUST ONLY specify 60 seconds when specifying the + periodic "leap second" in the time value. For example: + + COMPLETED:19970630T235960Z + +4.3.6 Duration + + Value Name: DURATION + + Purpose: This value type is used to identify properties that contain + a duration of time. + + Formal Definition: The value type is defined by the following + notation: + + dur-value = (["+"] / "-") "P" (dur-date / dur-time / dur-week) + + dur-date = dur-day [dur-time] + dur-time = "T" (dur-hour / dur-minute / dur-second) + dur-week = 1*DIGIT "W" + dur-hour = 1*DIGIT "H" [dur-minute] + dur-minute = 1*DIGIT "M" [dur-second] + dur-second = 1*DIGIT "S" + dur-day = 1*DIGIT "D" + + Description: If the property permits, multiple "duration" values are + specified by a COMMA character (US-ASCII decimal 44) separated list + of values. The format is expressed as the [ISO 8601] basic format for + the duration of time. The format can represent durations in terms of + weeks, days, hours, minutes, and seconds. + + + + +Dawson & Stenerson Standards Track [Page 37] + +RFC 2445 iCalendar November 1998 + + + No additional content value encoding (i.e., BACKSLASH character + encoding) are defined for this value type. + + Example: A duration of 15 days, 5 hours and 20 seconds would be: + + P15DT5H0M20S + + A duration of 7 weeks would be: + + P7W + +4.3.7 Float + + Value Name: FLOAT + + Purpose: This value type is used to identify properties that contain + a real number value. + + Formal Definition: The value type is defined by the following + notation: + + float = (["+"] / "-") 1*DIGIT ["." 1*DIGIT] + + Description: If the property permits, multiple "float" values are + specified by a COMMA character (US-ASCII decimal 44) separated list + of values. + + No additional content value encoding (i.e., BACKSLASH character + encoding) is defined for this value type. + + Example: + + 1000000.0000001 + 1.333 + -3.14 + +4.3.8 Integer + + Value Name:INTEGER + + Purpose: This value type is used to identify properties that contain + a signed integer value. + + Formal Definition: The value type is defined by the following + notation: + + integer = (["+"] / "-") 1*DIGIT + + + + +Dawson & Stenerson Standards Track [Page 38] + +RFC 2445 iCalendar November 1998 + + + Description: If the property permits, multiple "integer" values are + specified by a COMMA character (US-ASCII decimal 44) separated list + of values. The valid range for "integer" is -2147483648 to + 2147483647. If the sign is not specified, then the value is assumed + to be positive. + + No additional content value encoding (i.e., BACKSLASH character + encoding) is defined for this value type. + + Example: + + 1234567890 + -1234567890 + +1234567890 + 432109876 + +4.3.9 Period of Time + + Value Name: PERIOD + + Purpose: This value type is used to identify values that contain a + precise period of time. + + Formal Definition: The data type is defined by the following + notation: + + period = period-explicit / period-start + + period-explicit = date-time "/" date-time + ; [ISO 8601] complete representation basic format for a period of + ; time consisting of a start and end. The start MUST be before the + ; end. + + period-start = date-time "/" dur-value + ; [ISO 8601] complete representation basic format for a period of + ; time consisting of a start and positive duration of time. + + Description: If the property permits, multiple "period" values are + specified by a COMMA character (US-ASCII decimal 44) separated list + of values. There are two forms of a period of time. First, a period + of time is identified by its start and its end. This format is + expressed as the [ISO 8601] complete representation, basic format for + "DATE-TIME" start of the period, followed by a SOLIDUS character + (US-ASCII decimal 47), followed by the "DATE-TIME" of the end of the + period. The start of the period MUST be before the end of the period. + Second, a period of time can also be defined by a start and a + positive duration of time. The format is expressed as the [ISO 8601] + complete representation, basic format for the "DATE-TIME" start of + + + +Dawson & Stenerson Standards Track [Page 39] + +RFC 2445 iCalendar November 1998 + + + the period, followed by a SOLIDUS character (US-ASCII decimal 47), + followed by the [ISO 8601] basic format for "DURATION" of the period. + + Example: The period starting at 18:00:00 UTC, on January 1, 1997 and + ending at 07:00:00 UTC on January 2, 1997 would be: + + 19970101T180000Z/19970102T070000Z + + The period start at 18:00:00 on January 1, 1997 and lasting 5 hours + and 30 minutes would be: + + 19970101T180000Z/PT5H30M + + No additional content value encoding (i.e., BACKSLASH character + encoding) is defined for this value type. + +4.3.10 Recurrence Rule + + Value Name: RECUR + + Purpose: This value type is used to identify properties that contain + a recurrence rule specification. + + Formal Definition: The value type is defined by the following + notation: + + recur = "FREQ"=freq *( + + ; either UNTIL or COUNT may appear in a 'recur', + ; but UNTIL and COUNT MUST NOT occur in the same 'recur' + + ( ";" "UNTIL" "=" enddate ) / + ( ";" "COUNT" "=" 1*DIGIT ) / + + ; the rest of these keywords are optional, + ; but MUST NOT occur more than once + + ( ";" "INTERVAL" "=" 1*DIGIT ) / + ( ";" "BYSECOND" "=" byseclist ) / + ( ";" "BYMINUTE" "=" byminlist ) / + ( ";" "BYHOUR" "=" byhrlist ) / + ( ";" "BYDAY" "=" bywdaylist ) / + ( ";" "BYMONTHDAY" "=" bymodaylist ) / + ( ";" "BYYEARDAY" "=" byyrdaylist ) / + ( ";" "BYWEEKNO" "=" bywknolist ) / + ( ";" "BYMONTH" "=" bymolist ) / + ( ";" "BYSETPOS" "=" bysplist ) / + ( ";" "WKST" "=" weekday ) / + + + +Dawson & Stenerson Standards Track [Page 40] + +RFC 2445 iCalendar November 1998 + + + ( ";" x-name "=" text ) + ) + + freq = "SECONDLY" / "MINUTELY" / "HOURLY" / "DAILY" + / "WEEKLY" / "MONTHLY" / "YEARLY" + + enddate = date + enddate =/ date-time ;An UTC value + + byseclist = seconds / ( seconds *("," seconds) ) + + seconds = 1DIGIT / 2DIGIT ;0 to 59 + + byminlist = minutes / ( minutes *("," minutes) ) + + minutes = 1DIGIT / 2DIGIT ;0 to 59 + + byhrlist = hour / ( hour *("," hour) ) + + hour = 1DIGIT / 2DIGIT ;0 to 23 + + bywdaylist = weekdaynum / ( weekdaynum *("," weekdaynum) ) + + weekdaynum = [([plus] ordwk / minus ordwk)] weekday + + plus = "+" + + minus = "-" + + ordwk = 1DIGIT / 2DIGIT ;1 to 53 + + weekday = "SU" / "MO" / "TU" / "WE" / "TH" / "FR" / "SA" + ;Corresponding to SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, + ;FRIDAY, SATURDAY and SUNDAY days of the week. + + bymodaylist = monthdaynum / ( monthdaynum *("," monthdaynum) ) + + monthdaynum = ([plus] ordmoday) / (minus ordmoday) + + ordmoday = 1DIGIT / 2DIGIT ;1 to 31 + + byyrdaylist = yeardaynum / ( yeardaynum *("," yeardaynum) ) + + yeardaynum = ([plus] ordyrday) / (minus ordyrday) + + ordyrday = 1DIGIT / 2DIGIT / 3DIGIT ;1 to 366 + + bywknolist = weeknum / ( weeknum *("," weeknum) ) + + + +Dawson & Stenerson Standards Track [Page 41] + +RFC 2445 iCalendar November 1998 + + + weeknum = ([plus] ordwk) / (minus ordwk) + + bymolist = monthnum / ( monthnum *("," monthnum) ) + + monthnum = 1DIGIT / 2DIGIT ;1 to 12 + + bysplist = setposday / ( setposday *("," setposday) ) + + setposday = yeardaynum + + Description: If the property permits, multiple "recur" values are + specified by a COMMA character (US-ASCII decimal 44) separated list + of values. The value type is a structured value consisting of a list + of one or more recurrence grammar parts. Each rule part is defined by + a NAME=VALUE pair. The rule parts are separated from each other by + the SEMICOLON character (US-ASCII decimal 59). The rule parts are not + ordered in any particular sequence. Individual rule parts MUST only + be specified once. + + The FREQ rule part identifies the type of recurrence rule. This rule + part MUST be specified in the recurrence rule. Valid values include + SECONDLY, to specify repeating events based on an interval of a + second or more; MINUTELY, to specify repeating events based on an + interval of a minute or more; HOURLY, to specify repeating events + based on an interval of an hour or more; DAILY, to specify repeating + events based on an interval of a day or more; WEEKLY, to specify + repeating events based on an interval of a week or more; MONTHLY, to + specify repeating events based on an interval of a month or more; and + YEARLY, to specify repeating events based on an interval of a year or + more. + + The INTERVAL rule part contains a positive integer representing how + often the recurrence rule repeats. The default value is "1", meaning + every second for a SECONDLY rule, or every minute for a MINUTELY + rule, every hour for an HOURLY rule, every day for a DAILY rule, + every week for a WEEKLY rule, every month for a MONTHLY rule and + every year for a YEARLY rule. + + The UNTIL rule part defines a date-time value which bounds the + recurrence rule in an inclusive manner. If the value specified by + UNTIL is synchronized with the specified recurrence, this date or + date-time becomes the last instance of the recurrence. If specified + as a date-time value, then it MUST be specified in an UTC time + format. If not present, and the COUNT rule part is also not present, + the RRULE is considered to repeat forever. + + The COUNT rule part defines the number of occurrences at which to + range-bound the recurrence. The "DTSTART" property value, if + + + +Dawson & Stenerson Standards Track [Page 42] + +RFC 2445 iCalendar November 1998 + + + specified, counts as the first occurrence. + + The BYSECOND rule part specifies a COMMA character (US-ASCII decimal + 44) separated list of seconds within a minute. Valid values are 0 to + 59. The BYMINUTE rule part specifies a COMMA character (US-ASCII + decimal 44) separated list of minutes within an hour. Valid values + are 0 to 59. The BYHOUR rule part specifies a COMMA character (US- + ASCII decimal 44) separated list of hours of the day. Valid values + are 0 to 23. + + The BYDAY rule part specifies a COMMA character (US-ASCII decimal 44) + separated list of days of the week; MO indicates Monday; TU indicates + Tuesday; WE indicates Wednesday; TH indicates Thursday; FR indicates + Friday; SA indicates Saturday; SU indicates Sunday. + + Each BYDAY value can also be preceded by a positive (+n) or negative + (-n) integer. If present, this indicates the nth occurrence of the + specific day within the MONTHLY or YEARLY RRULE. For example, within + a MONTHLY rule, +1MO (or simply 1MO) represents the first Monday + within the month, whereas -1MO represents the last Monday of the + month. If an integer modifier is not present, it means all days of + this type within the specified frequency. For example, within a + MONTHLY rule, MO represents all Mondays within the month. + + The BYMONTHDAY rule part specifies a COMMA character (ASCII decimal + 44) separated list of days of the month. Valid values are 1 to 31 or + -31 to -1. For example, -10 represents the tenth to the last day of + the month. + + The BYYEARDAY rule part specifies a COMMA character (US-ASCII decimal + 44) separated list of days of the year. Valid values are 1 to 366 or + -366 to -1. For example, -1 represents the last day of the year + (December 31st) and -306 represents the 306th to the last day of the + year (March 1st). + + The BYWEEKNO rule part specifies a COMMA character (US-ASCII decimal + 44) separated list of ordinals specifying weeks of the year. Valid + values are 1 to 53 or -53 to -1. This corresponds to weeks according + to week numbering as defined in [ISO 8601]. A week is defined as a + seven day period, starting on the day of the week defined to be the + week start (see WKST). Week number one of the calendar year is the + first week which contains at least four (4) days in that calendar + year. This rule part is only valid for YEARLY rules. For example, 3 + represents the third week of the year. + + Note: Assuming a Monday week start, week 53 can only occur when + Thursday is January 1 or if it is a leap year and Wednesday is + January 1. + + + +Dawson & Stenerson Standards Track [Page 43] + +RFC 2445 iCalendar November 1998 + + + The BYMONTH rule part specifies a COMMA character (US-ASCII decimal + 44) separated list of months of the year. Valid values are 1 to 12. + + The WKST rule part specifies the day on which the workweek starts. + Valid values are MO, TU, WE, TH, FR, SA and SU. This is significant + when a WEEKLY RRULE has an interval greater than 1, and a BYDAY rule + part is specified. This is also significant when in a YEARLY RRULE + when a BYWEEKNO rule part is specified. The default value is MO. + + The BYSETPOS rule part specifies a COMMA character (US-ASCII decimal + 44) separated list of values which corresponds to the nth occurrence + within the set of events specified by the rule. Valid values are 1 to + 366 or -366 to -1. It MUST only be used in conjunction with another + BYxxx rule part. For example "the last work day of the month" could + be represented as: + + RRULE:FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1 + + Each BYSETPOS value can include a positive (+n) or negative (-n) + integer. If present, this indicates the nth occurrence of the + specific occurrence within the set of events specified by the rule. + + If BYxxx rule part values are found which are beyond the available + scope (ie, BYMONTHDAY=30 in February), they are simply ignored. + + Information, not contained in the rule, necessary to determine the + various recurrence instance start time and dates are derived from the + Start Time (DTSTART) entry attribute. For example, + "FREQ=YEARLY;BYMONTH=1" doesn't specify a specific day within the + month or a time. This information would be the same as what is + specified for DTSTART. + + BYxxx rule parts modify the recurrence in some manner. BYxxx rule + parts for a period of time which is the same or greater than the + frequency generally reduce or limit the number of occurrences of the + recurrence generated. For example, "FREQ=DAILY;BYMONTH=1" reduces the + number of recurrence instances from all days (if BYMONTH tag is not + present) to all days in January. BYxxx rule parts for a period of + time less than the frequency generally increase or expand the number + of occurrences of the recurrence. For example, + "FREQ=YEARLY;BYMONTH=1,2" increases the number of days within the + yearly recurrence set from 1 (if BYMONTH tag is not present) to 2. + + If multiple BYxxx rule parts are specified, then after evaluating the + specified FREQ and INTERVAL rule parts, the BYxxx rule parts are + applied to the current set of evaluated occurrences in the following + order: BYMONTH, BYWEEKNO, BYYEARDAY, BYMONTHDAY, BYDAY, BYHOUR, + BYMINUTE, BYSECOND and BYSETPOS; then COUNT and UNTIL are evaluated. + + + +Dawson & Stenerson Standards Track [Page 44] + +RFC 2445 iCalendar November 1998 + + + Here is an example of evaluating multiple BYxxx rule parts. + + DTSTART;TZID=US-Eastern:19970105T083000 + RRULE:FREQ=YEARLY;INTERVAL=2;BYMONTH=1;BYDAY=SU;BYHOUR=8,9; + BYMINUTE=30 + + First, the "INTERVAL=2" would be applied to "FREQ=YEARLY" to arrive + at "every other year". Then, "BYMONTH=1" would be applied to arrive + at "every January, every other year". Then, "BYDAY=SU" would be + applied to arrive at "every Sunday in January, every other year". + Then, "BYHOUR=8,9" would be applied to arrive at "every Sunday in + January at 8 AM and 9 AM, every other year". Then, "BYMINUTE=30" + would be applied to arrive at "every Sunday in January at 8:30 AM and + 9:30 AM, every other year". Then, lacking information from RRULE, the + second is derived from DTSTART, to end up in "every Sunday in January + at 8:30:00 AM and 9:30:00 AM, every other year". Similarly, if the + BYMINUTE, BYHOUR, BYDAY, BYMONTHDAY or BYMONTH rule part were + missing, the appropriate minute, hour, day or month would have been + retrieved from the "DTSTART" property. + + No additional content value encoding (i.e., BACKSLASH character + encoding) is defined for this value type. + + Example: The following is a rule which specifies 10 meetings which + occur every other day: + + FREQ=DAILY;COUNT=10;INTERVAL=2 + + There are other examples specified in the "RRULE" specification. + +4.3.11 Text + + Value Name: TEXT + + Purpose This value type is used to identify values that contain human + readable text. + + Formal Definition: The character sets supported by this revision of + iCalendar are UTF-8 and US ASCII thereof. The applicability to other + character sets is for future work. The value type is defined by the + following notation. + + text = *(TSAFE-CHAR / ":" / DQUOTE / ESCAPED-CHAR) + ; Folded according to description above + + ESCAPED-CHAR = "\\" / "\;" / "\," / "\N" / "\n") + ; \\ encodes \, \N or \n encodes newline + ; \; encodes ;, \, encodes , + + + +Dawson & Stenerson Standards Track [Page 45] + +RFC 2445 iCalendar November 1998 + + + TSAFE-CHAR = %x20-21 / %x23-2B / %x2D-39 / %x3C-5B + %x5D-7E / NON-US-ASCII + ; Any character except CTLs not needed by the current + ; character set, DQUOTE, ";", ":", "\", "," + + Note: Certain other character sets may require modification of the + above definitions, but this is beyond the scope of this document. + + Description: If the property permits, multiple "text" values are + specified by a COMMA character (US-ASCII decimal 44) separated list + of values. + + The language in which the text is represented can be controlled by + the "LANGUAGE" property parameter. + + An intentional formatted text line break MUST only be included in a + "TEXT" property value by representing the line break with the + character sequence of BACKSLASH (US-ASCII decimal 92), followed by a + LATIN SMALL LETTER N (US-ASCII decimal 110) or a LATIN CAPITAL LETTER + N (US-ASCII decimal 78), that is "\n" or "\N". + + The "TEXT" property values may also contain special characters that + are used to signify delimiters, such as a COMMA character for lists + of values or a SEMICOLON character for structured values. In order to + support the inclusion of these special characters in "TEXT" property + values, they MUST be escaped with a BACKSLASH character. A BACKSLASH + character (US-ASCII decimal 92) in a "TEXT" property value MUST be + escaped with another BACKSLASH character. A COMMA character in a + "TEXT" property value MUST be escaped with a BACKSLASH character + (US-ASCII decimal 92). A SEMICOLON character in a "TEXT" property + value MUST be escaped with a BACKSLASH character (US-ASCII decimal + 92). However, a COLON character in a "TEXT" property value SHALL NOT + be escaped with a BACKSLASH character.Example: A multiple line value + of: + + Project XYZ Final Review + Conference Room - 3B + Come Prepared. + + would be represented as: + + Project XYZ Final Review\nConference Room - 3B\nCome Prepared. + + + + + + + + + +Dawson & Stenerson Standards Track [Page 46] + +RFC 2445 iCalendar November 1998 + + +4.3.12 Time + + Value Name: TIME + + Purpose: This value type is used to identify values that contain a + time of day. + + Formal Definition: The data type is defined by the following + notation: + + time = time-hour time-minute time-second [time-utc] + + time-hour = 2DIGIT ;00-23 + time-minute = 2DIGIT ;00-59 + time-second = 2DIGIT ;00-60 + ;The "60" value is used to account for "leap" seconds. + + time-utc = "Z" + + Description: If the property permits, multiple "time" values are + specified by a COMMA character (US-ASCII decimal 44) separated list + of values. No additional content value encoding (i.e., BACKSLASH + character encoding) is defined for this value type. + + The "TIME" data type is used to identify values that contain a time + of day. The format is based on the [ISO 8601] complete + representation, basic format for a time of day. The text format + consists of a two-digit 24-hour of the day (i.e., values 0-23), two- + digit minute in the hour (i.e., values 0-59), and two-digit seconds + in the minute (i.e., values 0-60). The seconds value of 60 MUST only + to be used to account for "leap" seconds. Fractions of a second are + not supported by this format. + + In parallel to the "DATE-TIME" definition above, the "TIME" data type + expresses time values in three forms: + + The form of time with UTC offset MUST NOT be used. For example, the + following is NOT VALID for a time value: + + 230000-0800 ;Invalid time format + + FORM #1 LOCAL TIME + + The local time form is simply a time value that does not contain the + UTC designator nor does it reference a time zone. For example, 11:00 + PM: + + 230000 + + + +Dawson & Stenerson Standards Track [Page 47] + +RFC 2445 iCalendar November 1998 + + + Time values of this type are said to be "floating" and are not bound + to any time zone in particular. They are used to represent the same + hour, minute, and second value regardless of which time zone is + currently being observed. For example, an event can be defined that + indicates that an individual will be busy from 11:00 AM to 1:00 PM + every day, no matter which time zone the person is in. In these + cases, a local time can be specified. The recipient of an iCalendar + object with a property value consisting of a local time, without any + relative time zone information, SHOULD interpret the value as being + fixed to whatever time zone the ATTENDEE is in at any given moment. + This means that two ATTENDEEs may participate in the same event at + different UTC times; floating time SHOULD only be used where that is + reasonable behavior. + + In most cases, a fixed time is desired. To properly communicate a + fixed time in a property value, either UTC time or local time with + time zone reference MUST be specified. + + The use of local time in a TIME value without the TZID property + parameter is to be interpreted as a local time value, regardless of + the existence of "VTIMEZONE" calendar components in the iCalendar + object. + + FORM #2: UTC TIME + + UTC time, or absolute time, is identified by a LATIN CAPITAL LETTER Z + suffix character (US-ASCII decimal 90), the UTC designator, appended + to the time value. For example, the following represents 07:00 AM + UTC: + + 070000Z + + The TZID property parameter MUST NOT be applied to TIME properties + whose time values are specified in UTC. + + FORM #3: LOCAL TIME AND TIME ZONE REFERENCE + + The local time with reference to time zone information form is + identified by the use the TZID property parameter to reference the + appropriate time zone definition. TZID is discussed in detail in the + section on Time Zone. + + Example: The following represents 8:30 AM in New York in Winter, five + hours behind UTC, in each of the three formats using the "X- + TIMEOFDAY" non-standard property: + + + + + + +Dawson & Stenerson Standards Track [Page 48] + +RFC 2445 iCalendar November 1998 + + + X-TIMEOFDAY:083000 + + X-TIMEOFDAY:133000Z + + X-TIMEOFDAY;TZID=US-Eastern:083000 + +4.3.13 URI + + Value Name: URI + + Purpose: This value type is used to identify values that contain a + uniform resource identifier (URI) type of reference to the property + value. + + Formal Definition: The data type is defined by the following + notation: + + uri = + + Description: This data type might be used to reference binary + information, for values that are large, or otherwise undesirable to + include directly in the iCalendar object. + + The URI value formats in RFC 1738, RFC 2111 and any other IETF + registered value format can be specified. + + Any IANA registered URI format can be used. These include, but are + not limited to, those defined in RFC 1738 and RFC 2111. + + When a property parameter value is a URI value type, the URI MUST be + specified as a quoted-string value. + + No additional content value encoding (i.e., BACKSLASH character + encoding) is defined for this value type. + + Example: The following is a URI for a network file: + + http://host1.com/my-report.txt + +4.3.14 UTC Offset + + Value Name: UTC-OFFSET + + Purpose: This value type is used to identify properties that contain + an offset from UTC to local time. + + Formal Definition: The data type is defined by the following + notation: + + + +Dawson & Stenerson Standards Track [Page 49] + +RFC 2445 iCalendar November 1998 + + + utc-offset = time-numzone ;As defined above in time data type + + time-numzone = ("+" / "-") time-hour time-minute [time- + second] + + Description: The PLUS SIGN character MUST be specified for positive + UTC offsets (i.e., ahead of UTC). The value of "-0000" and "-000000" + are not allowed. The time-second, if present, may not be 60; if + absent, it defaults to zero. + + No additional content value encoding (i.e., BACKSLASH character + encoding) is defined for this value type. + + Example: The following UTC offsets are given for standard time for + New York (five hours behind UTC) and Geneva (one hour ahead of UTC): + + -0500 + + +0100 + +4.4 iCalendar Object + + The Calendaring and Scheduling Core Object is a collection of + calendaring and scheduling information. Typically, this information + will consist of a single iCalendar object. However, multiple + iCalendar objects can be sequentially grouped together. The first + line and last line of the iCalendar object MUST contain a pair of + iCalendar object delimiter strings. The syntax for an iCalendar + object is as follows: + + icalobject = 1*("BEGIN" ":" "VCALENDAR" CRLF + icalbody + "END" ":" "VCALENDAR" CRLF) + + The following is a simple example of an iCalendar object: + + BEGIN:VCALENDAR + VERSION:2.0 + PRODID:-//hacksw/handcal//NONSGML v1.0//EN + BEGIN:VEVENT + DTSTART:19970714T170000Z + DTEND:19970715T035959Z + SUMMARY:Bastille Day Party + END:VEVENT + END:VCALENDAR + + + + + + +Dawson & Stenerson Standards Track [Page 50] + +RFC 2445 iCalendar November 1998 + + +4.5 Property + + A property is the definition of an individual attribute describing a + calendar or a calendar component. A property takes the form defined + by the "contentline" notation defined in section 4.1.1. + + The following is an example of a property: + + DTSTART:19960415T133000Z + + This memo imposes no ordering of properties within an iCalendar + object. + + Property names, parameter names and enumerated parameter values are + case insensitive. For example, the property name "DUE" is the same as + "due" and "Due", DTSTART;TZID=US-Eastern:19980714T120000 is the same + as DtStart;TzID=US-Eastern:19980714T120000. + +4.6 Calendar Components + + The body of the iCalendar object consists of a sequence of calendar + properties and one or more calendar components. The calendar + properties are attributes that apply to the calendar as a whole. The + calendar components are collections of properties that express a + particular calendar semantic. For example, the calendar component can + specify an event, a to-do, a journal entry, time zone information, or + free/busy time information, or an alarm. + + The body of the iCalendar object is defined by the following + notation: + + icalbody = calprops component + + calprops = 2*( + + ; 'prodid' and 'version' are both REQUIRED, + ; but MUST NOT occur more than once + + prodid /version / + + ; 'calscale' and 'method' are optional, + ; but MUST NOT occur more than once + + calscale / + method / + + x-prop + + + + +Dawson & Stenerson Standards Track [Page 51] + +RFC 2445 iCalendar November 1998 + + + ) + + component = 1*(eventc / todoc / journalc / freebusyc / + / timezonec / iana-comp / x-comp) + + iana-comp = "BEGIN" ":" iana-token CRLF + + 1*contentline + + "END" ":" iana-token CRLF + + x-comp = "BEGIN" ":" x-name CRLF + + 1*contentline + + "END" ":" x-name CRLF + + An iCalendar object MUST include the "PRODID" and "VERSION" calendar + properties. In addition, it MUST include at least one calendar + component. Special forms of iCalendar objects are possible to publish + just busy time (i.e., only a "VFREEBUSY" calendar component) or time + zone (i.e., only a "VTIMEZONE" calendar component) information. In + addition, a complex iCalendar object is possible that is used to + capture a complete snapshot of the contents of a calendar (e.g., + composite of many different calendar components). More commonly, an + iCalendar object will consist of just a single "VEVENT", "VTODO" or + "VJOURNAL" calendar component. + +4.6.1 Event Component + + Component Name: "VEVENT" + + Purpose: Provide a grouping of component properties that describe an + event. + + Format Definition: A "VEVENT" calendar component is defined by the + following notation: + + eventc = "BEGIN" ":" "VEVENT" CRLF + eventprop *alarmc + "END" ":" "VEVENT" CRLF + + eventprop = *( + + ; the following are optional, + ; but MUST NOT occur more than once + + class / created / description / dtstart / geo / + + + +Dawson & Stenerson Standards Track [Page 52] + +RFC 2445 iCalendar November 1998 + + + last-mod / location / organizer / priority / + dtstamp / seq / status / summary / transp / + uid / url / recurid / + + ; either 'dtend' or 'duration' may appear in + ; a 'eventprop', but 'dtend' and 'duration' + ; MUST NOT occur in the same 'eventprop' + + dtend / duration / + + ; the following are optional, + ; and MAY occur more than once + + attach / attendee / categories / comment / + contact / exdate / exrule / rstatus / related / + resources / rdate / rrule / x-prop + + ) + + Description: A "VEVENT" calendar component is a grouping of component + properties, and possibly including "VALARM" calendar components, that + represents a scheduled amount of time on a calendar. For example, it + can be an activity; such as a one-hour long, department meeting from + 8:00 AM to 9:00 AM, tomorrow. Generally, an event will take up time + on an individual calendar. Hence, the event will appear as an opaque + interval in a search for busy time. Alternately, the event can have + its Time Transparency set to "TRANSPARENT" in order to prevent + blocking of the event in searches for busy time. + + The "VEVENT" is also the calendar component used to specify an + anniversary or daily reminder within a calendar. These events have a + DATE value type for the "DTSTART" property instead of the default + data type of DATE-TIME. If such a "VEVENT" has a "DTEND" property, it + MUST be specified as a DATE value also. The anniversary type of + "VEVENT" can span more than one date (i.e, "DTEND" property value is + set to a calendar date after the "DTSTART" property value). + + The "DTSTART" property for a "VEVENT" specifies the inclusive start + of the event. For recurring events, it also specifies the very first + instance in the recurrence set. The "DTEND" property for a "VEVENT" + calendar component specifies the non-inclusive end of the event. For + cases where a "VEVENT" calendar component specifies a "DTSTART" + property with a DATE data type but no "DTEND" property, the events + non-inclusive end is the end of the calendar date specified by the + "DTSTART" property. For cases where a "VEVENT" calendar component + specifies a "DTSTART" property with a DATE-TIME data type but no + "DTEND" property, the event ends on the same calendar date and time + of day specified by the "DTSTART" property. + + + +Dawson & Stenerson Standards Track [Page 53] + +RFC 2445 iCalendar November 1998 + + + The "VEVENT" calendar component cannot be nested within another + calendar component. However, "VEVENT" calendar components can be + related to each other or to a "VTODO" or to a "VJOURNAL" calendar + component with the "RELATED-TO" property. + + Example: The following is an example of the "VEVENT" calendar + component used to represent a meeting that will also be opaque to + searches for busy time: + + BEGIN:VEVENT + UID:19970901T130000Z-123401@host.com + DTSTAMP:19970901T1300Z + DTSTART:19970903T163000Z + DTEND:19970903T190000Z + SUMMARY:Annual Employee Review + CLASS:PRIVATE + CATEGORIES:BUSINESS,HUMAN RESOURCES + END:VEVENT + + The following is an example of the "VEVENT" calendar component used + to represent a reminder that will not be opaque, but rather + transparent, to searches for busy time: + + BEGIN:VEVENT + UID:19970901T130000Z-123402@host.com + DTSTAMP:19970901T1300Z + DTSTART:19970401T163000Z + DTEND:19970402T010000Z + SUMMARY:Laurel is in sensitivity awareness class. + CLASS:PUBLIC + CATEGORIES:BUSINESS,HUMAN RESOURCES + TRANSP:TRANSPARENT + END:VEVENT + + The following is an example of the "VEVENT" calendar component used + to represent an anniversary that will occur annually. Since it takes + up no time, it will not appear as opaque in a search for busy time; + no matter what the value of the "TRANSP" property indicates: + + BEGIN:VEVENT + UID:19970901T130000Z-123403@host.com + DTSTAMP:19970901T1300Z + DTSTART:19971102 + SUMMARY:Our Blissful Anniversary + CLASS:CONFIDENTIAL + CATEGORIES:ANNIVERSARY,PERSONAL,SPECIAL OCCASION + RRULE:FREQ=YEARLY + END:VEVENT + + + +Dawson & Stenerson Standards Track [Page 54] + +RFC 2445 iCalendar November 1998 + + +4.6.2 To-do Component + + Component Name: VTODO + + Purpose: Provide a grouping of calendar properties that describe a + to-do. + + Formal Definition: A "VTODO" calendar component is defined by the + following notation: + + todoc = "BEGIN" ":" "VTODO" CRLF + todoprop *alarmc + "END" ":" "VTODO" CRLF + + todoprop = *( + + ; the following are optional, + ; but MUST NOT occur more than once + + class / completed / created / description / dtstamp / + dtstart / geo / last-mod / location / organizer / + percent / priority / recurid / seq / status / + summary / uid / url / + + ; either 'due' or 'duration' may appear in + ; a 'todoprop', but 'due' and 'duration' + ; MUST NOT occur in the same 'todoprop' + + due / duration / + + ; the following are optional, + ; and MAY occur more than once + attach / attendee / categories / comment / contact / + exdate / exrule / rstatus / related / resources / + rdate / rrule / x-prop + + ) + + Description: A "VTODO" calendar component is a grouping of component + properties and possibly "VALARM" calendar components that represent + an action-item or assignment. For example, it can be used to + represent an item of work assigned to an individual; such as "turn in + travel expense today". + + The "VTODO" calendar component cannot be nested within another + calendar component. However, "VTODO" calendar components can be + related to each other or to a "VTODO" or to a "VJOURNAL" calendar + component with the "RELATED-TO" property. + + + +Dawson & Stenerson Standards Track [Page 55] + +RFC 2445 iCalendar November 1998 + + + A "VTODO" calendar component without the "DTSTART" and "DUE" (or + "DURATION") properties specifies a to-do that will be associated with + each successive calendar date, until it is completed. + + Example: The following is an example of a "VTODO" calendar component: + + BEGIN:VTODO + UID:19970901T130000Z-123404@host.com + DTSTAMP:19970901T1300Z + DTSTART:19970415T133000Z + DUE:19970416T045959Z + SUMMARY:1996 Income Tax Preparation + CLASS:CONFIDENTIAL + CATEGORIES:FAMILY,FINANCE + PRIORITY:1 + STATUS:NEEDS-ACTION + END:VTODO + +4.6.3 Journal Component + + Component Name: VJOURNAL + + Purpose: Provide a grouping of component properties that describe a + journal entry. + + Formal Definition: A "VJOURNAL" calendar component is defined by the + following notation: + + journalc = "BEGIN" ":" "VJOURNAL" CRLF + jourprop + "END" ":" "VJOURNAL" CRLF + + jourprop = *( + + ; the following are optional, + ; but MUST NOT occur more than once + + class / created / description / dtstart / dtstamp / + last-mod / organizer / recurid / seq / status / + summary / uid / url / + + ; the following are optional, + ; and MAY occur more than once + + attach / attendee / categories / comment / + contact / exdate / exrule / related / rdate / + rrule / rstatus / x-prop + + + + +Dawson & Stenerson Standards Track [Page 56] + +RFC 2445 iCalendar November 1998 + + + ) + + Description: A "VJOURNAL" calendar component is a grouping of + component properties that represent one or more descriptive text + notes associated with a particular calendar date. The "DTSTART" + property is used to specify the calendar date that the journal entry + is associated with. Generally, it will have a DATE value data type, + but it can also be used to specify a DATE-TIME value data type. + Examples of a journal entry include a daily record of a legislative + body or a journal entry of individual telephone contacts for the day + or an ordered list of accomplishments for the day. The "VJOURNAL" + calendar component can also be used to associate a document with a + calendar date. + + The "VJOURNAL" calendar component does not take up time on a + calendar. Hence, it does not play a role in free or busy time + searches - - it is as though it has a time transparency value of + TRANSPARENT. It is transparent to any such searches. + + The "VJOURNAL" calendar component cannot be nested within another + calendar component. However, "VJOURNAL" calendar components can be + related to each other or to a "VEVENT" or to a "VTODO" calendar + component, with the "RELATED-TO" property. + + Example: The following is an example of the "VJOURNAL" calendar + component: + + BEGIN:VJOURNAL + UID:19970901T130000Z-123405@host.com + DTSTAMP:19970901T1300Z + DTSTART;VALUE=DATE:19970317 + SUMMARY:Staff meeting minutes + DESCRIPTION:1. Staff meeting: Participants include Joe\, Lisa + and Bob. Aurora project plans were reviewed. There is currently + no budget reserves for this project. Lisa will escalate to + management. Next meeting on Tuesday.\n + 2. Telephone Conference: ABC Corp. sales representative called + to discuss new printer. Promised to get us a demo by Friday.\n + 3. Henry Miller (Handsoff Insurance): Car was totaled by tree. + Is looking into a loaner car. 654-2323 (tel). + END:VJOURNAL + + + + + + + + + + +Dawson & Stenerson Standards Track [Page 57] + +RFC 2445 iCalendar November 1998 + + +4.6.4 Free/Busy Component + + Component Name: VFREEBUSY + + Purpose: Provide a grouping of component properties that describe + either a request for free/busy time, describe a response to a request + for free/busy time or describe a published set of busy time. + + Formal Definition: A "VFREEBUSY" calendar component is defined by the + following notation: + + freebusyc = "BEGIN" ":" "VFREEBUSY" CRLF + fbprop + "END" ":" "VFREEBUSY" CRLF + + fbprop = *( + + ; the following are optional, + ; but MUST NOT occur more than once + + contact / dtstart / dtend / duration / dtstamp / + organizer / uid / url / + + ; the following are optional, + ; and MAY occur more than once + + attendee / comment / freebusy / rstatus / x-prop + + ) + + Description: A "VFREEBUSY" calendar component is a grouping of + component properties that represents either a request for, a reply to + a request for free or busy time information or a published set of + busy time information. + + When used to request free/busy time information, the "ATTENDEE" + property specifies the calendar users whose free/busy time is being + requested; the "ORGANIZER" property specifies the calendar user who + is requesting the free/busy time; the "DTSTART" and "DTEND" + properties specify the window of time for which the free/busy time is + being requested; the "UID" and "DTSTAMP" properties are specified to + assist in proper sequencing of multiple free/busy time requests. + + When used to reply to a request for free/busy time, the "ATTENDEE" + property specifies the calendar user responding to the free/busy time + request; the "ORGANIZER" property specifies the calendar user that + originally requested the free/busy time; the "FREEBUSY" property + specifies the free/busy time information (if it exists); and the + + + +Dawson & Stenerson Standards Track [Page 58] + +RFC 2445 iCalendar November 1998 + + + "UID" and "DTSTAMP" properties are specified to assist in proper + sequencing of multiple free/busy time replies. + + When used to publish busy time, the "ORGANIZER" property specifies + the calendar user associated with the published busy time; the + "DTSTART" and "DTEND" properties specify an inclusive time window + that surrounds the busy time information; the "FREEBUSY" property + specifies the published busy time information; and the "DTSTAMP" + property specifies the date/time that iCalendar object was created. + + The "VFREEBUSY" calendar component cannot be nested within another + calendar component. Multiple "VFREEBUSY" calendar components can be + specified within an iCalendar object. This permits the grouping of + Free/Busy information into logical collections, such as monthly + groups of busy time information. + + The "VFREEBUSY" calendar component is intended for use in iCalendar + object methods involving requests for free time, requests for busy + time, requests for both free and busy, and the associated replies. + + Free/Busy information is represented with the "FREEBUSY" property. + This property provides a terse representation of time periods. One or + more "FREEBUSY" properties can be specified in the "VFREEBUSY" + calendar component. + + When present in a "VFREEBUSY" calendar component, the "DTSTART" and + "DTEND" properties SHOULD be specified prior to any "FREEBUSY" + properties. In a free time request, these properties can be used in + combination with the "DURATION" property to represent a request for a + duration of free time within a specified window of time. + + The recurrence properties ("RRULE", "EXRULE", "RDATE", "EXDATE") are + not permitted within a "VFREEBUSY" calendar component. Any recurring + events are resolved into their individual busy time periods using the + "FREEBUSY" property. + + Example: The following is an example of a "VFREEBUSY" calendar + component used to request free or busy time information: + + BEGIN:VFREEBUSY + ORGANIZER:MAILTO:jane_doe@host1.com + ATTENDEE:MAILTO:john_public@host2.com + DTSTART:19971015T050000Z + DTEND:19971016T050000Z + DTSTAMP:19970901T083000Z + END:VFREEBUSY + + + + + +Dawson & Stenerson Standards Track [Page 59] + +RFC 2445 iCalendar November 1998 + + + The following is an example of a "VFREEBUSY" calendar component used + to reply to the request with busy time information: + + BEGIN:VFREEBUSY + ORGANIZER:MAILTO:jane_doe@host1.com + ATTENDEE:MAILTO:john_public@host2.com + DTSTAMP:19970901T100000Z + FREEBUSY;VALUE=PERIOD:19971015T050000Z/PT8H30M, + 19971015T160000Z/PT5H30M,19971015T223000Z/PT6H30M + URL:http://host2.com/pub/busy/jpublic-01.ifb + COMMENT:This iCalendar file contains busy time information for + the next three months. + END:VFREEBUSY + + The following is an example of a "VFREEBUSY" calendar component used + to publish busy time information. + + BEGIN:VFREEBUSY + ORGANIZER:jsmith@host.com + DTSTART:19980313T141711Z + DTEND:19980410T141711Z + FREEBUSY:19980314T233000Z/19980315T003000Z + FREEBUSY:19980316T153000Z/19980316T163000Z + FREEBUSY:19980318T030000Z/19980318T040000Z + URL:http://www.host.com/calendar/busytime/jsmith.ifb + END:VFREEBUSY + +4.6.5 Time Zone Component + + Component Name: VTIMEZONE + + Purpose: Provide a grouping of component properties that defines a + time zone. + + Formal Definition: A "VTIMEZONE" calendar component is defined by the + following notation: + + timezonec = "BEGIN" ":" "VTIMEZONE" CRLF + + 2*( + + ; 'tzid' is required, but MUST NOT occur more + ; than once + + tzid / + + ; 'last-mod' and 'tzurl' are optional, + but MUST NOT occur more than once + + + +Dawson & Stenerson Standards Track [Page 60] + +RFC 2445 iCalendar November 1998 + + + last-mod / tzurl / + + ; one of 'standardc' or 'daylightc' MUST occur + ..; and each MAY occur more than once. + + standardc / daylightc / + + ; the following is optional, + ; and MAY occur more than once + + x-prop + + ) + + "END" ":" "VTIMEZONE" CRLF + + standardc = "BEGIN" ":" "STANDARD" CRLF + + tzprop + + "END" ":" "STANDARD" CRLF + + daylightc = "BEGIN" ":" "DAYLIGHT" CRLF + + tzprop + + "END" ":" "DAYLIGHT" CRLF + + tzprop = 3*( + + ; the following are each REQUIRED, + ; but MUST NOT occur more than once + + dtstart / tzoffsetto / tzoffsetfrom / + + ; the following are optional, + ; and MAY occur more than once + + comment / rdate / rrule / tzname / x-prop + + ) + + Description: A time zone is unambiguously defined by the set of time + measurement rules determined by the governing body for a given + geographic area. These rules describe at a minimum the base offset + from UTC for the time zone, often referred to as the Standard Time + offset. Many locations adjust their Standard Time forward or backward + by one hour, in order to accommodate seasonal changes in number of + + + +Dawson & Stenerson Standards Track [Page 61] + +RFC 2445 iCalendar November 1998 + + + daylight hours, often referred to as Daylight Saving Time. Some + locations adjust their time by a fraction of an hour. Standard Time + is also known as Winter Time. Daylight Saving Time is also known as + Advanced Time, Summer Time, or Legal Time in certain countries. The + following table shows the changes in time zone rules in effect for + New York City starting from 1967. Each line represents a description + or rule for a particular observance. + + Effective Observance Rule + + Date (Date/Time) Offset Abbreviation + + 1967-* last Sun in Oct, 02:00 -0500 EST + + 1967-1973 last Sun in Apr, 02:00 -0400 EDT + + 1974-1974 Jan 6, 02:00 -0400 EDT + + 1975-1975 Feb 23, 02:00 -0400 EDT + + 1976-1986 last Sun in Apr, 02:00 -0400 EDT + + 1987-* first Sun in Apr, 02:00 -0400 EDT + + Note: The specification of a global time zone registry is not + addressed by this document and is left for future study. + However, implementers may find the Olson time zone database [TZ] + a useful reference. It is an informal, public-domain collection + of time zone information, which is currently being maintained by + volunteer Internet participants, and is used in several + operating systems. This database contains current and historical + time zone information for a wide variety of locations around the + globe; it provides a time zone identifier for every unique time + zone rule set in actual use since 1970, with historical data + going back to the introduction of standard time. + + Interoperability between two calendaring and scheduling applications, + especially for recurring events, to-dos or journal entries, is + dependent on the ability to capture and convey date and time + information in an unambiguous format. The specification of current + time zone information is integral to this behavior. + + If present, the "VTIMEZONE" calendar component defines the set of + Standard Time and Daylight Saving Time observances (or rules) for a + particular time zone for a given interval of time. The "VTIMEZONE" + calendar component cannot be nested within other calendar components. + Multiple "VTIMEZONE" calendar components can exist in an iCalendar + object. In this situation, each "VTIMEZONE" MUST represent a unique + + + +Dawson & Stenerson Standards Track [Page 62] + +RFC 2445 iCalendar November 1998 + + + time zone definition. This is necessary for some classes of events, + such as airline flights, that start in one time zone and end in + another. + + The "VTIMEZONE" calendar component MUST be present if the iCalendar + object contains an RRULE that generates dates on both sides of a time + zone shift (e.g. both in Standard Time and Daylight Saving Time) + unless the iCalendar object intends to convey a floating time (See + the section "4.1.10.11 Time" for proper interpretation of floating + time). It can be present if the iCalendar object does not contain + such a RRULE. In addition, if a RRULE is present, there MUST be valid + time zone information for all recurrence instances. + + The "VTIMEZONE" calendar component MUST include the "TZID" property + and at least one definition of a standard or daylight component. The + standard or daylight component MUST include the "DTSTART", + "TZOFFSETFROM" and "TZOFFSETTO" properties. + + An individual "VTIMEZONE" calendar component MUST be specified for + each unique "TZID" parameter value specified in the iCalendar object. + + Each "VTIMEZONE" calendar component consists of a collection of one + or more sub-components that describe the rule for a particular + observance (either a Standard Time or a Daylight Saving Time + observance). The "STANDARD" sub-component consists of a collection of + properties that describe Standard Time. The "DAYLIGHT" sub-component + consists of a collection of properties that describe Daylight Saving + Time. In general this collection of properties consists of: + + - the first onset date-time for the observance + + - the last onset date-time for the observance, if a last onset + is known. + + - the offset to be applied for the observance + + - a rule that describes the day and time when the observance + takes effect + + - an optional name for the observance + + For a given time zone, there may be multiple unique definitions of + the observances over a period of time. Each observance is described + using either a "STANDARD" or "DAYLIGHT" sub-component. The collection + of these sub-components is used to describe the time zone for a given + period of time. The offset to apply at any given time is found by + locating the observance that has the last onset date and time before + the time in question, and using the offset value from that + + + +Dawson & Stenerson Standards Track [Page 63] + +RFC 2445 iCalendar November 1998 + + + observance. + + The top-level properties in a "VTIMEZONE" calendar component are: + + The mandatory "TZID" property is a text value that uniquely + identifies the VTIMZONE calendar component within the scope of an + iCalendar object. + + The optional "LAST-MODIFIED" property is a UTC value that specifies + the date and time that this time zone definition was last updated. + + The optional "TZURL" property is url value that points to a published + VTIMEZONE definition. TZURL SHOULD refer to a resource that is + accessible by anyone who might need to interpret the object. This + SHOULD NOT normally be a file: URL or other URL that is not widely- + accessible. + + The collection of properties that are used to define the STANDARD and + DAYLIGHT sub-components include: + + The mandatory "DTSTART" property gives the effective onset date and + local time for the time zone sub-component definition. "DTSTART" in + this usage MUST be specified as a local DATE-TIME value. + + The mandatory "TZOFFSETFROM" property gives the UTC offset which is + in use when the onset of this time zone observance begins. + "TZOFFSETFROM" is combined with "DTSTART" to define the effective + onset for the time zone sub-component definition. For example, the + following represents the time at which the observance of Standard + Time took effect in Fall 1967 for New York City: + + DTSTART:19671029T020000 + + TZOFFSETFROM:-0400 + + The mandatory "TZOFFSETTO " property gives the UTC offset for the + time zone sub-component (Standard Time or Daylight Saving Time) when + this observance is in use. + + The optional "TZNAME" property is the customary name for the time + zone. It may be specified multiple times, to allow for specifying + multiple language variants of the time zone names. This could be used + for displaying dates. + + If specified, the onset for the observance defined by the time zone + sub-component is defined by either the "RRULE" or "RDATE" property. + If neither is specified, only one sub-component can be specified in + the "VTIMEZONE" calendar component and it is assumed that the single + + + +Dawson & Stenerson Standards Track [Page 64] + +RFC 2445 iCalendar November 1998 + + + observance specified is always in effect. + + The "RRULE" property defines the recurrence rule for the onset of the + observance defined by this time zone sub-component. Some specific + requirements for the usage of RRULE for this purpose include: + + - If observance is known to have an effective end date, the + "UNTIL" recurrence rule parameter MUST be used to specify the + last valid onset of this observance (i.e., the UNTIL date-time + will be equal to the last instance generated by the recurrence + pattern). It MUST be specified in UTC time. + + - The "DTSTART" and the "TZOFFSETTO" properties MUST be used + when generating the onset date-time values (instances) from the + RRULE. + + Alternatively, the "RDATE" property can be used to define the onset + of the observance by giving the individual onset date and times. + "RDATE" in this usage MUST be specified as a local DATE-TIME value in + UTC time. + + The optional "COMMENT" property is also allowed for descriptive + explanatory text. + + Example: The following are examples of the "VTIMEZONE" calendar + component: + + This is an example showing time zone information for the Eastern + United States using "RDATE" property. Note that this is only suitable + for a recurring event that starts on or later than April 6, 1997 at + 03:00:00 EDT (i.e., the earliest effective transition date and time) + and ends no later than April 7, 1998 02:00:00 EST (i.e., latest valid + date and time for EST in this scenario). For example, this can be + used for a recurring event that occurs every Friday, 8am-9:00 AM, + starting June 1, 1997, ending December 31, 1997. + + BEGIN:VTIMEZONE + TZID:US-Eastern + LAST-MODIFIED:19870101T000000Z + BEGIN:STANDARD + DTSTART:19971026T020000 + RDATE:19971026T020000 + TZOFFSETFROM:-0400 + TZOFFSETTO:-0500 + TZNAME:EST + END:STANDARD + BEGIN:DAYLIGHT + DTSTART:19971026T020000 + + + +Dawson & Stenerson Standards Track [Page 65] + +RFC 2445 iCalendar November 1998 + + + RDATE:19970406T020000 + TZOFFSETFROM:-0500 + TZOFFSETTO:-0400 + TZNAME:EDT + END:DAYLIGHT + END:VTIMEZONE + + This is a simple example showing the current time zone rules for the + Eastern United States using a RRULE recurrence pattern. Note that + there is no effective end date to either of the Standard Time or + Daylight Time rules. This information would be valid for a recurring + event starting today and continuing indefinitely. + + BEGIN:VTIMEZONE + TZID:US-Eastern + LAST-MODIFIED:19870101T000000Z + TZURL:http://zones.stds_r_us.net/tz/US-Eastern + BEGIN:STANDARD + DTSTART:19671029T020000 + RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 + TZOFFSETFROM:-0400 + TZOFFSETTO:-0500 + TZNAME:EST + END:STANDARD + BEGIN:DAYLIGHT + DTSTART:19870405T020000 + RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4 + TZOFFSETFROM:-0500 + TZOFFSETTO:-0400 + TZNAME:EDT + END:DAYLIGHT + END:VTIMEZONE + + This is an example showing a fictitious set of rules for the Eastern + United States, where the Daylight Time rule has an effective end date + (i.e., after that date, Daylight Time is no longer observed). + + BEGIN:VTIMEZONE + TZID:US--Fictitious-Eastern + LAST-MODIFIED:19870101T000000Z + BEGIN:STANDARD + DTSTART:19671029T020000 + RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 + TZOFFSETFROM:-0400 + TZOFFSETTO:-0500 + TZNAME:EST + END:STANDARD + + + + +Dawson & Stenerson Standards Track [Page 66] + +RFC 2445 iCalendar November 1998 + + + BEGIN:DAYLIGHT + DTSTART:19870405T020000 + RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4;UNTIL=19980404T070000Z + TZOFFSETFROM:-0500 + TZOFFSETTO:-0400 + TZNAME:EDT + END:DAYLIGHT + END:VTIMEZONE + + This is an example showing a fictitious set of rules for the Eastern + United States, where the first Daylight Time rule has an effective + end date. There is a second Daylight Time rule that picks up where + the other left off. + + BEGIN:VTIMEZONE + TZID:US--Fictitious-Eastern + LAST-MODIFIED:19870101T000000Z + BEGIN:STANDARD + DTSTART:19671029T020000 + RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 + TZOFFSETFROM:-0400 + TZOFFSETTO:-0500 + TZNAME:EST + END:STANDARD + BEGIN:DAYLIGHT + DTSTART:19870405T020000 + RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4;UNTIL=19980404T070000Z + TZOFFSETFROM:-0500 + TZOFFSETTO:-0400 + TZNAME:EDT + END:DAYLIGHT + BEGIN:DAYLIGHT + DTSTART:19990424T020000 + RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=4 + TZOFFSETFROM:-0500 + TZOFFSETTO:-0400 + TZNAME:EDT + END:DAYLIGHT + END:VTIMEZONE + +4.6.6 Alarm Component + + Component Name: VALARM + + Purpose: Provide a grouping of component properties that define an + alarm. + + + + + +Dawson & Stenerson Standards Track [Page 67] + +RFC 2445 iCalendar November 1998 + + + Formal Definition: A "VALARM" calendar component is defined by the + following notation: + + alarmc = "BEGIN" ":" "VALARM" CRLF + (audioprop / dispprop / emailprop / procprop) + "END" ":" "VALARM" CRLF + + audioprop = 2*( + + ; 'action' and 'trigger' are both REQUIRED, + ; but MUST NOT occur more than once + + action / trigger / + + ; 'duration' and 'repeat' are both optional, + ; and MUST NOT occur more than once each, + ; but if one occurs, so MUST the other + + duration / repeat / + + ; the following is optional, + ; but MUST NOT occur more than once + + attach / + + ; the following is optional, + ; and MAY occur more than once + + x-prop + + ) + + + + dispprop = 3*( + + ; the following are all REQUIRED, + ; but MUST NOT occur more than once + + action / description / trigger / + + ; 'duration' and 'repeat' are both optional, + ; and MUST NOT occur more than once each, + ; but if one occurs, so MUST the other + + duration / repeat / + + ; the following is optional, + + + +Dawson & Stenerson Standards Track [Page 68] + +RFC 2445 iCalendar November 1998 + + + ; and MAY occur more than once + + *x-prop + + ) + + + + emailprop = 5*( + + ; the following are all REQUIRED, + ; but MUST NOT occur more than once + + action / description / trigger / summary + + ; the following is REQUIRED, + ; and MAY occur more than once + + attendee / + + ; 'duration' and 'repeat' are both optional, + ; and MUST NOT occur more than once each, + ; but if one occurs, so MUST the other + + duration / repeat / + + ; the following are optional, + ; and MAY occur more than once + + attach / x-prop + + ) + + + + procprop = 3*( + + ; the following are all REQUIRED, + ; but MUST NOT occur more than once + + action / attach / trigger / + + ; 'duration' and 'repeat' are both optional, + ; and MUST NOT occur more than once each, + ; but if one occurs, so MUST the other + + duration / repeat / + + + + +Dawson & Stenerson Standards Track [Page 69] + +RFC 2445 iCalendar November 1998 + + + ; 'description' is optional, + ; and MUST NOT occur more than once + + description / + + ; the following is optional, + ; and MAY occur more than once + + x-prop + + ) + + Description: A "VALARM" calendar component is a grouping of component + properties that is a reminder or alarm for an event or a to-do. For + example, it may be used to define a reminder for a pending event or + an overdue to-do. + + The "VALARM" calendar component MUST include the "ACTION" and + "TRIGGER" properties. The "ACTION" property further constrains the + "VALARM" calendar component in the following ways: + + When the action is "AUDIO", the alarm can also include one and only + one "ATTACH" property, which MUST point to a sound resource, which is + rendered when the alarm is triggered. + + When the action is "DISPLAY", the alarm MUST also include a + "DESCRIPTION" property, which contains the text to be displayed when + the alarm is triggered. + + When the action is "EMAIL", the alarm MUST include a "DESCRIPTION" + property, which contains the text to be used as the message body, a + "SUMMARY" property, which contains the text to be used as the message + subject, and one or more "ATTENDEE" properties, which contain the + email address of attendees to receive the message. It can also + include one or more "ATTACH" properties, which are intended to be + sent as message attachments. When the alarm is triggered, the email + message is sent. + + When the action is "PROCEDURE", the alarm MUST include one and only + one "ATTACH" property, which MUST point to a procedure resource, + which is invoked when the alarm is triggered. + + The "VALARM" calendar component MUST only appear within either a + "VEVENT" or "VTODO" calendar component. "VALARM" calendar components + cannot be nested. Multiple mutually independent "VALARM" calendar + components can be specified for a single "VEVENT" or "VTODO" calendar + component. + + + + +Dawson & Stenerson Standards Track [Page 70] + +RFC 2445 iCalendar November 1998 + + + The "TRIGGER" property specifies when the alarm will be triggered. + The "TRIGGER" property specifies a duration prior to the start of an + event or a to-do. The "TRIGGER" edge may be explicitly set to be + relative to the "START" or "END" of the event or to-do with the + "RELATED" parameter of the "TRIGGER" property. The "TRIGGER" property + value type can alternatively be set to an absolute calendar date and + time of day value. + + In an alarm set to trigger on the "START" of an event or to-do, the + "DTSTART" property MUST be present in the associated event or to-do. + In an alarm in a "VEVENT" calendar component set to trigger on the + "END" of the event, either the "DTEND" property MUST be present, or + the "DTSTART" and "DURATION" properties MUST both be present. In an + alarm in a "VTODO" calendar component set to trigger on the "END" of + the to-do, either the "DUE" property MUST be present, or the + "DTSTART" and "DURATION" properties MUST both be present. + + The alarm can be defined such that it triggers repeatedly. A + definition of an alarm with a repeating trigger MUST include both the + "DURATION" and "REPEAT" properties. The "DURATION" property specifies + the delay period, after which the alarm will repeat. The "REPEAT" + property specifies the number of additional repetitions that the + alarm will triggered. This repitition count is in addition to the + initial triggering of the alarm. Both of these properties MUST be + present in order to specify a repeating alarm. If one of these two + properties is absent, then the alarm will not repeat beyond the + initial trigger. + + The "ACTION" property is used within the "VALARM" calendar component + to specify the type of action invoked when the alarm is triggered. + The "VALARM" properties provide enough information for a specific + action to be invoked. It is typically the responsibility of a + "Calendar User Agent" (CUA) to deliver the alarm in the specified + fashion. An "ACTION" property value of AUDIO specifies an alarm that + causes a sound to be played to alert the user; DISPLAY specifies an + alarm that causes a text message to be displayed to the user; EMAIL + specifies an alarm that causes an electronic email message to be + delivered to one or more email addresses; and PROCEDURE specifies an + alarm that causes a procedure to be executed. The "ACTION" property + MUST specify one and only one of these values. + + In an AUDIO alarm, if the optional "ATTACH" property is included, it + MUST specify an audio sound resource. The intention is that the sound + will be played as the alarm effect. If an "ATTACH" property is + specified that does not refer to a sound resource, or if the + specified sound resource cannot be rendered (because its format is + unsupported, or because it cannot be retrieved), then the CUA or + other entity responsible for playing the sound may choose a fallback + + + +Dawson & Stenerson Standards Track [Page 71] + +RFC 2445 iCalendar November 1998 + + + action, such as playing a built-in default sound, or playing no sound + at all. + + In a DISPLAY alarm, the intended alarm effect is for the text value + of the "DESCRIPTION" property to be displayed to the user. + + In an EMAIL alarm, the intended alarm effect is for an email message + to be composed and delivered to all the addresses specified by the + "ATTENDEE" properties in the "VALARM" calendar component. The + "DESCRIPTION" property of the "VALARM" calendar component MUST be + used as the body text of the message, and the "SUMMARY" property MUST + be used as the subject text. Any "ATTACH" properties in the "VALARM" + calendar component SHOULD be sent as attachments to the message. + + In a PROCEDURE alarm, the "ATTACH" property in the "VALARM" calendar + component MUST specify a procedure or program that is intended to be + invoked as the alarm effect. If the procedure or program is in a + format that cannot be rendered, then no procedure alarm will be + invoked. If the "DESCRIPTION" property is present, its value + specifies the argument string to be passed to the procedure or + program. "Calendar User Agents" that receive an iCalendar object with + this category of alarm, can disable or allow the "Calendar User" to + disable, or otherwise ignore this type of alarm. While a very useful + alarm capability, the PROCEDURE type of alarm SHOULD be treated by + the "Calendar User Agent" as a potential security risk. + + Example: The following example is for a "VALARM" calendar component + that specifies an audio alarm that will sound at a precise time and + repeat 4 more times at 15 minute intervals: + + BEGIN:VALARM + TRIGGER;VALUE=DATE-TIME:19970317T133000Z + REPEAT:4 + DURATION:PT15M + ACTION:AUDIO + ATTACH;FMTTYPE=audio/basic:ftp://host.com/pub/sounds/bell-01.aud + END:VALARM + + The following example is for a "VALARM" calendar component that + specifies a display alarm that will trigger 30 minutes before the + scheduled start of the event or the due date/time of the to-do it is + associated with and will repeat 2 more times at 15 minute intervals: + + BEGIN:VALARM + TRIGGER:-PT30M + REPEAT:2 + DURATION:PT15M + ACTION:DISPLAY + + + +Dawson & Stenerson Standards Track [Page 72] + +RFC 2445 iCalendar November 1998 + + + DESCRIPTION:Breakfast meeting with executive\n + team at 8:30 AM EST. + END:VALARM + + The following example is for a "VALARM" calendar component that + specifies an email alarm that will trigger 2 days before the + scheduled due date/time of a to-do it is associated with. It does not + repeat. The email has a subject, body and attachment link. + + BEGIN:VALARM + TRIGGER:-P2D + ACTION:EMAIL + ATTENDEE:MAILTO:john_doe@host.com + SUMMARY:*** REMINDER: SEND AGENDA FOR WEEKLY STAFF MEETING *** + DESCRIPTION:A draft agenda needs to be sent out to the attendees + to the weekly managers meeting (MGR-LIST). Attached is a + pointer the document template for the agenda file. + ATTACH;FMTTYPE=application/binary:http://host.com/templates/agen + da.doc + END:VALARM + + The following example is for a "VALARM" calendar component that + specifies a procedural alarm that will trigger at a precise date/time + and will repeat 23 more times at one hour intervals. The alarm will + invoke a procedure file. + + BEGIN:VALARM + TRIGGER;VALUE=DATE-TIME:19980101T050000Z + REPEAT:23 + DURATION:PT1H + ACTION:PROCEDURE + ATTACH;FMTTYPE=application/binary:ftp://host.com/novo- + procs/felizano.exe + END:VALARM + +4.7 Calendar Properties + + The Calendar Properties are attributes that apply to the iCalendar + object, as a whole. These properties do not appear within a calendar + component. They SHOULD be specified after the "BEGIN:VCALENDAR" + property and prior to any calendar component. + +4.7.1 Calendar Scale + + Property Name: CALSCALE + + Purpose: This property defines the calendar scale used for the + calendar information specified in the iCalendar object. + + + +Dawson & Stenerson Standards Track [Page 73] + +RFC 2445 iCalendar November 1998 + + + Value Type: TEXT + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: Property can be specified in an iCalendar object. The + default value is "GREGORIAN". + + Description: This memo is based on the Gregorian calendar scale. The + Gregorian calendar scale is assumed if this property is not specified + in the iCalendar object. It is expected that other calendar scales + will be defined in other specifications or by future versions of this + memo. + + Format Definition: The property is defined by the following notation: + + calscale = "CALSCALE" calparam ":" calvalue CRLF + + calparam = *(";" xparam) + + calvalue = "GREGORIAN" / iana-token + + Example: The following is an example of this property: + + CALSCALE:GREGORIAN + +4.7.2 Method + + Property Name: METHOD + + Purpose: This property defines the iCalendar object method associated + with the calendar object. + + Value Type: TEXT + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: The property can be specified in an iCalendar object. + + Description: When used in a MIME message entity, the value of this + property MUST be the same as the Content-Type "method" parameter + value. This property can only appear once within the iCalendar + object. If either the "METHOD" property or the Content-Type "method" + parameter is specified, then the other MUST also be specified. + + No methods are defined by this specification. This is the subject of + other specifications, such as the iCalendar Transport-independent + + + +Dawson & Stenerson Standards Track [Page 74] + +RFC 2445 iCalendar November 1998 + + + Interoperability Protocol (iTIP) defined by [ITIP]. + + If this property is not present in the iCalendar object, then a + scheduling transaction MUST NOT be assumed. In such cases, the + iCalendar object is merely being used to transport a snapshot of some + calendar information; without the intention of conveying a scheduling + semantic. + + Format Definition: The property is defined by the following notation: + + method = "METHOD" metparam ":" metvalue CRLF + + metparam = *(";" xparam) + + metvalue = iana-token + + Example: The following is a hypothetical example of this property to + convey that the iCalendar object is a request for a meeting: + + METHOD:REQUEST + +4.7.3 Product Identifier + + Property Name: PRODID + + Purpose: This property specifies the identifier for the product that + created the iCalendar object. + + Value Type: TEXT + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: The property MUST be specified once in an iCalendar + object. + + Description: The vendor of the implementation SHOULD assure that this + is a globally unique identifier; using some technique such as an FPI + value, as defined in [ISO 9070]. + + This property SHOULD not be used to alter the interpretation of an + iCalendar object beyond the semantics specified in this memo. For + example, it is not to be used to further the understanding of non- + standard properties. + + Format Definition: The property is defined by the following notation: + + prodid = "PRODID" pidparam ":" pidvalue CRLF + + + +Dawson & Stenerson Standards Track [Page 75] + +RFC 2445 iCalendar November 1998 + + + pidparam = *(";" xparam) + + pidvalue = text + ;Any text that describes the product and version + ;and that is generally assured of being unique. + + Example: The following is an example of this property. It does not + imply that English is the default language. + + PRODID:-//ABC Corporation//NONSGML My Product//EN + +4.7.4 Version + + Property Name: VERSION + + Purpose: This property specifies the identifier corresponding to the + highest version number or the minimum and maximum range of the + iCalendar specification that is required in order to interpret the + iCalendar object. + + Value Type: TEXT + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: This property MUST be specified by an iCalendar object, + but MUST only be specified once. + + Description: A value of "2.0" corresponds to this memo. + + Format Definition: The property is defined by the following notation: + + version = "VERSION" verparam ":" vervalue CRLF + + verparam = *(";" xparam) + + vervalue = "2.0" ;This memo + / maxver + / (minver ";" maxver) + + minver = + ;Minimum iCalendar version needed to parse the iCalendar object + + maxver = + ;Maximum iCalendar version needed to parse the iCalendar object + + Example: The following is an example of this property: + + + + +Dawson & Stenerson Standards Track [Page 76] + +RFC 2445 iCalendar November 1998 + + + VERSION:2.0 + +4.8 Component Properties + + The following properties can appear within calendar components, as + specified by each component property definition. + +4.8.1 Descriptive Component Properties + + The following properties specify descriptive information about + calendar components. + +4.8.1.1 Attachment + + Property Name: ATTACH + + Purpose: The property provides the capability to associate a document + object with a calendar component. + + Value Type: The default value type for this property is URI. The + value type can also be set to BINARY to indicate inline binary + encoded content information. + + Property Parameters: Non-standard, inline encoding, format type and + value data type property parameters can be specified on this + property. + + Conformance: The property can be specified in a "VEVENT", "VTODO", + "VJOURNAL" or "VALARM" calendar components. + + Description: The property can be specified within "VEVENT", "VTODO", + "VJOURNAL", or "VALARM" calendar components. This property can be + specified multiple times within an iCalendar object. + + Format Definition: The property is defined by the following notation: + + attach = "ATTACH" attparam ":" uri CRLF + + attach =/ "ATTACH" attparam ";" "ENCODING" "=" "BASE64" + ";" "VALUE" "=" "BINARY" ":" binary + + attparam = *( + + ; the following is optional, + ; but MUST NOT occur more than once + + (";" fmttypeparam) / + + + + +Dawson & Stenerson Standards Track [Page 77] + +RFC 2445 iCalendar November 1998 + + + ; the following is optional, + ; and MAY occur more than once + + (";" xparam) + + ) + + Example: The following are examples of this property: + + ATTACH:CID:jsmith.part3.960817T083000.xyzMail@host1.com + + ATTACH;FMTTYPE=application/postscript:ftp://xyzCorp.com/pub/ + reports/r-960812.ps + +4.8.1.2 Categories + + Property Name: CATEGORIES + + Purpose: This property defines the categories for a calendar + component. + + Value Type: TEXT + + Property Parameters: Non-standard and language property parameters + can be specified on this property. + + Conformance: The property can be specified within "VEVENT", "VTODO" + or "VJOURNAL" calendar components. + + Description: This property is used to specify categories or subtypes + of the calendar component. The categories are useful in searching for + a calendar component of a particular type and category. Within the + "VEVENT", "VTODO" or "VJOURNAL" calendar components, more than one + category can be specified as a list of categories separated by the + COMMA character (US-ASCII decimal 44). + + Format Definition: The property is defined by the following notation: + + categories = "CATEGORIES" catparam ":" text *("," text) + CRLF + + catparam = *( + + ; the following is optional, + ; but MUST NOT occur more than once + + (";" languageparam ) / + + + + +Dawson & Stenerson Standards Track [Page 78] + +RFC 2445 iCalendar November 1998 + + + ; the following is optional, + ; and MAY occur more than once + + (";" xparam) + + ) + + Example: The following are examples of this property: + + CATEGORIES:APPOINTMENT,EDUCATION + + CATEGORIES:MEETING + +4.8.1.3 Classification + + Property Name: CLASS + + Purpose: This property defines the access classification for a + calendar component. + + Value Type: TEXT + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: The property can be specified once in a "VEVENT", + "VTODO" or "VJOURNAL" calendar components. + + Description: An access classification is only one component of the + general security system within a calendar application. It provides a + method of capturing the scope of the access the calendar owner + intends for information within an individual calendar entry. The + access classification of an individual iCalendar component is useful + when measured along with the other security components of a calendar + system (e.g., calendar user authentication, authorization, access + rights, access role, etc.). Hence, the semantics of the individual + access classifications cannot be completely defined by this memo + alone. Additionally, due to the "blind" nature of most exchange + processes using this memo, these access classifications cannot serve + as an enforcement statement for a system receiving an iCalendar + object. Rather, they provide a method for capturing the intention of + the calendar owner for the access to the calendar component. + + Format Definition: The property is defined by the following notation: + + class = "CLASS" classparam ":" classvalue CRLF + + classparam = *(";" xparam) + + + +Dawson & Stenerson Standards Track [Page 79] + +RFC 2445 iCalendar November 1998 + + + classvalue = "PUBLIC" / "PRIVATE" / "CONFIDENTIAL" / iana-token + / x-name + ;Default is PUBLIC + + Example: The following is an example of this property: + + CLASS:PUBLIC + +4.8.1.4 Comment + + Property Name: COMMENT + + Purpose: This property specifies non-processing information intended + to provide a comment to the calendar user. + + Value Type: TEXT + + Property Parameters: Non-standard, alternate text representation and + language property parameters can be specified on this property. + + Conformance: This property can be specified in "VEVENT", "VTODO", + "VJOURNAL", "VTIMEZONE" or "VFREEBUSY" calendar components. + + Description: The property can be specified multiple times. + + Format Definition: The property is defined by the following notation: + + comment = "COMMENT" commparam ":" text CRLF + + commparam = *( + + ; the following are optional, + ; but MUST NOT occur more than once + + (";" altrepparam) / (";" languageparam) / + + ; the following is optional, + ; and MAY occur more than once + + (";" xparam) + + ) + + Example: The following is an example of this property: + + COMMENT:The meeting really needs to include both ourselves + and the customer. We can't hold this meeting without them. + As a matter of fact\, the venue for the meeting ought to be at + + + +Dawson & Stenerson Standards Track [Page 80] + +RFC 2445 iCalendar November 1998 + + + their site. - - John + + The data type for this property is TEXT. + +4.8.1.5 Description + + Property Name: DESCRIPTION + + Purpose: This property provides a more complete description of the + calendar component, than that provided by the "SUMMARY" property. + + Value Type: TEXT + + Property Parameters: Non-standard, alternate text representation and + language property parameters can be specified on this property. + + Conformance: The property can be specified in the "VEVENT", "VTODO", + "VJOURNAL" or "VALARM" calendar components. The property can be + specified multiple times only within a "VJOURNAL" calendar component. + + Description: This property is used in the "VEVENT" and "VTODO" to + capture lengthy textual decriptions associated with the activity. + + This property is used in the "VJOURNAL" calendar component to capture + one more textual journal entries. + + This property is used in the "VALARM" calendar component to capture + the display text for a DISPLAY category of alarm, to capture the body + text for an EMAIL category of alarm and to capture the argument + string for a PROCEDURE category of alarm. + + Format Definition: The property is defined by the following notation: + + description = "DESCRIPTION" descparam ":" text CRLF + + descparam = *( + + ; the following are optional, + ; but MUST NOT occur more than once + + (";" altrepparam) / (";" languageparam) / + + ; the following is optional, + ; and MAY occur more than once + + (";" xparam) + + ) + + + +Dawson & Stenerson Standards Track [Page 81] + +RFC 2445 iCalendar November 1998 + + + Example: The following is an example of the property with formatted + line breaks in the property value: + + DESCRIPTION:Meeting to provide technical review for "Phoenix" + design.\n Happy Face Conference Room. Phoenix design team + MUST attend this meeting.\n RSVP to team leader. + + The following is an example of the property with folding of long + lines: + + DESCRIPTION:Last draft of the new novel is to be completed + for the editor's proof today. + +4.8.1.6 Geographic Position + + Property Name: GEO + + Purpose: This property specifies information related to the global + position for the activity specified by a calendar component. + + Value Type: FLOAT. The value MUST be two SEMICOLON separated FLOAT + values. + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: This property can be specified in "VEVENT" or "VTODO" + calendar components. + + Description: The property value specifies latitude and longitude, in + that order (i.e., "LAT LON" ordering). The longitude represents the + location east or west of the prime meridian as a positive or negative + real number, respectively. The longitude and latitude values MAY be + specified up to six decimal places, which will allow for accuracy to + within one meter of geographical position. Receiving applications + MUST accept values of this precision and MAY truncate values of + greater precision. + + Values for latitude and longitude shall be expressed as decimal + fractions of degrees. Whole degrees of latitude shall be represented + by a two-digit decimal number ranging from 0 through 90. Whole + degrees of longitude shall be represented by a decimal number ranging + from 0 through 180. When a decimal fraction of a degree is specified, + it shall be separated from the whole number of degrees by a decimal + point. + + + + + + +Dawson & Stenerson Standards Track [Page 82] + +RFC 2445 iCalendar November 1998 + + + Latitudes north of the equator shall be specified by a plus sign (+), + or by the absence of a minus sign (-), preceding the digits + designating degrees. Latitudes south of the Equator shall be + designated by a minus sign (-) preceding the digits designating + degrees. A point on the Equator shall be assigned to the Northern + Hemisphere. + + Longitudes east of the prime meridian shall be specified by a plus + sign (+), or by the absence of a minus sign (-), preceding the digits + designating degrees. Longitudes west of the meridian shall be + designated by minus sign (-) preceding the digits designating + degrees. A point on the prime meridian shall be assigned to the + Eastern Hemisphere. A point on the 180th meridian shall be assigned + to the Western Hemisphere. One exception to this last convention is + permitted. For the special condition of describing a band of latitude + around the earth, the East Bounding Coordinate data element shall be + assigned the value +180 (180) degrees. + + Any spatial address with a latitude of +90 (90) or -90 degrees will + specify the position at the North or South Pole, respectively. The + component for longitude may have any legal value. + + With the exception of the special condition described above, this + form is specified in Department of Commerce, 1986, Representation of + geographic point locations for information interchange (Federal + Information Processing Standard 70-1): Washington, Department of + Commerce, National Institute of Standards and Technology. + + The simple formula for converting degrees-minutes-seconds into + decimal degrees is: + + decimal = degrees + minutes/60 + seconds/3600. + + Format Definition: The property is defined by the following notation: + + geo = "GEO" geoparam ":" geovalue CRLF + + geoparam = *(";" xparam) + + geovalue = float ";" float + ;Latitude and Longitude components + + Example: The following is an example of this property: + + GEO:37.386013;-122.082932 + + + + + + +Dawson & Stenerson Standards Track [Page 83] + +RFC 2445 iCalendar November 1998 + + +4.8.1.7 Location + + Property Name: LOCATION + + Purpose: The property defines the intended venue for the activity + defined by a calendar component. + + Value Type: TEXT + + Property Parameters: Non-standard, alternate text representation and + language property parameters can be specified on this property. + + Conformance: This property can be specified in "VEVENT" or "VTODO" + calendar component. + + Description: Specific venues such as conference or meeting rooms may + be explicitly specified using this property. An alternate + representation may be specified that is a URI that points to + directory information with more structured specification of the + location. For example, the alternate representation may specify + either an LDAP URI pointing to an LDAP server entry or a CID URI + pointing to a MIME body part containing a vCard [RFC 2426] for the + location. + + Format Definition: The property is defined by the following notation: + + location = "LOCATION locparam ":" text CRLF + + locparam = *( + + ; the following are optional, + ; but MUST NOT occur more than once + + (";" altrepparam) / (";" languageparam) / + + ; the following is optional, + ; and MAY occur more than once + + (";" xparam) + + ) + + Example: The following are some examples of this property: + + LOCATION:Conference Room - F123, Bldg. 002 + + LOCATION;ALTREP="http://xyzcorp.com/conf-rooms/f123.vcf": + Conference Room - F123, Bldg. 002 + + + +Dawson & Stenerson Standards Track [Page 84] + +RFC 2445 iCalendar November 1998 + + +4.8.1.8 Percent Complete + + Property Name: PERCENT-COMPLETE + + Purpose: This property is used by an assignee or delegatee of a to-do + to convey the percent completion of a to-do to the Organizer. + + Value Type: INTEGER + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: This property can be specified in a "VTODO" calendar + component. + + Description: The property value is a positive integer between zero + and one hundred. A value of "0" indicates the to-do has not yet been + started. A value of "100" indicates that the to-do has been + completed. Integer values in between indicate the percent partially + complete. + + When a to-do is assigned to multiple individuals, the property value + indicates the percent complete for that portion of the to-do assigned + to the assignee or delegatee. For example, if a to-do is assigned to + both individuals "A" and "B". A reply from "A" with a percent + complete of "70" indicates that "A" has completed 70% of the to-do + assigned to them. A reply from "B" with a percent complete of "50" + indicates "B" has completed 50% of the to-do assigned to them. + + Format Definition: The property is defined by the following notation: + + percent = "PERCENT-COMPLETE" pctparam ":" integer CRLF + + pctparam = *(";" xparam) + + Example: The following is an example of this property to show 39% + completion: + + PERCENT-COMPLETE:39 + +4.8.1.9 Priority + + Property Name: PRIORITY + + Purpose: The property defines the relative priority for a calendar + component. + + Value Type: INTEGER + + + +Dawson & Stenerson Standards Track [Page 85] + +RFC 2445 iCalendar November 1998 + + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: The property can be specified in a "VEVENT" or "VTODO" + calendar component. + + Description: The priority is specified as an integer in the range + zero to nine. A value of zero (US-ASCII decimal 48) specifies an + undefined priority. A value of one (US-ASCII decimal 49) is the + highest priority. A value of two (US-ASCII decimal 50) is the second + highest priority. Subsequent numbers specify a decreasing ordinal + priority. A value of nine (US-ASCII decimal 58) is the lowest + priority. + + A CUA with a three-level priority scheme of "HIGH", "MEDIUM" and + "LOW" is mapped into this property such that a property value in the + range of one (US-ASCII decimal 49) to four (US-ASCII decimal 52) + specifies "HIGH" priority. A value of five (US-ASCII decimal 53) is + the normal or "MEDIUM" priority. A value in the range of six (US- + ASCII decimal 54) to nine (US-ASCII decimal 58) is "LOW" priority. + + A CUA with a priority schema of "A1", "A2", "A3", "B1", "B2", ..., + "C3" is mapped into this property such that a property value of one + (US-ASCII decimal 49) specifies "A1", a property value of two (US- + ASCII decimal 50) specifies "A2", a property value of three (US-ASCII + decimal 51) specifies "A3", and so forth up to a property value of 9 + (US-ASCII decimal 58) specifies "C3". + + Other integer values are reserved for future use. + + Within a "VEVENT" calendar component, this property specifies a + priority for the event. This property may be useful when more than + one event is scheduled for a given time period. + + Within a "VTODO" calendar component, this property specified a + priority for the to-do. This property is useful in prioritizing + multiple action items for a given time period. + + Format Definition: The property is specified by the following + notation: + + priority = "PRIORITY" prioparam ":" privalue CRLF + ;Default is zero + + prioparam = *(";" xparam) + + privalue = integer ;Must be in the range [0..9] + ; All other values are reserved for future use + + + +Dawson & Stenerson Standards Track [Page 86] + +RFC 2445 iCalendar November 1998 + + + The following is an example of a property with the highest priority: + + PRIORITY:1 + + The following is an example of a property with a next highest + priority: + + PRIORITY:2 + + Example: The following is an example of a property with no priority. + This is equivalent to not specifying the "PRIORITY" property: + + PRIORITY:0 + +4.8.1.10 Resources + + Property Name: RESOURCES + + Purpose: This property defines the equipment or resources anticipated + for an activity specified by a calendar entity.. + + Value Type: TEXT + + Property Parameters: Non-standard, alternate text representation and + language property parameters can be specified on this property. + + Conformance: This property can be specified in "VEVENT" or "VTODO" + calendar component. + + Description: The property value is an arbitrary text. More than one + resource can be specified as a list of resources separated by the + COMMA character (US-ASCII decimal 44). + + Format Definition: The property is defined by the following notation: + + resources = "RESOURCES" resrcparam ":" text *("," text) CRLF + + resrcparam = *( + + ; the following are optional, + ; but MUST NOT occur more than once + + (";" altrepparam) / (";" languageparam) / + + ; the following is optional, + ; and MAY occur more than once + + + + + +Dawson & Stenerson Standards Track [Page 87] + +RFC 2445 iCalendar November 1998 + + + (";" xparam) + + ) + + Example: The following is an example of this property: + + RESOURCES:EASEL,PROJECTOR,VCR + + RESOURCES;LANGUAGE=fr:1 raton-laveur + +4.8.1.11 Status + + Property Name: STATUS + + Purpose: This property defines the overall status or confirmation for + the calendar component. + + Value Type: TEXT + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: This property can be specified in "VEVENT", "VTODO" or + "VJOURNAL" calendar components. + + Description: In a group scheduled calendar component, the property is + used by the "Organizer" to provide a confirmation of the event to the + "Attendees". For example in a "VEVENT" calendar component, the + "Organizer" can indicate that a meeting is tentative, confirmed or + cancelled. In a "VTODO" calendar component, the "Organizer" can + indicate that an action item needs action, is completed, is in + process or being worked on, or has been cancelled. In a "VJOURNAL" + calendar component, the "Organizer" can indicate that a journal entry + is draft, final or has been cancelled or removed. + + Format Definition: The property is defined by the following notation: + + status = "STATUS" statparam] ":" statvalue CRLF + + statparam = *(";" xparam) + + statvalue = "TENTATIVE" ;Indicates event is + ;tentative. + / "CONFIRMED" ;Indicates event is + ;definite. + / "CANCELLED" ;Indicates event was + ;cancelled. + ;Status values for a "VEVENT" + + + +Dawson & Stenerson Standards Track [Page 88] + +RFC 2445 iCalendar November 1998 + + + statvalue =/ "NEEDS-ACTION" ;Indicates to-do needs action. + / "COMPLETED" ;Indicates to-do completed. + / "IN-PROCESS" ;Indicates to-do in process of + / "CANCELLED" ;Indicates to-do was cancelled. + ;Status values for "VTODO". + + statvalue =/ "DRAFT" ;Indicates journal is draft. + / "FINAL" ;Indicates journal is final. + / "CANCELLED" ;Indicates journal is removed. + ;Status values for "VJOURNAL". + + Example: The following is an example of this property for a "VEVENT" + calendar component: + + STATUS:TENTATIVE + + The following is an example of this property for a "VTODO" calendar + component: + + STATUS:NEEDS-ACTION + + The following is an example of this property for a "VJOURNAL" + calendar component: + + STATUS:DRAFT + +4.8.1.12 Summary + + Property Name: SUMMARY + + Purpose: This property defines a short summary or subject for the + calendar component. + + Value Type: TEXT + + Property Parameters: Non-standard, alternate text representation and + language property parameters can be specified on this property. + + Conformance: The property can be specified in "VEVENT", "VTODO", + "VJOURNAL" or "VALARM" calendar components. + + Description: This property is used in the "VEVENT", "VTODO" and + "VJOURNAL" calendar components to capture a short, one line summary + about the activity or journal entry. + + This property is used in the "VALARM" calendar component to capture + the subject of an EMAIL category of alarm. + + + + +Dawson & Stenerson Standards Track [Page 89] + +RFC 2445 iCalendar November 1998 + + + Format Definition: The property is defined by the following notation: + + summary = "SUMMARY" summparam ":" text CRLF + + summparam = *( + + ; the following are optional, + ; but MUST NOT occur more than once + + (";" altrepparam) / (";" languageparam) / + + ; the following is optional, + ; and MAY occur more than once + + (";" xparam) + + ) + + Example: The following is an example of this property: + + SUMMARY:Department Party + +4.8.2 Date and Time Component Properties + + The following properties specify date and time related information in + calendar components. + +4.8.2.1 Date/Time Completed + + Property Name: COMPLETED + + Purpose: This property defines the date and time that a to-do was + actually completed. + + Value Type: DATE-TIME + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: The property can be specified in a "VTODO" calendar + component. + + Description: The date and time MUST be in a UTC format. + + Format Definition: The property is defined by the following notation: + + completed = "COMPLETED" compparam ":" date-time CRLF + + + + +Dawson & Stenerson Standards Track [Page 90] + +RFC 2445 iCalendar November 1998 + + + compparam = *(";" xparam) + + Example: The following is an example of this property: + + COMPLETED:19960401T235959Z + +4.8.2.2 Date/Time End + + Property Name: DTEND + + Purpose: This property specifies the date and time that a calendar + component ends. + + Value Type: The default value type is DATE-TIME. The value type can + be set to a DATE value type. + + Property Parameters: Non-standard, value data type, time zone + identifier property parameters can be specified on this property. + + Conformance: This property can be specified in "VEVENT" or + "VFREEBUSY" calendar components. + + Description: Within the "VEVENT" calendar component, this property + defines the date and time by which the event ends. The value MUST be + later in time than the value of the "DTSTART" property. + + Within the "VFREEBUSY" calendar component, this property defines the + end date and time for the free or busy time information. The time + MUST be specified in the UTC time format. The value MUST be later in + time than the value of the "DTSTART" property. + + Format Definition: The property is defined by the following notation: + + dtend = "DTEND" dtendparam":" dtendval CRLF + + dtendparam = *( + + ; the following are optional, + ; but MUST NOT occur more than once + + (";" "VALUE" "=" ("DATE-TIME" / "DATE")) / + (";" tzidparam) / + + ; the following is optional, + ; and MAY occur more than once + + + + + + +Dawson & Stenerson Standards Track [Page 91] + +RFC 2445 iCalendar November 1998 + + + (";" xparam) + + ) + + + + dtendval = date-time / date + ;Value MUST match value type + + Example: The following is an example of this property: + + DTEND:19960401T235959Z + + DTEND;VALUE=DATE:19980704 + +4.8.2.3 Date/Time Due + + Property Name: DUE + + Purpose: This property defines the date and time that a to-do is + expected to be completed. + + Value Type: The default value type is DATE-TIME. The value type can + be set to a DATE value type. + + Property Parameters: Non-standard, value data type, time zone + identifier property parameters can be specified on this property. + + Conformance: The property can be specified once in a "VTODO" calendar + component. + + Description: The value MUST be a date/time equal to or after the + DTSTART value, if specified. + + Format Definition: The property is defined by the following notation: + + due = "DUE" dueparam":" dueval CRLF + + dueparam = *( + ; the following are optional, + ; but MUST NOT occur more than once + + (";" "VALUE" "=" ("DATE-TIME" / "DATE")) / + (";" tzidparam) / + + ; the following is optional, + ; and MAY occur more than once + + + + +Dawson & Stenerson Standards Track [Page 92] + +RFC 2445 iCalendar November 1998 + + + *(";" xparam) + + ) + + + + dueval = date-time / date + ;Value MUST match value type + + Example: The following is an example of this property: + + DUE:19980430T235959Z + +4.8.2.4 Date/Time Start + + Property Name: DTSTART + + Purpose: This property specifies when the calendar component begins. + + Value Type: The default value type is DATE-TIME. The time value MUST + be one of the forms defined for the DATE-TIME value type. The value + type can be set to a DATE value type. + + Property Parameters: Non-standard, value data type, time zone + identifier property parameters can be specified on this property. + + Conformance: This property can be specified in the "VEVENT", "VTODO", + "VFREEBUSY", or "VTIMEZONE" calendar components. + + Description: Within the "VEVENT" calendar component, this property + defines the start date and time for the event. The property is + REQUIRED in "VEVENT" calendar components. Events can have a start + date/time but no end date/time. In that case, the event does not take + up any time. + + Within the "VFREEBUSY" calendar component, this property defines the + start date and time for the free or busy time information. The time + MUST be specified in UTC time. + + Within the "VTIMEZONE" calendar component, this property defines the + effective start date and time for a time zone specification. This + property is REQUIRED within each STANDARD and DAYLIGHT part included + in "VTIMEZONE" calendar components and MUST be specified as a local + DATE-TIME without the "TZID" property parameter. + + Format Definition: The property is defined by the following notation: + + dtstart = "DTSTART" dtstparam ":" dtstval CRLF + + + +Dawson & Stenerson Standards Track [Page 93] + +RFC 2445 iCalendar November 1998 + + + dtstparam = *( + + ; the following are optional, + ; but MUST NOT occur more than once + + (";" "VALUE" "=" ("DATE-TIME" / "DATE")) / + (";" tzidparam) / + + ; the following is optional, + ; and MAY occur more than once + + *(";" xparam) + + ) + + + + dtstval = date-time / date + ;Value MUST match value type + + Example: The following is an example of this property: + + DTSTART:19980118T073000Z + +4.8.2.5 Duration + + Property Name: DURATION + + Purpose: The property specifies a positive duration of time. + + Value Type: DURATION + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: The property can be specified in "VEVENT", "VTODO", + "VFREEBUSY" or "VALARM" calendar components. + + Description: In a "VEVENT" calendar component the property may be + used to specify a duration of the event, instead of an explicit end + date/time. In a "VTODO" calendar component the property may be used + to specify a duration for the to-do, instead of an explicit due + date/time. In a "VFREEBUSY" calendar component the property may be + used to specify the interval of free time being requested. In a + "VALARM" calendar component the property may be used to specify the + delay period prior to repeating an alarm. + + Format Definition: The property is defined by the following notation: + + + +Dawson & Stenerson Standards Track [Page 94] + +RFC 2445 iCalendar November 1998 + + + duration = "DURATION" durparam ":" dur-value CRLF + ;consisting of a positive duration of time. + + durparam = *(";" xparam) + + Example: The following is an example of this property that specifies + an interval of time of 1 hour and zero minutes and zero seconds: + + DURATION:PT1H0M0S + + The following is an example of this property that specifies an + interval of time of 15 minutes. + + DURATION:PT15M + +4.8.2.6 Free/Busy Time + + Property Name: FREEBUSY + + Purpose: The property defines one or more free or busy time + intervals. + + Value Type: PERIOD. The date and time values MUST be in an UTC time + format. + + Property Parameters: Non-standard or free/busy time type property + parameters can be specified on this property. + + Conformance: The property can be specified in a "VFREEBUSY" calendar + component. + + Property Parameter: "FBTYPE" and non-standard parameters can be + specified on this property. + + Description: These time periods can be specified as either a start + and end date-time or a start date-time and duration. The date and + time MUST be a UTC time format. + + "FREEBUSY" properties within the "VFREEBUSY" calendar component + SHOULD be sorted in ascending order, based on start time and then end + time, with the earliest periods first. + + The "FREEBUSY" property can specify more than one value, separated by + the COMMA character (US-ASCII decimal 44). In such cases, the + "FREEBUSY" property values SHOULD all be of the same "FBTYPE" + property parameter type (e.g., all values of a particular "FBTYPE" + listed together in a single property). + + + + +Dawson & Stenerson Standards Track [Page 95] + +RFC 2445 iCalendar November 1998 + + + Format Definition: The property is defined by the following notation: + + freebusy = "FREEBUSY" fbparam ":" fbvalue + CRLF + + fbparam = *( + ; the following is optional, + ; but MUST NOT occur more than once + + (";" fbtypeparam) / + + ; the following is optional, + ; and MAY occur more than once + + (";" xparam) + + ) + + fbvalue = period *["," period] + ;Time value MUST be in the UTC time format. + + Example: The following are some examples of this property: + + FREEBUSY;FBTYPE=BUSY-UNAVAILABLE:19970308T160000Z/PT8H30M + + FREEBUSY;FBTYPE=FREE:19970308T160000Z/PT3H,19970308T200000Z/PT1H + + FREEBUSY;FBTYPE=FREE:19970308T160000Z/PT3H,19970308T200000Z/PT1H, + 19970308T230000Z/19970309T000000Z + +4.8.2.7 Time Transparency + + Property Name: TRANSP + + Purpose: This property defines whether an event is transparent or not + to busy time searches. + + Value Type: TEXT + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: This property can be specified once in a "VEVENT" + calendar component. + + Description: Time Transparency is the characteristic of an event that + determines whether it appears to consume time on a calendar. Events + that consume actual time for the individual or resource associated + + + +Dawson & Stenerson Standards Track [Page 96] + +RFC 2445 iCalendar November 1998 + + + with the calendar SHOULD be recorded as OPAQUE, allowing them to be + detected by free-busy time searches. Other events, which do not take + up the individual's (or resource's) time SHOULD be recorded as + TRANSPARENT, making them invisible to free-busy time searches. + + Format Definition: The property is specified by the following + notation: + + transp = "TRANSP" tranparam ":" transvalue CRLF + + tranparam = *(";" xparam) + + transvalue = "OPAQUE" ;Blocks or opaque on busy time searches. + / "TRANSPARENT" ;Transparent on busy time searches. + ;Default value is OPAQUE + + Example: The following is an example of this property for an event + that is transparent or does not block on free/busy time searches: + + TRANSP:TRANSPARENT + + The following is an example of this property for an event that is + opaque or blocks on free/busy time searches: + + TRANSP:OPAQUE + +4.8.3 Time Zone Component Properties + + The following properties specify time zone information in calendar + components. + +4.8.3.1 Time Zone Identifier + + Property Name: TZID + + Purpose: This property specifies the text value that uniquely + identifies the "VTIMEZONE" calendar component. + + Value Type: TEXT + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: This property MUST be specified in a "VTIMEZONE" + calendar component. + + + + + + +Dawson & Stenerson Standards Track [Page 97] + +RFC 2445 iCalendar November 1998 + + + Description: This is the label by which a time zone calendar + component is referenced by any iCalendar properties whose data type + is either DATE-TIME or TIME and not intended to specify a UTC or a + "floating" time. The presence of the SOLIDUS character (US-ASCII + decimal 47) as a prefix, indicates that this TZID represents an + unique ID in a globally defined time zone registry (when such + registry is defined). + + Note: This document does not define a naming convention for time + zone identifiers. Implementers may want to use the naming + conventions defined in existing time zone specifications such as + the public-domain Olson database [TZ]. The specification of + globally unique time zone identifiers is not addressed by this + document and is left for future study. + + Format Definition: This property is defined by the following + notation: + + tzid = "TZID" tzidpropparam ":" [tzidprefix] text CRLF + + tzidpropparam = *(";" xparam) + + ;tzidprefix = "/" + ; Defined previously. Just listed here for reader convenience. + + Example: The following are examples of non-globally unique time zone + identifiers: + + TZID:US-Eastern + + TZID:California-Los_Angeles + + The following is an example of a fictitious globally unique time zone + identifier: + + TZID:/US-New_York-New_York + +4.8.3.2 Time Zone Name + + Property Name: TZNAME + + Purpose: This property specifies the customary designation for a time + zone description. + + Value Type: TEXT + + Property Parameters: Non-standard and language property parameters + can be specified on this property. + + + +Dawson & Stenerson Standards Track [Page 98] + +RFC 2445 iCalendar November 1998 + + + Conformance: This property can be specified in a "VTIMEZONE" calendar + component. + + Description: This property may be specified in multiple languages; in + order to provide for different language requirements. + + Format Definition: This property is defined by the following + notation: + + tzname = "TZNAME" tznparam ":" text CRLF + + tznparam = *( + + ; the following is optional, + ; but MUST NOT occur more than once + + (";" languageparam) / + + ; the following is optional, + ; and MAY occur more than once + + (";" xparam) + + ) + + Example: The following are example of this property: + + TZNAME:EST + + The following is an example of this property when two different + languages for the time zone name are specified: + + TZNAME;LANGUAGE=en:EST + TZNAME;LANGUAGE=fr-CA:HNE + +4.8.3.3 Time Zone Offset From + + Property Name: TZOFFSETFROM + + Purpose: This property specifies the offset which is in use prior to + this time zone observance. + + Value Type: UTC-OFFSET + + Property Parameters: Non-standard property parameters can be + specified on this property. + + + + + +Dawson & Stenerson Standards Track [Page 99] + +RFC 2445 iCalendar November 1998 + + + Conformance: This property MUST be specified in a "VTIMEZONE" + calendar component. + + Description: This property specifies the offset which is in use prior + to this time observance. It is used to calculate the absolute time at + which the transition to a given observance takes place. This property + MUST only be specified in a "VTIMEZONE" calendar component. A + "VTIMEZONE" calendar component MUST include this property. The + property value is a signed numeric indicating the number of hours and + possibly minutes from UTC. Positive numbers represent time zones east + of the prime meridian, or ahead of UTC. Negative numbers represent + time zones west of the prime meridian, or behind UTC. + + Format Definition: The property is defined by the following notation: + + tzoffsetfrom = "TZOFFSETFROM" frmparam ":" utc-offset + CRLF + + frmparam = *(";" xparam) + + Example: The following are examples of this property: + + TZOFFSETFROM:-0500 + + TZOFFSETFROM:+1345 + +4.8.3.4 Time Zone Offset To + + Property Name: TZOFFSETTO + + Purpose: This property specifies the offset which is in use in this + time zone observance. + + Value Type: UTC-OFFSET + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: This property MUST be specified in a "VTIMEZONE" + calendar component. + + Description: This property specifies the offset which is in use in + this time zone observance. It is used to calculate the absolute time + for the new observance. The property value is a signed numeric + indicating the number of hours and possibly minutes from UTC. + Positive numbers represent time zones east of the prime meridian, or + ahead of UTC. Negative numbers represent time zones west of the prime + meridian, or behind UTC. + + + +Dawson & Stenerson Standards Track [Page 100] + +RFC 2445 iCalendar November 1998 + + + Format Definition: The property is defined by the following notation: + + tzoffsetto = "TZOFFSETTO" toparam ":" utc-offset CRLF + + toparam = *(";" xparam) + + Example: The following are examples of this property: + + TZOFFSETTO:-0400 + + TZOFFSETTO:+1245 + +4.8.3.5 Time Zone URL + + Property Name: TZURL + + Purpose: The TZURL provides a means for a VTIMEZONE component to + point to a network location that can be used to retrieve an up-to- + date version of itself. + + Value Type: URI + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: This property can be specified in a "VTIMEZONE" calendar + component. + + Description: The TZURL provides a means for a VTIMEZONE component to + point to a network location that can be used to retrieve an up-to- + date version of itself. This provides a hook to handle changes + government bodies impose upon time zone definitions. Retrieval of + this resource results in an iCalendar object containing a single + VTIMEZONE component and a METHOD property set to PUBLISH. + + Format Definition: The property is defined by the following notation: + + tzurl = "TZURL" tzurlparam ":" uri CRLF + + tzurlparam = *(";" xparam) + + Example: The following is an example of this property: + + TZURL:http://timezones.r.us.net/tz/US-California-Los_Angeles + + + + + + + +Dawson & Stenerson Standards Track [Page 101] + +RFC 2445 iCalendar November 1998 + + +4.8.4 Relationship Component Properties + + The following properties specify relationship information in calendar + components. + +4.8.4.1 Attendee + + Property Name: ATTENDEE + + Purpose: The property defines an "Attendee" within a calendar + component. + + Value Type: CAL-ADDRESS + + Property Parameters: Non-standard, language, calendar user type, + group or list membership, participation role, participation status, + RSVP expectation, delegatee, delegator, sent by, common name or + directory entry reference property parameters can be specified on + this property. + + Conformance: This property MUST be specified in an iCalendar object + that specifies a group scheduled calendar entity. This property MUST + NOT be specified in an iCalendar object when publishing the calendar + information (e.g., NOT in an iCalendar object that specifies the + publication of a calendar user's busy time, event, to-do or journal). + This property is not specified in an iCalendar object that specifies + only a time zone definition or that defines calendar entities that + are not group scheduled entities, but are entities only on a single + user's calendar. + + Description: The property MUST only be specified within calendar + components to specify participants, non-participants and the chair of + a group scheduled calendar entity. The property is specified within + an "EMAIL" category of the "VALARM" calendar component to specify an + email address that is to receive the email type of iCalendar alarm. + + The property parameter CN is for the common or displayable name + associated with the calendar address; ROLE, for the intended role + that the attendee will have in the calendar component; PARTSTAT, for + the status of the attendee's participation; RSVP, for indicating + whether the favor of a reply is requested; CUTYPE, to indicate the + type of calendar user; MEMBER, to indicate the groups that the + attendee belongs to; DELEGATED-TO, to indicate the calendar users + that the original request was delegated to; and DELEGATED-FROM, to + indicate whom the request was delegated from; SENT-BY, to indicate + whom is acting on behalf of the ATTENDEE; and DIR, to indicate the + URI that points to the directory information corresponding to the + attendee. These property parameters can be specified on an "ATTENDEE" + + + +Dawson & Stenerson Standards Track [Page 102] + +RFC 2445 iCalendar November 1998 + + + property in either a "VEVENT", "VTODO" or "VJOURNAL" calendar + component. They MUST not be specified in an "ATTENDEE" property in a + "VFREEBUSY" or "VALARM" calendar component. If the LANGUAGE property + parameter is specified, the identified language applies to the CN + parameter. + + A recipient delegated a request MUST inherit the RSVP and ROLE values + from the attendee that delegated the request to them. + + Multiple attendees can be specified by including multiple "ATTENDEE" + properties within the calendar component. + + Format Definition: The property is defined by the following notation: + + attendee = "ATTENDEE" attparam ":" cal-address CRLF + + attparam = *( + + ; the following are optional, + ; but MUST NOT occur more than once + + (";" cutypeparam) / (";"memberparam) / + (";" roleparam) / (";" partstatparam) / + (";" rsvpparam) / (";" deltoparam) / + (";" delfromparam) / (";" sentbyparam) / + (";"cnparam) / (";" dirparam) / + (";" languageparam) / + + ; the following is optional, + ; and MAY occur more than once + + (";" xparam) + + ) + + Example: The following are examples of this property's use for a to- + do: + + ORGANIZER:MAILTO:jsmith@host1.com + ATTENDEE;MEMBER="MAILTO:DEV-GROUP@host2.com": + MAILTO:joecool@host2.com + ATTENDEE;DELEGATED-FROM="MAILTO:immud@host3.com": + MAILTO:ildoit@host1.com + + The following is an example of this property used for specifying + multiple attendees to an event: + + + + + +Dawson & Stenerson Standards Track [Page 103] + +RFC 2445 iCalendar November 1998 + + + ORGANIZER:MAILTO:jsmith@host1.com + ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=TENTATIVE;CN=Henry Cabot + :MAILTO:hcabot@host2.com + ATTENDEE;ROLE=REQ-PARTICIPANT;DELEGATED-FROM="MAILTO:bob@host.com" + ;PARTSTAT=ACCEPTED;CN=Jane Doe:MAILTO:jdoe@host1.com + + The following is an example of this property with a URI to the + directory information associated with the attendee: + + ATTENDEE;CN=John Smith;DIR="ldap://host.com:6666/o=eDABC% + 20Industries,c=3DUS??(cn=3DBJim%20Dolittle)":MAILTO:jimdo@ + host1.com + + The following is an example of this property with "delegatee" and + "delegator" information for an event: + + ORGANIZER;CN=John Smith:MAILTO:jsmith@host.com + ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=TENTATIVE;DELEGATED-FROM= + "MAILTO:iamboss@host2.com";CN=Henry Cabot:MAILTO:hcabot@ + host2.com + ATTENDEE;ROLE=NON-PARTICIPANT;PARTSTAT=DELEGATED;DELEGATED-TO= + "MAILTO:hcabot@host2.com";CN=The Big Cheese:MAILTO:iamboss + @host2.com + ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=ACCEPTED;CN=Jane Doe + :MAILTO:jdoe@host1.com + + Example: The following is an example of this property's use when + another calendar user is acting on behalf of the "Attendee": + + ATTENDEE;SENT-BY=MAILTO:jan_doe@host1.com;CN=John Smith:MAILTO: + jsmith@host1.com + +4.8.4.2 Contact + + Property Name: CONTACT + + Purpose: The property is used to represent contact information or + alternately a reference to contact information associated with the + calendar component. + + Value Type: TEXT + + Property Parameters: Non-standard, alternate text representation and + language property parameters can be specified on this property. + + Conformance: The property can be specified in a "VEVENT", "VTODO", + "VJOURNAL" or "VFREEBUSY" calendar component. + + + + +Dawson & Stenerson Standards Track [Page 104] + +RFC 2445 iCalendar November 1998 + + + Description: The property value consists of textual contact + information. An alternative representation for the property value can + also be specified that refers to a URI pointing to an alternate form, + such as a vCard [RFC 2426], for the contact information. + + Format Definition: The property is defined by the following notation: + + contact = "CONTACT" contparam ":" text CRLF + + contparam = *( + ; the following are optional, + ; but MUST NOT occur more than once + + (";" altrepparam) / (";" languageparam) / + + ; the following is optional, + ; and MAY occur more than once + + (";" xparam) + + ) + + Example: The following is an example of this property referencing + textual contact information: + + CONTACT:Jim Dolittle\, ABC Industries\, +1-919-555-1234 + + The following is an example of this property with an alternate + representation of a LDAP URI to a directory entry containing the + contact information: + + CONTACT;ALTREP="ldap://host.com:6666/o=3DABC%20Industries\, + c=3DUS??(cn=3DBJim%20Dolittle)":Jim Dolittle\, ABC Industries\, + +1-919-555-1234 + + The following is an example of this property with an alternate + representation of a MIME body part containing the contact + information, such as a vCard [RFC 2426] embedded in a [MIME-DIR] + content-type: + + CONTACT;ALTREP="CID=":Jim + Dolittle\, ABC Industries\, +1-919-555-1234 + + The following is an example of this property referencing a network + resource, such as a vCard [RFC 2426] object containing the contact + information: + + + + + +Dawson & Stenerson Standards Track [Page 105] + +RFC 2445 iCalendar November 1998 + + + CONTACT;ALTREP="http://host.com/pdi/jdoe.vcf":Jim + Dolittle\, ABC Industries\, +1-919-555-1234 + +4.8.4.3 Organizer + + Property Name: ORGANIZER + + Purpose: The property defines the organizer for a calendar component. + + Value Type: CAL-ADDRESS + + Property Parameters: Non-standard, language, common name, directory + entry reference, sent by property parameters can be specified on this + property. + + Conformance: This property MUST be specified in an iCalendar object + that specifies a group scheduled calendar entity. This property MUST + be specified in an iCalendar object that specifies the publication of + a calendar user's busy time. This property MUST NOT be specified in + an iCalendar object that specifies only a time zone definition or + that defines calendar entities that are not group scheduled entities, + but are entities only on a single user's calendar. + + Description: The property is specified within the "VEVENT", "VTODO", + "VJOURNAL calendar components to specify the organizer of a group + scheduled calendar entity. The property is specified within the + "VFREEBUSY" calendar component to specify the calendar user + requesting the free or busy time. When publishing a "VFREEBUSY" + calendar component, the property is used to specify the calendar that + the published busy time came from. + + The property has the property parameters CN, for specifying the + common or display name associated with the "Organizer", DIR, for + specifying a pointer to the directory information associated with the + "Organizer", SENT-BY, for specifying another calendar user that is + acting on behalf of the "Organizer". The non-standard parameters may + also be specified on this property. If the LANGUAGE property + parameter is specified, the identified language applies to the CN + parameter value. + + Format Definition: The property is defined by the following notation: + + organizer = "ORGANIZER" orgparam ":" + cal-address CRLF + + orgparam = *( + + ; the following are optional, + + + +Dawson & Stenerson Standards Track [Page 106] + +RFC 2445 iCalendar November 1998 + + + ; but MUST NOT occur more than once + + (";" cnparam) / (";" dirparam) / (";" sentbyparam) / + (";" languageparam) / + + ; the following is optional, + ; and MAY occur more than once + + (";" xparam) + + ) + + Example: The following is an example of this property: + + ORGANIZER;CN=John Smith:MAILTO:jsmith@host1.com + + The following is an example of this property with a pointer to the + directory information associated with the organizer: + + ORGANIZER;CN=JohnSmith;DIR="ldap://host.com:6666/o=3DDC%20Associ + ates,c=3DUS??(cn=3DJohn%20Smith)":MAILTO:jsmith@host1.com + + The following is an example of this property used by another calendar + user who is acting on behalf of the organizer, with responses + intended to be sent back to the organizer, not the other calendar + user: + + ORGANIZER;SENT-BY="MAILTO:jane_doe@host.com": + MAILTO:jsmith@host1.com + +4.8.4.4 Recurrence ID + + Property Name: RECURRENCE-ID + + Purpose: This property is used in conjunction with the "UID" and + "SEQUENCE" property to identify a specific instance of a recurring + "VEVENT", "VTODO" or "VJOURNAL" calendar component. The property + value is the effective value of the "DTSTART" property of the + recurrence instance. + + Value Type: The default value type for this property is DATE-TIME. + The time format can be any of the valid forms defined for a DATE-TIME + value type. See DATE-TIME value type definition for specific + interpretations of the various forms. The value type can be set to + DATE. + + + + + + +Dawson & Stenerson Standards Track [Page 107] + +RFC 2445 iCalendar November 1998 + + + Property Parameters: Non-standard property, value data type, time + zone identifier and recurrence identifier range parameters can be + specified on this property. + + Conformance: This property can be specified in an iCalendar object + containing a recurring calendar component. + + Description: The full range of calendar components specified by a + recurrence set is referenced by referring to just the "UID" property + value corresponding to the calendar component. The "RECURRENCE-ID" + property allows the reference to an individual instance within the + recurrence set. + + If the value of the "DTSTART" property is a DATE type value, then the + value MUST be the calendar date for the recurrence instance. + + The date/time value is set to the time when the original recurrence + instance would occur; meaning that if the intent is to change a + Friday meeting to Thursday, the date/time is still set to the + original Friday meeting. + + The "RECURRENCE-ID" property is used in conjunction with the "UID" + and "SEQUENCE" property to identify a particular instance of a + recurring event, to-do or journal. For a given pair of "UID" and + "SEQUENCE" property values, the "RECURRENCE-ID" value for a + recurrence instance is fixed. When the definition of the recurrence + set for a calendar component changes, and hence the "SEQUENCE" + property value changes, the "RECURRENCE-ID" for a given recurrence + instance might also change.The "RANGE" parameter is used to specify + the effective range of recurrence instances from the instance + specified by the "RECURRENCE-ID" property value. The default value + for the range parameter is the single recurrence instance only. The + value can also be "THISANDPRIOR" to indicate a range defined by the + given recurrence instance and all prior instances or the value can be + "THISANDFUTURE" to indicate a range defined by the given recurrence + instance and all subsequent instances. + + Format Definition: The property is defined by the following notation: + + recurid = "RECURRENCE-ID" ridparam ":" ridval CRLF + + ridparam = *( + + ; the following are optional, + ; but MUST NOT occur more than once + + (";" "VALUE" "=" ("DATE-TIME" / "DATE)) / + (";" tzidparam) / (";" rangeparam) / + + + +Dawson & Stenerson Standards Track [Page 108] + +RFC 2445 iCalendar November 1998 + + + ; the following is optional, + ; and MAY occur more than once + + (";" xparam) + + ) + + ridval = date-time / date + ;Value MUST match value type + + Example: The following are examples of this property: + + RECURRENCE-ID;VALUE=DATE:19960401 + + RECURRENCE-ID;RANGE=THISANDFUTURE:19960120T120000Z + +4.8.4.5 Related To + + Property Name: RELATED-TO + + Purpose: The property is used to represent a relationship or + reference between one calendar component and another. + + Value Type: TEXT + + Property Parameters: Non-standard and relationship type property + parameters can be specified on this property. + + Conformance: The property can be specified one or more times in the + "VEVENT", "VTODO" or "VJOURNAL" calendar components. + + Description: The property value consists of the persistent, globally + unique identifier of another calendar component. This value would be + represented in a calendar component by the "UID" property. + + By default, the property value points to another calendar component + that has a PARENT relationship to the referencing object. The + "RELTYPE" property parameter is used to either explicitly state the + default PARENT relationship type to the referenced calendar component + or to override the default PARENT relationship type and specify + either a CHILD or SIBLING relationship. The PARENT relationship + indicates that the calendar component is a subordinate of the + referenced calendar component. The CHILD relationship indicates that + the calendar component is a superior of the referenced calendar + component. The SIBLING relationship indicates that the calendar + component is a peer of the referenced calendar component. + + + + + +Dawson & Stenerson Standards Track [Page 109] + +RFC 2445 iCalendar November 1998 + + + Changes to a calendar component referenced by this property can have + an implicit impact on the related calendar component. For example, if + a group event changes its start or end date or time, then the + related, dependent events will need to have their start and end dates + changed in a corresponding way. Similarly, if a PARENT calendar + component is canceled or deleted, then there is an implied impact to + the related CHILD calendar components. This property is intended only + to provide information on the relationship of calendar components. It + is up to the target calendar system to maintain any property + implications of this relationship. + + Format Definition: The property is defined by the following notation: + + related = "RELATED-TO" [relparam] ":" text CRLF + + relparam = *( + + ; the following is optional, + ; but MUST NOT occur more than once + + (";" reltypeparam) / + + ; the following is optional, + ; and MAY occur more than once + + (";" xparm) + + ) + + The following is an example of this property: + + RELATED-TO: + + RELATED-TO:<19960401-080045-4000F192713-0052@host1.com> + +4.8.4.6 Uniform Resource Locator + + Property Name: URL + + Purpose: This property defines a Uniform Resource Locator (URL) + associated with the iCalendar object. + + Value Type: URI + + Property Parameters: Non-standard property parameters can be + specified on this property. + + + + + +Dawson & Stenerson Standards Track [Page 110] + +RFC 2445 iCalendar November 1998 + + + Conformance: This property can be specified once in the "VEVENT", + "VTODO", "VJOURNAL" or "VFREEBUSY" calendar components. + + Description: This property may be used in a calendar component to + convey a location where a more dynamic rendition of the calendar + information associated with the calendar component can be found. This + memo does not attempt to standardize the form of the URI, nor the + format of the resource pointed to by the property value. If the URL + property and Content-Location MIME header are both specified, they + MUST point to the same resource. + + Format Definition: The property is defined by the following notation: + + url = "URL" urlparam ":" uri CRLF + + urlparam = *(";" xparam) + + Example: The following is an example of this property: + + URL:http://abc.com/pub/calendars/jsmith/mytime.ics + +4.8.4.7 Unique Identifier + + Property Name: UID + + Purpose: This property defines the persistent, globally unique + identifier for the calendar component. + + Value Type: TEXT + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: The property MUST be specified in the "VEVENT", "VTODO", + "VJOURNAL" or "VFREEBUSY" calendar components. + + Description: The UID itself MUST be a globally unique identifier. The + generator of the identifier MUST guarantee that the identifier is + unique. There are several algorithms that can be used to accomplish + this. The identifier is RECOMMENDED to be the identical syntax to the + [RFC 822] addr-spec. A good method to assure uniqueness is to put the + domain name or a domain literal IP address of the host on which the + identifier was created on the right hand side of the "@", and on the + left hand side, put a combination of the current calendar date and + time of day (i.e., formatted in as a DATE-TIME value) along with some + other currently unique (perhaps sequential) identifier available on + the system (for example, a process id number). Using a date/time + value on the left hand side and a domain name or domain literal on + + + +Dawson & Stenerson Standards Track [Page 111] + +RFC 2445 iCalendar November 1998 + + + the right hand side makes it possible to guarantee uniqueness since + no two hosts should be using the same domain name or IP address at + the same time. Though other algorithms will work, it is RECOMMENDED + that the right hand side contain some domain identifier (either of + the host itself or otherwise) such that the generator of the message + identifier can guarantee the uniqueness of the left hand side within + the scope of that domain. + + This is the method for correlating scheduling messages with the + referenced "VEVENT", "VTODO", or "VJOURNAL" calendar component. + + The full range of calendar components specified by a recurrence set + is referenced by referring to just the "UID" property value + corresponding to the calendar component. The "RECURRENCE-ID" property + allows the reference to an individual instance within the recurrence + set. + + This property is an important method for group scheduling + applications to match requests with later replies, modifications or + deletion requests. Calendaring and scheduling applications MUST + generate this property in "VEVENT", "VTODO" and "VJOURNAL" calendar + components to assure interoperability with other group scheduling + applications. This identifier is created by the calendar system that + generates an iCalendar object. + + Implementations MUST be able to receive and persist values of at + least 255 characters for this property. + + Format Definition: The property is defined by the following notation: + + uid = "UID" uidparam ":" text CRLF + + uidparam = *(";" xparam) + + Example: The following is an example of this property: + + UID:19960401T080045Z-4000F192713-0052@host1.com + +4.8.5 Recurrence Component Properties + + The following properties specify recurrence information in calendar + components. + +4.8.5.1 Exception Date/Times + + Property Name: EXDATE + + + + + +Dawson & Stenerson Standards Track [Page 112] + +RFC 2445 iCalendar November 1998 + + + Purpose: This property defines the list of date/time exceptions for a + recurring calendar component. + + Value Type: The default value type for this property is DATE-TIME. + The value type can be set to DATE. + + Property Parameters: Non-standard, value data type and time zone + identifier property parameters can be specified on this property. + + Conformance: This property can be specified in an iCalendar object + that includes a recurring calendar component. + + Description: The exception dates, if specified, are used in computing + the recurrence set. The recurrence set is the complete set of + recurrence instances for a calendar component. The recurrence set is + generated by considering the initial "DTSTART" property along with + the "RRULE", "RDATE", "EXDATE" and "EXRULE" properties contained + within the iCalendar object. The "DTSTART" property defines the first + instance in the recurrence set. Multiple instances of the "RRULE" and + "EXRULE" properties can also be specified to define more + sophisticated recurrence sets. The final recurrence set is generated + by gathering all of the start date-times generated by any of the + specified "RRULE" and "RDATE" properties, and then excluding any + start date and times which fall within the union of start date and + times generated by any specified "EXRULE" and "EXDATE" properties. + This implies that start date and times within exclusion related + properties (i.e., "EXDATE" and "EXRULE") take precedence over those + specified by inclusion properties (i.e., "RDATE" and "RRULE"). Where + duplicate instances are generated by the "RRULE" and "RDATE" + properties, only one recurrence is considered. Duplicate instances + are ignored. + + The "EXDATE" property can be used to exclude the value specified in + "DTSTART". However, in such cases the original "DTSTART" date MUST + still be maintained by the calendaring and scheduling system because + the original "DTSTART" value has inherent usage dependencies by other + properties such as the "RECURRENCE-ID". + + Format Definition: The property is defined by the following notation: + + exdate = "EXDATE" exdtparam ":" exdtval *("," exdtval) CRLF + + exdtparam = *( + + ; the following are optional, + ; but MUST NOT occur more than once + + (";" "VALUE" "=" ("DATE-TIME" / "DATE")) / + + + +Dawson & Stenerson Standards Track [Page 113] + +RFC 2445 iCalendar November 1998 + + + (";" tzidparam) / + + ; the following is optional, + ; and MAY occur more than once + + (";" xparam) + + ) + + exdtval = date-time / date + ;Value MUST match value type + + Example: The following is an example of this property: + + EXDATE:19960402T010000Z,19960403T010000Z,19960404T010000Z + +4.8.5.2 Exception Rule + + Property Name: EXRULE + + Purpose: This property defines a rule or repeating pattern for an + exception to a recurrence set. + + Value Type: RECUR + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: This property can be specified in "VEVENT", "VTODO" or + "VJOURNAL" calendar components. + + Description: The exception rule, if specified, is used in computing + the recurrence set. The recurrence set is the complete set of + recurrence instances for a calendar component. The recurrence set is + generated by considering the initial "DTSTART" property along with + the "RRULE", "RDATE", "EXDATE" and "EXRULE" properties contained + within the iCalendar object. The "DTSTART" defines the first instance + in the recurrence set. Multiple instances of the "RRULE" and "EXRULE" + properties can also be specified to define more sophisticated + recurrence sets. The final recurrence set is generated by gathering + all of the start date-times generated by any of the specified "RRULE" + and "RDATE" properties, and excluding any start date and times which + fall within the union of start date and times generated by any + specified "EXRULE" and "EXDATE" properties. This implies that start + date and times within exclusion related properties (i.e., "EXDATE" + and "EXRULE") take precedence over those specified by inclusion + + + + + +Dawson & Stenerson Standards Track [Page 114] + +RFC 2445 iCalendar November 1998 + + + properties (i.e., "RDATE" and "RRULE"). Where duplicate instances are + generated by the "RRULE" and "RDATE" properties, only one recurrence + is considered. Duplicate instances are ignored. + + The "EXRULE" property can be used to exclude the value specified in + "DTSTART". However, in such cases the original "DTSTART" date MUST + still be maintained by the calendaring and scheduling system because + the original "DTSTART" value has inherent usage dependencies by other + properties such as the "RECURRENCE-ID". + + Format Definition: The property is defined by the following notation: + + exrule = "EXRULE" exrparam ":" recur CRLF + + exrparam = *(";" xparam) + + Example: The following are examples of this property. Except every + other week, on Tuesday and Thursday for 4 occurrences: + + EXRULE:FREQ=WEEKLY;COUNT=4;INTERVAL=2;BYDAY=TU,TH + + Except daily for 10 occurrences: + + EXRULE:FREQ=DAILY;COUNT=10 + + Except yearly in June and July for 8 occurrences: + + EXRULE:FREQ=YEARLY;COUNT=8;BYMONTH=6,7 + +4.8.5.3 Recurrence Date/Times + + Property Name: RDATE + + Purpose: This property defines the list of date/times for a + recurrence set. + + Value Type: The default value type for this property is DATE-TIME. + The value type can be set to DATE or PERIOD. + + Property Parameters: Non-standard, value data type and time zone + identifier property parameters can be specified on this property. + + Conformance: The property can be specified in "VEVENT", "VTODO", + "VJOURNAL" or "VTIMEZONE" calendar components. + + + + + + + +Dawson & Stenerson Standards Track [Page 115] + +RFC 2445 iCalendar November 1998 + + + Description: This property can appear along with the "RRULE" property + to define an aggregate set of repeating occurrences. When they both + appear in an iCalendar object, the recurring events are defined by + the union of occurrences defined by both the "RDATE" and "RRULE". + + The recurrence dates, if specified, are used in computing the + recurrence set. The recurrence set is the complete set of recurrence + instances for a calendar component. The recurrence set is generated + by considering the initial "DTSTART" property along with the "RRULE", + "RDATE", "EXDATE" and "EXRULE" properties contained within the + iCalendar object. The "DTSTART" property defines the first instance + in the recurrence set. Multiple instances of the "RRULE" and "EXRULE" + properties can also be specified to define more sophisticated + recurrence sets. The final recurrence set is generated by gathering + all of the start date/times generated by any of the specified "RRULE" + and "RDATE" properties, and excluding any start date/times which fall + within the union of start date/times generated by any specified + "EXRULE" and "EXDATE" properties. This implies that start date/times + within exclusion related properties (i.e., "EXDATE" and "EXRULE") + take precedence over those specified by inclusion properties (i.e., + "RDATE" and "RRULE"). Where duplicate instances are generated by the + "RRULE" and "RDATE" properties, only one recurrence is considered. + Duplicate instances are ignored. + + Format Definition: The property is defined by the following notation: + + rdate = "RDATE" rdtparam ":" rdtval *("," rdtval) CRLF + + rdtparam = *( + + ; the following are optional, + ; but MUST NOT occur more than once + + (";" "VALUE" "=" ("DATE-TIME" / "DATE" / "PERIOD")) / + (";" tzidparam) / + + ; the following is optional, + ; and MAY occur more than once + + (";" xparam) + + ) + + rdtval = date-time / date / period + ;Value MUST match value type + + Example: The following are examples of this property: + + + + +Dawson & Stenerson Standards Track [Page 116] + +RFC 2445 iCalendar November 1998 + + + RDATE:19970714T123000Z + + RDATE;TZID=US-EASTERN:19970714T083000 + + RDATE;VALUE=PERIOD:19960403T020000Z/19960403T040000Z, + 19960404T010000Z/PT3H + + RDATE;VALUE=DATE:19970101,19970120,19970217,19970421 + 19970526,19970704,19970901,19971014,19971128,19971129,19971225 + +4.8.5.4 Recurrence Rule + + Property Name: RRULE + + Purpose: This property defines a rule or repeating pattern for + recurring events, to-dos, or time zone definitions. + + Value Type: RECUR + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: This property can be specified one or more times in + recurring "VEVENT", "VTODO" and "VJOURNAL" calendar components. It + can also be specified once in each STANDARD or DAYLIGHT sub-component + of the "VTIMEZONE" calendar component. + + Description: The recurrence rule, if specified, is used in computing + the recurrence set. The recurrence set is the complete set of + recurrence instances for a calendar component. The recurrence set is + generated by considering the initial "DTSTART" property along with + the "RRULE", "RDATE", "EXDATE" and "EXRULE" properties contained + within the iCalendar object. The "DTSTART" property defines the first + instance in the recurrence set. Multiple instances of the "RRULE" and + "EXRULE" properties can also be specified to define more + sophisticated recurrence sets. The final recurrence set is generated + by gathering all of the start date/times generated by any of the + specified "RRULE" and "RDATE" properties, and excluding any start + date/times which fall within the union of start date/times generated + by any specified "EXRULE" and "EXDATE" properties. This implies that + start date/times within exclusion related properties (i.e., "EXDATE" + and "EXRULE") take precedence over those specified by inclusion + properties (i.e., "RDATE" and "RRULE"). Where duplicate instances are + generated by the "RRULE" and "RDATE" properties, only one recurrence + is considered. Duplicate instances are ignored. + + + + + + +Dawson & Stenerson Standards Track [Page 117] + +RFC 2445 iCalendar November 1998 + + + The "DTSTART" and "DTEND" property pair or "DTSTART" and "DURATION" + property pair, specified within the iCalendar object defines the + first instance of the recurrence. When used with a recurrence rule, + the "DTSTART" and "DTEND" properties MUST be specified in local time + and the appropriate set of "VTIMEZONE" calendar components MUST be + included. For detail on the usage of the "VTIMEZONE" calendar + component, see the "VTIMEZONE" calendar component definition. + + Any duration associated with the iCalendar object applies to all + members of the generated recurrence set. Any modified duration for + specific recurrences MUST be explicitly specified using the "RDATE" + property. + + Format Definition: This property is defined by the following + notation: + + rrule = "RRULE" rrulparam ":" recur CRLF + + rrulparam = *(";" xparam) + + Example: All examples assume the Eastern United States time zone. + + Daily for 10 occurrences: + + DTSTART;TZID=US-Eastern:19970902T090000 + RRULE:FREQ=DAILY;COUNT=10 + + ==> (1997 9:00 AM EDT)September 2-11 + + Daily until December 24, 1997: + + DTSTART;TZID=US-Eastern:19970902T090000 + RRULE:FREQ=DAILY;UNTIL=19971224T000000Z + + ==> (1997 9:00 AM EDT)September 2-30;October 1-25 + (1997 9:00 AM EST)October 26-31;November 1-30;December 1-23 + + Every other day - forever: + + DTSTART;TZID=US-Eastern:19970902T090000 + RRULE:FREQ=DAILY;INTERVAL=2 + ==> (1997 9:00 AM EDT)September2,4,6,8...24,26,28,30; + October 2,4,6...20,22,24 + (1997 9:00 AM EST)October 26,28,30;November 1,3,5,7...25,27,29; + Dec 1,3,... + + Every 10 days, 5 occurrences: + + + + +Dawson & Stenerson Standards Track [Page 118] + +RFC 2445 iCalendar November 1998 + + + DTSTART;TZID=US-Eastern:19970902T090000 + RRULE:FREQ=DAILY;INTERVAL=10;COUNT=5 + + ==> (1997 9:00 AM EDT)September 2,12,22;October 2,12 + + Everyday in January, for 3 years: + + DTSTART;TZID=US-Eastern:19980101T090000 + RRULE:FREQ=YEARLY;UNTIL=20000131T090000Z; + BYMONTH=1;BYDAY=SU,MO,TU,WE,TH,FR,SA + or + RRULE:FREQ=DAILY;UNTIL=20000131T090000Z;BYMONTH=1 + + ==> (1998 9:00 AM EDT)January 1-31 + (1999 9:00 AM EDT)January 1-31 + (2000 9:00 AM EDT)January 1-31 + + Weekly for 10 occurrences + + DTSTART;TZID=US-Eastern:19970902T090000 + RRULE:FREQ=WEEKLY;COUNT=10 + + ==> (1997 9:00 AM EDT)September 2,9,16,23,30;October 7,14,21 + (1997 9:00 AM EST)October 28;November 4 + + Weekly until December 24, 1997 + + DTSTART;TZID=US-Eastern:19970902T090000 + RRULE:FREQ=WEEKLY;UNTIL=19971224T000000Z + + ==> (1997 9:00 AM EDT)September 2,9,16,23,30;October 7,14,21 + (1997 9:00 AM EST)October 28;November 4,11,18,25; + December 2,9,16,23 + Every other week - forever: + + DTSTART;TZID=US-Eastern:19970902T090000 + RRULE:FREQ=WEEKLY;INTERVAL=2;WKST=SU + + ==> (1997 9:00 AM EDT)September 2,16,30;October 14 + (1997 9:00 AM EST)October 28;November 11,25;December 9,23 + (1998 9:00 AM EST)January 6,20;February + ... + + Weekly on Tuesday and Thursday for 5 weeks: + + DTSTART;TZID=US-Eastern:19970902T090000 + RRULE:FREQ=WEEKLY;UNTIL=19971007T000000Z;WKST=SU;BYDAY=TU,TH + or + + + +Dawson & Stenerson Standards Track [Page 119] + +RFC 2445 iCalendar November 1998 + + + RRULE:FREQ=WEEKLY;COUNT=10;WKST=SU;BYDAY=TU,TH + + ==> (1997 9:00 AM EDT)September 2,4,9,11,16,18,23,25,30;October 2 + + Every other week on Monday, Wednesday and Friday until December 24, + 1997, but starting on Tuesday, September 2, 1997: + + DTSTART;TZID=US-Eastern:19970902T090000 + RRULE:FREQ=WEEKLY;INTERVAL=2;UNTIL=19971224T000000Z;WKST=SU; + BYDAY=MO,WE,FR + ==> (1997 9:00 AM EDT)September 2,3,5,15,17,19,29;October + 1,3,13,15,17 + (1997 9:00 AM EST)October 27,29,31;November 10,12,14,24,26,28; + December 8,10,12,22 + + Every other week on Tuesday and Thursday, for 8 occurrences: + + DTSTART;TZID=US-Eastern:19970902T090000 + RRULE:FREQ=WEEKLY;INTERVAL=2;COUNT=8;WKST=SU;BYDAY=TU,TH + + ==> (1997 9:00 AM EDT)September 2,4,16,18,30;October 2,14,16 + + Monthly on the 1st Friday for ten occurrences: + + DTSTART;TZID=US-Eastern:19970905T090000 + RRULE:FREQ=MONTHLY;COUNT=10;BYDAY=1FR + + ==> (1997 9:00 AM EDT)September 5;October 3 + (1997 9:00 AM EST)November 7;Dec 5 + (1998 9:00 AM EST)January 2;February 6;March 6;April 3 + (1998 9:00 AM EDT)May 1;June 5 + + Monthly on the 1st Friday until December 24, 1997: + + DTSTART;TZID=US-Eastern:19970905T090000 + RRULE:FREQ=MONTHLY;UNTIL=19971224T000000Z;BYDAY=1FR + + ==> (1997 9:00 AM EDT)September 5;October 3 + (1997 9:00 AM EST)November 7;December 5 + + Every other month on the 1st and last Sunday of the month for 10 + occurrences: + + DTSTART;TZID=US-Eastern:19970907T090000 + RRULE:FREQ=MONTHLY;INTERVAL=2;COUNT=10;BYDAY=1SU,-1SU + + ==> (1997 9:00 AM EDT)September 7,28 + (1997 9:00 AM EST)November 2,30 + + + +Dawson & Stenerson Standards Track [Page 120] + +RFC 2445 iCalendar November 1998 + + + (1998 9:00 AM EST)January 4,25;March 1,29 + (1998 9:00 AM EDT)May 3,31 + + Monthly on the second to last Monday of the month for 6 months: + + DTSTART;TZID=US-Eastern:19970922T090000 + RRULE:FREQ=MONTHLY;COUNT=6;BYDAY=-2MO + + ==> (1997 9:00 AM EDT)September 22;October 20 + (1997 9:00 AM EST)November 17;December 22 + (1998 9:00 AM EST)January 19;February 16 + + Monthly on the third to the last day of the month, forever: + + DTSTART;TZID=US-Eastern:19970928T090000 + RRULE:FREQ=MONTHLY;BYMONTHDAY=-3 + + ==> (1997 9:00 AM EDT)September 28 + (1997 9:00 AM EST)October 29;November 28;December 29 + (1998 9:00 AM EST)January 29;February 26 + ... + + Monthly on the 2nd and 15th of the month for 10 occurrences: + + DTSTART;TZID=US-Eastern:19970902T090000 + RRULE:FREQ=MONTHLY;COUNT=10;BYMONTHDAY=2,15 + + ==> (1997 9:00 AM EDT)September 2,15;October 2,15 + (1997 9:00 AM EST)November 2,15;December 2,15 + (1998 9:00 AM EST)January 2,15 + + Monthly on the first and last day of the month for 10 occurrences: + + DTSTART;TZID=US-Eastern:19970930T090000 + RRULE:FREQ=MONTHLY;COUNT=10;BYMONTHDAY=1,-1 + + ==> (1997 9:00 AM EDT)September 30;October 1 + (1997 9:00 AM EST)October 31;November 1,30;December 1,31 + (1998 9:00 AM EST)January 1,31;February 1 + + Every 18 months on the 10th thru 15th of the month for 10 + occurrences: + + DTSTART;TZID=US-Eastern:19970910T090000 + RRULE:FREQ=MONTHLY;INTERVAL=18;COUNT=10;BYMONTHDAY=10,11,12,13,14, + 15 + + ==> (1997 9:00 AM EDT)September 10,11,12,13,14,15 + + + +Dawson & Stenerson Standards Track [Page 121] + +RFC 2445 iCalendar November 1998 + + + (1999 9:00 AM EST)March 10,11,12,13 + + Every Tuesday, every other month: + + DTSTART;TZID=US-Eastern:19970902T090000 + RRULE:FREQ=MONTHLY;INTERVAL=2;BYDAY=TU + + ==> (1997 9:00 AM EDT)September 2,9,16,23,30 + (1997 9:00 AM EST)November 4,11,18,25 + (1998 9:00 AM EST)January 6,13,20,27;March 3,10,17,24,31 + ... + + Yearly in June and July for 10 occurrences: + + DTSTART;TZID=US-Eastern:19970610T090000 + RRULE:FREQ=YEARLY;COUNT=10;BYMONTH=6,7 + ==> (1997 9:00 AM EDT)June 10;July 10 + (1998 9:00 AM EDT)June 10;July 10 + (1999 9:00 AM EDT)June 10;July 10 + (2000 9:00 AM EDT)June 10;July 10 + (2001 9:00 AM EDT)June 10;July 10 + Note: Since none of the BYDAY, BYMONTHDAY or BYYEARDAY components + are specified, the day is gotten from DTSTART + + Every other year on January, February, and March for 10 occurrences: + + DTSTART;TZID=US-Eastern:19970310T090000 + RRULE:FREQ=YEARLY;INTERVAL=2;COUNT=10;BYMONTH=1,2,3 + + ==> (1997 9:00 AM EST)March 10 + (1999 9:00 AM EST)January 10;February 10;March 10 + (2001 9:00 AM EST)January 10;February 10;March 10 + (2003 9:00 AM EST)January 10;February 10;March 10 + + Every 3rd year on the 1st, 100th and 200th day for 10 occurrences: + + DTSTART;TZID=US-Eastern:19970101T090000 + RRULE:FREQ=YEARLY;INTERVAL=3;COUNT=10;BYYEARDAY=1,100,200 + + ==> (1997 9:00 AM EST)January 1 + (1997 9:00 AM EDT)April 10;July 19 + (2000 9:00 AM EST)January 1 + (2000 9:00 AM EDT)April 9;July 18 + (2003 9:00 AM EST)January 1 + (2003 9:00 AM EDT)April 10;July 19 + (2006 9:00 AM EST)January 1 + + Every 20th Monday of the year, forever: + + + +Dawson & Stenerson Standards Track [Page 122] + +RFC 2445 iCalendar November 1998 + + + DTSTART;TZID=US-Eastern:19970519T090000 + RRULE:FREQ=YEARLY;BYDAY=20MO + + ==> (1997 9:00 AM EDT)May 19 + (1998 9:00 AM EDT)May 18 + (1999 9:00 AM EDT)May 17 + ... + + Monday of week number 20 (where the default start of the week is + Monday), forever: + + DTSTART;TZID=US-Eastern:19970512T090000 + RRULE:FREQ=YEARLY;BYWEEKNO=20;BYDAY=MO + + ==> (1997 9:00 AM EDT)May 12 + (1998 9:00 AM EDT)May 11 + (1999 9:00 AM EDT)May 17 + ... + + Every Thursday in March, forever: + + DTSTART;TZID=US-Eastern:19970313T090000 + RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=TH + + ==> (1997 9:00 AM EST)March 13,20,27 + (1998 9:00 AM EST)March 5,12,19,26 + (1999 9:00 AM EST)March 4,11,18,25 + ... + + Every Thursday, but only during June, July, and August, forever: + + DTSTART;TZID=US-Eastern:19970605T090000 + RRULE:FREQ=YEARLY;BYDAY=TH;BYMONTH=6,7,8 + + ==> (1997 9:00 AM EDT)June 5,12,19,26;July 3,10,17,24,31; + August 7,14,21,28 + (1998 9:00 AM EDT)June 4,11,18,25;July 2,9,16,23,30; + August 6,13,20,27 + (1999 9:00 AM EDT)June 3,10,17,24;July 1,8,15,22,29; + August 5,12,19,26 + ... + + Every Friday the 13th, forever: + + DTSTART;TZID=US-Eastern:19970902T090000 + EXDATE;TZID=US-Eastern:19970902T090000 + RRULE:FREQ=MONTHLY;BYDAY=FR;BYMONTHDAY=13 + + + + +Dawson & Stenerson Standards Track [Page 123] + +RFC 2445 iCalendar November 1998 + + + ==> (1998 9:00 AM EST)February 13;March 13;November 13 + (1999 9:00 AM EDT)August 13 + (2000 9:00 AM EDT)October 13 + ... + + The first Saturday that follows the first Sunday of the month, + forever: + + DTSTART;TZID=US-Eastern:19970913T090000 + RRULE:FREQ=MONTHLY;BYDAY=SA;BYMONTHDAY=7,8,9,10,11,12,13 + + ==> (1997 9:00 AM EDT)September 13;October 11 + (1997 9:00 AM EST)November 8;December 13 + (1998 9:00 AM EST)January 10;February 7;March 7 + (1998 9:00 AM EDT)April 11;May 9;June 13... + ... + + Every four years, the first Tuesday after a Monday in November, + forever (U.S. Presidential Election day): + + DTSTART;TZID=US-Eastern:19961105T090000 + RRULE:FREQ=YEARLY;INTERVAL=4;BYMONTH=11;BYDAY=TU;BYMONTHDAY=2,3,4, + 5,6,7,8 + + ==> (1996 9:00 AM EST)November 5 + (2000 9:00 AM EST)November 7 + (2004 9:00 AM EST)November 2 + ... + + The 3rd instance into the month of one of Tuesday, Wednesday or + Thursday, for the next 3 months: + + DTSTART;TZID=US-Eastern:19970904T090000 + RRULE:FREQ=MONTHLY;COUNT=3;BYDAY=TU,WE,TH;BYSETPOS=3 + + ==> (1997 9:00 AM EDT)September 4;October 7 + (1997 9:00 AM EST)November 6 + + The 2nd to last weekday of the month: + + DTSTART;TZID=US-Eastern:19970929T090000 + RRULE:FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-2 + + ==> (1997 9:00 AM EDT)September 29 + (1997 9:00 AM EST)October 30;November 27;December 30 + (1998 9:00 AM EST)January 29;February 26;March 30 + ... + + + + +Dawson & Stenerson Standards Track [Page 124] + +RFC 2445 iCalendar November 1998 + + + Every 3 hours from 9:00 AM to 5:00 PM on a specific day: + + DTSTART;TZID=US-Eastern:19970902T090000 + RRULE:FREQ=HOURLY;INTERVAL=3;UNTIL=19970902T170000Z + + ==> (September 2, 1997 EDT)09:00,12:00,15:00 + + Every 15 minutes for 6 occurrences: + + DTSTART;TZID=US-Eastern:19970902T090000 + RRULE:FREQ=MINUTELY;INTERVAL=15;COUNT=6 + + ==> (September 2, 1997 EDT)09:00,09:15,09:30,09:45,10:00,10:15 + + Every hour and a half for 4 occurrences: + + DTSTART;TZID=US-Eastern:19970902T090000 + RRULE:FREQ=MINUTELY;INTERVAL=90;COUNT=4 + + ==> (September 2, 1997 EDT)09:00,10:30;12:00;13:30 + + Every 20 minutes from 9:00 AM to 4:40 PM every day: + + DTSTART;TZID=US-Eastern:19970902T090000 + RRULE:FREQ=DAILY;BYHOUR=9,10,11,12,13,14,15,16;BYMINUTE=0,20,40 + or + RRULE:FREQ=MINUTELY;INTERVAL=20;BYHOUR=9,10,11,12,13,14,15,16 + + ==> (September 2, 1997 EDT)9:00,9:20,9:40,10:00,10:20, + ... 16:00,16:20,16:40 + (September 3, 1997 EDT)9:00,9:20,9:40,10:00,10:20, + ...16:00,16:20,16:40 + ... + + An example where the days generated makes a difference because of + WKST: + + DTSTART;TZID=US-Eastern:19970805T090000 + RRULE:FREQ=WEEKLY;INTERVAL=2;COUNT=4;BYDAY=TU,SU;WKST=MO + + ==> (1997 EDT)Aug 5,10,19,24 + + changing only WKST from MO to SU, yields different results... + + DTSTART;TZID=US-Eastern:19970805T090000 + RRULE:FREQ=WEEKLY;INTERVAL=2;COUNT=4;BYDAY=TU,SU;WKST=SU + ==> (1997 EDT)August 5,17,19,31 + + + + +Dawson & Stenerson Standards Track [Page 125] + +RFC 2445 iCalendar November 1998 + + +4.8.6 Alarm Component Properties + + The following properties specify alarm information in calendar + components. + +4.8.6.1 Action + + Property Name: ACTION + + Purpose: This property defines the action to be invoked when an alarm + is triggered. + + Value Type: TEXT + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: This property MUST be specified once in a "VALARM" + calendar component. + + Description: Each "VALARM" calendar component has a particular type + of action associated with it. This property specifies the type of + action + + Format Definition: The property is defined by the following notation: + + action = "ACTION" actionparam ":" actionvalue CRLF + + actionparam = *(";" xparam) + + actionvalue = "AUDIO" / "DISPLAY" / "EMAIL" / "PROCEDURE" + / iana-token / x-name + + Example: The following are examples of this property in a "VALARM" + calendar component: + + ACTION:AUDIO + + ACTION:DISPLAY + + ACTION:PROCEDURE + +4.8.6.2 Repeat Count + + Property Name: REPEAT + + Purpose: This property defines the number of time the alarm should be + repeated, after the initial trigger. + + + +Dawson & Stenerson Standards Track [Page 126] + +RFC 2445 iCalendar November 1998 + + + Value Type: INTEGER + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: This property can be specified in a "VALARM" calendar + component. + + Description: If the alarm triggers more than once, then this property + MUST be specified along with the "DURATION" property. + + Format Definition: The property is defined by the following notation: + + repeatcnt = "REPEAT" repparam ":" integer CRLF + ;Default is "0", zero. + + repparam = *(";" xparam) + + Example: The following is an example of this property for an alarm + that repeats 4 additional times with a 5 minute delay after the + initial triggering of the alarm: + + REPEAT:4 + DURATION:PT5M + +4.8.6.3 Trigger + + Property Name: TRIGGER + + Purpose: This property specifies when an alarm will trigger. + + Value Type: The default value type is DURATION. The value type can be + set to a DATE-TIME value type, in which case the value MUST specify a + UTC formatted DATE-TIME value. + + Property Parameters: Non-standard, value data type, time zone + identifier or trigger relationship property parameters can be + specified on this property. The trigger relationship property + parameter MUST only be specified when the value type is DURATION. + + Conformance: This property MUST be specified in the "VALARM" calendar + component. + + Description: Within the "VALARM" calendar component, this property + defines when the alarm will trigger. The default value type is + DURATION, specifying a relative time for the trigger of the alarm. + The default duration is relative to the start of an event or to-do + that the alarm is associated with. The duration can be explicitly set + + + +Dawson & Stenerson Standards Track [Page 127] + +RFC 2445 iCalendar November 1998 + + + to trigger from either the end or the start of the associated event + or to-do with the "RELATED" parameter. A value of START will set the + alarm to trigger off the start of the associated event or to-do. A + value of END will set the alarm to trigger off the end of the + associated event or to-do. + + Either a positive or negative duration may be specified for the + "TRIGGER" property. An alarm with a positive duration is triggered + after the associated start or end of the event or to-do. An alarm + with a negative duration is triggered before the associated start or + end of the event or to-do. + + The "RELATED" property parameter is not valid if the value type of + the property is set to DATE-TIME (i.e., for an absolute date and time + alarm trigger). If a value type of DATE-TIME is specified, then the + property value MUST be specified in the UTC time format. If an + absolute trigger is specified on an alarm for a recurring event or + to-do, then the alarm will only trigger for the specified absolute + date/time, along with any specified repeating instances. + + If the trigger is set relative to START, then the "DTSTART" property + MUST be present in the associated "VEVENT" or "VTODO" calendar + component. If an alarm is specified for an event with the trigger set + relative to the END, then the "DTEND" property or the "DSTART" and + "DURATION' properties MUST be present in the associated "VEVENT" + calendar component. If the alarm is specified for a to-do with a + trigger set relative to the END, then either the "DUE" property or + the "DSTART" and "DURATION' properties MUST be present in the + associated "VTODO" calendar component. + + Alarms specified in an event or to-do which is defined in terms of a + DATE value type will be triggered relative to 00:00:00 UTC on the + specified date. For example, if "DTSTART:19980205, then the duration + trigger will be relative to19980205T000000Z. + + Format Definition: The property is defined by the following notation: + + trigger = "TRIGGER" (trigrel / trigabs) + + trigrel = *( + + ; the following are optional, + ; but MUST NOT occur more than once + + (";" "VALUE" "=" "DURATION") / + (";" trigrelparam) / + + ; the following is optional, + + + +Dawson & Stenerson Standards Track [Page 128] + +RFC 2445 iCalendar November 1998 + + + ; and MAY occur more than once + + (";" xparam) + ) ":" dur-value + + trigabs = 1*( + + ; the following is REQUIRED, + ; but MUST NOT occur more than once + + (";" "VALUE" "=" "DATE-TIME") / + + ; the following is optional, + ; and MAY occur more than once + + (";" xparam) + + ) ":" date-time + + Example: A trigger set 15 minutes prior to the start of the event or + to-do. + + TRIGGER:-P15M + + A trigger set 5 minutes after the end of the event or to-do. + + TRIGGER;RELATED=END:P5M + + A trigger set to an absolute date/time. + + TRIGGER;VALUE=DATE-TIME:19980101T050000Z + +4.8.7 Change Management Component Properties + + The following properties specify change management information in + calendar components. + +4.8.7.1 Date/Time Created + + Property Name: CREATED + + Purpose: This property specifies the date and time that the calendar + information was created by the calendar user agent in the calendar + store. + + Note: This is analogous to the creation date and time for a file + in the file system. + + + + +Dawson & Stenerson Standards Track [Page 129] + +RFC 2445 iCalendar November 1998 + + + Value Type: DATE-TIME + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: The property can be specified once in "VEVENT", "VTODO" + or "VJOURNAL" calendar components. + + Description: The date and time is a UTC value. + + Format Definition: The property is defined by the following notation: + + created = "CREATED" creaparam ":" date-time CRLF + + creaparam = *(";" xparam) + + Example: The following is an example of this property: + + CREATED:19960329T133000Z + +4.8.7.2 Date/Time Stamp + + Property Name: DTSTAMP + + Purpose: The property indicates the date/time that the instance of + the iCalendar object was created. + + Value Type: DATE-TIME + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: This property MUST be included in the "VEVENT", "VTODO", + "VJOURNAL" or "VFREEBUSY" calendar components. + + Description: The value MUST be specified in the UTC time format. + + This property is also useful to protocols such as [IMIP] that have + inherent latency issues with the delivery of content. This property + will assist in the proper sequencing of messages containing iCalendar + objects. + + This property is different than the "CREATED" and "LAST-MODIFIED" + properties. These two properties are used to specify when the + particular calendar data in the calendar store was created and last + modified. This is different than when the iCalendar object + representation of the calendar service information was created or + last modified. + + + +Dawson & Stenerson Standards Track [Page 130] + +RFC 2445 iCalendar November 1998 + + + Format Definition: The property is defined by the following notation: + + dtstamp = "DTSTAMP" stmparam ":" date-time CRLF + + stmparam = *(";" xparam) + + Example: + + DTSTAMP:19971210T080000Z + +4.8.7.3 Last Modified + + Property Name: LAST-MODIFIED + + Purpose: The property specifies the date and time that the + information associated with the calendar component was last revised + in the calendar store. + + Note: This is analogous to the modification date and time for a + file in the file system. + + Value Type: DATE-TIME + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: This property can be specified in the "EVENT", "VTODO", + "VJOURNAL" or "VTIMEZONE" calendar components. + + Description: The property value MUST be specified in the UTC time + format. + + Format Definition: The property is defined by the following notation: + + last-mod = "LAST-MODIFIED" lstparam ":" date-time CRLF + + lstparam = *(";" xparam) + + Example: The following is are examples of this property: + + LAST-MODIFIED:19960817T133000Z + +4.8.7.4 Sequence Number + + Property Name: SEQUENCE + + Purpose: This property defines the revision sequence number of the + calendar component within a sequence of revisions. + + + +Dawson & Stenerson Standards Track [Page 131] + +RFC 2445 iCalendar November 1998 + + + Value Type: integer + + Property Parameters: Non-standard property parameters can be + specified on this property. + + Conformance: The property can be specified in "VEVENT", "VTODO" or + "VJOURNAL" calendar component. + + Description: When a calendar component is created, its sequence + number is zero (US-ASCII decimal 48). It is monotonically incremented + by the "Organizer's" CUA each time the "Organizer" makes a + significant revision to the calendar component. When the "Organizer" + makes changes to one of the following properties, the sequence number + MUST be incremented: + + . "DTSTART" + + . "DTEND" + + . "DUE" + + . "RDATE" + + . "RRULE" + + . "EXDATE" + + . "EXRULE" + + . "STATUS" + + In addition, changes made by the "Organizer" to other properties can + also force the sequence number to be incremented. The "Organizer" CUA + MUST increment the sequence number when ever it makes changes to + properties in the calendar component that the "Organizer" deems will + jeopardize the validity of the participation status of the + "Attendees". For example, changing the location of a meeting from one + locale to another distant locale could effectively impact the + participation status of the "Attendees". + + The "Organizer" includes this property in an iCalendar object that it + sends to an "Attendee" to specify the current version of the calendar + component. + + The "Attendee" includes this property in an iCalendar object that it + sends to the "Organizer" to specify the version of the calendar + component that the "Attendee" is referring to. + + + + +Dawson & Stenerson Standards Track [Page 132] + +RFC 2445 iCalendar November 1998 + + + A change to the sequence number is not the mechanism that an + "Organizer" uses to request a response from the "Attendees". The + "RSVP" parameter on the "ATTENDEE" property is used by the + "Organizer" to indicate that a response from the "Attendees" is + requested. + + Format Definition: This property is defined by the following + notation: + + seq = "SEQUENCE" seqparam ":" integer CRLF + ; Default is "0" + + seqparam = *(";" xparam) + + Example: The following is an example of this property for a calendar + component that was just created by the "Organizer". + + SEQUENCE:0 + + The following is an example of this property for a calendar component + that has been revised two different times by the "Organizer". + + SEQUENCE:2 + +4.8.8 Miscellaneous Component Properties + + The following properties specify information about a number of + miscellaneous features of calendar components. + +4.8.8.1 Non-standard Properties + + Property Name: Any property name with a "X-" prefix + + Purpose: This class of property provides a framework for defining + non-standard properties. + + Value Type: TEXT + + Property Parameters: Non-standard and language property parameters + can be specified on this property. + + Conformance: This property can be specified in any calendar + component. + + Description: The MIME Calendaring and Scheduling Content Type + provides a "standard mechanism for doing non-standard things". This + extension support is provided for implementers to "push the envelope" + on the existing version of the memo. Extension properties are + + + +Dawson & Stenerson Standards Track [Page 133] + +RFC 2445 iCalendar November 1998 + + + specified by property and/or property parameter names that have the + prefix text of "X-" (the two character sequence: LATIN CAPITAL LETTER + X character followed by the HYPEN-MINUS character). It is recommended + that vendors concatenate onto this sentinel another short prefix text + to identify the vendor. This will facilitate readability of the + extensions and minimize possible collision of names between different + vendors. User agents that support this content type are expected to + be able to parse the extension properties and property parameters but + can ignore them. + + At present, there is no registration authority for names of extension + properties and property parameters. The data type for this property + is TEXT. Optionally, the data type can be any of the other valid data + types. + + Format Definition: The property is defined by the following notation: + + x-prop = x-name *(";" xparam) [";" languageparam] ":" text CRLF + ; Lines longer than 75 octets should be folded + + Example: The following might be the ABC vendor's extension for an + audio-clip form of subject property: + + X-ABC-MMSUBJ;X-ABC-MMSUBJTYPE=wave:http://load.noise.org/mysubj.wav + +4.8.8.2 Request Status + + Property Name: REQUEST-STATUS + + Purpose: This property defines the status code returned for a + scheduling request. + + Value Type: TEXT + + Property Parameters: Non-standard and language property parameters + can be specified on this property. + + Conformance: The property can be specified in "VEVENT", "VTODO", + "VJOURNAL" or "VFREEBUSY" calendar component. + + Description: This property is used to return status code information + related to the processing of an associated iCalendar object. The data + type for this property is TEXT. + + The value consists of a short return status component, a longer + return status description component, and optionally a status-specific + data component. The components of the value are separated by the + SEMICOLON character (US-ASCII decimal 59). + + + +Dawson & Stenerson Standards Track [Page 134] + +RFC 2445 iCalendar November 1998 + + + The short return status is a PERIOD character (US-ASCII decimal 46) + separated 3-tuple of integers. For example, "3.1.1". The successive + levels of integers provide for a successive level of status code + granularity. + + The following are initial classes for the return status code. + Individual iCalendar object methods will define specific return + status codes for these classes. In addition, other classes for the + return status code may be defined using the registration process + defined later in this memo. + + |==============+===============================================| + | Short Return | Longer Return Status Description | + | Status Code | | + |==============+===============================================| + | 1.xx | Preliminary success. This class of status | + | | of status code indicates that the request has | + | | request has been initially processed but that | + | | completion is pending. | + |==============+===============================================| + | 2.xx | Successful. This class of status code | + | | indicates that the request was completed | + | | successfuly. However, the exact status code | + | | can indicate that a fallback has been taken. | + |==============+===============================================| + | 3.xx | Client Error. This class of status code | + | | indicates that the request was not successful.| + | | The error is the result of either a syntax or | + | | a semantic error in the client formatted | + | | request. Request should not be retried until | + | | the condition in the request is corrected. | + |==============+===============================================| + | 4.xx | Scheduling Error. This class of status code | + | | indicates that the request was not successful.| + | | Some sort of error occurred within the | + | | calendaring and scheduling service, not | + | | directly related to the request itself. | + |==============+===============================================| + + Format Definition: The property is defined by the following notation: + + rstatus = "REQUEST-STATUS" rstatparam ":" + statcode ";" statdesc [";" extdata] + + rstatparam = *( + + ; the following is optional, + ; but MUST NOT occur more than once + + + +Dawson & Stenerson Standards Track [Page 135] + +RFC 2445 iCalendar November 1998 + + + (";" languageparm) / + + ; the following is optional, + ; and MAY occur more than once + + (";" xparam) + + ) + + statcode = 1*DIGIT *("." 1*DIGIT) + ;Hierarchical, numeric return status code + + statdesc = text + ;Textual status description + + extdata = text + ;Textual exception data. For example, the offending property + ;name and value or complete property line. + + Example: The following are some possible examples of this property. + The COMMA and SEMICOLON separator characters in the property value + are BACKSLASH character escaped because they appear in a text value. + + REQUEST-STATUS:2.0;Success + + REQUEST-STATUS:3.1;Invalid property value;DTSTART:96-Apr-01 + + REQUEST-STATUS:2.8; Success\, repeating event ignored. Scheduled + as a single event.;RRULE:FREQ=WEEKLY\;INTERVAL=2 + + REQUEST-STATUS:4.1;Event conflict. Date/time is busy. + + REQUEST-STATUS:3.7;Invalid calendar user;ATTENDEE: + MAILTO:jsmith@host.com + +5 iCalendar Object Examples + + The following examples are provided as an informational source of + illustrative iCalendar objects consistent with this content type. + + The following example specifies a three-day conference that begins at + 8:00 AM EDT, September 18, 1996 and end at 6:00 PM EDT, September 20, + 1996. + + BEGIN:VCALENDAR PRODID:-//xyz Corp//NONSGML PDA Calendar Verson + 1.0//EN VERSION:2.0 BEGIN:VEVENT DTSTAMP:19960704T120000Z + UID:uid1@host.com ORGANIZER:MAILTO:jsmith@host.com + DTSTART:19960918T143000Z DTEND:19960920T220000Z STATUS:CONFIRMED + + + +Dawson & Stenerson Standards Track [Page 136] + +RFC 2445 iCalendar November 1998 + + + CATEGORIES:CONFERENCE SUMMARY:Networld+Interop Conference + DESCRIPTION:Networld+Interop Conference + and Exhibit\nAtlanta World Congress Center\n + Atlanta, Georgia END:VEVENT END:VCALENDAR + + The following example specifies a group scheduled meeting that begin + at 8:30 AM EST on March 12, 1998 and end at 9:30 AM EST on March 12, + 1998. The "Organizer" has scheduled the meeting with one or more + calendar users in a group. A time zone specification for Eastern + United States has been specified. + + BEGIN:VCALENDAR + PRODID:-//RDU Software//NONSGML HandCal//EN + VERSION:2.0 + BEGIN:VTIMEZONE + TZID:US-Eastern + BEGIN:STANDARD + DTSTART:19981025T020000 + RDATE:19981025T020000 + TZOFFSETFROM:-0400 + TZOFFSETTO:-0500 + TZNAME:EST + END:STANDARD + BEGIN:DAYLIGHT + DTSTART:19990404T020000 + RDATE:19990404T020000 + TZOFFSETFROM:-0500 + TZOFFSETTO:-0400 + TZNAME:EDT + END:DAYLIGHT + END:VTIMEZONE + BEGIN:VEVENT + DTSTAMP:19980309T231000Z + UID:guid-1.host1.com + ORGANIZER;ROLE=CHAIR:MAILTO:mrbig@host.com + ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT;CUTYPE=GROUP: + MAILTO:employee-A@host.com + DESCRIPTION:Project XYZ Review Meeting + CATEGORIES:MEETING + CLASS:PUBLIC + CREATED:19980309T130000Z + SUMMARY:XYZ Project Review + DTSTART;TZID=US-Eastern:19980312T083000 + DTEND;TZID=US-Eastern:19980312T093000 + LOCATION:1CP Conference Room 4350 + END:VEVENT + END:VCALENDAR + + + + +Dawson & Stenerson Standards Track [Page 137] + +RFC 2445 iCalendar November 1998 + + + The following is an example of an iCalendar object passed in a MIME + message with a single body part consisting of a "text/calendar" + Content Type. + + TO:jsmith@host1.com + FROM:jdoe@host1.com + MIME-VERSION:1.0 + MESSAGE-ID: + CONTENT-TYPE:text/calendar + + BEGIN:VCALENDAR + METHOD:xyz + VERSION:2.0 + PRODID:-//ABC Corporation//NONSGML My Product//EN + BEGIN:VEVENT + DTSTAMP:19970324T1200Z + SEQUENCE:0 + UID:uid3@host1.com + ORGANIZER:MAILTO:jdoe@host1.com + ATTENDEE;RSVP=TRUE:MAILTO:jsmith@host1.com + DTSTART:19970324T123000Z + DTEND:19970324T210000Z + CATEGORIES:MEETING,PROJECT + CLASS:PUBLIC + SUMMARY:Calendaring Interoperability Planning Meeting + DESCRIPTION:Discuss how we can test c&s interoperability\n + using iCalendar and other IETF standards. + LOCATION:LDB Lobby + ATTACH;FMTTYPE=application/postscript:ftp://xyzCorp.com/pub/ + conf/bkgrnd.ps + END:VEVENT + END:VCALENDAR + + The following is an example of a to-do due on April 15, 1998. An + audio alarm has been specified to remind the calendar user at noon, + the day before the to-do is expected to be completed and repeat + hourly, four additional times. The to-do definition has been modified + twice since it was initially created. + + BEGIN:VCALENDAR + VERSION:2.0 + PRODID:-//ABC Corporation//NONSGML My Product//EN + BEGIN:VTODO + DTSTAMP:19980130T134500Z + SEQUENCE:2 + UID:uid4@host1.com + ORGANIZER:MAILTO:unclesam@us.gov + ATTENDEE;PARTSTAT=ACCEPTED:MAILTO:jqpublic@host.com + + + +Dawson & Stenerson Standards Track [Page 138] + +RFC 2445 iCalendar November 1998 + + + DUE:19980415T235959 + STATUS:NEEDS-ACTION + SUMMARY:Submit Income Taxes + BEGIN:VALARM + ACTION:AUDIO + TRIGGER:19980403T120000 + ATTACH;FMTTYPE=audio/basic:http://host.com/pub/audio- + files/ssbanner.aud + REPEAT:4 + DURATION:PT1H + END:VALARM + END:VTODO + END:VCALENDAR + + The following is an example of a journal entry. + + BEGIN:VCALENDAR + VERSION:2.0 + PRODID:-//ABC Corporation//NONSGML My Product//EN + BEGIN:VJOURNAL + DTSTAMP:19970324T120000Z + UID:uid5@host1.com + ORGANIZER:MAILTO:jsmith@host.com + STATUS:DRAFT + CLASS:PUBLIC + CATEGORY:Project Report, XYZ, Weekly Meeting + DESCRIPTION:Project xyz Review Meeting Minutes\n + Agenda\n1. Review of project version 1.0 requirements.\n2. + Definition + of project processes.\n3. Review of project schedule.\n + Participants: John Smith, Jane Doe, Jim Dandy\n-It was + decided that the requirements need to be signed off by + product marketing.\n-Project processes were accepted.\n + -Project schedule needs to account for scheduled holidays + and employee vacation time. Check with HR for specific + dates.\n-New schedule will be distributed by Friday.\n- + Next weeks meeting is cancelled. No meeting until 3/23. + END:VJOURNAL + END:VCALENDAR + + The following is an example of published busy time information. The + iCalendar object might be placed in the network resource + www.host.com/calendar/busytime/jsmith.ifb. + + BEGIN:VCALENDAR + VERSION:2.0 + PRODID:-//RDU Software//NONSGML HandCal//EN + BEGIN:VFREEBUSY + + + +Dawson & Stenerson Standards Track [Page 139] + +RFC 2445 iCalendar November 1998 + + + ORGANIZER:MAILTO:jsmith@host.com + DTSTART:19980313T141711Z + DTEND:19980410T141711Z + FREEBUSY:19980314T233000Z/19980315T003000Z + FREEBUSY:19980316T153000Z/19980316T163000Z + FREEBUSY:19980318T030000Z/19980318T040000Z + URL:http://www.host.com/calendar/busytime/jsmith.ifb + END:VFREEBUSY + END:VCALENDAR + +6 Recommended Practices + + These recommended practices should be followed in order to assure + consistent handling of the following cases for an iCalendar object. + + 1. Content lines longer than 75 octets SHOULD be folded. + + 2. A calendar entry with a "DTSTART" property but no "DTEND" + property does not take up any time. It is intended to represent + an event that is associated with a given calendar date and time + of day, such as an anniversary. Since the event does not take up + any time, it MUST NOT be used to record busy time no matter what + the value for the "TRANSP" property. + + 3. When the "DTSTART" and "DTEND", for "VEVENT", "VJOURNAL" and + "VFREEBUSY" calendar components, and "DTSTART" and "DUE", for + "VTODO" calendar components, have the same value data type (e.g., + DATE-TIME), they SHOULD specify values in the same time format + (e.g., UTC time format). + + 4. When the combination of the "RRULE" and "RDATE" properties on an + iCalendar object produces multiple instances having the same + start date/time, they should be collapsed to, and considered as, + a single instance. + + 5. When a calendar user receives multiple requests for the same + calendar component (e.g., REQUEST for a "VEVENT" calendar + component) as a result of being on multiple mailing lists + specified by "ATTENDEE" properties in the request, they SHOULD + respond to only one of the requests. The calendar user SHOULD + also specify (using the "MEMBER" parameter of the "ATTENDEE" + property) which mailing list they are a member of. + + 6. An implementation can truncate a "SUMMARY" property value to 255 + characters. + + + + + + +Dawson & Stenerson Standards Track [Page 140] + +RFC 2445 iCalendar November 1998 + + + 7. If seconds of the minute are not supported by an implementation, + then a value of "00" SHOULD be specified for the seconds + component in a time value. + + 8. If the value type parameter (VALUE=) contains an unknown value + type, it SHOULD be treated as TEXT. + + 9. TZURL values SHOULD NOT be specified as a FILE URI type. This URI + form can be useful within an organization, but is problematic in + the Internet. + + 10. Some possible English values for CATEGORIES property include + "ANNIVERSARY", "APPOINTMENT", "BUSINESS", "EDUCATION", + "HOLIDAY", "MEETING", "MISCELLANEOUS", "NON-WORKING HOURS", "NOT + IN OFFICE", "PERSONAL", "PHONE CALL", "SICK DAY", "SPECIAL + OCCASION", "TRAVEL", "VACATION". Categories can be specified in + any registered language. + + 11. Some possible English values for RESOURCES property include + "CATERING", "CHAIRS", "COMPUTER PROJECTOR", "EASEL", "OVERHEAD + PROJECTOR", "SPEAKER PHONE", "TABLE", "TV", "VCR", "VIDEO + PHONE", "VEHICLE". Resources can be specified in any registered + language. + +7 Registration of Content Type Elements + + This section provides the process for registration of MIME + Calendaring and Scheduling Content Type iCalendar object methods and + new or modified properties. + +7.1 Registration of New and Modified iCalendar Object Methods + + New MIME Calendaring and Scheduling Content Type iCalendar object + methods are registered by the publication of an IETF Request for + Comments (RFC). Changes to an iCalendar object method are registered + by the publication of a revision of the RFC defining the method. + +7.2 Registration of New Properties + + This section defines procedures by which new properties or enumerated + property values for the MIME Calendaring and Scheduling Content Type + can be registered with the IANA. Non-IANA properties can be used by + bilateral agreement, provided the associated properties names follow + the "X-" convention. + + The procedures defined here are designed to allow public comment and + review of new properties, while posing only a small impediment to the + definition of new properties. + + + +Dawson & Stenerson Standards Track [Page 141] + +RFC 2445 iCalendar November 1998 + + + Registration of a new property is accomplished by the following + steps. + +7.2.1 Define the property + + A property is defined by completing the following template. + + To: ietf-calendar@imc.org + + Subject: Registration of text/calendar MIME property XXX + + Property name: + + Property purpose: + + Property value type(s): + + Property parameter (s): + + Conformance: + + Description: + + Format definition: + + Examples: + + The meaning of each field in the template is as follows. + + Property name: The name of the property, as it will appear in the + body of an text/calendar MIME Content-Type "property: value" line to + the left of the colon ":". + + Property purpose: The purpose of the property (e.g., to indicate a + delegate for the event or to-do, etc.). Give a short but clear + description. + + Property value type (s): Any of the valid value types for the + property value needs to be specified. The default value type also + needs to be specified. If a new value type is specified, it needs to + be declared in this section. + + Property parameter (s): Any of the valid property parameters for the + property needs to be specified. + + Conformance: The calendar components that the property can appear in + needs to be specified. + + + + +Dawson & Stenerson Standards Track [Page 142] + +RFC 2445 iCalendar November 1998 + + + Description: Any special notes about the property, how it is to be + used, etc. + + Format definition: The ABNF for the property definition needs to be + specified. + + Examples: One or more examples of instances of the property needs to + be specified. + +7.2.2 Post the Property definition + + The property description MUST be posted to the new property + discussion list, ietf-calendar@imc.org. + +7.2.3 Allow a comment period + + Discussion on the new property MUST be allowed to take place on the + list for a minimum of two weeks. Consensus MUST be reached on the + property before proceeding to the next step. + +7.2.4 Submit the property for approval + + Once the two-week comment period has elapsed, and the proposer is + convinced consensus has been reached on the property, the + registration application should be submitted to the Method Reviewer + for approval. The Method Reviewer is appointed to the Application + Area Directors and can either accept or reject the property + registration. An accepted registration should be passed on by the + Method Reviewer to the IANA for inclusion in the official IANA method + registry. The registration can be rejected for any of the following + reasons. 1) Insufficient comment period; 2) Consensus not reached; 3) + Technical deficiencies raised on the list or elsewhere have not been + addressed. The Method Reviewer's decision to reject a property can be + appealed by the proposer to the IESG, or the objections raised can be + addressed by the proposer and the property resubmitted. + +7.3 Property Change Control + + Existing properties can be changed using the same process by which + they were registered. + + 1. Define the change + + 2. Post the change + + 3. Allow a comment period + + 4. Submit the property for approval + + + +Dawson & Stenerson Standards Track [Page 143] + +RFC 2445 iCalendar November 1998 + + + Note that the original author or any other interested party can + propose a change to an existing property, but that such changes + should only be proposed when there are serious omissions or errors in + the published memo. The Method Reviewer can object to a change if it + is not backward compatible, but is not required to do so. + + Property definitions can never be deleted from the IANA registry, but + properties which are no longer believed to be useful can be declared + OBSOLETE by a change to their "intended use" field. + +8 References + + [IMIP] Dawson, F., Mansour, S. and S. Silverberg, "iCalendar + Message-based Interoperability Protocol (IMIP)", RFC 2447, + November 1998. + + [ITIP] Silverberg, S., Mansour, S., Dawson, F. and R. Hopson, + "iCalendar Transport-Independent Interoperability Protocol + (iTIP) : Scheduling Events, Busy Time, To-dos and Journal + Entries", RFC 2446, November 1998. + + [ISO 8601] ISO 8601, "Data elements and interchange formats- + Information interchange--Representation of dates and + times", International Organization for Standardization, + June, 1988. + + [ISO 9070] ISO/IEC 9070, "Information Technology_SGML Support + Facilities--Registration Procedures for Public Text Owner + Identifiers", Second Edition, International Organization + for Standardization, April 1991. + + [RFC 822] Crocker, D., "Standard for the Format of ARPA Internet + Text Messages", STD 11, RFC 822, August 1982. + + [RFC 1738] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform + Resource Locators (URL)", RFC 1738, December 1994. + + [RFC 1766] Alvestrand, H., "Tags for the Identification of + Languages", RFC 1766, March 1995. + + [RFC 2045] Freed, N. and N. Borenstein, " Multipurpose Internet Mail + Extensions (MIME) - Part One: Format of Internet Message + Bodies", RFC 2045, November 1996. + + [RFC 2046] Freed, N. and N. Borenstein, " Multipurpose Internet Mail + Extensions (MIME) - Part Two: Media Types", RFC 2046, + November 1996. + + + + +Dawson & Stenerson Standards Track [Page 144] + +RFC 2445 iCalendar November 1998 + + + [RFC 2048] Freed, N., Klensin, J. and J. Postel, "Multipurpose + Internet Mail Extensions (MIME) - Part Four: Registration + Procedures", RFC 2048, January 1997. + + [RFC 2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC 2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997. + + [RFC 2279] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", RFC 2279, January 1998. + + [RFC 2425] Howes, T., Smith, M. and F. Dawson, "A MIME Content-Type + for Directory Information", RFC 2425, September 1998. + + [RFC 2426] Dawson, F. and T. Howes, "vCard MIME Directory Profile", + RFC 2426, September 1998. + + [TZ] Olson, A.D., et al, Time zone code and data, + ftp://elsie.nci.nih.gov/pub/, updated periodically. + + [VCAL] Internet Mail Consortium, "vCalendar - The Electronic + Calendaring and Scheduling Exchange Format", + http://www.imc.org/pdi/vcal-10.txt, September 18, 1996. + +9 Acknowledgments + + A hearty thanks to the IETF Calendaring and Scheduling Working Group + and also the following individuals who have participated in the + drafting, review and discussion of this memo: + + Roland Alden, Harald T. Alvestrand, Eric Berman, Denis Bigorgne, John + Binici, Bill Bliss, Philippe Boucher, Steve Carter, Andre + Courtemanche, Dave Crocker, David Curley, Alec Dun, John Evans, Ross + Finlayson, Randell Flint, Ned Freed, Patrik Faltstrom, Chuck + Grandgent, Mark Handley, Steve Hanna, Paul B. Hill, Paul Hoffman, + Ross Hopson, Mark Horton, Daryl Huff, Bruce Kahn, C. Harald Koch, + Ryan Jansen, Don Lavange, Antoine Leca, Theodore Lorek, Steve + Mansour, Skip Montanaro, Keith Moore, Cecil Murray, Chris Newman, + John Noerenberg, Ralph Patterson, Pete Resnick, Keith Rhodes, Robert + Ripberger, John Rose, Doug Royer, Andras Salamar, Ted Schuh, Vinod + Seraphin, Derrick Shadel, Ken Shan, Andrew Shuman, Steve Silverberg, + William P. Spencer, John Sun, Mark Towfiq, Yvonne Tso, Robert Visnov, + James L. Weiner, Mike Weston, William Wyatt. + + + + + + +Dawson & Stenerson Standards Track [Page 145] + +RFC 2445 iCalendar November 1998 + + +10 Authors' and Chairs' Addresses + + The following address information is provided in a MIME-VCARD, + Electronic Business Card, format. + + The authors of this memo are: + + BEGIN:VCARD + VERSION:3.0 + N:Dawson;Frank + FN:Frank Dawson + ORG:Lotus Development Corporation + ADR;TYPE=WORK,POSTAL,PARCEL:;;6544 Battleford Drive; + Raleigh;NC;27613-3502;USA + TEL;TYPE=WORK,MSG:+1-919-676-9515 + TEL;TYPE=WORK,FAX:+1-919-676-9564 + EMAIL;TYPE=PREF,INTERNET:Frank_Dawson@Lotus.com + EMAIL;TYPE=INTERNET:fdawson@earthlink.net + URL:http://home.earthlink.net/~fdawson + END:VCARD + + BEGIN:VCARD + VERSION:3.0 + N:Stenerson;Derik + FN:Derik Stenerson + ORG:Microsoft Corporation + ADR;TYPE=WORK,POSTAL,PARCEL:;;One Microsoft Way; + Redmond;WA;98052-6399;USA + TEL;TYPE=WORK,MSG:+1-425-936-5522 + TEL;TYPE=WORK,FAX:+1-425-936-7329 + EMAIL;TYPE=INTERNET:deriks@Microsoft.com + END:VCARD + + The iCalendar object is a result of the work of the Internet + Engineering Task Force Calendaring and Scheduling Working Group. The + chairmen of that working group are: + + BEGIN:VCARD + VERSION:3.0 + N:Ganguly;Anik + FN:Anik Ganguly + ORG: Open Text Inc. + ADR;TYPE=WORK,POSTAL,PARCEL:;Suite 101;38777 West Six Mile Road; + Livonia;MI;48152;USA + TEL;TYPE=WORK,MSG:+1-734-542-5955 + EMAIL;TYPE=INTERNET:ganguly@acm.org + END:VCARD + + + + +Dawson & Stenerson Standards Track [Page 146] + +RFC 2445 iCalendar November 1998 + + + The co-chairman of that working group is: + + BEGIN:VCARD + VERSION:3.0 + N:Moskowitz;Robert + FN:Robert Moskowitz + EMAIL;TYPE=INTERNET:rgm-ietf@htt-consult.com + END:VCARD + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Dawson & Stenerson Standards Track [Page 147] + +RFC 2445 iCalendar November 1998 + + +11. Full Copyright Statement + + Copyright (C) The Internet Society (1998). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + + + + + + + + + + + + + + + + + + + + + + + + +Dawson & Stenerson Standards Track [Page 148] + diff --git a/specs/rfc2739-calendar-attrs.txt b/specs/rfc2739-calendar-attrs.txt new file mode 100644 index 0000000..5c1dbbc --- /dev/null +++ b/specs/rfc2739-calendar-attrs.txt @@ -0,0 +1,899 @@ + + + + + + +Network Working Group T. Small +Request for Comments: 2739 XpertSite.Com +Category: Standards Track D. Hennessy + ISOCOR + F. Dawson + Lotus + January 2000 + + + Calendar Attributes for vCard and LDAP + + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2000). All Rights Reserved. + +Abstract + + When scheduling a calendar entity, such as an event, it is a + prerequisite that an organizer has the calendar address of each + attendee that will be invited to the event. Additionally, access to + an attendee's current "busy time" provides an a priori indication of + whether the attendee will be free to participate in the event. + + In order to meet these challenges, a calendar user agent (CUA) needs + a mechanism to locate (URI) individual user's calendar and free/busy + time. + + This memo defines three mechanisms for obtaining a URI to a user's + calendar and free/busy time. These include: + + - Manual transfer of the information; + + - Personal data exchange using the vCard format; and + + - Directory lookup using the LDAP protocol. + + + + + + + +Small, et al. Standards Track [Page 1] + +RFC 2739 Locating a Calendar User January 2000 + + +Table of Contents + + 1 CALENDARING AND SCHEDULING URIS...................................3 + 1.1 FREE/BUSY URI (FBURL) .........................................3 + 1.2 CALENDAR ACCESS URI (CAPURI) ..................................4 + 1.3 CALENDAR URI (CALURI) .........................................4 + 1.4 DEFAULT URIS ..................................................4 + 2 DISTRIBUTION......................................................4 + 2.1 MANUAL TRANSFER ...............................................5 + 2.2 PERSONAL DATA EXCHANGE USING A VCARD ..........................5 + 2.3 VCARD SCHEMA EXTENSIONS .......................................5 + 2.3.1 FBURL Property IANA Registration ...........................6 + 2.3.2 CALADRURI Property IANA Registration .......................7 + 2.3.3 CAPURI Property IANA Registration ......................... 8 + 2.3.4 CALURI Property IANA Registration ......................... 8 + 2.4 DIRECTORY LOOKUP USING THE LDAP V3 PROTOCOL .................. 9 + 2.4.1 LDAP Schema Extensions .................................... 9 + 2.4.2 Notation ..................................................10 + 2.4.3 Object Definitions ........................................10 + 2.4.3.1 calEntry ..............................................10 + 2.4.4 Attribute Definitions .....................................10 + 2.4.4.1 calCalURI .............................................10 + 2.4.4.2 calFBURL ..............................................10 + 2.4.4.3 calCAPURI .............................................11 + 2.4.4.4 calCalAdrURI ..........................................11 + 2.4.4.5 calOtherCalURIs .......................................11 + 2.4.4.6 calOtherFBURLs ........................................11 + 2.4.4.7 calOtherCAPURIs .......................................12 + 2.4.4.8 calOtherCalAdrURIs ....................................12 + 3 IANA Considerations..............................................12 + 4 Security Considerations..........................................12 + 5 Acknowledgments..................................................13 + 6 Authors' Addresses...............................................13 + 7 Bibliography.....................................................15 + 8 Full Copyright Statement.........................................16 + + + + + + + + + + + + + + + + +Small, et al. Standards Track [Page 2] + +RFC 2739 Locating a Calendar User January 2000 + + +1 Calendaring and Scheduling URIs + + This memo defines four classes of URIs. URIs are more useful if it is + understood what the URIs point to. Here is a brief description: + +1.1 Free/Busy URI (FBURL) + + The free/busy URI is defined to be a transport independent location + where a client can obtain information about when a user is busy. At + the present time, this URI only points to busy time data. Future + revisions of this specification may provide for the extended + capability of publishing free time data. + + If a calendaring and scheduling client (i.e., CUA) were to retrieve + data from this location using FTP or HTTP, it would get back an + iCalendar object [4] containing one or more "VFREEBUSY" calendar + components. If a MIME transport is being used, the response will be + contained within a "text/calendar" MIME body part as specified in the + iCalendar specification [4]. For example: + + BEGIN:VCALENDAR + VERSION:2.0 + PRODID:-//hacksw/handcal//NONSGML v1.0//EN + METHOD:PUBLISH + BEGIN:VFREEBUSY + ATTENDEE:MAILTO:jane_doe@host1.com + DTSTART:19971013T050000Z + DTEND:19971124T050000Z + DTSTAMP:19970901T083000Z + FREEBUSY:19971015T133000Z/19971015T180000Z + FREEBUSY:19971015T190000Z/19971015T220000Z + FBURL:http://www.host.com/calendar/busy/jdoe.ifb + END:VFREEBUSY + END:VCALENDAR + + The amount of busy time data pointed to by the FBURL will generally + be pre-determined; for example one month of busy time data. As a + guideline, it is recommended that the previous six weeks of busy time + data be published at the location associated with the FBURL. If this + URI points to a file resource, it is recommended that the file + extension be "ifb" to distinguish it from an arbitrary iCalendar + object (e.g., with the "ics" file extension). + + + + + + + + + +Small, et al. Standards Track [Page 3] + +RFC 2739 Locating a Calendar User January 2000 + + +1.2 Calendar Access URI (CAPURI) + + The Calendar Access URI is defined to be a protocol independent + location from which a calendaring and scheduling client (i.e., CUA) + can communicate with a user's entire calendar. + + The semantics for using this URI as an access protocol locator are + yet to be defined by the IETF CALSCH Working Group. This will be + addressed in the "Calendar Access Protocol" specification. + +1.3 Calendar URI (CALURI) + + The Calendar URI is defined to be a protocol independent location + from which a calendaring and scheduling client (i.e. CUA) can + retrieve an entire copy of a user's calendar. Retrieving data from + this URI obtains a published "snapshot" of the user's calendar. + + HTTP URI -- If the URI is an HTTP URI, then the content returned with + a GET should be a "text/calendar" MIME body part containing one or + more iCalendar object. + + FTP URI -- If the URI is an FTP URI, then the resource pointed to + should be a file with an "ics" file extension containing one or more + iCalendar objects. + +1.4 Default URIs + + There are many cases where a user may have more than one calendar. In + these cases, a user may have multiple URIs, each URI pointing to a + calendar or free/busy data. + + To make the case of multiple calendars simpler for clients, the + concept of the "default" calendar is introduced. A "default" calendar + is one that the user has designated as the calendar that other users + should look at when accessing the user's calendar, or retrieving the + user's free/busy time. + + The default calendar may, in fact, include rolled-up information from + all the user's other calendars. The other calendars may only exist + for organizational purposes. + +2 Distribution + + These four URIs provide valuable pointers to calendaring and + scheduling data that other users need in order to know when to + schedule meetings, etc. There are several possibilities on how users + can communicate these URIs to other users. The following section + outlines how these URIs can be distributed to other users. + + + +Small, et al. Standards Track [Page 4] + +RFC 2739 Locating a Calendar User January 2000 + + +2.1 Manual Transfer + + The simplest way to obtain these URIs is for a user to communicate + the URIs using some out-of-band mechanism such as verbally, or in an + e-mail message, or by printing these URIs on a paper business card. + + When using this mechanism, the user obtains these URIs using an out- + of-band mechanism and then enters these URIs into their calendaring + software manually. + +2.2 Personal Data Exchange Using A vCard + + A more sophisticated way to obtain these URIs is for users to publish + vCards containing these URIs. The vCard object can be transferred + between one another. Since many e-mail clients allow a user to + automatically include a vCard with every message that the user sends, + this provides a simple, transparent way for a user to distribute + their calendaring and scheduling URIs. + + On the receiving end, an e-mail client that provides an integrated + vCard database can provide a way to lookup calendaring URIs for users + whose vCards are stored locally. + +2.3 vCard Schema Extensions + + Since the vCard [3] specification doesn't specify how to encode + calendaring URIs in a vCard, this section is provided as an extension + to vCard which specifies how to encode calendaring URIs within a + vCard. + + Inside a vCard object, four new properties are defined: "CALURI", + "CAPURI", "CALADRURI", and "FBURL", as defined above. + + Any vCard can have one or more of these properties, each representing + a calendar or free/busy time that is associated with the user. + + One of these properties can be designated as the "default" by adding + the "PREF" parameter. + + + + + + + + + + + + + +Small, et al. Standards Track [Page 5] + +RFC 2739 Locating a Calendar User January 2000 + + + Here is a simple example of a vCard containing a "FBURL" and a + "CALURI". + + BEGIN:VCARD + VERSION:3.0 + N:Dun;Alec + FN:Alec Dun + ORG:Microsoft Corporation + ADR;WORK;POSTAL;PARCEL:;;One Microsoft Way; + Redmond;WA;98052-6399;USA + TEL;WORK;MSG:+1-206-936-4544 + TEL;WORK;FAX:+1-206-936-7329 + EMAIL;INTERNET:user@host1.com + CALADRURI;PREF:mailto:user@host1.com + CALURI;PREF:http://cal.host1.com/user/cal.ics + FBURL;PREF:http://cal.host1.com/user/fb.ifb + CALURI:http://cal.company.com/projectA/pjtA.ics + FBURL:http://cal.company.com/projectA/pjtAfb.ifb + END:VCARD + +2.3.1 FBURL Property IANA Registration + + To: ietf-mime-directory@imc.org + + Subject: Registration of FBURL type for text/directory MIME type + vCard profile. + + Type name: FBURL + + Type purpose: To specify the URI for a user's busy time in a vCard + object. + + Type encoding: 8bit + + Type value: A single URI value. + + Type special notes: Where multiple FBURL properties are specified, + the default FBURL property is indicated with the PREF parameter. The + FTP or HTTP type of URI points to an iCalendar object associated with + a snapshot of the last six weeks of the user's busy time data. If the + iCalendar object is represented as a file or document, it's file type + should be "ifb". + + Intended usage: Refer to section 1.1. + + + + + + + +Small, et al. Standards Track [Page 6] + +RFC 2739 Locating a Calendar User January 2000 + + + Type examples: + + FBURL;PREF:http://www.host1.com/busy/janedoe + FBURL:FTP://ftp.host.com/busy/project-a.ifb + +2.3.2 CALADRURI Property IANA Registration + + To: ietf-mime-directory@imc.org + + Subject: Registration of CALADRURI type for application/directory + MIME type vCard profile. + + Type name: CALADRURI + + Type purpose: To specify the location to which an event request + should be sent for the user. + + Type encoding: 8bit + + Type value: A single URI value. + + Type special notes: Where multiple CALADRURI properties are + specified, the default CALADRURI property is indicated with the PREF + parameter. + + Intended usage: Refer to section 1.2. + + Type examples: + + CALADRURI;PREF:mailto:janedoe@host.com + + + + + + + + + + + + + + + + + + + + + +Small, et al. Standards Track [Page 7] + +RFC 2739 Locating a Calendar User January 2000 + + +2.3.3 CAPURI Property IANA Registration + + To: ietf-mime-directory@imc.org + + Subject: Registration of CAPURI type for application/directory MIME + type vCard profile. + + Type name: CAPURI + + Type purpose: To specify a protocol independent location from which a + calendaring and scheduling client (i.e., CUA) can communicate with a + user's entire calendar. + + Type encoding: 8bit + + Type value: A single URI value. + + Type special notes: Where multiple CAPURI properties are specified, + the default CAPURI property is indicated with the PREF parameter. + + Intended usage: Refer to section 1.3. + +2.3.4 CALURI Property IANA Registration + + To: ietf-mime-directory@imc.org + + Subject: Registration of CALURI type for text/directory MIME type + vCard profile. + + Type name: CALURI + + Type purpose: To specify the URI for a user's calendar in a vCard + object. + + Type encoding: 8bit + + Type value type: A single URI value. + + Type special notes: Where multiple CALURI properties are specified, + the default CALURI property is indicated with the PREF parameter. The + property should contain a URI pointing to an iCalendar object + associated with a snapshot of the user's calendar store. If the + iCalendar object is represented as a file or document, it's file type + should be "ics". + + Intended usage: Refer to section 1.4. + + + + + +Small, et al. Standards Track [Page 8] + +RFC 2739 Locating a Calendar User January 2000 + + + Type examples: + + CALURI;PREF:http://cal.host1.com/calA + CALURI:ftp://ftp.host1.com/calA.ics + +2.4 Directory Lookup Using The LDAP v3 Protocol + + Another way to obtain these URIs is to look them up in a directory + using the LDAP protocol [1]. + + If a user's URIs can be found using directory lookup (i.e., searching + for one of the LDAP schema extensions defined below), they should, in + general, be considered "more up-to-date" than URIs in any vCards that + are stored locally. + +2.4.1 LDAP Schema Extensions + + In order to encode the calendaring URIs in the directory, the + following are defined: + + - One object class: + + - calEntry + + - Eight attributes: + + - calCalURI + + - calFBURL + + - calCAPURI + + - calCalAdrURI + + - calOtherCalURIs + + - calOtherFBURLs + + - calOtherCAPURIs + + - calOtherCalAdrURIs + + The calCalURI contains the URI to a snapshot of the user's entire + default calendar. The calFBURL contains the URI to the user's default + busy time data. The calCAPURI represents contains a URI that can be + used to communicate with the user's calendar. The calCalAdrURI + contains a URI that points to the location to which event requests + should be sent for that user. + + + +Small, et al. Standards Track [Page 9] + +RFC 2739 Locating a Calendar User January 2000 + + + The calOtherCalURIs is a multi-valued property containing URIs to + snapshots of other calendars that the user may have. The + calOtherFBURLs is a multi-valued property containing URIs to other + free/busy data that the user may have. The calOtherCAPURIs attribute + is a multi-valued property containing URIs to other calendars that + the user may have. The calOtherCalAdrURIs attribute is a multi-valued + property containing URIs to other locations that a user may want + event requests sent to. + + There is no predetermined order to the values in either multi-valued + property. + +2.4.2 Notation + + The notation used in this memo is the same as that used in [2]. + +2.4.3 Object Definitions + +2.4.3.1 calEntry + + The Calendar Entry is a class derived from "TOP" [2], which contains + the four calendaring attributes. + + (1.2.840.113556.1.5.87 + NAME 'calEntry' + TOP + AUXILIARY + MAY (calCalURI calFBURL calOtherCalURIs calOtherFBURLs calCAPURI + calOtherCAPURLs) + ) + +2.4.4 Attribute Definitions + +2.4.4.1 calCalURI + + (1.2.840.113556.1.4.478 + NAME 'calCalURI' + EQUALITY caseIgnoreMatch + SUBSTRING caseIgnoreMatch + SYNTAX 'IA5String' + USAGE userApplications + ) + +2.4.4.2 calFBURL + + (1.2.840.113556.1.4.479 + NAME 'calFBURL' + EQUALITY caseIgnoreMatch + + + +Small, et al. Standards Track [Page 10] + +RFC 2739 Locating a Calendar User January 2000 + + + SUBSTRING caseIgnoreMatch + SYNTAX 'IA5String' + USAGE userApplications + ) + +2.4.4.3 calCAPURI + + (1.2.840.113556.1.4.480 + NAME 'calCAPURI' + EQUALITY caseIgnoreMatch + SUBSTRING caseIgnoreMatch + SYNTAX 'IA5String' + USAGE userApplications + ) + +2.4.4.4 calCalAdrURI + + (1.2.840.113556.1.4.481 + NAME 'calCalAdrURI' + EQUALITY caseIgnoreMatch + SUBSTRING caseIgnoreMatch + SYNTAX 'IA5String' + USAGE userApplications + ) + +2.4.4.5 calOtherCalURIs + + (1.2.840.113556.1.4.482 + NAME 'calOtherCalURIs' + EQUALITY caseIgnoreMatch + SUBSTRING caseIgnoreMatch + SYNTAX 'IA5String' + MULTI-VALUE + USAGE userApplications + ) + +2.4.4.6 calOtherFBURLs + + (1.2.840.113556.1.4.483 + NAME 'calOtherFBURLs' + EQUALITY caseIgnoreMatch + SUBSTRING caseIgnoreMatch + SYNTAX 'IA5String' + MULTI-VALUE + USAGE userApplications + ) + + + + + +Small, et al. Standards Track [Page 11] + +RFC 2739 Locating a Calendar User January 2000 + + +2.4.4.7 calOtherCAPURIs + + (1.2.840.113556.1.4.484 + NAME 'calOtherCAPURIs' + EQUALITY caseIgnoreMatch + SUBSTRING caseIgnoreMatch + SYNTAX 'IA5String' + MULTI-VALUE + USAGE userApplications + ) + +2.4.4.8 calOtherCalAdrURIs + + (1.2.840.113556.1.4.485 + NAME 'calOtherCalAdrURIs' + EQUALITY caseIgnoreMatch + SUBSTRING caseIgnoreMatch + SYNTAX 'IA5String' + MULTI-VALUE + USAGE userApplications + ) + +3 IANA Considerations + + This memo defines IANA registered extensions to the attributes + defined by LDAP [1] and vCard [3]. + + IANA registration proposals for vCard are to be emailed to the + registration agent for the "text/directory" MIME content-type, + using the format defined in + [3]. + +4 Security Considerations + + Standard vCard and LDAP security rules and support apply for the + extensions described in this document, and there are no special + security issues for these extensions. + + Please note, though, that LDAP servers may permit anonymous clients + to refresh entries which they did not create. Servers are also + permitted to control a refresh access to an entry by requiring + clients to bind before issuing a RefreshRequest. This will have + implications on the server performance and scalability. + + Please also note, though, that vCard objects may have been created by + an entity other than that represented by the vCard. Recipients should + be certain of the source that generated the vCard. + + + + +Small, et al. Standards Track [Page 12] + +RFC 2739 Locating a Calendar User January 2000 + + + Also, care should be taken in making use of information obtained from + directory servers that has been supplied by client, as it may now be + out of date. In many networks, for example, IP addresses are + automatically assigned when a host connects to the network, and may + be reassigned if that host later disconnects. An IP address obtained + from the directory may no longer be assigned to the host that placed + the address in the directory. This issue is not specific to LDAP or + dynamic directories. + +5 Acknowledgments + + The authors wish to acknowledge the work of Alec Dun, who acted as an + author for the early drafts of this memo. In addition, this document + received input from the various participants in the IETF CALSCH + Working Group discussions. + +6 Authors' Addresses + + The following address information is provided in a vCard v3.0 [3], + Electronic Business Card, format. + + BEGIN:VCARD + VERSION:3.0 + N:Small;Tony + FN:Tony Small + ORG:XpertSite.Com + ADR;TYPE=WORK,POSTAL,PARCEL:;;4700 42nd Ave. SW, Suite 440; + Seattle;WA;98116;USA + TEL;TYPE=WORK,MSG:+1-206-937-9972 + TEL;TYPE=WORK,FAX:+1-206-936-7329 + EMAIL;TYPE=INTERNET:tony@xpertsite.com + CALADRURI:MAILTO:tony@xpertsite.com + END:VCARD + + BEGIN:VCARD + VERSION:3.0 + N:Hennessy;Denis + FN:Denis Hennessy + ORG:ISOCOR + ADR;TYPE=WORK,POSTAL,PARCEL:;;42-47 Lower Mount St; + Dublin 2;Ireland + TEL;TYPE=WORK,MSG:+353-1-676-0366 + TEL;TYPE=WORK,FAX:+353-1-676-0856 + EMAIL;TYPE=INTERNET:denis.hennessy@isocor.com + CALADRURI:MAILTO:denis.hennessy@isocor.com + END:VCARD + + + + + +Small, et al. Standards Track [Page 13] + +RFC 2739 Locating a Calendar User January 2000 + + + BEGIN:VCARD + VERSION:3.0 + N:Dawson;Frank + FN:Frank Dawson + ORG:Lotus Development Corporation + ADR;TYPE=WORK,POSTAL,PARCEL:;;6544 Battleford Drive; + Raleigh;NC;27613-3502;USA + TEL;TYPE=WORK,PREF:+1-617-693-8728 + TEL;TYPE=WORK,MSG:+1-919-676-9515 + TEL;TYPE=FAX:+1-617-693-8728 + EMAIL;TYPE=INTERNET,PREF:Frank_Dawson@Lotus.com + EMAIL;TYPE=INTERNET:fdawson@earthlink.net + CALADRURI;TYPE=PREF:MAILTO:Frank_Dawson@Lotus.com + CALADRURI:MAILTO:fdawson@earthlink.net + URL:http://home.earthlink.net/~fdawson + END:VCARD + + This memo is a result of the work of the Internet Engineering Task + Force Calendaring and scheduling Working Group. The chairman of that + working group is: + + BEGIN:VCARD + VERSION:3.0 + N:Egen;Pat + FN:Pat Egen + ORG:Engan Consulting + ADR;TYPE=WORK:;;803 Creek Overlook;Chattanooga;TN;37415;USA + TEL;TYPE=WORK,VOICE:423.875.2652 + TEL;TYPE=WORK,FAX:423.875.2017 + EMAIL:pregen@egenconsulting.com + URL:http://www.egenconsulting.com + CALADRURI:MAILTO:pregen@egenconsulting.com + END:VCARD + + + + + + + + + + + + + + + + + + +Small, et al. Standards Track [Page 14] + +RFC 2739 Locating a Calendar User January 2000 + + +7 Bibliography + + [1] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access + Protocol (v3)", RFC 2251, December 1997. + + [2] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight + Directory Access Protocol (v3): Attribute Syntax Definitions", + RFC 2252, December 1997. + + [3] Dawson, F. and T. Howes, "vCard MIME Directory Profile", RFC + 2426, September 1998. + + [4] Dawson, F. and D. Stenerson, "Internet Calendaring and Scheduling + Core Object Specification (iCalendar)", RFC 2445, November 1997. + + [5] Dawson, F. and S. Mansour, "iCalendar Message-Based + Interopability Protocal (iMIP)", RFC 2447, November 1997. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Small, et al. Standards Track [Page 15] + +RFC 2739 Locating a Calendar User January 2000 + + +8 Full Copyright Statement + + Copyright (C) The Internet Society (2000). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Small, et al. Standards Track [Page 16] + diff --git a/specs/rfc4770-im-attrs.txt b/specs/rfc4770-im-attrs.txt new file mode 100644 index 0000000..8b3060c --- /dev/null +++ b/specs/rfc4770-im-attrs.txt @@ -0,0 +1,395 @@ + + + + + + +Network Working Group C. Jennings +Request for Comments: 4770 Cisco Systems +Category: Standards Track J. Reschke, Ed. + greenbytes + January 2007 + + + vCard Extensions for Instant Messaging (IM) + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The IETF Trust (2007). + +Abstract + + This document describes an extension to vCard to support Instant + Messaging (IM) and Presence Protocol (PP) applications. IM and PP + are becoming increasingly common ways of communicating, and users + want to save this contact information in their address books. It + allows a URI that is associated with IM or PP to be specified inside + a vCard. + +Table of Contents + + 1. Overview ........................................................2 + 2. IANA Considerations .............................................3 + 3. Formal Grammar ..................................................4 + 4. Example .........................................................4 + 5. Security Considerations .........................................4 + 6. Acknowledgments .................................................4 + 7. References ......................................................5 + 7.1. Normative References .......................................5 + 7.2. Informational References ...................................5 + + + + + + + + + + +Jennings & Reschke Standards Track [Page 1] + +RFC 4770 IMPP vCard January 2007 + + +1. Overview + + As more and more people use various instant messaging (IM) and + presence protocol (PP) applications, it becomes important for them to + be able to share this contact address information, along with the + rest of their contact information. RFC 2425 [1] and RFC 2426 [2] + define a standard format for this information, which is referred to + as vCard. This document defines a new type in a vCard for + representing instant IM and PP URIs. It is very similar to existing + types for representing email address and telephone contact + information. + + The type entry to hold this new contact information is an IMPP type. + The IMPP entry has a single URI (see RFC 3986 [3]) that indicates the + address of a service that provides IM, PP, or both. Also defined are + some parameters that give hints as to when certain URIs would be + appropriate. A given vCard can have multiple IMPP entries, but each + entry can contain only one URI. Each IMPP entry can contain multiple + parameters. Any combination of parameters is valid, although a + parameter should occur, at most, once in a given IMPP entry. + + The type of URI indicates what protocols might be usable for + accessing it, but this document does not define any of the types. + For example, a URI type of + + o "sip" [5] indicates to use SIP/SIMPLE, + o "xmpp" [6] indicates to use XMPP, + o "irc" indicates to use IRC, + o "ymsgr" indicates to use yahoo, + o "msn" might indicate to use Microsoft messenger, + o "aim" indicates to use AOL, and + o "im" [7] or "pres" [8] indicates that a CPIM or CPP gateway should + be used. + + The normative definition of this new vCard type is given in Section + 2, and an informational ABNF is provided in Section 3. + + + + + + + + + + + + + + + +Jennings & Reschke Standards Track [Page 2] + +RFC 4770 IMPP vCard January 2007 + + +2. IANA Considerations + + The required email to define this extension (as defined in RFC 2425 + [1]) was sent on October 29, 2004, to the ietf-mime-direct@imc.org + mailing list with the subject "Registration of text/directory MIME + type IMPP" (see ). + + This specification updates the "text/directory MIME Types" + subregistry in the "text/directory MIME Registrations" registry at + http://www.iana.org/assignments/text-directory-registrations with the + following information: + + Type name: IMPP + + Type purpose: To specify the URI for instant messaging and presence + protocol communications with the object the vCard represents. + + Type encoding: 8bit + + Type value: A single URI. The type of the URI indicates the protocol + that can be used for this contact. + + Type special notes: The type may include the type parameter "TYPE" to + specify an intended use for the URI. The TYPE parameter values + include one or more of the following: + + o An indication of the type of communication for which this URI is + appropriate. This can be a value of PERSONAL or BUSINESS. + + o An indication of the location of a device associated with this + URI. Values can be HOME, WORK, or MOBILE. + + o The value PREF indicates this is a preferred address and has the + same semantics as the PREF value in a TEL type. + + Additional information can be found in RFC 4770. + + Intended usage: COMMON + + + + + + + + + + + + +Jennings & Reschke Standards Track [Page 3] + +RFC 4770 IMPP vCard January 2007 + + +3. Formal Grammar + + The following ABNF grammar [4] extends the grammar found in RFC 2425 + [1] (Section 5.8.2) and RFC 2426 [2] (Section 4). + + ;For name="IMPP" + param = impp-param ; Only impp parameters are allowed + + value = URI + ; URI defined in Section 3 of [3] + + impp-param = "TYPE" "=" impp-type *("," impp-type) + + impp-type = "PERSONAL" / "BUSINESS" / ; purpose of communications + "HOME" / "WORK" / "MOBILE" / + "PREF" / + iana-token / x-name; + ; Values are case insensitive + +4. Example + + BEGIN:vCard + VERSION:3.0 + FN:Alice Doe + IMPP;TYPE=personal,pref:im:alice@example.com + END:vCard + +5. Security Considerations + + This does not introduce additional security issues beyond the current + vCard specification. It is worth noting that many people consider + their presence information more sensitive than other address + information. Any system that stores or transfers vCards needs to + carefully consider the privacy issues around this information. + +6. Acknowledgments + + Thanks to Brian Carpenter, Lars Eggert, Ted Hardie, Paul Hoffman, Sam + Roberts, and Pekka Pessi for their comments. + + + + + + + + + + + + +Jennings & Reschke Standards Track [Page 4] + +RFC 4770 IMPP vCard January 2007 + + +7. References + +7.1. Normative References + + + [1] Howes, T., Smith, M., and F. Dawson, "A MIME Content-Type for + Directory Information", RFC 2425, September 1998. + + [2] Dawson, F. and T. Howes, "vCard MIME Directory Profile", RFC + 2426, September 1998. + + [3] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, + January 2005. + + [4] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 4234, October 2005. + +7.2. Informational References + + [5] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., + Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: + Session Initiation Protocol", RFC 3261, June 2002. + + [6] Saint-Andre, P., "Internationalized Resource Identifiers (IRIs) + and Uniform Resource Identifiers (URIs) for the Extensible + Messaging and Presence Protocol (XMPP)", RFC 4622, July 2006. + + [7] Peterson, J., "Common Profile for Instant Messaging (CPIM)", RFC + 3860, August 2004. + + [8] Peterson, J., "Common Profile for Presence (CPP)", RFC 3859, + August 2004. + + + + + + + + + + + + + + + + + + +Jennings & Reschke Standards Track [Page 5] + +RFC 4770 IMPP vCard January 2007 + + +Authors' Addresses + + Cullen Jennings + Cisco Systems + 170 West Tasman Drive + MS: SJC-21/2 + San Jose, CA 95134 + USA + + Phone: +1 408 902-3341 + EMail: fluffy@cisco.com + + + Julian F. Reschke (editor) + greenbytes GmbH + Hafenweg 16 + Muenster, NW 48155 + Germany + + Phone: +49 251 2807760 + EMail: julian.reschke@greenbytes.de + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Jennings & Reschke Standards Track [Page 6] + +RFC 4770 IMPP vCard January 2007 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2007). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST, + AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT + THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY + IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR + PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + +Jennings & Reschke Standards Track [Page 7] + diff --git a/specs/rfc5545-icalendar-2.0-bis.txt b/specs/rfc5545-icalendar-2.0-bis.txt new file mode 100644 index 0000000..47ea31d --- /dev/null +++ b/specs/rfc5545-icalendar-2.0-bis.txt @@ -0,0 +1,9411 @@ + + + + + + +Network Working Group B. Desruisseaux, Ed. +Request for Comments: 5545 Oracle +Obsoletes: 2445 September 2009 +Category: Standards Track + + + Internet Calendaring and Scheduling Core Object Specification + (iCalendar) + +Abstract + +This document defines the iCalendar data format for representing and +exchanging calendaring and scheduling information such as events, +to-dos, journal entries, and free/busy information, independent of any +particular calendar service or protocol. + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright and License Notice + + Copyright (c) 2009 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 BSD License. + + This document may contain material from IETF Documents or IETF + Contributions published or made publicly available before November + 10, 2008. The person(s) controlling the copyright in some of this + material may not have granted the IETF Trust the right to allow + modifications of such material outside the IETF Standards Process. + Without obtaining an adequate license from the person(s) controlling + the copyright in such materials, this document may not be modified + outside the IETF Standards Process, and derivative works of it may + not be created outside the IETF Standards Process, except to format + + + +Desruisseaux Standards Track [Page 1] + +RFC 5545 iCalendar September 2009 + + + it for publication as an RFC or to translate it into languages other + than English. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 + 2. Basic Grammar and Conventions . . . . . . . . . . . . . . . . 6 + 2.1. Formatting Conventions . . . . . . . . . . . . . . . . . 6 + 2.2. Related Memos . . . . . . . . . . . . . . . . . . . . . . 7 + 3. iCalendar Object Specification . . . . . . . . . . . . . . . 8 + 3.1. Content Lines . . . . . . . . . . . . . . . . . . . . . . 8 + 3.1.1. List and Field Separators . . . . . . . . . . . . . . 11 + 3.1.2. Multiple Values . . . . . . . . . . . . . . . . . . . 11 + 3.1.3. Binary Content . . . . . . . . . . . . . . . . . . . 11 + 3.1.4. Character Set . . . . . . . . . . . . . . . . . . . . 12 + 3.2. Property Parameters . . . . . . . . . . . . . . . . . . . 12 + 3.2.1. Alternate Text Representation . . . . . . . . . . . . 13 + 3.2.2. Common Name . . . . . . . . . . . . . . . . . . . . . 15 + 3.2.3. Calendar User Type . . . . . . . . . . . . . . . . . 15 + 3.2.4. Delegators . . . . . . . . . . . . . . . . . . . . . 16 + 3.2.5. Delegatees . . . . . . . . . . . . . . . . . . . . . 16 + 3.2.6. Directory Entry Reference . . . . . . . . . . . . . . 17 + 3.2.7. Inline Encoding . . . . . . . . . . . . . . . . . . . 17 + 3.2.8. Format Type . . . . . . . . . . . . . . . . . . . . . 18 + 3.2.9. Free/Busy Time Type . . . . . . . . . . . . . . . . . 19 + 3.2.10. Language . . . . . . . . . . . . . . . . . . . . . . 20 + 3.2.11. Group or List Membership . . . . . . . . . . . . . . 20 + 3.2.12. Participation Status . . . . . . . . . . . . . . . . 21 + 3.2.13. Recurrence Identifier Range . . . . . . . . . . . . . 22 + 3.2.14. Alarm Trigger Relationship . . . . . . . . . . . . . 23 + 3.2.15. Relationship Type . . . . . . . . . . . . . . . . . . 24 + 3.2.16. Participation Role . . . . . . . . . . . . . . . . . 25 + 3.2.17. RSVP Expectation . . . . . . . . . . . . . . . . . . 25 + 3.2.18. Sent By . . . . . . . . . . . . . . . . . . . . . . . 26 + 3.2.19. Time Zone Identifier . . . . . . . . . . . . . . . . 26 + 3.2.20. Value Data Types . . . . . . . . . . . . . . . . . . 28 + 3.3. Property Value Data Types . . . . . . . . . . . . . . . . 29 + 3.3.1. Binary . . . . . . . . . . . . . . . . . . . . . . . 29 + 3.3.2. Boolean . . . . . . . . . . . . . . . . . . . . . . . 30 + 3.3.3. Calendar User Address . . . . . . . . . . . . . . . . 30 + 3.3.4. Date . . . . . . . . . . . . . . . . . . . . . . . . 31 + 3.3.5. Date-Time . . . . . . . . . . . . . . . . . . . . . . 31 + 3.3.6. Duration . . . . . . . . . . . . . . . . . . . . . . 34 + 3.3.7. Float . . . . . . . . . . . . . . . . . . . . . . . . 35 + 3.3.8. Integer . . . . . . . . . . . . . . . . . . . . . . . 35 + 3.3.9. Period of Time . . . . . . . . . . . . . . . . . . . 36 + 3.3.10. Recurrence Rule . . . . . . . . . . . . . . . . . . . 37 + 3.3.11. Text . . . . . . . . . . . . . . . . . . . . . . . . 45 + + + +Desruisseaux Standards Track [Page 2] + +RFC 5545 iCalendar September 2009 + + + 3.3.12. Time . . . . . . . . . . . . . . . . . . . . . . . . 46 + 3.3.13. URI . . . . . . . . . . . . . . . . . . . . . . . . . 48 + 3.3.14. UTC Offset . . . . . . . . . . . . . . . . . . . . . 49 + 3.4. iCalendar Object . . . . . . . . . . . . . . . . . . . . 49 + 3.5. Property . . . . . . . . . . . . . . . . . . . . . . . . 50 + 3.6. Calendar Components . . . . . . . . . . . . . . . . . . . 50 + 3.6.1. Event Component . . . . . . . . . . . . . . . . . . . 52 + 3.6.2. To-Do Component . . . . . . . . . . . . . . . . . . . 56 + 3.6.3. Journal Component . . . . . . . . . . . . . . . . . . 58 + 3.6.4. Free/Busy Component . . . . . . . . . . . . . . . . . 60 + 3.6.5. Time Zone Component . . . . . . . . . . . . . . . . . 63 + 3.6.6. Alarm Component . . . . . . . . . . . . . . . . . . . 72 + 3.7. Calendar Properties . . . . . . . . . . . . . . . . . . . 77 + 3.7.1. Calendar Scale . . . . . . . . . . . . . . . . . . . 77 + 3.7.2. Method . . . . . . . . . . . . . . . . . . . . . . . 78 + 3.7.3. Product Identifier . . . . . . . . . . . . . . . . . 79 + 3.7.4. Version . . . . . . . . . . . . . . . . . . . . . . . 80 + 3.8. Component Properties . . . . . . . . . . . . . . . . . . 81 + 3.8.1. Descriptive Component Properties . . . . . . . . . . 81 + 3.8.1.1. Attachment . . . . . . . . . . . . . . . . . . . 81 + 3.8.1.2. Categories . . . . . . . . . . . . . . . . . . . 82 + 3.8.1.3. Classification . . . . . . . . . . . . . . . . . 83 + 3.8.1.4. Comment . . . . . . . . . . . . . . . . . . . . . 84 + 3.8.1.5. Description . . . . . . . . . . . . . . . . . . . 85 + 3.8.1.6. Geographic Position . . . . . . . . . . . . . . . 87 + 3.8.1.7. Location . . . . . . . . . . . . . . . . . . . . 88 + 3.8.1.8. Percent Complete . . . . . . . . . . . . . . . . 89 + 3.8.1.9. Priority . . . . . . . . . . . . . . . . . . . . 90 + 3.8.1.10. Resources . . . . . . . . . . . . . . . . . . . . 92 + 3.8.1.11. Status . . . . . . . . . . . . . . . . . . . . . 93 + 3.8.1.12. Summary . . . . . . . . . . . . . . . . . . . . . 94 + 3.8.2. Date and Time Component Properties . . . . . . . . . 95 + 3.8.2.1. Date-Time Completed . . . . . . . . . . . . . . . 95 + 3.8.2.2. Date-Time End . . . . . . . . . . . . . . . . . . 96 + 3.8.2.3. Date-Time Due . . . . . . . . . . . . . . . . . . 97 + 3.8.2.4. Date-Time Start . . . . . . . . . . . . . . . . . 99 + 3.8.2.5. Duration . . . . . . . . . . . . . . . . . . . . 100 + 3.8.2.6. Free/Busy Time . . . . . . . . . . . . . . . . . 101 + 3.8.2.7. Time Transparency . . . . . . . . . . . . . . . . 102 + 3.8.3. Time Zone Component Properties . . . . . . . . . . . 103 + 3.8.3.1. Time Zone Identifier . . . . . . . . . . . . . . 103 + 3.8.3.2. Time Zone Name . . . . . . . . . . . . . . . . . 105 + 3.8.3.3. Time Zone Offset From . . . . . . . . . . . . . . 106 + 3.8.3.4. Time Zone Offset To . . . . . . . . . . . . . . . 106 + 3.8.3.5. Time Zone URL . . . . . . . . . . . . . . . . . . 107 + 3.8.4. Relationship Component Properties . . . . . . . . . . 108 + 3.8.4.1. Attendee . . . . . . . . . . . . . . . . . . . . 108 + 3.8.4.2. Contact . . . . . . . . . . . . . . . . . . . . . 111 + + + +Desruisseaux Standards Track [Page 3] + +RFC 5545 iCalendar September 2009 + + + 3.8.4.3. Organizer . . . . . . . . . . . . . . . . . . . . 113 + 3.8.4.4. Recurrence ID . . . . . . . . . . . . . . . . . . 114 + 3.8.4.5. Related To . . . . . . . . . . . . . . . . . . . 117 + 3.8.4.6. Uniform Resource Locator . . . . . . . . . . . . 118 + 3.8.4.7. Unique Identifier . . . . . . . . . . . . . . . . 119 + 3.8.5. Recurrence Component Properties . . . . . . . . . . . 120 + 3.8.5.1. Exception Date-Times . . . . . . . . . . . . . . 120 + 3.8.5.2. Recurrence Date-Times . . . . . . . . . . . . . . 122 + 3.8.5.3. Recurrence Rule . . . . . . . . . . . . . . . . . 124 + 3.8.6. Alarm Component Properties . . . . . . . . . . . . . 134 + 3.8.6.1. Action . . . . . . . . . . . . . . . . . . . . . 134 + 3.8.6.2. Repeat Count . . . . . . . . . . . . . . . . . . 135 + 3.8.6.3. Trigger . . . . . . . . . . . . . . . . . . . . . 135 + 3.8.7. Change Management Component Properties . . . . . . . 138 + 3.8.7.1. Date-Time Created . . . . . . . . . . . . . . . . 138 + 3.8.7.2. Date-Time Stamp . . . . . . . . . . . . . . . . . 139 + 3.8.7.3. Last Modified . . . . . . . . . . . . . . . . . . 140 + 3.8.7.4. Sequence Number . . . . . . . . . . . . . . . . . 141 + 3.8.8. Miscellaneous Component Properties . . . . . . . . . 142 + 3.8.8.1. IANA Properties . . . . . . . . . . . . . . . . . 142 + 3.8.8.2. Non-Standard Properties . . . . . . . . . . . . . 142 + 3.8.8.3. Request Status . . . . . . . . . . . . . . . . . 144 + 4. iCalendar Object Examples . . . . . . . . . . . . . . . . . . 146 + 5. Recommended Practices . . . . . . . . . . . . . . . . . . . . 150 + 6. Internationalization Considerations . . . . . . . . . . . . . 151 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 151 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 151 + 8.1. iCalendar Media Type Registration . . . . . . . . . . . . 151 + 8.2. New iCalendar Elements Registration . . . . . . . . . . . 155 + 8.2.1. iCalendar Elements Registration Procedure . . . . . . 155 + 8.2.2. Registration Template for Components . . . . . . . . 155 + 8.2.3. Registration Template for Properties . . . . . . . . 156 + 8.2.4. Registration Template for Parameters . . . . . . . . 156 + 8.2.5. Registration Template for Value Data Types . . . . . 157 + 8.2.6. Registration Template for Values . . . . . . . . . . 157 + 8.3. Initial iCalendar Elements Registries . . . . . . . . . . 158 + 8.3.1. Components Registry . . . . . . . . . . . . . . . . . 158 + 8.3.2. Properties Registry . . . . . . . . . . . . . . . . . 158 + 8.3.3. Parameters Registry . . . . . . . . . . . . . . . . . 161 + 8.3.4. Value Data Types Registry . . . . . . . . . . . . . . 162 + 8.3.5. Calendar User Types Registry . . . . . . . . . . . . 162 + 8.3.6. Free/Busy Time Types Registry . . . . . . . . . . . . 163 + 8.3.7. Participation Statuses Registry . . . . . . . . . . . 163 + 8.3.8. Relationship Types Registry . . . . . . . . . . . . . 164 + 8.3.9. Participation Roles Registry . . . . . . . . . . . . 164 + 8.3.10. Actions Registry . . . . . . . . . . . . . . . . . . 165 + 8.3.11. Classifications Registry . . . . . . . . . . . . . . 165 + 8.3.12. Methods Registry . . . . . . . . . . . . . . . . . . 165 + + + +Desruisseaux Standards Track [Page 4] + +RFC 5545 iCalendar September 2009 + + + 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 165 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 166 + 10.1. Normative References . . . . . . . . . . . . . . . . . . 166 + 10.2. Informative References . . . . . . . . . . . . . . . . . 167 + Appendix A. Differences from RFC 2445 . . . . . . . . . . . . . 169 + A.1. New Restrictions . . . . . . . . . . . . . . . . . . . . 169 + A.2. Restrictions Removed . . . . . . . . . . . . . . . . . . 169 + A.3. Deprecated Features . . . . . . . . . . . . . . . . . . . 169 + +1. Introduction + + The use of calendaring and scheduling has grown considerably in the + last decade. Enterprise and inter-enterprise business has become + dependent on rapid scheduling of events and actions using this + information technology. This memo is intended to progress the level + of interoperability possible between dissimilar calendaring and + scheduling applications. This memo defines a MIME content type for + exchanging electronic calendaring and scheduling information. The + Internet Calendaring and Scheduling Core Object Specification, or + iCalendar, allows for the capture and exchange of information + normally stored within a calendaring and scheduling application; such + as a Personal Information Manager (PIM) or a Group-Scheduling + product. + + The iCalendar format is suitable as an exchange format between + applications or systems. The format is defined in terms of a MIME + content type. This will enable the object to be exchanged using + several transports, including but not limited to SMTP, HTTP, a file + system, desktop interactive protocols such as the use of a memory- + based clipboard or drag/drop interactions, point-to-point + asynchronous communication, wired-network transport, or some form of + unwired transport such as infrared. + + The memo also provides for the definition of iCalendar object methods + that will map this content type to a set of messages for supporting + calendaring and scheduling operations such as requesting, replying + to, modifying, and canceling meetings or appointments, to-dos, and + journal entries. The iCalendar object methods can be used to define + other calendaring and scheduling operations such as requesting for + and replying with free/busy time data. Such a scheduling protocol is + defined in the iCalendar Transport-independent Interoperability + Protocol (iTIP) defined in [2446bis]. + + The memo also includes a formal grammar for the content type based on + the Internet ABNF defined in [RFC5234]. This ABNF is required for + the implementation of parsers and to serve as the definitive + reference when ambiguities or questions arise in interpreting the + descriptive prose definition of the memo. Additional restrictions + + + +Desruisseaux Standards Track [Page 5] + +RFC 5545 iCalendar September 2009 + + + that could not easily be expressed with the ABNF syntax are specified + as comments in the ABNF. Comments with normative statements should + be treated as such. + +2. Basic Grammar and Conventions + + 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]. + + This memo makes use of both a descriptive prose and a more formal + notation for defining the calendaring and scheduling format. + + The notation used in this memo is the ABNF notation of [RFC5234]. + Readers intending on implementing the format defined in this memo + should be familiar with this notation in order to properly interpret + the specifications of this memo. + + All numeric values used in this memo are given in decimal notation. + + All names of properties, property parameters, enumerated property + values, and property parameter values are case-insensitive. However, + all other property values are case-sensitive, unless otherwise + stated. + + Note: All indented editorial notes, such as this one, are intended + to provide the reader with additional information. The + information is not essential to the building of an implementation + conformant with this memo. The information is provided to + highlight a particular feature or characteristic of the memo. + + The format for the iCalendar object is based on the syntax of the + text/directory media type [RFC2425]. While the iCalendar object is + not a profile of the text/directory media type [RFC2425], it does + reuse a number of the elements from the [RFC2425] specification. + +2.1. Formatting Conventions + + The elements defined in this memo are defined in prose. Many of the + terms used to describe these have common usage that is different than + the standards usage of this memo. In order to reference, within this + memo, elements of the calendaring and scheduling model, core object + (this memo), or interoperability protocol [2446bis] some formatting + conventions have been used. Calendaring and scheduling roles are + referred to in quoted-strings of text with the first character of + each word in uppercase. For example, "Organizer" refers to a role of + a "Calendar User" within the scheduling protocol defined by + [2446bis]. Calendar components defined by this memo are referred to + + + +Desruisseaux Standards Track [Page 6] + +RFC 5545 iCalendar September 2009 + + + with capitalized, quoted-strings of text. All calendar components + start with the letter "V". For example, "VEVENT" refers to the event + calendar component, "VTODO" refers to the to-do calendar component, + and "VJOURNAL" refers to the daily journal calendar component. + Scheduling methods defined by iTIP [2446bis] are referred to with + capitalized, quoted-strings of text. For example, "REQUEST" refers + to the method for requesting a scheduling calendar component be + created or modified, and "REPLY" refers to the method a recipient of + a request uses to update their status with the "Organizer" of the + calendar component. + + The properties defined by this memo are referred to with capitalized, + quoted-strings of text, followed by the word "property". For + example, "ATTENDEE" property refers to the iCalendar property used to + convey the calendar address of a calendar user. Property parameters + defined by this memo are referred to with lowercase, quoted-strings + of text, followed by the word "parameter". For example, "value" + parameter refers to the iCalendar property parameter used to override + the default value type for a property value. Enumerated values + defined by this memo are referred to with capitalized text, either + alone or followed by the word "value". For example, the "MINUTELY" + value can be used with the "FREQ" component of the "RECUR" value type + to specify repeating components based on an interval of one minute or + more. + + The following table lists the different characters from the + [US-ASCII] character set that is referenced in this document. For + each character, the table specifies the character name used + throughout this document, along with its US-ASCII decimal codepoint. + + + + + + + + + + + + + + + + + + + + + + +Desruisseaux Standards Track [Page 7] + +RFC 5545 iCalendar September 2009 + + + +------------------------+-------------------+ + | Character name | Decimal codepoint | + +------------------------+-------------------+ + | HTAB | 9 | + | LF | 10 | + | CR | 13 | + | DQUOTE | 22 | + | SPACE | 32 | + | PLUS SIGN | 43 | + | COMMA | 44 | + | HYPHEN-MINUS | 45 | + | PERIOD | 46 | + | SOLIDUS | 47 | + | COLON | 58 | + | SEMICOLON | 59 | + | LATIN CAPITAL LETTER N | 78 | + | LATIN CAPITAL LETTER T | 84 | + | LATIN CAPITAL LETTER X | 88 | + | LATIN CAPITAL LETTER Z | 90 | + | BACKSLASH | 92 | + | LATIN SMALL LETTER N | 110 | + +------------------------+-------------------+ + +2.2. Related Memos + + Implementers will need to be familiar with several other memos that, + along with this memo, form a framework for Internet calendaring and + scheduling standards. This memo specifies a core specification of + objects, value types, properties, and property parameters. + + o iTIP [2446bis] specifies an interoperability protocol for + scheduling between different implementations; + + o iCalendar Message-Based Interoperability Protocol (iMIP) [2447bis] + specifies an Internet email binding for [2446bis]. + + This memo does not attempt to repeat the specification of concepts or + definitions from these other memos. Where possible, references are + made to the memo that provides for the specification of these + concepts or definitions. + +3. iCalendar Object Specification + + The following sections define the details of a Calendaring and + Scheduling Core Object Specification. The Calendaring and Scheduling + Core Object is a collection of calendaring and scheduling + information. Typically, this information will consist of an + iCalendar stream with one or more iCalendar objects. The body of the + + + +Desruisseaux Standards Track [Page 8] + +RFC 5545 iCalendar September 2009 + + + iCalendar object consists of a sequence of calendar properties and + one or more calendar components. + + Section 3.1 defines the content line format; Section 3.2 defines the + property parameter format; Section 3.3 defines the data types for + property values; Section 3.4 defines the iCalendar object format; + Section 3.5 defines the iCalendar property format; Section 3.6 + defines the calendar component format; Section 3.7 defines calendar + properties; and Section 3.8 defines calendar component properties. + + This information is intended to be an integral part of the MIME + content type registration. In addition, this information can be used + independent of such content registration. In particular, this memo + has direct applicability for use as a calendaring and scheduling + exchange format in file-, memory-, or network-based transport + mechanisms. + +3.1. Content Lines + + The iCalendar object is organized into individual lines of text, + called content lines. Content lines are delimited by a line break, + which is a CRLF sequence (CR character followed by LF character). + + Lines of text SHOULD NOT be longer than 75 octets, excluding the line + break. Long content lines SHOULD be split into a multiple line + representations using a line "folding" technique. That is, a long + line can be split between any two characters by inserting a CRLF + immediately followed by a single linear white-space character (i.e., + SPACE or HTAB). Any sequence of CRLF followed immediately by a + single linear white-space character is ignored (i.e., removed) when + processing the content type. + + For example, the line: + + DESCRIPTION:This is a long description that exists on a long line. + + Can be represented as: + + DESCRIPTION:This is a lo + ng description + that exists on a long line. + + The process of moving from this folded multiple-line representation + to its single-line representation is called "unfolding". Unfolding + is accomplished by removing the CRLF and the linear white-space + character that immediately follows. + + + + + +Desruisseaux Standards Track [Page 9] + +RFC 5545 iCalendar September 2009 + + + When parsing a content line, folded lines MUST first be unfolded + according to the unfolding procedure described above. + + Note: It is possible for very simple implementations to generate + improperly folded lines in the middle of a UTF-8 multi-octet + sequence. For this reason, implementations need to unfold lines + in such a way to properly restore the original sequence. + + The content information associated with an iCalendar object is + formatted using a syntax similar to that defined by [RFC2425]. That + is, the content information consists of CRLF-separated content lines. + + The following notation defines the lines of content in an iCalendar + object: + + contentline = name *(";" param ) ":" value CRLF + ; This ABNF is just a general definition for an initial parsing + ; of the content line into its property name, parameter list, + ; and value string + + ; When parsing a content line, folded lines MUST first + ; be unfolded according to the unfolding procedure + ; described above. When generating a content line, lines + ; longer than 75 octets SHOULD be folded according to + ; the folding procedure described above. + + name = iana-token / x-name + + iana-token = 1*(ALPHA / DIGIT / "-") + ; iCalendar identifier registered with IANA + + x-name = "X-" [vendorid "-"] 1*(ALPHA / DIGIT / "-") + ; Reserved for experimental use. + + vendorid = 3*(ALPHA / DIGIT) + ; Vendor identification + + param = param-name "=" param-value *("," param-value) + ; Each property defines the specific ABNF for the parameters + ; allowed on the property. Refer to specific properties for + ; precise parameter ABNF. + + param-name = iana-token / x-name + + param-value = paramtext / quoted-string + + paramtext = *SAFE-CHAR + + + + +Desruisseaux Standards Track [Page 10] + +RFC 5545 iCalendar September 2009 + + + value = *VALUE-CHAR + + quoted-string = DQUOTE *QSAFE-CHAR DQUOTE + + QSAFE-CHAR = WSP / %x21 / %x23-7E / NON-US-ASCII + ; Any character except CONTROL and DQUOTE + + SAFE-CHAR = WSP / %x21 / %x23-2B / %x2D-39 / %x3C-7E + / NON-US-ASCII + ; Any character except CONTROL, DQUOTE, ";", ":", "," + + VALUE-CHAR = WSP / %x21-7E / NON-US-ASCII + ; Any textual character + + NON-US-ASCII = UTF8-2 / UTF8-3 / UTF8-4 + ; UTF8-2, UTF8-3, and UTF8-4 are defined in [RFC3629] + + CONTROL = %x00-08 / %x0A-1F / %x7F + ; All the controls except HTAB + + The property value component of a content line has a format that is + property specific. Refer to the section describing each property for + a definition of this format. + + All names of properties, property parameters, enumerated property + values and property parameter values are case-insensitive. However, + all other property values are case-sensitive, unless otherwise + stated. + +3.1.1. List and Field Separators + + Some properties and parameters allow a list of values. Values in a + list of values MUST be separated by a COMMA character. There is no + significance to the order of values in a list. For those parameter + values (such as those that specify URI values) that are specified in + quoted-strings, the individual quoted-strings are separated by a + COMMA character. + + Some property values are defined in terms of multiple parts. These + structured property values MUST have their value parts separated by a + SEMICOLON character. + + Some properties allow a list of parameters. Each property parameter + in a list of property parameters MUST be separated by a SEMICOLON + character. + + + + + + +Desruisseaux Standards Track [Page 11] + +RFC 5545 iCalendar September 2009 + + + Property parameters with values containing a COLON character, a + SEMICOLON character or a COMMA character MUST be placed in quoted + text. + + For example, in the following properties, a SEMICOLON is used to + separate property parameters from each other and a COMMA character is + used to separate property values in a value list. + + ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT:mailto: + jsmith@example.com + + RDATE;VALUE=DATE:19970304,19970504,19970704,19970904 + +3.1.2. Multiple Values + + Some properties defined in the iCalendar object can have multiple + values. The general rule for encoding multi-valued items is to + simply create a new content line for each value, including the + property name. However, it should be noted that some properties + support encoding multiple values in a single property by separating + the values with a COMMA character. Individual property definitions + should be consulted for determining whether a specific property + allows multiple values and in which of these two forms. Multi-valued + properties MUST NOT be used to specify multiple language variants of + the same value. Calendar applications SHOULD display all values. + +3.1.3. Binary Content + + Binary content information in an iCalendar object SHOULD be + referenced using a URI within a property value. That is, the binary + content information SHOULD be placed in an external MIME entity that + can be referenced by a URI from within the iCalendar object. In + applications where this is not feasible, binary content information + can be included within an iCalendar object, but only after first + encoding it into text using the "BASE64" encoding method defined in + [RFC4648]. Inline binary content SHOULD only be used in applications + whose special circumstances demand that an iCalendar object be + expressed as a single entity. A property containing inline binary + content information MUST specify the "ENCODING" property parameter. + Binary content information placed external to the iCalendar object + MUST be referenced by a uniform resource identifier (URI). + + The following example specifies an "ATTACH" property that references + an attachment external to the iCalendar object with a URI reference: + + ATTACH:http://example.com/public/quarterly-report.doc + + + + + +Desruisseaux Standards Track [Page 12] + +RFC 5545 iCalendar September 2009 + + + The following example specifies an "ATTACH" property with inline + binary encoded content information: + + ATTACH;FMTTYPE=text/plain;ENCODING=BASE64;VALUE=BINARY:VGhlIH + F1aWNrIGJyb3duIGZveCBqdW1wcyBvdmVyIHRoZSBsYXp5IGRvZy4 + +3.1.4. Character Set + + There is not a property parameter to declare the charset used in a + property value. The default charset for an iCalendar stream is UTF-8 + as defined in [RFC3629]. + + The "charset" Content-Type parameter MUST be used in MIME transports + to specify the charset being used. + +3.2. Property Parameters + + A property can have attributes with which it is associated. These + "property parameters" contain meta-information about the property or + the property value. Property parameters are provided to specify such + information as the location of an alternate text representation for a + property value, the language of a text property value, the value type + of the property value, and other attributes. + + Property parameter values that contain the COLON, SEMICOLON, or COMMA + character separators MUST be specified as quoted-string text values. + Property parameter values MUST NOT contain the DQUOTE character. The + DQUOTE character is used as a delimiter for parameter values that + contain restricted characters or URI text. For example: + + DESCRIPTION;ALTREP="cid:part1.0001@example.org":The Fall'98 Wild + Wizards Conference - - Las Vegas\, NV\, USA + + Property parameter values that are not in quoted-strings are case- + insensitive. + + The general property parameters defined by this memo are defined by + the following notation: + + + + + + + + + + + + + +Desruisseaux Standards Track [Page 13] + +RFC 5545 iCalendar September 2009 + + + icalparameter = altrepparam ; Alternate text representation + / cnparam ; Common name + / cutypeparam ; Calendar user type + / delfromparam ; Delegator + / deltoparam ; Delegatee + / dirparam ; Directory entry + / encodingparam ; Inline encoding + / fmttypeparam ; Format type + / fbtypeparam ; Free/busy time type + / languageparam ; Language for text + / memberparam ; Group or list membership + / partstatparam ; Participation status + / rangeparam ; Recurrence identifier range + / trigrelparam ; Alarm trigger relationship + / reltypeparam ; Relationship type + / roleparam ; Participation role + / rsvpparam ; RSVP expectation + / sentbyparam ; Sent by + / tzidparam ; Reference to time zone object + / valuetypeparam ; Property value data type + / other-param + + other-param = (iana-param / x-param) + + iana-param = iana-token "=" param-value *("," param-value) + ; Some other IANA-registered iCalendar parameter. + + x-param = x-name "=" param-value *("," param-value) + ; A non-standard, experimental parameter. + + Applications MUST ignore x-param and iana-param values they don't + recognize. + +3.2.1. Alternate Text Representation + + Parameter Name: ALTREP + + Purpose: To specify an alternate text representation for the + property value. + + Format Definition: This property parameter is defined by the + following notation: + + altrepparam = "ALTREP" "=" DQUOTE uri DQUOTE + + Description: This parameter specifies a URI that points to an + alternate representation for a textual property value. A property + specifying this parameter MUST also include a value that reflects + + + +Desruisseaux Standards Track [Page 14] + +RFC 5545 iCalendar September 2009 + + + the default representation of the text value. The URI parameter + value MUST be specified in a quoted-string. + + Note: While there is no restriction imposed on the URI schemes + allowed for this parameter, Content Identifier (CID) [RFC2392], + HTTP [RFC2616], and HTTPS [RFC2818] are the URI schemes most + commonly used by current implementations. + + Example: + + DESCRIPTION;ALTREP="CID:part3.msg.970415T083000@example.com": + Project XYZ Review Meeting will include the following agenda + items: (a) Market Overview\, (b) Finances\, (c) Project Man + agement + + The "ALTREP" property parameter value might point to a "text/html" + content portion. + + Content-Type:text/html + Content-Id: + + + + + + +

+ Project XYZ Review Meeting will include + the following agenda items: +

    +
  1. Market Overview
    2. +
  2. Finances
    3. +
  3. Project Management
    4. +
+

+ + + +3.2.2. Common Name + + Parameter Name: CN + + Purpose: To specify the common name to be associated with the + calendar user specified by the property. + + Format Definition: This property parameter is defined by the + following notation: + + + + +Desruisseaux Standards Track [Page 15] + +RFC 5545 iCalendar September 2009 + + + cnparam = "CN" "=" param-value + + Description: This parameter can be specified on properties with a + CAL-ADDRESS value type. The parameter specifies the common name + to be associated with the calendar user specified by the property. + The parameter value is text. The parameter value can be used for + display text to be associated with the calendar address specified + by the property. + + Example: + + ORGANIZER;CN="John Smith":mailto:jsmith@example.com + +3.2.3. Calendar User Type + + Parameter Name: CUTYPE + + Purpose: To identify the type of calendar user specified by the + property. + + Format Definition: This property parameter is defined by the + following notation: + + cutypeparam = "CUTYPE" "=" + ("INDIVIDUAL" ; An individual + / "GROUP" ; A group of individuals + / "RESOURCE" ; A physical resource + / "ROOM" ; A room resource + / "UNKNOWN" ; Otherwise not known + / x-name ; Experimental type + / iana-token) ; Other IANA-registered + ; type + ; Default is INDIVIDUAL + + Description: This parameter can be specified on properties with a + CAL-ADDRESS value type. The parameter identifies the type of + calendar user specified by the property. If not specified on a + property that allows this parameter, the default is INDIVIDUAL. + Applications MUST treat x-name and iana-token values they don't + recognize the same way as they would the UNKNOWN value. + + Example: + + ATTENDEE;CUTYPE=GROUP:mailto:ietf-calsch@example.org + + + + + + + +Desruisseaux Standards Track [Page 16] + +RFC 5545 iCalendar September 2009 + + +3.2.4. Delegators + + Parameter Name: DELEGATED-FROM + + Purpose: To specify the calendar users that have delegated their + participation to the calendar user specified by the property. + + Format Definition: This property parameter is defined by the + following notation: + + delfromparam = "DELEGATED-FROM" "=" DQUOTE cal-address + DQUOTE *("," DQUOTE cal-address DQUOTE) + + Description: This parameter can be specified on properties with a + CAL-ADDRESS value type. This parameter specifies those calendar + users that have delegated their participation in a group-scheduled + event or to-do to the calendar user specified by the property. + The individual calendar address parameter values MUST each be + specified in a quoted-string. + + Example: + + ATTENDEE;DELEGATED-FROM="mailto:jsmith@example.com":mailto: + jdoe@example.com + +3.2.5. Delegatees + + Parameter Name: DELEGATED-TO + + Purpose: To specify the calendar users to whom the calendar user + specified by the property has delegated participation. + + Format Definition: This property parameter is defined by the + following notation: + + deltoparam = "DELEGATED-TO" "=" DQUOTE cal-address DQUOTE + *("," DQUOTE cal-address DQUOTE) + + Description: This parameter can be specified on properties with a + CAL-ADDRESS value type. This parameter specifies those calendar + users whom have been delegated participation in a group-scheduled + event or to-do by the calendar user specified by the property. + The individual calendar address parameter values MUST each be + specified in a quoted-string. + + + + + + + +Desruisseaux Standards Track [Page 17] + +RFC 5545 iCalendar September 2009 + + + Example: + + ATTENDEE;DELEGATED-TO="mailto:jdoe@example.com","mailto:jqpublic + @example.com":mailto:jsmith@example.com + +3.2.6. Directory Entry Reference + + Parameter Name: DIR + + Purpose: To specify reference to a directory entry associated with + the calendar user specified by the property. + + Format Definition: This property parameter is defined by the + following notation: + + dirparam = "DIR" "=" DQUOTE uri DQUOTE + + Description: This parameter can be specified on properties with a + CAL-ADDRESS value type. The parameter specifies a reference to + the directory entry associated with the calendar user specified by + the property. The parameter value is a URI. The URI parameter + value MUST be specified in a quoted-string. + + Note: While there is no restriction imposed on the URI schemes + allowed for this parameter, CID [RFC2392], DATA [RFC2397], FILE + [RFC1738], FTP [RFC1738], HTTP [RFC2616], HTTPS [RFC2818], LDAP + [RFC4516], and MID [RFC2392] are the URI schemes most commonly + used by current implementations. + + Example: + + ORGANIZER;DIR="ldap://example.com:6666/o=ABC%20Industries, + c=US???(cn=Jim%20Dolittle)":mailto:jimdo@example.com + +3.2.7. Inline Encoding + + Parameter Name: ENCODING + + Purpose: To specify an alternate inline encoding for the property + value. + + Format Definition: This property parameter is defined by the + following notation: + + + + + + + + +Desruisseaux Standards Track [Page 18] + +RFC 5545 iCalendar September 2009 + + + encodingparam = "ENCODING" "=" + ( "8BIT" + ; "8bit" text encoding is defined in [RFC2045] + / "BASE64" + ; "BASE64" binary encoding format is defined in [RFC4648] + ) + + Description: This property parameter identifies the inline encoding + used in a property value. The default encoding is "8BIT", + corresponding to a property value consisting of text. The + "BASE64" encoding type corresponds to a property value encoded + using the "BASE64" encoding defined in [RFC2045]. + + If the value type parameter is ";VALUE=BINARY", then the inline + encoding parameter MUST be specified with the value + ";ENCODING=BASE64". + + Example: + + ATTACH;FMTTYPE=text/plain;ENCODING=BASE64;VALUE=BINARY:TG9yZW + 0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2ljaW + 5nIGVsaXQsIHNlZCBkbyBlaXVzbW9kIHRlbXBvciBpbmNpZGlkdW50IHV0IG + xhYm9yZSBldCBkb2xvcmUgbWFnbmEgYWxpcXVhLiBVdCBlbmltIGFkIG1pbm + ltIHZlbmlhbSwgcXVpcyBub3N0cnVkIGV4ZXJjaXRhdGlvbiB1bGxhbWNvIG + xhYm9yaXMgbmlzaSB1dCBhbGlxdWlwIGV4IGVhIGNvbW1vZG8gY29uc2VxdW + F0LiBEdWlzIGF1dGUgaXJ1cmUgZG9sb3IgaW4gcmVwcmVoZW5kZXJpdCBpbi + B2b2x1cHRhdGUgdmVsaXQgZXNzZSBjaWxsdW0gZG9sb3JlIGV1IGZ1Z2lhdC + BudWxsYSBwYXJpYXR1ci4gRXhjZXB0ZXVyIHNpbnQgb2NjYWVjYXQgY3VwaW + RhdGF0IG5vbiBwcm9pZGVudCwgc3VudCBpbiBjdWxwYSBxdWkgb2ZmaWNpYS + BkZXNlcnVudCBtb2xsaXQgYW5pbSBpZCBlc3QgbGFib3J1bS4= + +3.2.8. Format Type + + Parameter Name: FMTTYPE + + Purpose: To specify the content type of a referenced object. + + Format Definition: This property parameter is defined by the + following notation: + + fmttypeparam = "FMTTYPE" "=" type-name "/" subtype-name + ; Where "type-name" and "subtype-name" are + ; defined in Section 4.2 of [RFC4288]. + + Description: This parameter can be specified on properties that are + used to reference an object. The parameter specifies the media + type [RFC4288] of the referenced object. For example, on the + "ATTACH" property, an FTP type URI value does not, by itself, + + + +Desruisseaux Standards Track [Page 19] + +RFC 5545 iCalendar September 2009 + + + necessarily convey the type of content associated with the + resource. The parameter value MUST be the text for either an + IANA-registered media type or a non-standard media type. + + Example: + + ATTACH;FMTTYPE=application/msword:ftp://example.com/pub/docs/ + agenda.doc + +3.2.9. Free/Busy Time Type + + Parameter Name: FBTYPE + + Purpose: To specify the free or busy time type. + + Format Definition: This property parameter is defined by the + following notation: + + fbtypeparam = "FBTYPE" "=" ("FREE" / "BUSY" + / "BUSY-UNAVAILABLE" / "BUSY-TENTATIVE" + / x-name + ; Some experimental iCalendar free/busy type. + / iana-token) + ; Some other IANA-registered iCalendar free/busy type. + + Description: This parameter specifies the free or busy time type. + The value FREE indicates that the time interval is free for + scheduling. The value BUSY indicates that the time interval is + busy because one or more events have been scheduled for that + interval. The value BUSY-UNAVAILABLE indicates that the time + interval is busy and that the interval can not be scheduled. The + value BUSY-TENTATIVE indicates that the time interval is busy + because one or more events have been tentatively scheduled for + that interval. If not specified on a property that allows this + parameter, the default is BUSY. Applications MUST treat x-name + and iana-token values they don't recognize the same way as they + would the BUSY value. + + Example: The following is an example of this parameter on a + "FREEBUSY" property. + + FREEBUSY;FBTYPE=BUSY:19980415T133000Z/19980415T170000Z + + + + + + + + + +Desruisseaux Standards Track [Page 20] + +RFC 5545 iCalendar September 2009 + + +3.2.10. Language + + Parameter Name: LANGUAGE + + Purpose: To specify the language for text values in a property or + property parameter. + + Format Definition: This property parameter is defined by the + following notation: + + languageparam = "LANGUAGE" "=" language + + language = Language-Tag + ; As defined in [RFC5646]. + + Description: This parameter identifies the language of the text in + the property value and of all property parameter values of the + property. The value of the "LANGUAGE" property parameter is that + defined in [RFC5646]. + + For transport in a MIME entity, the Content-Language header field + can be used to set the default language for the entire body part. + Otherwise, no default language is assumed. + + Example: The following are examples of this parameter on the + "SUMMARY" and "LOCATION" properties: + + SUMMARY;LANGUAGE=en-US:Company Holiday Party + + LOCATION;LANGUAGE=en:Germany + + LOCATION;LANGUAGE=no:Tyskland + +3.2.11. Group or List Membership + + Parameter Name: MEMBER + + Purpose: To specify the group or list membership of the calendar + user specified by the property. + + Format Definition: This property parameter is defined by the + following notation: + + memberparam = "MEMBER" "=" DQUOTE cal-address DQUOTE + *("," DQUOTE cal-address DQUOTE) + + + + + + +Desruisseaux Standards Track [Page 21] + +RFC 5545 iCalendar September 2009 + + + Description: This parameter can be specified on properties with a + CAL-ADDRESS value type. The parameter identifies the groups or + list membership for the calendar user specified by the property. + The parameter value is either a single calendar address in a + quoted-string or a COMMA-separated list of calendar addresses, + each in a quoted-string. The individual calendar address + parameter values MUST each be specified in a quoted-string. + + Example: + + ATTENDEE;MEMBER="mailto:ietf-calsch@example.org":mailto: + jsmith@example.com + + ATTENDEE;MEMBER="mailto:projectA@example.com","mailto:pr + ojectB@example.com":mailto:janedoe@example.com + +3.2.12. Participation Status + + Parameter Name: PARTSTAT + + Purpose: To specify the participation status for the calendar user + specified by the property. + + Format Definition: This property parameter is defined by the + following notation: + + partstatparam = "PARTSTAT" "=" + (partstat-event + / partstat-todo + / partstat-jour) + + partstat-event = ("NEEDS-ACTION" ; Event needs action + / "ACCEPTED" ; Event accepted + / "DECLINED" ; Event declined + / "TENTATIVE" ; Event tentatively + ; accepted + / "DELEGATED" ; Event delegated + / x-name ; Experimental status + / iana-token) ; Other IANA-registered + ; status + ; These are the participation statuses for a "VEVENT". + ; Default is NEEDS-ACTION. + + partstat-todo = ("NEEDS-ACTION" ; To-do needs action + / "ACCEPTED" ; To-do accepted + / "DECLINED" ; To-do declined + / "TENTATIVE" ; To-do tentatively + ; accepted + + + +Desruisseaux Standards Track [Page 22] + +RFC 5545 iCalendar September 2009 + + + / "DELEGATED" ; To-do delegated + / "COMPLETED" ; To-do completed + ; COMPLETED property has + ; DATE-TIME completed + / "IN-PROCESS" ; To-do in process of + ; being completed + / x-name ; Experimental status + / iana-token) ; Other IANA-registered + ; status + ; These are the participation statuses for a "VTODO". + ; Default is NEEDS-ACTION. + + + + partstat-jour = ("NEEDS-ACTION" ; Journal needs action + / "ACCEPTED" ; Journal accepted + / "DECLINED" ; Journal declined + / x-name ; Experimental status + / iana-token) ; Other IANA-registered + ; status + ; These are the participation statuses for a "VJOURNAL". + ; Default is NEEDS-ACTION. + + Description: This parameter can be specified on properties with a + CAL-ADDRESS value type. The parameter identifies the + participation status for the calendar user specified by the + property value. The parameter values differ depending on whether + they are associated with a group-scheduled "VEVENT", "VTODO", or + "VJOURNAL". The values MUST match one of the values allowed for + the given calendar component. If not specified on a property that + allows this parameter, the default value is NEEDS-ACTION. + Applications MUST treat x-name and iana-token values they don't + recognize the same way as they would the NEEDS-ACTION value. + + Example: + + ATTENDEE;PARTSTAT=DECLINED:mailto:jsmith@example.com + +3.2.13. Recurrence Identifier Range + + Parameter Name: RANGE + + Purpose: To specify the effective range of recurrence instances from + the instance specified by the recurrence identifier specified by + the property. + + Format Definition: This property parameter is defined by the + following notation: + + + +Desruisseaux Standards Track [Page 23] + +RFC 5545 iCalendar September 2009 + + + rangeparam = "RANGE" "=" "THISANDFUTURE" + ; To specify the instance specified by the recurrence identifier + ; and all subsequent recurrence instances. + + Description: This parameter can be specified on a property that + specifies a recurrence identifier. The parameter specifies the + effective range of recurrence instances that is specified by the + property. The effective range is from the recurrence identifier + specified by the property. If this parameter is not specified on + an allowed property, then the default range is the single instance + specified by the recurrence identifier value of the property. The + parameter value can only be "THISANDFUTURE" to indicate a range + defined by the recurrence identifier and all subsequent instances. + The value "THISANDPRIOR" is deprecated by this revision of + iCalendar and MUST NOT be generated by applications. + + Example: + + RECURRENCE-ID;RANGE=THISANDFUTURE:19980401T133000Z + +3.2.14. Alarm Trigger Relationship + + Parameter Name: RELATED + + Purpose: To specify the relationship of the alarm trigger with + respect to the start or end of the calendar component. + + Format Definition: This property parameter is defined by the + following notation: + + trigrelparam = "RELATED" "=" + ("START" ; Trigger off of start + / "END") ; Trigger off of end + + Description: This parameter can be specified on properties that + specify an alarm trigger with a "DURATION" value type. The + parameter specifies whether the alarm will trigger relative to the + start or end of the calendar component. The parameter value START + will set the alarm to trigger off the start of the calendar + component; the parameter value END will set the alarm to trigger + off the end of the calendar component. If the parameter is not + specified on an allowable property, then the default is START. + + Example: + + TRIGGER;RELATED=END:PT5M + + + + + +Desruisseaux Standards Track [Page 24] + +RFC 5545 iCalendar September 2009 + + +3.2.15. Relationship Type + + Parameter Name: RELTYPE + + Purpose: To specify the type of hierarchical relationship associated + with the calendar component specified by the property. + + Format Definition: This property parameter is defined by the + following notation: + + reltypeparam = "RELTYPE" "=" + ("PARENT" ; Parent relationship - Default + / "CHILD" ; Child relationship + / "SIBLING" ; Sibling relationship + / iana-token ; Some other IANA-registered + ; iCalendar relationship type + / x-name) ; A non-standard, experimental + ; relationship type + + Description: This parameter can be specified on a property that + references another related calendar. The parameter specifies the + hierarchical relationship type of the calendar component + referenced by the property. The parameter value can be PARENT, to + indicate that the referenced calendar component is a superior of + calendar component; CHILD to indicate that the referenced calendar + component is a subordinate of the calendar component; or SIBLING + to indicate that the referenced calendar component is a peer of + the calendar component. If this parameter is not specified on an + allowable property, the default relationship type is PARENT. + Applications MUST treat x-name and iana-token values they don't + recognize the same way as they would the PARENT value. + + Example: + + RELATED-TO;RELTYPE=SIBLING:19960401-080045-4000F192713@ + example.com + +3.2.16. Participation Role + + Parameter Name: ROLE + + Purpose: To specify the participation role for the calendar user + specified by the property. + + Format Definition: This property parameter is defined by the + following notation: + + + + + +Desruisseaux Standards Track [Page 25] + +RFC 5545 iCalendar September 2009 + + + roleparam = "ROLE" "=" + ("CHAIR" ; Indicates chair of the + ; calendar entity + / "REQ-PARTICIPANT" ; Indicates a participant whose + ; participation is required + / "OPT-PARTICIPANT" ; Indicates a participant whose + ; participation is optional + / "NON-PARTICIPANT" ; Indicates a participant who + ; is copied for information + ; purposes only + / x-name ; Experimental role + / iana-token) ; Other IANA role + ; Default is REQ-PARTICIPANT + + Description: This parameter can be specified on properties with a + CAL-ADDRESS value type. The parameter specifies the participation + role for the calendar user specified by the property in the group + schedule calendar component. If not specified on a property that + allows this parameter, the default value is REQ-PARTICIPANT. + Applications MUST treat x-name and iana-token values they don't + recognize the same way as they would the REQ-PARTICIPANT value. + + Example: + + ATTENDEE;ROLE=CHAIR:mailto:mrbig@example.com + +3.2.17. RSVP Expectation + + Parameter Name: RSVP + + Purpose: To specify whether there is an expectation of a favor of a + reply from the calendar user specified by the property value. + + Format Definition: This property parameter is defined by the + following notation: + + rsvpparam = "RSVP" "=" ("TRUE" / "FALSE") + ; Default is FALSE + + Description: This parameter can be specified on properties with a + CAL-ADDRESS value type. The parameter identifies the expectation + of a reply from the calendar user specified by the property value. + This parameter is used by the "Organizer" to request a + participation status reply from an "Attendee" of a group-scheduled + event or to-do. If not specified on a property that allows this + parameter, the default value is FALSE. + + + + + +Desruisseaux Standards Track [Page 26] + +RFC 5545 iCalendar September 2009 + + + Example: + + ATTENDEE;RSVP=TRUE:mailto:jsmith@example.com + +3.2.18. Sent By + + Parameter Name: SENT-BY + + Purpose: To specify the calendar user that is acting on behalf of + the calendar user specified by the property. + + Format Definition: This property parameter is defined by the + following notation: + + sentbyparam = "SENT-BY" "=" DQUOTE cal-address DQUOTE + + Description: This parameter can be specified on properties with a + CAL-ADDRESS value type. The parameter specifies the calendar user + that is acting on behalf of the calendar user specified by the + property. The parameter value MUST be a mailto URI as defined in + [RFC2368]. The individual calendar address parameter values MUST + each be specified in a quoted-string. + + Example: + + ORGANIZER;SENT-BY="mailto:sray@example.com":mailto: + jsmith@example.com + +3.2.19. Time Zone Identifier + + Parameter Name: TZID + + Purpose: To specify the identifier for the time zone definition for + a time component in the property value. + + Format Definition: This property parameter is defined by the + following notation: + + tzidparam = "TZID" "=" [tzidprefix] paramtext + + tzidprefix = "/" + + Description: This parameter MUST be specified on the "DTSTART", + "DTEND", "DUE", "EXDATE", and "RDATE" properties when either a + DATE-TIME or TIME value type is specified and when the value is + neither a UTC or a "floating" time. Refer to the DATE-TIME or + TIME value type definition for a description of UTC and "floating + time" formats. This property parameter specifies a text value + + + +Desruisseaux Standards Track [Page 27] + +RFC 5545 iCalendar September 2009 + + + that uniquely identifies the "VTIMEZONE" calendar component to be + used when evaluating the time portion of the property. The value + of the "TZID" property parameter will be equal to the value of the + "TZID" property for the matching time zone definition. An + individual "VTIMEZONE" calendar component MUST be specified for + each unique "TZID" parameter value specified in the iCalendar + object. + + The parameter MUST be specified on properties with a DATE-TIME + value if the DATE-TIME is not either a UTC or a "floating" time. + Failure to include and follow VTIMEZONE definitions in iCalendar + objects may lead to inconsistent understanding of the local time + at any given location. + + The presence of the SOLIDUS character as a prefix, indicates that + this "TZID" represents a unique ID in a globally defined time zone + registry (when such registry is defined). + + Note: This document does not define a naming convention for + time zone identifiers. Implementers may want to use the naming + conventions defined in existing time zone specifications such + as the public-domain TZ database [TZDB]. The specification of + globally unique time zone identifiers is not addressed by this + document and is left for future study. + + The following are examples of this property parameter: + + DTSTART;TZID=America/New_York:19980119T020000 + + DTEND;TZID=America/New_York:19980119T030000 + + The "TZID" property parameter MUST NOT be applied to DATE + properties and DATE-TIME or TIME properties whose time values are + specified in UTC. + + The use of local time in a DATE-TIME or TIME value without the + "TZID" property parameter is to be interpreted as floating time, + regardless of the existence of "VTIMEZONE" calendar components in + the iCalendar object. + + For more information, see the sections on the value types DATE- + TIME and TIME. + + + + + + + + + +Desruisseaux Standards Track [Page 28] + +RFC 5545 iCalendar September 2009 + + +3.2.20. Value Data Types + + Parameter Name: VALUE + + Purpose: To explicitly specify the value type format for a property + value. + + Format Definition: This property parameter is defined by the + following notation: + + valuetypeparam = "VALUE" "=" valuetype + + valuetype = ("BINARY" + / "BOOLEAN" + / "CAL-ADDRESS" + / "DATE" + / "DATE-TIME" + / "DURATION" + / "FLOAT" + / "INTEGER" + / "PERIOD" + / "RECUR" + / "TEXT" + / "TIME" + / "URI" + / "UTC-OFFSET" + / x-name + ; Some experimental iCalendar value type. + / iana-token) + ; Some other IANA-registered iCalendar value type. + + Description: This parameter specifies the value type and format of + the property value. The property values MUST be of a single value + type. For example, a "RDATE" property cannot have a combination + of DATE-TIME and TIME value types. + + If the property's value is the default value type, then this + parameter need not be specified. However, if the property's + default value type is overridden by some other allowable value + type, then this parameter MUST be specified. + + Applications MUST preserve the value data for x-name and iana- + token values that they don't recognize without attempting to + interpret or parse the value data. + + + + + + + +Desruisseaux Standards Track [Page 29] + +RFC 5545 iCalendar September 2009 + + +3.3. Property Value Data Types + + The properties in an iCalendar object are strongly typed. The + definition of each property restricts the value to be one of the + value data types, or simply value types, defined in this section. + The value type for a property will either be specified implicitly as + the default value type or will be explicitly specified with the + "VALUE" parameter. If the value type of a property is one of the + alternate valid types, then it MUST be explicitly specified with the + "VALUE" parameter. + +3.3.1. Binary + + Value Name: BINARY + + Purpose: This value type is used to identify properties that contain + a character encoding of inline binary data. For example, an + inline attachment of a document might be included in an iCalendar + object. + + Format Definition: This value type is defined by the following + notation: + + binary = *(4b-char) [b-end] + ; A "BASE64" encoded character string, as defined by [RFC4648]. + + b-end = (2b-char "==") / (3b-char "=") + + b-char = ALPHA / DIGIT / "+" / "/" + + Description: Property values with this value type MUST also include + the inline encoding parameter sequence of ";ENCODING=BASE64". + That is, all inline binary data MUST first be character encoded + using the "BASE64" encoding method defined in [RFC2045]. No + additional content value encoding (i.e., BACKSLASH character + encoding, see Section 3.3.11) is defined for this value type. + + + + + + + + + + + + + + + +Desruisseaux Standards Track [Page 30] + +RFC 5545 iCalendar September 2009 + + + Example: The following is an example of a "BASE64" encoded binary + value data: + + ATTACH;FMTTYPE=image/vnd.microsoft.icon;ENCODING=BASE64;VALUE + =BINARY:AAABAAEAEBAQAAEABAAoAQAAFgAAACgAAAAQAAAAIAAAAAEABAAA + AAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAAAAgIAAAICAgADAwMAA////AAAA + AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA + AAAAAAAAAAAAAAAAAAAAAAMwAAAAAAABNEMQAAAAAAAkQgAAAAAAJEREQgAA + ACECQ0QgEgAAQxQzM0E0AABERCRCREQAADRDJEJEQwAAAhA0QwEQAAAAAERE + AAAAAAAAREQAAAAAAAAkQgAAAAAAAAMgAAAAAAAAAAAAAAAAAAAAAAAAAAAA + AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA + AAAAAAAAAAAA + +3.3.2. Boolean + + Value Name: BOOLEAN + + Purpose: This value type is used to identify properties that contain + either a "TRUE" or "FALSE" Boolean value. + + Format Definition: This value type is defined by the following + notation: + + boolean = "TRUE" / "FALSE" + + Description: These values are case-insensitive text. No additional + content value encoding (i.e., BACKSLASH character encoding, see + Section 3.3.11) is defined for this value type. + + Example: The following is an example of a hypothetical property that + has a BOOLEAN value type: + + TRUE + +3.3.3. Calendar User Address + + Value Name: CAL-ADDRESS + + Purpose: This value type is used to identify properties that contain + a calendar user address. + + Format Definition: This value type is defined by the following + notation: + + cal-address = uri + + Description: The value is a URI as defined by [RFC3986] or any other + IANA-registered form for a URI. When used to address an Internet + + + +Desruisseaux Standards Track [Page 31] + +RFC 5545 iCalendar September 2009 + + + email transport address for a calendar user, the value MUST be a + mailto URI, as defined by [RFC2368]. No additional content value + encoding (i.e., BACKSLASH character encoding, see Section 3.3.11) + is defined for this value type. + + Example: + + mailto:jane_doe@example.com + +3.3.4. Date + + Value Name: DATE + + Purpose: This value type is used to identify values that contain a + calendar date. + + Format Definition: This value type is defined by the following + notation: + + date = date-value + + date-value = date-fullyear date-month date-mday + date-fullyear = 4DIGIT + date-month = 2DIGIT ;01-12 + date-mday = 2DIGIT ;01-28, 01-29, 01-30, 01-31 + ;based on month/year + + Description: If the property permits, multiple "date" values are + specified as a COMMA-separated list of values. The format for the + value type is based on the [ISO.8601.2004] complete + representation, basic format for a calendar date. The textual + format specifies a four-digit year, two-digit month, and two-digit + day of the month. There are no separator characters between the + year, month, and day component text. + + No additional content value encoding (i.e., BACKSLASH character + encoding, see Section 3.3.11) is defined for this value type. + + Example: The following represents July 14, 1997: + + 19970714 + +3.3.5. Date-Time + + Value Name: DATE-TIME + + Purpose: This value type is used to identify values that specify a + precise calendar date and time of day. + + + +Desruisseaux Standards Track [Page 32] + +RFC 5545 iCalendar September 2009 + + + Format Definition: This value type is defined by the following + notation: + + date-time = date "T" time ;As specified in the DATE and TIME + ;value definitions + + Description: If the property permits, multiple "DATE-TIME" values + are specified as a COMMA-separated list of values. No additional + content value encoding (i.e., BACKSLASH character encoding, see + Section 3.3.11) is defined for this value type. + + The "DATE-TIME" value type is used to identify values that contain + a precise calendar date and time of day. The format is based on + the [ISO.8601.2004] complete representation, basic format for a + calendar date and time of day. The text format is a concatenation + of the "date", followed by the LATIN CAPITAL LETTER T character, + the time designator, followed by the "time" format. + + The "DATE-TIME" value type expresses time values in three forms: + + The form of date and time with UTC offset MUST NOT be used. For + example, the following is not valid for a DATE-TIME value: + + 19980119T230000-0800 ;Invalid time format + + FORM #1: DATE WITH LOCAL TIME + + The date with local time form is simply a DATE-TIME value that + does not contain the UTC designator nor does it reference a time + zone. For example, the following represents January 18, 1998, at + 11 PM: + + 19980118T230000 + + DATE-TIME values of this type are said to be "floating" and are + not bound to any time zone in particular. They are used to + represent the same hour, minute, and second value regardless of + which time zone is currently being observed. For example, an + event can be defined that indicates that an individual will be + busy from 11:00 AM to 1:00 PM every day, no matter which time zone + the person is in. In these cases, a local time can be specified. + The recipient of an iCalendar object with a property value + consisting of a local time, without any relative time zone + information, SHOULD interpret the value as being fixed to whatever + time zone the "ATTENDEE" is in at any given moment. This means + that two "Attendees", in different time zones, receiving the same + event definition as a floating time, may be participating in the + + + + +Desruisseaux Standards Track [Page 33] + +RFC 5545 iCalendar September 2009 + + + event at different actual times. Floating time SHOULD only be + used where that is the reasonable behavior. + + In most cases, a fixed time is desired. To properly communicate a + fixed time in a property value, either UTC time or local time with + time zone reference MUST be specified. + + The use of local time in a DATE-TIME value without the "TZID" + property parameter is to be interpreted as floating time, + regardless of the existence of "VTIMEZONE" calendar components in + the iCalendar object. + + FORM #2: DATE WITH UTC TIME + + The date with UTC time, or absolute time, is identified by a LATIN + CAPITAL LETTER Z suffix character, the UTC designator, appended to + the time value. For example, the following represents January 19, + 1998, at 0700 UTC: + + 19980119T070000Z + + The "TZID" property parameter MUST NOT be applied to DATE-TIME + properties whose time values are specified in UTC. + + FORM #3: DATE WITH LOCAL TIME AND TIME ZONE REFERENCE + + The date and local time with reference to time zone information is + identified by the use the "TZID" property parameter to reference + the appropriate time zone definition. "TZID" is discussed in + detail in Section 3.2.19. For example, the following represents + 2:00 A.M. in New York on January 19, 1998: + + TZID=America/New_York:19980119T020000 + + If, based on the definition of the referenced time zone, the local + time described occurs more than once (when changing from daylight + to standard time), the DATE-TIME value refers to the first + occurrence of the referenced time. Thus, TZID=America/ + New_York:20071104T013000 indicates November 4, 2007 at 1:30 A.M. + EDT (UTC-04:00). If the local time described does not occur (when + changing from standard to daylight time), the DATE-TIME value is + interpreted using the UTC offset before the gap in local times. + Thus, TZID=America/New_York:20070311T023000 indicates March 11, + 2007 at 3:30 A.M. EDT (UTC-04:00), one hour after 1:30 A.M. EST + (UTC-05:00). + + + + + + +Desruisseaux Standards Track [Page 34] + +RFC 5545 iCalendar September 2009 + + + A time value MUST only specify the second 60 when specifying a + positive leap second. For example: + + 19970630T235960Z + + Implementations that do not support leap seconds SHOULD interpret + the second 60 as equivalent to the second 59. + + Example: The following represents July 14, 1997, at 1:30 PM in New + York City in each of the three time formats, using the "DTSTART" + property. + + DTSTART:19970714T133000 ; Local time + DTSTART:19970714T173000Z ; UTC time + DTSTART;TZID=America/New_York:19970714T133000 + ; Local time and time + ; zone reference + +3.3.6. Duration + + Value Name: DURATION + + Purpose: This value type is used to identify properties that contain + a duration of time. + + Format Definition: This value type is defined by the following + notation: + + dur-value = (["+"] / "-") "P" (dur-date / dur-time / dur-week) + + dur-date = dur-day [dur-time] + dur-time = "T" (dur-hour / dur-minute / dur-second) + dur-week = 1*DIGIT "W" + dur-hour = 1*DIGIT "H" [dur-minute] + dur-minute = 1*DIGIT "M" [dur-second] + dur-second = 1*DIGIT "S" + dur-day = 1*DIGIT "D" + + Description: If the property permits, multiple "duration" values are + specified by a COMMA-separated list of values. The format is + based on the [ISO.8601.2004] complete representation basic format + with designators for the duration of time. The format can + represent nominal durations (weeks and days) and accurate + durations (hours, minutes, and seconds). Note that unlike + [ISO.8601.2004], this value type doesn't support the "Y" and "M" + designators to specify durations in terms of years and months. + + + + + +Desruisseaux Standards Track [Page 35] + +RFC 5545 iCalendar September 2009 + + + The duration of a week or a day depends on its position in the + calendar. In the case of discontinuities in the time scale, such + as the change from standard time to daylight time and back, the + computation of the exact duration requires the subtraction or + addition of the change of duration of the discontinuity. Leap + seconds MUST NOT be considered when computing an exact duration. + When computing an exact duration, the greatest order time + components MUST be added first, that is, the number of days MUST + be added first, followed by the number of hours, number of + minutes, and number of seconds. + + Negative durations are typically used to schedule an alarm to + trigger before an associated time (see Section 3.8.6.3). + + No additional content value encoding (i.e., BACKSLASH character + encoding, see Section 3.3.11) are defined for this value type. + + Example: A duration of 15 days, 5 hours, and 20 seconds would be: + + P15DT5H0M20S + + A duration of 7 weeks would be: + + P7W + +3.3.7. Float + + Value Name: FLOAT + + Purpose: This value type is used to identify properties that contain + a real-number value. + + Format Definition: This value type is defined by the following + notation: + + float = (["+"] / "-") 1*DIGIT ["." 1*DIGIT] + + Description: If the property permits, multiple "float" values are + specified by a COMMA-separated list of values. + + No additional content value encoding (i.e., BACKSLASH character + encoding, see Section 3.3.11) is defined for this value type. + + Example: + + 1000000.0000001 + 1.333 + -3.14 + + + +Desruisseaux Standards Track [Page 36] + +RFC 5545 iCalendar September 2009 + + +3.3.8. Integer + + Value Name: INTEGER + + Purpose: This value type is used to identify properties that contain + a signed integer value. + + Format Definition: This value type is defined by the following + notation: + + integer = (["+"] / "-") 1*DIGIT + + Description: If the property permits, multiple "integer" values are + specified by a COMMA-separated list of values. The valid range + for "integer" is -2147483648 to 2147483647. If the sign is not + specified, then the value is assumed to be positive. + + No additional content value encoding (i.e., BACKSLASH character + encoding, see Section 3.3.11) is defined for this value type. + + Example: + + 1234567890 + -1234567890 + +1234567890 + 432109876 + +3.3.9. Period of Time + + Value Name: PERIOD + + Purpose: This value type is used to identify values that contain a + precise period of time. + + Format Definition: This value type is defined by the following + notation: + + period = period-explicit / period-start + + period-explicit = date-time "/" date-time + ; [ISO.8601.2004] complete representation basic format for a + ; period of time consisting of a start and end. The start MUST + ; be before the end. + + period-start = date-time "/" dur-value + ; [ISO.8601.2004] complete representation basic format for a + ; period of time consisting of a start and positive duration + ; of time. + + + +Desruisseaux Standards Track [Page 37] + +RFC 5545 iCalendar September 2009 + + + Description: If the property permits, multiple "period" values are + specified by a COMMA-separated list of values. There are two + forms of a period of time. First, a period of time is identified + by its start and its end. This format is based on the + [ISO.8601.2004] complete representation, basic format for "DATE- + TIME" start of the period, followed by a SOLIDUS character + followed by the "DATE-TIME" of the end of the period. The start + of the period MUST be before the end of the period. Second, a + period of time can also be defined by a start and a positive + duration of time. The format is based on the [ISO.8601.2004] + complete representation, basic format for the "DATE-TIME" start of + the period, followed by a SOLIDUS character, followed by the + [ISO.8601.2004] basic format for "DURATION" of the period. + + Example: The period starting at 18:00:00 UTC, on January 1, 1997 and + ending at 07:00:00 UTC on January 2, 1997 would be: + + 19970101T180000Z/19970102T070000Z + + The period start at 18:00:00 on January 1, 1997 and lasting 5 + hours and 30 minutes would be: + + 19970101T180000Z/PT5H30M + + No additional content value encoding (i.e., BACKSLASH character + encoding, see Section 3.3.11) is defined for this value type. + +3.3.10. Recurrence Rule + + Value Name: RECUR + + Purpose: This value type is used to identify properties that contain + a recurrence rule specification. + + Format Definition: This value type is defined by the following + notation: + + recur = recur-rule-part *( ";" recur-rule-part ) + ; + ; The rule parts are not ordered in any + ; particular sequence. + ; + ; The FREQ rule part is REQUIRED, + ; but MUST NOT occur more than once. + ; + ; The UNTIL or COUNT rule parts are OPTIONAL, + ; but they MUST NOT occur in the same 'recur'. + ; + + + +Desruisseaux Standards Track [Page 38] + +RFC 5545 iCalendar September 2009 + + + ; The other rule parts are OPTIONAL, + ; but MUST NOT occur more than once. + + recur-rule-part = ( "FREQ" "=" freq ) + / ( "UNTIL" "=" enddate ) + / ( "COUNT" "=" 1*DIGIT ) + / ( "INTERVAL" "=" 1*DIGIT ) + / ( "BYSECOND" "=" byseclist ) + / ( "BYMINUTE" "=" byminlist ) + / ( "BYHOUR" "=" byhrlist ) + / ( "BYDAY" "=" bywdaylist ) + / ( "BYMONTHDAY" "=" bymodaylist ) + / ( "BYYEARDAY" "=" byyrdaylist ) + / ( "BYWEEKNO" "=" bywknolist ) + / ( "BYMONTH" "=" bymolist ) + / ( "BYSETPOS" "=" bysplist ) + / ( "WKST" "=" weekday ) + + freq = "SECONDLY" / "MINUTELY" / "HOURLY" / "DAILY" + / "WEEKLY" / "MONTHLY" / "YEARLY" + + enddate = date / date-time + + byseclist = ( seconds *("," seconds) ) + + seconds = 1*2DIGIT ;0 to 60 + + byminlist = ( minutes *("," minutes) ) + + minutes = 1*2DIGIT ;0 to 59 + + byhrlist = ( hour *("," hour) ) + + hour = 1*2DIGIT ;0 to 23 + + bywdaylist = ( weekdaynum *("," weekdaynum) ) + + weekdaynum = [[plus / minus] ordwk] weekday + + plus = "+" + + minus = "-" + + ordwk = 1*2DIGIT ;1 to 53 + + weekday = "SU" / "MO" / "TU" / "WE" / "TH" / "FR" / "SA" + ;Corresponding to SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, + ;FRIDAY, and SATURDAY days of the week. + + + +Desruisseaux Standards Track [Page 39] + +RFC 5545 iCalendar September 2009 + + + bymodaylist = ( monthdaynum *("," monthdaynum) ) + + monthdaynum = [plus / minus] ordmoday + + ordmoday = 1*2DIGIT ;1 to 31 + + byyrdaylist = ( yeardaynum *("," yeardaynum) ) + + yeardaynum = [plus / minus] ordyrday + + ordyrday = 1*3DIGIT ;1 to 366 + + bywknolist = ( weeknum *("," weeknum) ) + + weeknum = [plus / minus] ordwk + + bymolist = ( monthnum *("," monthnum) ) + + monthnum = 1*2DIGIT ;1 to 12 + + bysplist = ( setposday *("," setposday) ) + + setposday = yeardaynum + + Description: This value type is a structured value consisting of a + list of one or more recurrence grammar parts. Each rule part is + defined by a NAME=VALUE pair. The rule parts are separated from + each other by the SEMICOLON character. The rule parts are not + ordered in any particular sequence. Individual rule parts MUST + only be specified once. Compliant applications MUST accept rule + parts ordered in any sequence, but to ensure backward + compatibility with applications that pre-date this revision of + iCalendar the FREQ rule part MUST be the first rule part specified + in a RECUR value. + + The FREQ rule part identifies the type of recurrence rule. This + rule part MUST be specified in the recurrence rule. Valid values + include SECONDLY, to specify repeating events based on an interval + of a second or more; MINUTELY, to specify repeating events based + on an interval of a minute or more; HOURLY, to specify repeating + events based on an interval of an hour or more; DAILY, to specify + repeating events based on an interval of a day or more; WEEKLY, to + specify repeating events based on an interval of a week or more; + MONTHLY, to specify repeating events based on an interval of a + month or more; and YEARLY, to specify repeating events based on an + interval of a year or more. + + + + + +Desruisseaux Standards Track [Page 40] + +RFC 5545 iCalendar September 2009 + + + The INTERVAL rule part contains a positive integer representing at + which intervals the recurrence rule repeats. The default value is + "1", meaning every second for a SECONDLY rule, every minute for a + MINUTELY rule, every hour for an HOURLY rule, every day for a + DAILY rule, every week for a WEEKLY rule, every month for a + MONTHLY rule, and every year for a YEARLY rule. For example, + within a DAILY rule, a value of "8" means every eight days. + + The UNTIL rule part defines a DATE or DATE-TIME value that bounds + the recurrence rule in an inclusive manner. If the value + specified by UNTIL is synchronized with the specified recurrence, + this DATE or DATE-TIME becomes the last instance of the + recurrence. The value of the UNTIL rule part MUST have the same + value type as the "DTSTART" property. Furthermore, if the + "DTSTART" property is specified as a date with local time, then + the UNTIL rule part MUST also be specified as a date with local + time. If the "DTSTART" property is specified as a date with UTC + time or a date with local time and time zone reference, then the + UNTIL rule part MUST be specified as a date with UTC time. In the + case of the "STANDARD" and "DAYLIGHT" sub-components the UNTIL + rule part MUST always be specified as a date with UTC time. If + specified as a DATE-TIME value, then it MUST be specified in a UTC + time format. If not present, and the COUNT rule part is also not + present, the "RRULE" is considered to repeat forever. + + The COUNT rule part defines the number of occurrences at which to + range-bound the recurrence. The "DTSTART" property value always + counts as the first occurrence. + + The BYSECOND rule part specifies a COMMA-separated list of seconds + within a minute. Valid values are 0 to 60. The BYMINUTE rule + part specifies a COMMA-separated list of minutes within an hour. + Valid values are 0 to 59. The BYHOUR rule part specifies a COMMA- + separated list of hours of the day. Valid values are 0 to 23. + The BYSECOND, BYMINUTE and BYHOUR rule parts MUST NOT be specified + when the associated "DTSTART" property has a DATE value type. + These rule parts MUST be ignored in RECUR value that violate the + above requirement (e.g., generated by applications that pre-date + this revision of iCalendar). + + The BYDAY rule part specifies a COMMA-separated list of days of + the week; SU indicates Sunday; MO indicates Monday; TU indicates + Tuesday; WE indicates Wednesday; TH indicates Thursday; FR + indicates Friday; and SA indicates Saturday. + + Each BYDAY value can also be preceded by a positive (+n) or + negative (-n) integer. If present, this indicates the nth + occurrence of a specific day within the MONTHLY or YEARLY "RRULE". + + + +Desruisseaux Standards Track [Page 41] + +RFC 5545 iCalendar September 2009 + + + For example, within a MONTHLY rule, +1MO (or simply 1MO) + represents the first Monday within the month, whereas -1MO + represents the last Monday of the month. The numeric value in a + BYDAY rule part with the FREQ rule part set to YEARLY corresponds + to an offset within the month when the BYMONTH rule part is + present, and corresponds to an offset within the year when the + BYWEEKNO or BYMONTH rule parts are present. If an integer + modifier is not present, it means all days of this type within the + specified frequency. For example, within a MONTHLY rule, MO + represents all Mondays within the month. The BYDAY rule part MUST + NOT be specified with a numeric value when the FREQ rule part is + not set to MONTHLY or YEARLY. Furthermore, the BYDAY rule part + MUST NOT be specified with a numeric value with the FREQ rule part + set to YEARLY when the BYWEEKNO rule part is specified. + + The BYMONTHDAY rule part specifies a COMMA-separated list of days + of the month. Valid values are 1 to 31 or -31 to -1. For + example, -10 represents the tenth to the last day of the month. + The BYMONTHDAY rule part MUST NOT be specified when the FREQ rule + part is set to WEEKLY. + + The BYYEARDAY rule part specifies a COMMA-separated list of days + of the year. Valid values are 1 to 366 or -366 to -1. For + example, -1 represents the last day of the year (December 31st) + and -306 represents the 306th to the last day of the year (March + 1st). The BYYEARDAY rule part MUST NOT be specified when the FREQ + rule part is set to DAILY, WEEKLY, or MONTHLY. + + The BYWEEKNO rule part specifies a COMMA-separated list of + ordinals specifying weeks of the year. Valid values are 1 to 53 + or -53 to -1. This corresponds to weeks according to week + numbering as defined in [ISO.8601.2004]. A week is defined as a + seven day period, starting on the day of the week defined to be + the week start (see WKST). Week number one of the calendar year + is the first week that contains at least four (4) days in that + calendar year. This rule part MUST NOT be used when the FREQ rule + part is set to anything other than YEARLY. For example, 3 + represents the third week of the year. + + Note: Assuming a Monday week start, week 53 can only occur when + Thursday is January 1 or if it is a leap year and Wednesday is + January 1. + + The BYMONTH rule part specifies a COMMA-separated list of months + of the year. Valid values are 1 to 12. + + The WKST rule part specifies the day on which the workweek starts. + Valid values are MO, TU, WE, TH, FR, SA, and SU. This is + + + +Desruisseaux Standards Track [Page 42] + +RFC 5545 iCalendar September 2009 + + + significant when a WEEKLY "RRULE" has an interval greater than 1, + and a BYDAY rule part is specified. This is also significant when + in a YEARLY "RRULE" when a BYWEEKNO rule part is specified. The + default value is MO. + + The BYSETPOS rule part specifies a COMMA-separated list of values + that corresponds to the nth occurrence within the set of + recurrence instances specified by the rule. BYSETPOS operates on + a set of recurrence instances in one interval of the recurrence + rule. For example, in a WEEKLY rule, the interval would be one + week A set of recurrence instances starts at the beginning of the + interval defined by the FREQ rule part. Valid values are 1 to 366 + or -366 to -1. It MUST only be used in conjunction with another + BYxxx rule part. For example "the last work day of the month" + could be represented as: + + FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1 + + Each BYSETPOS value can include a positive (+n) or negative (-n) + integer. If present, this indicates the nth occurrence of the + specific occurrence within the set of occurrences specified by the + rule. + + Recurrence rules may generate recurrence instances with an invalid + date (e.g., February 30) or nonexistent local time (e.g., 1:30 AM + on a day where the local time is moved forward by an hour at 1:00 + AM). Such recurrence instances MUST be ignored and MUST NOT be + counted as part of the recurrence set. + + Information, not contained in the rule, necessary to determine the + various recurrence instance start time and dates are derived from + the Start Time ("DTSTART") component attribute. For example, + "FREQ=YEARLY;BYMONTH=1" doesn't specify a specific day within the + month or a time. This information would be the same as what is + specified for "DTSTART". + + BYxxx rule parts modify the recurrence in some manner. BYxxx rule + parts for a period of time that is the same or greater than the + frequency generally reduce or limit the number of occurrences of + the recurrence generated. For example, "FREQ=DAILY;BYMONTH=1" + reduces the number of recurrence instances from all days (if + BYMONTH rule part is not present) to all days in January. BYxxx + rule parts for a period of time less than the frequency generally + increase or expand the number of occurrences of the recurrence. + For example, "FREQ=YEARLY;BYMONTH=1,2" increases the number of + days within the yearly recurrence set from 1 (if BYMONTH rule part + is not present) to 2. + + + + +Desruisseaux Standards Track [Page 43] + +RFC 5545 iCalendar September 2009 + + + If multiple BYxxx rule parts are specified, then after evaluating + the specified FREQ and INTERVAL rule parts, the BYxxx rule parts + are applied to the current set of evaluated occurrences in the + following order: BYMONTH, BYWEEKNO, BYYEARDAY, BYMONTHDAY, BYDAY, + BYHOUR, BYMINUTE, BYSECOND and BYSETPOS; then COUNT and UNTIL are + evaluated. + + The table below summarizes the dependency of BYxxx rule part + expand or limit behavior on the FREQ rule part value. + + The term "N/A" means that the corresponding BYxxx rule part MUST + NOT be used with the corresponding FREQ value. + + BYDAY has some special behavior depending on the FREQ value and + this is described in separate notes below the table. + + +----------+--------+--------+-------+-------+------+-------+------+ + | |SECONDLY|MINUTELY|HOURLY |DAILY |WEEKLY|MONTHLY|YEARLY| + +----------+--------+--------+-------+-------+------+-------+------+ + |BYMONTH |Limit |Limit |Limit |Limit |Limit |Limit |Expand| + +----------+--------+--------+-------+-------+------+-------+------+ + |BYWEEKNO |N/A |N/A |N/A |N/A |N/A |N/A |Expand| + +----------+--------+--------+-------+-------+------+-------+------+ + |BYYEARDAY |Limit |Limit |Limit |N/A |N/A |N/A |Expand| + +----------+--------+--------+-------+-------+------+-------+------+ + |BYMONTHDAY|Limit |Limit |Limit |Limit |N/A |Expand |Expand| + +----------+--------+--------+-------+-------+------+-------+------+ + |BYDAY |Limit |Limit |Limit |Limit |Expand|Note 1 |Note 2| + +----------+--------+--------+-------+-------+------+-------+------+ + |BYHOUR |Limit |Limit |Limit |Expand |Expand|Expand |Expand| + +----------+--------+--------+-------+-------+------+-------+------+ + |BYMINUTE |Limit |Limit |Expand |Expand |Expand|Expand |Expand| + +----------+--------+--------+-------+-------+------+-------+------+ + |BYSECOND |Limit |Expand |Expand |Expand |Expand|Expand |Expand| + +----------+--------+--------+-------+-------+------+-------+------+ + |BYSETPOS |Limit |Limit |Limit |Limit |Limit |Limit |Limit | + +----------+--------+--------+-------+-------+------+-------+------+ + + Note 1: Limit if BYMONTHDAY is present; otherwise, special expand + for MONTHLY. + + Note 2: Limit if BYYEARDAY or BYMONTHDAY is present; otherwise, + special expand for WEEKLY if BYWEEKNO present; otherwise, + special expand for MONTHLY if BYMONTH present; otherwise, + special expand for YEARLY. + + + + + + +Desruisseaux Standards Track [Page 44] + +RFC 5545 iCalendar September 2009 + + + Here is an example of evaluating multiple BYxxx rule parts. + + DTSTART;TZID=America/New_York:19970105T083000 + RRULE:FREQ=YEARLY;INTERVAL=2;BYMONTH=1;BYDAY=SU;BYHOUR=8,9; + BYMINUTE=30 + + First, the "INTERVAL=2" would be applied to "FREQ=YEARLY" to + arrive at "every other year". Then, "BYMONTH=1" would be applied + to arrive at "every January, every other year". Then, "BYDAY=SU" + would be applied to arrive at "every Sunday in January, every + other year". Then, "BYHOUR=8,9" would be applied to arrive at + "every Sunday in January at 8 AM and 9 AM, every other year". + Then, "BYMINUTE=30" would be applied to arrive at "every Sunday in + January at 8:30 AM and 9:30 AM, every other year". Then, lacking + information from "RRULE", the second is derived from "DTSTART", to + end up in "every Sunday in January at 8:30:00 AM and 9:30:00 AM, + every other year". Similarly, if the BYMINUTE, BYHOUR, BYDAY, + BYMONTHDAY, or BYMONTH rule part were missing, the appropriate + minute, hour, day, or month would have been retrieved from the + "DTSTART" property. + + If the computed local start time of a recurrence instance does not + exist, or occurs more than once, for the specified time zone, the + time of the recurrence instance is interpreted in the same manner + as an explicit DATE-TIME value describing that date and time, as + specified in Section 3.3.5. + + No additional content value encoding (i.e., BACKSLASH character + encoding, see Section 3.3.11) is defined for this value type. + + Example: The following is a rule that specifies 10 occurrences that + occur every other day: + + FREQ=DAILY;COUNT=10;INTERVAL=2 + + There are other examples specified in Section 3.8.5.3. + +3.3.11. Text + + Value Name: TEXT + + Purpose: This value type is used to identify values that contain + human-readable text. + + Format Definition: This value type is defined by the following + notation: + + + + + +Desruisseaux Standards Track [Page 45] + +RFC 5545 iCalendar September 2009 + + + text = *(TSAFE-CHAR / ":" / DQUOTE / ESCAPED-CHAR) + ; Folded according to description above + + ESCAPED-CHAR = ("\\" / "\;" / "\," / "\N" / "\n") + ; \\ encodes \, \N or \n encodes newline + ; \; encodes ;, \, encodes , + + TSAFE-CHAR = WSP / %x21 / %x23-2B / %x2D-39 / %x3C-5B / + %x5D-7E / NON-US-ASCII + ; Any character except CONTROLs not needed by the current + ; character set, DQUOTE, ";", ":", "\", "," + + Description: If the property permits, multiple TEXT values are + specified by a COMMA-separated list of values. + + The language in which the text is represented can be controlled by + the "LANGUAGE" property parameter. + + An intentional formatted text line break MUST only be included in + a "TEXT" property value by representing the line break with the + character sequence of BACKSLASH, followed by a LATIN SMALL LETTER + N or a LATIN CAPITAL LETTER N, that is "\n" or "\N". + + The "TEXT" property values may also contain special characters + that are used to signify delimiters, such as a COMMA character for + lists of values or a SEMICOLON character for structured values. + In order to support the inclusion of these special characters in + "TEXT" property values, they MUST be escaped with a BACKSLASH + character. A BACKSLASH character in a "TEXT" property value MUST + be escaped with another BACKSLASH character. A COMMA character in + a "TEXT" property value MUST be escaped with a BACKSLASH + character. A SEMICOLON character in a "TEXT" property value MUST + be escaped with a BACKSLASH character. However, a COLON character + in a "TEXT" property value SHALL NOT be escaped with a BACKSLASH + character. + + Example: A multiple line value of: + + Project XYZ Final Review + Conference Room - 3B + Come Prepared. + + would be represented as: + + Project XYZ Final Review\nConference Room - 3B\nCome Prepared. + + + + + + +Desruisseaux Standards Track [Page 46] + +RFC 5545 iCalendar September 2009 + + +3.3.12. Time + + Value Name: TIME + + Purpose: This value type is used to identify values that contain a + time of day. + + Format Definition: This value type is defined by the following + notation: + + time = time-hour time-minute time-second [time-utc] + + time-hour = 2DIGIT ;00-23 + time-minute = 2DIGIT ;00-59 + time-second = 2DIGIT ;00-60 + ;The "60" value is used to account for positive "leap" seconds. + + time-utc = "Z" + + Description: If the property permits, multiple "time" values are + specified by a COMMA-separated list of values. No additional + content value encoding (i.e., BACKSLASH character encoding, see + Section 3.3.11) is defined for this value type. + + The "TIME" value type is used to identify values that contain a + time of day. The format is based on the [ISO.8601.2004] complete + representation, basic format for a time of day. The text format + consists of a two-digit, 24-hour of the day (i.e., values 00-23), + two-digit minute in the hour (i.e., values 00-59), and two-digit + seconds in the minute (i.e., values 00-60). The seconds value of + 60 MUST only be used to account for positive "leap" seconds. + Fractions of a second are not supported by this format. + + In parallel to the "DATE-TIME" definition above, the "TIME" value + type expresses time values in three forms: + + The form of time with UTC offset MUST NOT be used. For example, + the following is not valid for a time value: + + 230000-0800 ;Invalid time format + + FORM #1 LOCAL TIME + + The local time form is simply a time value that does not contain + the UTC designator nor does it reference a time zone. For + example, 11:00 PM: + + 230000 + + + +Desruisseaux Standards Track [Page 47] + +RFC 5545 iCalendar September 2009 + + + Time values of this type are said to be "floating" and are not + bound to any time zone in particular. They are used to represent + the same hour, minute, and second value regardless of which time + zone is currently being observed. For example, an event can be + defined that indicates that an individual will be busy from 11:00 + AM to 1:00 PM every day, no matter which time zone the person is + in. In these cases, a local time can be specified. The recipient + of an iCalendar object with a property value consisting of a local + time, without any relative time zone information, SHOULD interpret + the value as being fixed to whatever time zone the "ATTENDEE" is + in at any given moment. This means that two "Attendees", may + participate in the same event at different UTC times; floating + time SHOULD only be used where that is reasonable behavior. + + In most cases, a fixed time is desired. To properly communicate a + fixed time in a property value, either UTC time or local time with + time zone reference MUST be specified. + + The use of local time in a TIME value without the "TZID" property + parameter is to be interpreted as floating time, regardless of the + existence of "VTIMEZONE" calendar components in the iCalendar + object. + + FORM #2: UTC TIME + + UTC time, or absolute time, is identified by a LATIN CAPITAL + LETTER Z suffix character, the UTC designator, appended to the + time value. For example, the following represents 07:00 AM UTC: + + 070000Z + + The "TZID" property parameter MUST NOT be applied to TIME + properties whose time values are specified in UTC. + + FORM #3: LOCAL TIME AND TIME ZONE REFERENCE + + The local time with reference to time zone information form is + identified by the use the "TZID" property parameter to reference + the appropriate time zone definition. "TZID" is discussed in + detail in Section 3.2.19. + + Example: The following represents 8:30 AM in New York in winter, + five hours behind UTC, in each of the three formats: + + 083000 + 133000Z + TZID=America/New_York:083000 + + + + +Desruisseaux Standards Track [Page 48] + +RFC 5545 iCalendar September 2009 + + +3.3.13. URI + + Value Name: URI + + Purpose: This value type is used to identify values that contain a + uniform resource identifier (URI) type of reference to the + property value. + + Format Definition: This value type is defined by the following + notation: + + uri = + + Description: This value type might be used to reference binary + information, for values that are large, or otherwise undesirable + to include directly in the iCalendar object. + + Property values with this value type MUST follow the generic URI + syntax defined in [RFC3986]. + + When a property parameter value is a URI value type, the URI MUST + be specified as a quoted-string value. + + No additional content value encoding (i.e., BACKSLASH character + encoding, see Section 3.3.11) is defined for this value type. + + Example: The following is a URI for a network file: + + http://example.com/my-report.txt + +3.3.14. UTC Offset + + Value Name: UTC-OFFSET + + Purpose: This value type is used to identify properties that contain + an offset from UTC to local time. + + Format Definition: This value type is defined by the following + notation: + + utc-offset = time-numzone + + time-numzone = ("+" / "-") time-hour time-minute [time-second] + + Description: The PLUS SIGN character MUST be specified for positive + UTC offsets (i.e., ahead of UTC). The HYPHEN-MINUS character MUST + be specified for negative UTC offsets (i.e., behind of UTC). The + + + + +Desruisseaux Standards Track [Page 49] + +RFC 5545 iCalendar September 2009 + + + value of "-0000" and "-000000" are not allowed. The time-second, + if present, MUST NOT be 60; if absent, it defaults to zero. + + No additional content value encoding (i.e., BACKSLASH character + encoding, see Section 3.3.11) is defined for this value type. + + Example: The following UTC offsets are given for standard time for + New York (five hours behind UTC) and Geneva (one hour ahead of + UTC): + + -0500 + + +0100 + +3.4. iCalendar Object + + The Calendaring and Scheduling Core Object is a collection of + calendaring and scheduling information. Typically, this information + will consist of an iCalendar stream with a single iCalendar object. + However, multiple iCalendar objects can be sequentially grouped + together in an iCalendar stream. The first line and last line of the + iCalendar object MUST contain a pair of iCalendar object delimiter + strings. The syntax for an iCalendar stream is as follows: + + icalstream = 1*icalobject + + icalobject = "BEGIN" ":" "VCALENDAR" CRLF + icalbody + "END" ":" "VCALENDAR" CRLF + + The following is a simple example of an iCalendar object: + + BEGIN:VCALENDAR + VERSION:2.0 + PRODID:-//hacksw/handcal//NONSGML v1.0//EN + BEGIN:VEVENT + UID:19970610T172345Z-AF23B2@example.com + DTSTAMP:19970610T172345Z + DTSTART:19970714T170000Z + DTEND:19970715T040000Z + SUMMARY:Bastille Day Party + END:VEVENT + END:VCALENDAR + + + + + + + + +Desruisseaux Standards Track [Page 50] + +RFC 5545 iCalendar September 2009 + + +3.5. Property + + A property is the definition of an individual attribute describing a + calendar object or a calendar component. A property takes the form + defined by the "contentline" notation defined in Section 3.1. + + The following is an example of a property: + + DTSTART:19960415T133000Z + + This memo imposes no ordering of properties within an iCalendar + object. + + Property names, parameter names, and enumerated parameter values are + case-insensitive. For example, the property name "DUE" is the same + as "due" and "Due", DTSTART;TZID=America/New_York:19980714T120000 is + the same as DtStart;TzID=America/New_York:19980714T120000. + +3.6. Calendar Components + + The body of the iCalendar object consists of a sequence of calendar + properties and one or more calendar components. The calendar + properties are attributes that apply to the calendar object as a + whole. The calendar components are collections of properties that + express a particular calendar semantic. For example, the calendar + component can specify an event, a to-do, a journal entry, time zone + information, free/busy time information, or an alarm. + + The body of the iCalendar object is defined by the following + notation: + + icalbody = calprops component + + calprops = *( + ; + ; The following are REQUIRED, + ; but MUST NOT occur more than once. + ; + prodid / version / + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + calscale / method / + ; + ; The following are OPTIONAL, + ; and MAY occur more than once. + ; + + + +Desruisseaux Standards Track [Page 51] + +RFC 5545 iCalendar September 2009 + + + x-prop / iana-prop + ; + ) + + component = 1*(eventc / todoc / journalc / freebusyc / + timezonec / iana-comp / x-comp) + + iana-comp = "BEGIN" ":" iana-token CRLF + 1*contentline + "END" ":" iana-token CRLF + + x-comp = "BEGIN" ":" x-name CRLF + 1*contentline + "END" ":" x-name CRLF + + An iCalendar object MUST include the "PRODID" and "VERSION" calendar + properties. In addition, it MUST include at least one calendar + component. Special forms of iCalendar objects are possible to + publish just busy time (i.e., only a "VFREEBUSY" calendar component) + or time zone (i.e., only a "VTIMEZONE" calendar component) + information. In addition, a complex iCalendar object that is used to + capture a complete snapshot of the contents of a calendar is possible + (e.g., composite of many different calendar components). More + commonly, an iCalendar object will consist of just a single "VEVENT", + "VTODO", or "VJOURNAL" calendar component. Applications MUST ignore + x-comp and iana-comp values they don't recognize. Applications that + support importing iCalendar objects SHOULD support all of the + component types defined in this document, and SHOULD NOT silently + drop any components as that can lead to user data loss. + +3.6.1. Event Component + + Component Name: VEVENT + + Purpose: Provide a grouping of component properties that describe an + event. + + Format Definition: A "VEVENT" calendar component is defined by the + following notation: + + eventc = "BEGIN" ":" "VEVENT" CRLF + eventprop *alarmc + "END" ":" "VEVENT" CRLF + + eventprop = *( + ; + ; The following are REQUIRED, + ; but MUST NOT occur more than once. + + + +Desruisseaux Standards Track [Page 52] + +RFC 5545 iCalendar September 2009 + + + ; + dtstamp / uid / + ; + ; The following is REQUIRED if the component + ; appears in an iCalendar object that doesn't + ; specify the "METHOD" property; otherwise, it + ; is OPTIONAL; in any case, it MUST NOT occur + ; more than once. + ; + dtstart / + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + class / created / description / geo / + last-mod / location / organizer / priority / + seq / status / summary / transp / + url / recurid / + ; + ; The following is OPTIONAL, + ; but SHOULD NOT occur more than once. + ; + rrule / + ; + ; Either 'dtend' or 'duration' MAY appear in + ; a 'eventprop', but 'dtend' and 'duration' + ; MUST NOT occur in the same 'eventprop'. + ; + dtend / duration / + ; + ; The following are OPTIONAL, + ; and MAY occur more than once. + ; + attach / attendee / categories / comment / + contact / exdate / rstatus / related / + resources / rdate / x-prop / iana-prop + ; + ) + + Description: A "VEVENT" calendar component is a grouping of + component properties, possibly including "VALARM" calendar + components, that represents a scheduled amount of time on a + calendar. For example, it can be an activity; such as a one-hour + long, department meeting from 8:00 AM to 9:00 AM, tomorrow. + Generally, an event will take up time on an individual calendar. + Hence, the event will appear as an opaque interval in a search for + busy time. Alternately, the event can have its Time Transparency + + + + +Desruisseaux Standards Track [Page 53] + +RFC 5545 iCalendar September 2009 + + + set to "TRANSPARENT" in order to prevent blocking of the event in + searches for busy time. + + The "VEVENT" is also the calendar component used to specify an + anniversary or daily reminder within a calendar. These events + have a DATE value type for the "DTSTART" property instead of the + default value type of DATE-TIME. If such a "VEVENT" has a "DTEND" + property, it MUST be specified as a DATE value also. The + anniversary type of "VEVENT" can span more than one date (i.e., + "DTEND" property value is set to a calendar date after the + "DTSTART" property value). If such a "VEVENT" has a "DURATION" + property, it MUST be specified as a "dur-day" or "dur-week" value. + + The "DTSTART" property for a "VEVENT" specifies the inclusive + start of the event. For recurring events, it also specifies the + very first instance in the recurrence set. The "DTEND" property + for a "VEVENT" calendar component specifies the non-inclusive end + of the event. For cases where a "VEVENT" calendar component + specifies a "DTSTART" property with a DATE value type but no + "DTEND" nor "DURATION" property, the event's duration is taken to + be one day. For cases where a "VEVENT" calendar component + specifies a "DTSTART" property with a DATE-TIME value type but no + "DTEND" property, the event ends on the same calendar date and + time of day specified by the "DTSTART" property. + + The "VEVENT" calendar component cannot be nested within another + calendar component. However, "VEVENT" calendar components can be + related to each other or to a "VTODO" or to a "VJOURNAL" calendar + component with the "RELATED-TO" property. + + Example: The following is an example of the "VEVENT" calendar + component used to represent a meeting that will also be opaque to + searches for busy time: + + BEGIN:VEVENT + UID:19970901T130000Z-123401@example.com + DTSTAMP:19970901T130000Z + DTSTART:19970903T163000Z + DTEND:19970903T190000Z + SUMMARY:Annual Employee Review + CLASS:PRIVATE + CATEGORIES:BUSINESS,HUMAN RESOURCES + END:VEVENT + + The following is an example of the "VEVENT" calendar component + used to represent a reminder that will not be opaque, but rather + transparent, to searches for busy time: + + + + +Desruisseaux Standards Track [Page 54] + +RFC 5545 iCalendar September 2009 + + + BEGIN:VEVENT + UID:19970901T130000Z-123402@example.com + DTSTAMP:19970901T130000Z + DTSTART:19970401T163000Z + DTEND:19970402T010000Z + SUMMARY:Laurel is in sensitivity awareness class. + CLASS:PUBLIC + CATEGORIES:BUSINESS,HUMAN RESOURCES + TRANSP:TRANSPARENT + END:VEVENT + + The following is an example of the "VEVENT" calendar component + used to represent an anniversary that will occur annually: + + BEGIN:VEVENT + UID:19970901T130000Z-123403@example.com + DTSTAMP:19970901T130000Z + DTSTART;VALUE=DATE:19971102 + SUMMARY:Our Blissful Anniversary + TRANSP:TRANSPARENT + CLASS:CONFIDENTIAL + CATEGORIES:ANNIVERSARY,PERSONAL,SPECIAL OCCASION + RRULE:FREQ=YEARLY + END:VEVENT + + The following is an example of the "VEVENT" calendar component + used to represent a multi-day event scheduled from June 28th, 2007 + to July 8th, 2007 inclusively. Note that the "DTEND" property is + set to July 9th, 2007, since the "DTEND" property specifies the + non-inclusive end of the event. + + BEGIN:VEVENT + UID:20070423T123432Z-541111@example.com + DTSTAMP:20070423T123432Z + DTSTART;VALUE=DATE:20070628 + DTEND;VALUE=DATE:20070709 + SUMMARY:Festival International de Jazz de Montreal + TRANSP:TRANSPARENT + END:VEVENT + +3.6.2. To-Do Component + + Component Name: VTODO + + Purpose: Provide a grouping of calendar properties that describe a + to-do. + + + + + +Desruisseaux Standards Track [Page 55] + +RFC 5545 iCalendar September 2009 + + + Format Definition: A "VTODO" calendar component is defined by the + following notation: + + todoc = "BEGIN" ":" "VTODO" CRLF + todoprop *alarmc + "END" ":" "VTODO" CRLF + + todoprop = *( + ; + ; The following are REQUIRED, + ; but MUST NOT occur more than once. + ; + dtstamp / uid / + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + class / completed / created / description / + dtstart / geo / last-mod / location / organizer / + percent / priority / recurid / seq / status / + summary / url / + ; + ; The following is OPTIONAL, + ; but SHOULD NOT occur more than once. + ; + rrule / + ; + ; Either 'due' or 'duration' MAY appear in + ; a 'todoprop', but 'due' and 'duration' + ; MUST NOT occur in the same 'todoprop'. + ; If 'duration' appear in a 'todoprop', + ; then 'dtstart' MUST also appear in + ; the same 'todoprop'. + ; + due / duration / + ; + ; The following are OPTIONAL, + ; and MAY occur more than once. + ; + attach / attendee / categories / comment / contact / + exdate / rstatus / related / resources / + rdate / x-prop / iana-prop + ; + ) + + Description: A "VTODO" calendar component is a grouping of component + properties and possibly "VALARM" calendar components that + represent an action-item or assignment. For example, it can be + + + +Desruisseaux Standards Track [Page 56] + +RFC 5545 iCalendar September 2009 + + + used to represent an item of work assigned to an individual; such + as "turn in travel expense today". + + The "VTODO" calendar component cannot be nested within another + calendar component. However, "VTODO" calendar components can be + related to each other or to a "VEVENT" or to a "VJOURNAL" calendar + component with the "RELATED-TO" property. + + A "VTODO" calendar component without the "DTSTART" and "DUE" (or + "DURATION") properties specifies a to-do that will be associated + with each successive calendar date, until it is completed. + + Examples: The following is an example of a "VTODO" calendar + component that needs to be completed before May 1st, 2007. On + midnight May 1st, 2007 this to-do would be considered overdue. + + BEGIN:VTODO + UID:20070313T123432Z-456553@example.com + DTSTAMP:20070313T123432Z + DUE;VALUE=DATE:20070501 + SUMMARY:Submit Quebec Income Tax Return for 2006 + CLASS:CONFIDENTIAL + CATEGORIES:FAMILY,FINANCE + STATUS:NEEDS-ACTION + END:VTODO + + The following is an example of a "VTODO" calendar component that + was due before 1:00 P.M. UTC on July 9th, 2007 and was completed + on July 7th, 2007 at 10:00 A.M. UTC. + + BEGIN:VTODO + UID:20070514T103211Z-123404@example.com + DTSTAMP:20070514T103211Z + DTSTART:20070514T110000Z + DUE:20070709T130000Z + COMPLETED:20070707T100000Z + SUMMARY:Submit Revised Internet-Draft + PRIORITY:1 + STATUS:NEEDS-ACTION + END:VTODO + +3.6.3. Journal Component + + Component Name: VJOURNAL + + Purpose: Provide a grouping of component properties that describe a + journal entry. + + + + +Desruisseaux Standards Track [Page 57] + +RFC 5545 iCalendar September 2009 + + + Format Definition: A "VJOURNAL" calendar component is defined by the + following notation: + + journalc = "BEGIN" ":" "VJOURNAL" CRLF + jourprop + "END" ":" "VJOURNAL" CRLF + + jourprop = *( + ; + ; The following are REQUIRED, + ; but MUST NOT occur more than once. + ; + dtstamp / uid / + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + class / created / dtstart / + last-mod / organizer / recurid / seq / + status / summary / url / + ; + ; The following is OPTIONAL, + ; but SHOULD NOT occur more than once. + ; + rrule / + ; + ; The following are OPTIONAL, + ; and MAY occur more than once. + ; + attach / attendee / categories / comment / + contact / description / exdate / related / rdate / + rstatus / x-prop / iana-prop + ; + ) + + Description: A "VJOURNAL" calendar component is a grouping of + component properties that represent one or more descriptive text + notes associated with a particular calendar date. The "DTSTART" + property is used to specify the calendar date with which the + journal entry is associated. Generally, it will have a DATE value + data type, but it can also be used to specify a DATE-TIME value + data type. Examples of a journal entry include a daily record of + a legislative body or a journal entry of individual telephone + contacts for the day or an ordered list of accomplishments for the + day. The "VJOURNAL" calendar component can also be used to + associate a document with a calendar date. + + + + + +Desruisseaux Standards Track [Page 58] + +RFC 5545 iCalendar September 2009 + + + The "VJOURNAL" calendar component does not take up time on a + calendar. Hence, it does not play a role in free or busy time + searches -- it is as though it has a time transparency value of + TRANSPARENT. It is transparent to any such searches. + + The "VJOURNAL" calendar component cannot be nested within another + calendar component. However, "VJOURNAL" calendar components can + be related to each other or to a "VEVENT" or to a "VTODO" calendar + component, with the "RELATED-TO" property. + + Example: The following is an example of the "VJOURNAL" calendar + component: + + BEGIN:VJOURNAL + UID:19970901T130000Z-123405@example.com + DTSTAMP:19970901T130000Z + DTSTART;VALUE=DATE:19970317 + SUMMARY:Staff meeting minutes + DESCRIPTION:1. Staff meeting: Participants include Joe\, + Lisa\, and Bob. Aurora project plans were reviewed. + There is currently no budget reserves for this project. + Lisa will escalate to management. Next meeting on Tuesday.\n + 2. Telephone Conference: ABC Corp. sales representative + called to discuss new printer. Promised to get us a demo by + Friday.\n3. Henry Miller (Handsoff Insurance): Car was + totaled by tree. Is looking into a loaner car. 555-2323 + (tel). + END:VJOURNAL + +3.6.4. Free/Busy Component + + Component Name: VFREEBUSY + + Purpose: Provide a grouping of component properties that describe + either a request for free/busy time, describe a response to a + request for free/busy time, or describe a published set of busy + time. + + Format Definition: A "VFREEBUSY" calendar component is defined by + the following notation: + + freebusyc = "BEGIN" ":" "VFREEBUSY" CRLF + fbprop + "END" ":" "VFREEBUSY" CRLF + + fbprop = *( + ; + ; The following are REQUIRED, + + + +Desruisseaux Standards Track [Page 59] + +RFC 5545 iCalendar September 2009 + + + ; but MUST NOT occur more than once. + ; + dtstamp / uid / + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + contact / dtstart / dtend / + organizer / url / + ; + ; The following are OPTIONAL, + ; and MAY occur more than once. + ; + attendee / comment / freebusy / rstatus / x-prop / + iana-prop + ; + ) + + Description: A "VFREEBUSY" calendar component is a grouping of + component properties that represents either a request for free or + busy time information, a reply to a request for free or busy time + information, or a published set of busy time information. + + When used to request free/busy time information, the "ATTENDEE" + property specifies the calendar users whose free/busy time is + being requested; the "ORGANIZER" property specifies the calendar + user who is requesting the free/busy time; the "DTSTART" and + "DTEND" properties specify the window of time for which the free/ + busy time is being requested; the "UID" and "DTSTAMP" properties + are specified to assist in proper sequencing of multiple free/busy + time requests. + + When used to reply to a request for free/busy time, the "ATTENDEE" + property specifies the calendar user responding to the free/busy + time request; the "ORGANIZER" property specifies the calendar user + that originally requested the free/busy time; the "FREEBUSY" + property specifies the free/busy time information (if it exists); + and the "UID" and "DTSTAMP" properties are specified to assist in + proper sequencing of multiple free/busy time replies. + + When used to publish busy time, the "ORGANIZER" property specifies + the calendar user associated with the published busy time; the + "DTSTART" and "DTEND" properties specify an inclusive time window + that surrounds the busy time information; the "FREEBUSY" property + specifies the published busy time information; and the "DTSTAMP" + property specifies the DATE-TIME that iCalendar object was + created. + + + + +Desruisseaux Standards Track [Page 60] + +RFC 5545 iCalendar September 2009 + + + The "VFREEBUSY" calendar component cannot be nested within another + calendar component. Multiple "VFREEBUSY" calendar components can + be specified within an iCalendar object. This permits the + grouping of free/busy information into logical collections, such + as monthly groups of busy time information. + + The "VFREEBUSY" calendar component is intended for use in + iCalendar object methods involving requests for free time, + requests for busy time, requests for both free and busy, and the + associated replies. + + Free/Busy information is represented with the "FREEBUSY" property. + This property provides a terse representation of time periods. + One or more "FREEBUSY" properties can be specified in the + "VFREEBUSY" calendar component. + + When present in a "VFREEBUSY" calendar component, the "DTSTART" + and "DTEND" properties SHOULD be specified prior to any "FREEBUSY" + properties. + + The recurrence properties ("RRULE", "RDATE", "EXDATE") are not + permitted within a "VFREEBUSY" calendar component. Any recurring + events are resolved into their individual busy time periods using + the "FREEBUSY" property. + + Example: The following is an example of a "VFREEBUSY" calendar + component used to request free or busy time information: + + BEGIN:VFREEBUSY + UID:19970901T082949Z-FA43EF@example.com + ORGANIZER:mailto:jane_doe@example.com + ATTENDEE:mailto:john_public@example.com + DTSTART:19971015T050000Z + DTEND:19971016T050000Z + DTSTAMP:19970901T083000Z + END:VFREEBUSY + + + + + + + + + + + + + + + +Desruisseaux Standards Track [Page 61] + +RFC 5545 iCalendar September 2009 + + + The following is an example of a "VFREEBUSY" calendar component + used to reply to the request with busy time information: + + BEGIN:VFREEBUSY + UID:19970901T095957Z-76A912@example.com + ORGANIZER:mailto:jane_doe@example.com + ATTENDEE:mailto:john_public@example.com + DTSTAMP:19970901T100000Z + FREEBUSY:19971015T050000Z/PT8H30M, + 19971015T160000Z/PT5H30M,19971015T223000Z/PT6H30M + URL:http://example.com/pub/busy/jpublic-01.ifb + COMMENT:This iCalendar file contains busy time information for + the next three months. + END:VFREEBUSY + + The following is an example of a "VFREEBUSY" calendar component + used to publish busy time information: + + BEGIN:VFREEBUSY + UID:19970901T115957Z-76A912@example.com + DTSTAMP:19970901T120000Z + ORGANIZER:jsmith@example.com + DTSTART:19980313T141711Z + DTEND:19980410T141711Z + FREEBUSY:19980314T233000Z/19980315T003000Z + FREEBUSY:19980316T153000Z/19980316T163000Z + FREEBUSY:19980318T030000Z/19980318T040000Z + URL:http://www.example.com/calendar/busytime/jsmith.ifb + END:VFREEBUSY + +3.6.5. Time Zone Component + + Component Name: VTIMEZONE + + Purpose: Provide a grouping of component properties that defines a + time zone. + + Format Definition: A "VTIMEZONE" calendar component is defined by + the following notation: + + timezonec = "BEGIN" ":" "VTIMEZONE" CRLF + *( + ; + ; 'tzid' is REQUIRED, but MUST NOT occur more + ; than once. + ; + tzid / + ; + + + +Desruisseaux Standards Track [Page 62] + +RFC 5545 iCalendar September 2009 + + + ; 'last-mod' and 'tzurl' are OPTIONAL, + ; but MUST NOT occur more than once. + ; + last-mod / tzurl / + ; + ; One of 'standardc' or 'daylightc' MUST occur + ; and each MAY occur more than once. + ; + standardc / daylightc / + ; + ; The following are OPTIONAL, + ; and MAY occur more than once. + ; + x-prop / iana-prop + ; + ) + "END" ":" "VTIMEZONE" CRLF + + standardc = "BEGIN" ":" "STANDARD" CRLF + tzprop + "END" ":" "STANDARD" CRLF + + daylightc = "BEGIN" ":" "DAYLIGHT" CRLF + tzprop + "END" ":" "DAYLIGHT" CRLF + + tzprop = *( + ; + ; The following are REQUIRED, + ; but MUST NOT occur more than once. + ; + dtstart / tzoffsetto / tzoffsetfrom / + ; + ; The following is OPTIONAL, + ; but SHOULD NOT occur more than once. + ; + rrule / + ; + ; The following are OPTIONAL, + ; and MAY occur more than once. + ; + comment / rdate / tzname / x-prop / iana-prop + ; + ) + + Description: A time zone is unambiguously defined by the set of time + measurement rules determined by the governing body for a given + geographic area. These rules describe, at a minimum, the base + + + +Desruisseaux Standards Track [Page 63] + +RFC 5545 iCalendar September 2009 + + + offset from UTC for the time zone, often referred to as the + Standard Time offset. Many locations adjust their Standard Time + forward or backward by one hour, in order to accommodate seasonal + changes in number of daylight hours, often referred to as Daylight + Saving Time. Some locations adjust their time by a fraction of an + hour. Standard Time is also known as Winter Time. Daylight + Saving Time is also known as Advanced Time, Summer Time, or Legal + Time in certain countries. The following table shows the changes + in time zone rules in effect for New York City starting from 1967. + Each line represents a description or rule for a particular + observance. + + Effective Observance Rule + + +-----------+--------------------------+--------+--------------+ + | Date | (Date-Time) | Offset | Abbreviation | + +-----------+--------------------------+--------+--------------+ + | 1967-1973 | last Sun in Apr, 02:00 | -0400 | EDT | + | | | | | + | 1967-2006 | last Sun in Oct, 02:00 | -0500 | EST | + | | | | | + | 1974-1974 | Jan 6, 02:00 | -0400 | EDT | + | | | | | + | 1975-1975 | Feb 23, 02:00 | -0400 | EDT | + | | | | | + | 1976-1986 | last Sun in Apr, 02:00 | -0400 | EDT | + | | | | | + | 1987-2006 | first Sun in Apr, 02:00 | -0400 | EDT | + | | | | | + | 2007-* | second Sun in Mar, 02:00 | -0400 | EDT | + | | | | | + | 2007-* | first Sun in Nov, 02:00 | -0500 | EST | + +-----------+--------------------------+--------+--------------+ + + Note: The specification of a global time zone registry is not + addressed by this document and is left for future study. + However, implementers may find the TZ database [TZDB] a useful + reference. It is an informal, public-domain collection of time + zone information, which is currently being maintained by + volunteer Internet participants, and is used in several + operating systems. This database contains current and + historical time zone information for a wide variety of + locations around the globe; it provides a time zone identifier + for every unique time zone rule set in actual use since 1970, + with historical data going back to the introduction of standard + time. + + + + + +Desruisseaux Standards Track [Page 64] + +RFC 5545 iCalendar September 2009 + + + Interoperability between two calendaring and scheduling + applications, especially for recurring events, to-dos or journal + entries, is dependent on the ability to capture and convey date + and time information in an unambiguous format. The specification + of current time zone information is integral to this behavior. + + If present, the "VTIMEZONE" calendar component defines the set of + Standard Time and Daylight Saving Time observances (or rules) for + a particular time zone for a given interval of time. The + "VTIMEZONE" calendar component cannot be nested within other + calendar components. Multiple "VTIMEZONE" calendar components can + exist in an iCalendar object. In this situation, each "VTIMEZONE" + MUST represent a unique time zone definition. This is necessary + for some classes of events, such as airline flights, that start in + one time zone and end in another. + + The "VTIMEZONE" calendar component MUST include the "TZID" + property and at least one definition of a "STANDARD" or "DAYLIGHT" + sub-component. The "STANDARD" or "DAYLIGHT" sub-component MUST + include the "DTSTART", "TZOFFSETFROM", and "TZOFFSETTO" + properties. + + An individual "VTIMEZONE" calendar component MUST be specified for + each unique "TZID" parameter value specified in the iCalendar + object. In addition, a "VTIMEZONE" calendar component, referred + to by a recurring calendar component, MUST provide valid time zone + information for all recurrence instances. + + Each "VTIMEZONE" calendar component consists of a collection of + one or more sub-components that describe the rule for a particular + observance (either a Standard Time or a Daylight Saving Time + observance). The "STANDARD" sub-component consists of a + collection of properties that describe Standard Time. The + "DAYLIGHT" sub-component consists of a collection of properties + that describe Daylight Saving Time. In general, this collection + of properties consists of: + + * the first onset DATE-TIME for the observance; + + * the last onset DATE-TIME for the observance, if a last onset is + known; + + * the offset to be applied for the observance; + + * a rule that describes the day and time when the observance + takes effect; + + * an optional name for the observance. + + + +Desruisseaux Standards Track [Page 65] + +RFC 5545 iCalendar September 2009 + + + For a given time zone, there may be multiple unique definitions of + the observances over a period of time. Each observance is + described using either a "STANDARD" or "DAYLIGHT" sub-component. + The collection of these sub-components is used to describe the + time zone for a given period of time. The offset to apply at any + given time is found by locating the observance that has the last + onset date and time before the time in question, and using the + offset value from that observance. + + The top-level properties in a "VTIMEZONE" calendar component are: + + The mandatory "TZID" property is a text value that uniquely + identifies the "VTIMEZONE" calendar component within the scope of + an iCalendar object. + + The optional "LAST-MODIFIED" property is a UTC value that + specifies the date and time that this time zone definition was + last updated. + + The optional "TZURL" property is a url value that points to a + published "VTIMEZONE" definition. "TZURL" SHOULD refer to a + resource that is accessible by anyone who might need to interpret + the object. This SHOULD NOT normally be a "file" URL or other URL + that is not widely accessible. + + The collection of properties that are used to define the + "STANDARD" and "DAYLIGHT" sub-components include: + + The mandatory "DTSTART" property gives the effective onset date + and local time for the time zone sub-component definition. + "DTSTART" in this usage MUST be specified as a date with a local + time value. + + The mandatory "TZOFFSETFROM" property gives the UTC offset that is + in use when the onset of this time zone observance begins. + "TZOFFSETFROM" is combined with "DTSTART" to define the effective + onset for the time zone sub-component definition. For example, + the following represents the time at which the observance of + Standard Time took effect in Fall 1967 for New York City: + + DTSTART:19671029T020000 + + TZOFFSETFROM:-0400 + + The mandatory "TZOFFSETTO" property gives the UTC offset for the + time zone sub-component (Standard Time or Daylight Saving Time) + when this observance is in use. + + + + +Desruisseaux Standards Track [Page 66] + +RFC 5545 iCalendar September 2009 + + + The optional "TZNAME" property is the customary name for the time + zone. This could be used for displaying dates. + + The onset DATE-TIME values for the observance defined by the time + zone sub-component is defined by the "DTSTART", "RRULE", and + "RDATE" properties. + + The "RRULE" property defines the recurrence rule for the onset of + the observance defined by this time zone sub-component. Some + specific requirements for the usage of "RRULE" for this purpose + include: + + * If observance is known to have an effective end date, the + "UNTIL" recurrence rule parameter MUST be used to specify the + last valid onset of this observance (i.e., the UNTIL DATE-TIME + will be equal to the last instance generated by the recurrence + pattern). It MUST be specified in UTC time. + + * The "DTSTART" and the "TZOFFSETFROM" properties MUST be used + when generating the onset DATE-TIME values (instances) from the + "RRULE". + + The "RDATE" property can also be used to define the onset of the + observance by giving the individual onset date and times. "RDATE" + in this usage MUST be specified as a date with local time value, + relative to the UTC offset specified in the "TZOFFSETFROM" + property. + + The optional "COMMENT" property is also allowed for descriptive + explanatory text. + + Example: The following are examples of the "VTIMEZONE" calendar + component: + + This is an example showing all the time zone rules for New York + City since April 30, 1967 at 03:00:00 EDT. + + BEGIN:VTIMEZONE + TZID:America/New_York + LAST-MODIFIED:20050809T050000Z + BEGIN:DAYLIGHT + DTSTART:19670430T020000 + RRULE:FREQ=YEARLY;BYMONTH=4;BYDAY=-1SU;UNTIL=19730429T070000Z + TZOFFSETFROM:-0500 + TZOFFSETTO:-0400 + TZNAME:EDT + END:DAYLIGHT + BEGIN:STANDARD + + + +Desruisseaux Standards Track [Page 67] + +RFC 5545 iCalendar September 2009 + + + DTSTART:19671029T020000 + RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU;UNTIL=20061029T060000Z + TZOFFSETFROM:-0400 + TZOFFSETTO:-0500 + TZNAME:EST + END:STANDARD + BEGIN:DAYLIGHT + DTSTART:19740106T020000 + RDATE:19750223T020000 + TZOFFSETFROM:-0500 + TZOFFSETTO:-0400 + TZNAME:EDT + END:DAYLIGHT + BEGIN:DAYLIGHT + DTSTART:19760425T020000 + RRULE:FREQ=YEARLY;BYMONTH=4;BYDAY=-1SU;UNTIL=19860427T070000Z + TZOFFSETFROM:-0500 + TZOFFSETTO:-0400 + TZNAME:EDT + END:DAYLIGHT + BEGIN:DAYLIGHT + DTSTART:19870405T020000 + RRULE:FREQ=YEARLY;BYMONTH=4;BYDAY=1SU;UNTIL=20060402T070000Z + TZOFFSETFROM:-0500 + TZOFFSETTO:-0400 + TZNAME:EDT + END:DAYLIGHT + BEGIN:DAYLIGHT + DTSTART:20070311T020000 + RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=2SU + TZOFFSETFROM:-0500 + TZOFFSETTO:-0400 + TZNAME:EDT + END:DAYLIGHT + BEGIN:STANDARD + DTSTART:20071104T020000 + RRULE:FREQ=YEARLY;BYMONTH=11;BYDAY=1SU + TZOFFSETFROM:-0400 + TZOFFSETTO:-0500 + TZNAME:EST + END:STANDARD + END:VTIMEZONE + + This is an example showing time zone information for New York City + using only the "DTSTART" property. Note that this is only + suitable for a recurring event that starts on or later than March + 11, 2007 at 03:00:00 EDT (i.e., the earliest effective transition + date and time) and ends no later than March 9, 2008 at 01:59:59 + + + +Desruisseaux Standards Track [Page 68] + +RFC 5545 iCalendar September 2009 + + + EST (i.e., latest valid date and time for EST in this scenario). + For example, this can be used for a recurring event that occurs + every Friday, 8:00 A.M.-9:00 A.M., starting June 1, 2007, ending + December 31, 2007, + + BEGIN:VTIMEZONE + TZID:America/New_York + LAST-MODIFIED:20050809T050000Z + BEGIN:STANDARD + DTSTART:20071104T020000 + TZOFFSETFROM:-0400 + TZOFFSETTO:-0500 + TZNAME:EST + END:STANDARD + BEGIN:DAYLIGHT + DTSTART:20070311T020000 + TZOFFSETFROM:-0500 + TZOFFSETTO:-0400 + TZNAME:EDT + END:DAYLIGHT + END:VTIMEZONE + + This is a simple example showing the current time zone rules for + New York City using a "RRULE" recurrence pattern. Note that there + is no effective end date to either of the Standard Time or + Daylight Time rules. This information would be valid for a + recurring event starting today and continuing indefinitely. + + BEGIN:VTIMEZONE + TZID:America/New_York + LAST-MODIFIED:20050809T050000Z + TZURL:http://zones.example.com/tz/America-New_York.ics + BEGIN:STANDARD + DTSTART:20071104T020000 + RRULE:FREQ=YEARLY;BYMONTH=11;BYDAY=1SU + TZOFFSETFROM:-0400 + TZOFFSETTO:-0500 + TZNAME:EST + END:STANDARD + BEGIN:DAYLIGHT + DTSTART:20070311T020000 + RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=2SU + TZOFFSETFROM:-0500 + TZOFFSETTO:-0400 + TZNAME:EDT + END:DAYLIGHT + END:VTIMEZONE + + + + +Desruisseaux Standards Track [Page 69] + +RFC 5545 iCalendar September 2009 + + + This is an example showing a set of rules for a fictitious time + zone where the Daylight Time rule has an effective end date (i.e., + after that date, Daylight Time is no longer observed). + + BEGIN:VTIMEZONE + TZID:Fictitious + LAST-MODIFIED:19870101T000000Z + BEGIN:STANDARD + DTSTART:19671029T020000 + RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 + TZOFFSETFROM:-0400 + TZOFFSETTO:-0500 + TZNAME:EST + END:STANDARD + BEGIN:DAYLIGHT + DTSTART:19870405T020000 + RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4;UNTIL=19980404T070000Z + TZOFFSETFROM:-0500 + TZOFFSETTO:-0400 + TZNAME:EDT + END:DAYLIGHT + END:VTIMEZONE + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Desruisseaux Standards Track [Page 70] + +RFC 5545 iCalendar September 2009 + + + This is an example showing a set of rules for a fictitious time + zone where the first Daylight Time rule has an effective end date. + There is a second Daylight Time rule that picks up where the other + left off. + + BEGIN:VTIMEZONE + TZID:Fictitious + LAST-MODIFIED:19870101T000000Z + BEGIN:STANDARD + DTSTART:19671029T020000 + RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 + TZOFFSETFROM:-0400 + TZOFFSETTO:-0500 + TZNAME:EST + END:STANDARD + BEGIN:DAYLIGHT + DTSTART:19870405T020000 + RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4;UNTIL=19980404T070000Z + TZOFFSETFROM:-0500 + TZOFFSETTO:-0400 + TZNAME:EDT + END:DAYLIGHT + BEGIN:DAYLIGHT + DTSTART:19990424T020000 + RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=4 + TZOFFSETFROM:-0500 + TZOFFSETTO:-0400 + TZNAME:EDT + END:DAYLIGHT + END:VTIMEZONE + +3.6.6. Alarm Component + + Component Name: VALARM + + Purpose: Provide a grouping of component properties that define an + alarm. + + Format Definition: A "VALARM" calendar component is defined by the + following notation: + + alarmc = "BEGIN" ":" "VALARM" CRLF + (audioprop / dispprop / emailprop) + "END" ":" "VALARM" CRLF + + audioprop = *( + ; + ; 'action' and 'trigger' are both REQUIRED, + + + +Desruisseaux Standards Track [Page 71] + +RFC 5545 iCalendar September 2009 + + + ; but MUST NOT occur more than once. + ; + action / trigger / + ; + ; 'duration' and 'repeat' are both OPTIONAL, + ; and MUST NOT occur more than once each; + ; but if one occurs, so MUST the other. + ; + duration / repeat / + ; + ; The following is OPTIONAL, + ; but MUST NOT occur more than once. + ; + attach / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + x-prop / iana-prop + ; + ) + + dispprop = *( + ; + ; The following are REQUIRED, + ; but MUST NOT occur more than once. + ; + action / description / trigger / + ; + ; 'duration' and 'repeat' are both OPTIONAL, + ; and MUST NOT occur more than once each; + ; but if one occurs, so MUST the other. + ; + duration / repeat / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + x-prop / iana-prop + ; + ) + + emailprop = *( + ; + ; The following are all REQUIRED, + ; but MUST NOT occur more than once. + ; + action / description / trigger / summary / + + + +Desruisseaux Standards Track [Page 72] + +RFC 5545 iCalendar September 2009 + + + ; + ; The following is REQUIRED, + ; and MAY occur more than once. + ; + attendee / + ; + ; 'duration' and 'repeat' are both OPTIONAL, + ; and MUST NOT occur more than once each; + ; but if one occurs, so MUST the other. + ; + duration / repeat / + ; + ; The following are OPTIONAL, + ; and MAY occur more than once. + ; + attach / x-prop / iana-prop + ; + ) + + Description: A "VALARM" calendar component is a grouping of + component properties that is a reminder or alarm for an event or a + to-do. For example, it may be used to define a reminder for a + pending event or an overdue to-do. + + The "VALARM" calendar component MUST include the "ACTION" and + "TRIGGER" properties. The "ACTION" property further constrains + the "VALARM" calendar component in the following ways: + + When the action is "AUDIO", the alarm can also include one and + only one "ATTACH" property, which MUST point to a sound resource, + which is rendered when the alarm is triggered. + + When the action is "DISPLAY", the alarm MUST also include a + "DESCRIPTION" property, which contains the text to be displayed + when the alarm is triggered. + + When the action is "EMAIL", the alarm MUST include a "DESCRIPTION" + property, which contains the text to be used as the message body, + a "SUMMARY" property, which contains the text to be used as the + message subject, and one or more "ATTENDEE" properties, which + contain the email address of attendees to receive the message. It + can also include one or more "ATTACH" properties, which are + intended to be sent as message attachments. When the alarm is + triggered, the email message is sent. + + The "VALARM" calendar component MUST only appear within either a + "VEVENT" or "VTODO" calendar component. "VALARM" calendar + components cannot be nested. Multiple mutually independent + + + +Desruisseaux Standards Track [Page 73] + +RFC 5545 iCalendar September 2009 + + + "VALARM" calendar components can be specified for a single + "VEVENT" or "VTODO" calendar component. + + The "TRIGGER" property specifies when the alarm will be triggered. + The "TRIGGER" property specifies a duration prior to the start of + an event or a to-do. The "TRIGGER" edge may be explicitly set to + be relative to the "START" or "END" of the event or to-do with the + "RELATED" parameter of the "TRIGGER" property. The "TRIGGER" + property value type can alternatively be set to an absolute + calendar date with UTC time. + + In an alarm set to trigger on the "START" of an event or to-do, + the "DTSTART" property MUST be present in the associated event or + to-do. In an alarm in a "VEVENT" calendar component set to + trigger on the "END" of the event, either the "DTEND" property + MUST be present, or the "DTSTART" and "DURATION" properties MUST + both be present. In an alarm in a "VTODO" calendar component set + to trigger on the "END" of the to-do, either the "DUE" property + MUST be present, or the "DTSTART" and "DURATION" properties MUST + both be present. + + The alarm can be defined such that it triggers repeatedly. A + definition of an alarm with a repeating trigger MUST include both + the "DURATION" and "REPEAT" properties. The "DURATION" property + specifies the delay period, after which the alarm will repeat. + The "REPEAT" property specifies the number of additional + repetitions that the alarm will be triggered. This repetition + count is in addition to the initial triggering of the alarm. Both + of these properties MUST be present in order to specify a + repeating alarm. If one of these two properties is absent, then + the alarm will not repeat beyond the initial trigger. + + The "ACTION" property is used within the "VALARM" calendar + component to specify the type of action invoked when the alarm is + triggered. The "VALARM" properties provide enough information for + a specific action to be invoked. It is typically the + responsibility of a "Calendar User Agent" (CUA) to deliver the + alarm in the specified fashion. An "ACTION" property value of + AUDIO specifies an alarm that causes a sound to be played to alert + the user; DISPLAY specifies an alarm that causes a text message to + be displayed to the user; and EMAIL specifies an alarm that causes + an electronic email message to be delivered to one or more email + addresses. + + In an AUDIO alarm, if the optional "ATTACH" property is included, + it MUST specify an audio sound resource. The intention is that + the sound will be played as the alarm effect. If an "ATTACH" + property is specified that does not refer to a sound resource, or + + + +Desruisseaux Standards Track [Page 74] + +RFC 5545 iCalendar September 2009 + + + if the specified sound resource cannot be rendered (because its + format is unsupported, or because it cannot be retrieved), then + the CUA or other entity responsible for playing the sound may + choose a fallback action, such as playing a built-in default + sound, or playing no sound at all. + + In a DISPLAY alarm, the intended alarm effect is for the text + value of the "DESCRIPTION" property to be displayed to the user. + + In an EMAIL alarm, the intended alarm effect is for an email + message to be composed and delivered to all the addresses + specified by the "ATTENDEE" properties in the "VALARM" calendar + component. The "DESCRIPTION" property of the "VALARM" calendar + component MUST be used as the body text of the message, and the + "SUMMARY" property MUST be used as the subject text. Any "ATTACH" + properties in the "VALARM" calendar component SHOULD be sent as + attachments to the message. + + Note: Implementations should carefully consider whether they + accept alarm components from untrusted sources, e.g., when + importing calendar objects from external sources. One + reasonable policy is to always ignore alarm components that the + calendar user has not set herself, or at least ask for + confirmation in such a case. + + Example: The following example is for a "VALARM" calendar component + that specifies an audio alarm that will sound at a precise time + and repeat 4 more times at 15-minute intervals: + + BEGIN:VALARM + TRIGGER;VALUE=DATE-TIME:19970317T133000Z + REPEAT:4 + DURATION:PT15M + ACTION:AUDIO + ATTACH;FMTTYPE=audio/basic:ftp://example.com/pub/ + sounds/bell-01.aud + END:VALARM + + The following example is for a "VALARM" calendar component that + specifies a display alarm that will trigger 30 minutes before the + scheduled start of the event or of the to-do it is associated with + and will repeat 2 more times at 15-minute intervals: + + + + + + + + + +Desruisseaux Standards Track [Page 75] + +RFC 5545 iCalendar September 2009 + + + BEGIN:VALARM + TRIGGER:-PT30M + REPEAT:2 + DURATION:PT15M + ACTION:DISPLAY + DESCRIPTION:Breakfast meeting with executive\n + team at 8:30 AM EST. + END:VALARM + + The following example is for a "VALARM" calendar component that + specifies an email alarm that will trigger 2 days before the + scheduled due DATE-TIME of a to-do with which it is associated. + It does not repeat. The email has a subject, body, and attachment + link. + + BEGIN:VALARM + TRIGGER;RELATED=END:-P2D + ACTION:EMAIL + ATTENDEE:mailto:john_doe@example.com + SUMMARY:*** REMINDER: SEND AGENDA FOR WEEKLY STAFF MEETING *** + DESCRIPTION:A draft agenda needs to be sent out to the attendees + to the weekly managers meeting (MGR-LIST). Attached is a + pointer the document template for the agenda file. + ATTACH;FMTTYPE=application/msword:http://example.com/ + templates/agenda.doc + END:VALARM + +3.7. Calendar Properties + + The Calendar Properties are attributes that apply to the iCalendar + object, as a whole. These properties do not appear within a calendar + component. They SHOULD be specified after the "BEGIN:VCALENDAR" + delimiter string and prior to any calendar component. + +3.7.1. Calendar Scale + + Property Name: CALSCALE + + Purpose: This property defines the calendar scale used for the + calendar information specified in the iCalendar object. + + Value Type: TEXT + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property can be specified once in an iCalendar + object. The default value is "GREGORIAN". + + + +Desruisseaux Standards Track [Page 76] + +RFC 5545 iCalendar September 2009 + + + Description: This memo is based on the Gregorian calendar scale. + The Gregorian calendar scale is assumed if this property is not + specified in the iCalendar object. It is expected that other + calendar scales will be defined in other specifications or by + future versions of this memo. + + Format Definition: This property is defined by the following + notation: + + calscale = "CALSCALE" calparam ":" calvalue CRLF + + calparam = *(";" other-param) + + calvalue = "GREGORIAN" + + Example: The following is an example of this property: + + CALSCALE:GREGORIAN + +3.7.2. Method + + Property Name: METHOD + + Purpose: This property defines the iCalendar object method + associated with the calendar object. + + Value Type: TEXT + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property can be specified once in an iCalendar + object. + + Description: When used in a MIME message entity, the value of this + property MUST be the same as the Content-Type "method" parameter + value. If either the "METHOD" property or the Content-Type + "method" parameter is specified, then the other MUST also be + specified. + + No methods are defined by this specification. This is the subject + of other specifications, such as the iCalendar Transport- + independent Interoperability Protocol (iTIP) defined by [2446bis]. + + If this property is not present in the iCalendar object, then a + scheduling transaction MUST NOT be assumed. In such cases, the + iCalendar object is merely being used to transport a snapshot of + + + + +Desruisseaux Standards Track [Page 77] + +RFC 5545 iCalendar September 2009 + + + some calendar information; without the intention of conveying a + scheduling semantic. + + Format Definition: This property is defined by the following + notation: + + method = "METHOD" metparam ":" metvalue CRLF + + metparam = *(";" other-param) + + metvalue = iana-token + + Example: The following is a hypothetical example of this property to + convey that the iCalendar object is a scheduling request: + + METHOD:REQUEST + +3.7.3. Product Identifier + + Property Name: PRODID + + Purpose: This property specifies the identifier for the product that + created the iCalendar object. + + Value Type: TEXT + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: The property MUST be specified once in an iCalendar + object. + + Description: The vendor of the implementation SHOULD assure that + this is a globally unique identifier; using some technique such as + an FPI value, as defined in [ISO.9070.1991]. + + This property SHOULD NOT be used to alter the interpretation of an + iCalendar object beyond the semantics specified in this memo. For + example, it is not to be used to further the understanding of non- + standard properties. + + Format Definition: This property is defined by the following + notation: + + prodid = "PRODID" pidparam ":" pidvalue CRLF + + pidparam = *(";" other-param) + + + + +Desruisseaux Standards Track [Page 78] + +RFC 5545 iCalendar September 2009 + + + pidvalue = text + ;Any text that describes the product and version + ;and that is generally assured of being unique. + + Example: The following is an example of this property. It does not + imply that English is the default language. + + PRODID:-//ABC Corporation//NONSGML My Product//EN + +3.7.4. Version + + Property Name: VERSION + + Purpose: This property specifies the identifier corresponding to the + highest version number or the minimum and maximum range of the + iCalendar specification that is required in order to interpret the + iCalendar object. + + Value Type: TEXT + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property MUST be specified once in an iCalendar + object. + + Description: A value of "2.0" corresponds to this memo. + + Format Definition: This property is defined by the following + notation: + + version = "VERSION" verparam ":" vervalue CRLF + + verparam = *(";" other-param) + + vervalue = "2.0" ;This memo + / maxver + / (minver ";" maxver) + + minver = + ;Minimum iCalendar version needed to parse the iCalendar object. + + maxver = + ;Maximum iCalendar version needed to parse the iCalendar object. + + + + + + + +Desruisseaux Standards Track [Page 79] + +RFC 5545 iCalendar September 2009 + + + Example: The following is an example of this property: + + VERSION:2.0 + +3.8. Component Properties + + The following properties can appear within calendar components, as + specified by each component property definition. + +3.8.1. Descriptive Component Properties + + The following properties specify descriptive information about + calendar components. + +3.8.1.1. Attachment + + Property Name: ATTACH + + Purpose: This property provides the capability to associate a + document object with a calendar component. + + Value Type: The default value type for this property is URI. The + value type can also be set to BINARY to indicate inline binary + encoded content information. + + Property Parameters: IANA, non-standard, inline encoding, and value + data type property parameters can be specified on this property. + The format type parameter can be specified on this property and is + RECOMMENDED for inline binary encoded content information. + + Conformance: This property can be specified multiple times in a + "VEVENT", "VTODO", "VJOURNAL", or "VALARM" calendar component with + the exception of AUDIO alarm that only allows this property to + occur once. + + Description: This property is used in "VEVENT", "VTODO", and + "VJOURNAL" calendar components to associate a resource (e.g., + document) with the calendar component. This property is used in + "VALARM" calendar components to specify an audio sound resource or + an email message attachment. This property can be specified as a + URI pointing to a resource or as inline binary encoded content. + + When this property is specified as inline binary encoded content, + calendar applications MAY attempt to guess the media type of the + resource via inspection of its content if and only if the media + type of the resource is not given by the "FMTTYPE" parameter. If + the media type remains unknown, calendar applications SHOULD treat + it as type "application/octet-stream". + + + +Desruisseaux Standards Track [Page 80] + +RFC 5545 iCalendar September 2009 + + + Format Definition: This property is defined by the following + notation: + + attach = "ATTACH" attachparam ( ":" uri ) / + ( + ";" "ENCODING" "=" "BASE64" + ";" "VALUE" "=" "BINARY" + ":" binary + ) + CRLF + + attachparam = *( + ; + ; The following is OPTIONAL for a URI value, + ; RECOMMENDED for a BINARY value, + ; and MUST NOT occur more than once. + ; + (";" fmttypeparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + Example: The following are examples of this property: + + ATTACH:CID:jsmith.part3.960817T083000.xyzMail@example.com + + ATTACH;FMTTYPE=application/postscript:ftp://example.com/pub/ + reports/r-960812.ps + +3.8.1.2. Categories + + Property Name: CATEGORIES + + Purpose: This property defines the categories for a calendar + component. + + Value Type: TEXT + + Property Parameters: IANA, non-standard, and language property + parameters can be specified on this property. + + Conformance: The property can be specified within "VEVENT", "VTODO", + or "VJOURNAL" calendar components. + + + + +Desruisseaux Standards Track [Page 81] + +RFC 5545 iCalendar September 2009 + + + Description: This property is used to specify categories or subtypes + of the calendar component. The categories are useful in searching + for a calendar component of a particular type and category. + Within the "VEVENT", "VTODO", or "VJOURNAL" calendar components, + more than one category can be specified as a COMMA-separated list + of categories. + + Format Definition: This property is defined by the following + notation: + + categories = "CATEGORIES" catparam ":" text *("," text) + CRLF + + catparam = *( + ; + ; The following is OPTIONAL, + ; but MUST NOT occur more than once. + ; + (";" languageparam ) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + Example: The following are examples of this property: + + CATEGORIES:APPOINTMENT,EDUCATION + + CATEGORIES:MEETING + +3.8.1.3. Classification + + Property Name: CLASS + + Purpose: This property defines the access classification for a + calendar component. + + Value Type: TEXT + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: The property can be specified once in a "VEVENT", + "VTODO", or "VJOURNAL" calendar components. + + + + +Desruisseaux Standards Track [Page 82] + +RFC 5545 iCalendar September 2009 + + + Description: An access classification is only one component of the + general security system within a calendar application. It + provides a method of capturing the scope of the access the + calendar owner intends for information within an individual + calendar entry. The access classification of an individual + iCalendar component is useful when measured along with the other + security components of a calendar system (e.g., calendar user + authentication, authorization, access rights, access role, etc.). + Hence, the semantics of the individual access classifications + cannot be completely defined by this memo alone. Additionally, + due to the "blind" nature of most exchange processes using this + memo, these access classifications cannot serve as an enforcement + statement for a system receiving an iCalendar object. Rather, + they provide a method for capturing the intention of the calendar + owner for the access to the calendar component. If not specified + in a component that allows this property, the default value is + PUBLIC. Applications MUST treat x-name and iana-token values they + don't recognize the same way as they would the PRIVATE value. + + Format Definition: This property is defined by the following + notation: + + class = "CLASS" classparam ":" classvalue CRLF + + classparam = *(";" other-param) + + classvalue = "PUBLIC" / "PRIVATE" / "CONFIDENTIAL" / iana-token + / x-name + ;Default is PUBLIC + + Example: The following is an example of this property: + + CLASS:PUBLIC + +3.8.1.4. Comment + + Property Name: COMMENT + + Purpose: This property specifies non-processing information intended + to provide a comment to the calendar user. + + Value Type: TEXT + + Property Parameters: IANA, non-standard, alternate text + representation, and language property parameters can be specified + on this property. + + + + + +Desruisseaux Standards Track [Page 83] + +RFC 5545 iCalendar September 2009 + + + Conformance: This property can be specified multiple times in + "VEVENT", "VTODO", "VJOURNAL", and "VFREEBUSY" calendar components + as well as in the "STANDARD" and "DAYLIGHT" sub-components. + + Description: This property is used to specify a comment to the + calendar user. + + Format Definition: This property is defined by the following + notation: + + comment = "COMMENT" commparam ":" text CRLF + + commparam = *( + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + (";" altrepparam) / (";" languageparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + Example: The following is an example of this property: + + COMMENT:The meeting really needs to include both ourselves + and the customer. We can't hold this meeting without them. + As a matter of fact\, the venue for the meeting ought to be at + their site. - - John + +3.8.1.5. Description + + Property Name: DESCRIPTION + + Purpose: This property provides a more complete description of the + calendar component than that provided by the "SUMMARY" property. + + Value Type: TEXT + + Property Parameters: IANA, non-standard, alternate text + representation, and language property parameters can be specified + on this property. + + + + + + +Desruisseaux Standards Track [Page 84] + +RFC 5545 iCalendar September 2009 + + + Conformance: The property can be specified in the "VEVENT", "VTODO", + "VJOURNAL", or "VALARM" calendar components. The property can be + specified multiple times only within a "VJOURNAL" calendar + component. + + Description: This property is used in the "VEVENT" and "VTODO" to + capture lengthy textual descriptions associated with the activity. + + This property is used in the "VJOURNAL" calendar component to + capture one or more textual journal entries. + + This property is used in the "VALARM" calendar component to + capture the display text for a DISPLAY category of alarm, and to + capture the body text for an EMAIL category of alarm. + + Format Definition: This property is defined by the following + notation: + + description = "DESCRIPTION" descparam ":" text CRLF + + descparam = *( + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + (";" altrepparam) / (";" languageparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + Example: The following is an example of this property with formatted + line breaks in the property value: + + DESCRIPTION:Meeting to provide technical review for "Phoenix" + design.\nHappy Face Conference Room. Phoenix design team + MUST attend this meeting.\nRSVP to team leader. + +3.8.1.6. Geographic Position + + Property Name: GEO + + Purpose: This property specifies information related to the global + position for the activity specified by a calendar component. + + + + +Desruisseaux Standards Track [Page 85] + +RFC 5545 iCalendar September 2009 + + + Value Type: FLOAT. The value MUST be two SEMICOLON-separated FLOAT + values. + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property can be specified in "VEVENT" or "VTODO" + calendar components. + + Description: This property value specifies latitude and longitude, + in that order (i.e., "LAT LON" ordering). The longitude + represents the location east or west of the prime meridian as a + positive or negative real number, respectively. The longitude and + latitude values MAY be specified up to six decimal places, which + will allow for accuracy to within one meter of geographical + position. Receiving applications MUST accept values of this + precision and MAY truncate values of greater precision. + + Values for latitude and longitude shall be expressed as decimal + fractions of degrees. Whole degrees of latitude shall be + represented by a two-digit decimal number ranging from 0 through + 90. Whole degrees of longitude shall be represented by a decimal + number ranging from 0 through 180. When a decimal fraction of a + degree is specified, it shall be separated from the whole number + of degrees by a decimal point. + + Latitudes north of the equator shall be specified by a plus sign + (+), or by the absence of a minus sign (-), preceding the digits + designating degrees. Latitudes south of the Equator shall be + designated by a minus sign (-) preceding the digits designating + degrees. A point on the Equator shall be assigned to the Northern + Hemisphere. + + Longitudes east of the prime meridian shall be specified by a plus + sign (+), or by the absence of a minus sign (-), preceding the + digits designating degrees. Longitudes west of the meridian shall + be designated by minus sign (-) preceding the digits designating + degrees. A point on the prime meridian shall be assigned to the + Eastern Hemisphere. A point on the 180th meridian shall be + assigned to the Western Hemisphere. One exception to this last + convention is permitted. For the special condition of describing + a band of latitude around the earth, the East Bounding Coordinate + data element shall be assigned the value +180 (180) degrees. + + Any spatial address with a latitude of +90 (90) or -90 degrees + will specify the position at the North or South Pole, + respectively. The component for longitude may have any legal + value. + + + +Desruisseaux Standards Track [Page 86] + +RFC 5545 iCalendar September 2009 + + + With the exception of the special condition described above, this + form is specified in [ANSI INCITS 61-1986]. + + The simple formula for converting degrees-minutes-seconds into + decimal degrees is: + + decimal = degrees + minutes/60 + seconds/3600. + + Format Definition: This property is defined by the following + notation: + + geo = "GEO" geoparam ":" geovalue CRLF + + geoparam = *(";" other-param) + + geovalue = float ";" float + ;Latitude and Longitude components + + Example: The following is an example of this property: + + GEO:37.386013;-122.082932 + +3.8.1.7. Location + + Property Name: LOCATION + + Purpose: This property defines the intended venue for the activity + defined by a calendar component. + + Value Type: TEXT + + Property Parameters: IANA, non-standard, alternate text + representation, and language property parameters can be specified + on this property. + + Conformance: This property can be specified in "VEVENT" or "VTODO" + calendar component. + + Description: Specific venues such as conference or meeting rooms may + be explicitly specified using this property. An alternate + representation may be specified that is a URI that points to + directory information with more structured specification of the + location. For example, the alternate representation may specify + either an LDAP URL [RFC4516] pointing to an LDAP server entry or a + CID URL [RFC2392] pointing to a MIME body part containing a + Virtual-Information Card (vCard) [RFC2426] for the location. + + + + + +Desruisseaux Standards Track [Page 87] + +RFC 5545 iCalendar September 2009 + + + Format Definition: This property is defined by the following + notation: + + location = "LOCATION" locparam ":" text CRLF + + locparam = *( + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + (";" altrepparam) / (";" languageparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + Example: The following are some examples of this property: + + LOCATION:Conference Room - F123\, Bldg. 002 + + LOCATION;ALTREP="http://xyzcorp.com/conf-rooms/f123.vcf": + Conference Room - F123\, Bldg. 002 + +3.8.1.8. Percent Complete + + Property Name: PERCENT-COMPLETE + + Purpose: This property is used by an assignee or delegatee of a + to-do to convey the percent completion of a to-do to the + "Organizer". + + Value Type: INTEGER + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property can be specified once in a "VTODO" + calendar component. + + Description: The property value is a positive integer between 0 and + 100. A value of "0" indicates the to-do has not yet been started. + A value of "100" indicates that the to-do has been completed. + Integer values in between indicate the percent partially complete. + + + + + +Desruisseaux Standards Track [Page 88] + +RFC 5545 iCalendar September 2009 + + + When a to-do is assigned to multiple individuals, the property + value indicates the percent complete for that portion of the to-do + assigned to the assignee or delegatee. For example, if a to-do is + assigned to both individuals "A" and "B". A reply from "A" with a + percent complete of "70" indicates that "A" has completed 70% of + the to-do assigned to them. A reply from "B" with a percent + complete of "50" indicates "B" has completed 50% of the to-do + assigned to them. + + Format Definition: This property is defined by the following + notation: + + percent = "PERCENT-COMPLETE" pctparam ":" integer CRLF + + pctparam = *(";" other-param) + + Example: The following is an example of this property to show 39% + completion: + + PERCENT-COMPLETE:39 + +3.8.1.9. Priority + + Property Name: PRIORITY + + Purpose: This property defines the relative priority for a calendar + component. + + Value Type: INTEGER + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property can be specified in "VEVENT" and "VTODO" + calendar components. + + Description: This priority is specified as an integer in the range 0 + to 9. A value of 0 specifies an undefined priority. A value of 1 + is the highest priority. A value of 2 is the second highest + priority. Subsequent numbers specify a decreasing ordinal + priority. A value of 9 is the lowest priority. + + A CUA with a three-level priority scheme of "HIGH", "MEDIUM", and + "LOW" is mapped into this property such that a property value in + the range of 1 to 4 specifies "HIGH" priority. A value of 5 is + the normal or "MEDIUM" priority. A value in the range of 6 to 9 + is "LOW" priority. + + + + +Desruisseaux Standards Track [Page 89] + +RFC 5545 iCalendar September 2009 + + + A CUA with a priority schema of "A1", "A2", "A3", "B1", "B2", ..., + "C3" is mapped into this property such that a property value of 1 + specifies "A1", a property value of 2 specifies "A2", a property + value of 3 specifies "A3", and so forth up to a property value of + 9 specifies "C3". + + Other integer values are reserved for future use. + + Within a "VEVENT" calendar component, this property specifies a + priority for the event. This property may be useful when more + than one event is scheduled for a given time period. + + Within a "VTODO" calendar component, this property specified a + priority for the to-do. This property is useful in prioritizing + multiple action items for a given time period. + + Format Definition: This property is defined by the following + notation: + + priority = "PRIORITY" prioparam ":" priovalue CRLF + ;Default is zero (i.e., undefined). + + prioparam = *(";" other-param) + + priovalue = integer ;Must be in the range [0..9] + ; All other values are reserved for future use. + + Example: The following is an example of a property with the highest + priority: + + PRIORITY:1 + + The following is an example of a property with a next highest + priority: + + PRIORITY:2 + + The following is an example of a property with no priority. This + is equivalent to not specifying the "PRIORITY" property: + + PRIORITY:0 + + + + + + + + + + +Desruisseaux Standards Track [Page 90] + +RFC 5545 iCalendar September 2009 + + +3.8.1.10. Resources + + Property Name: RESOURCES + + Purpose: This property defines the equipment or resources + anticipated for an activity specified by a calendar component. + + Value Type: TEXT + + Property Parameters: IANA, non-standard, alternate text + representation, and language property parameters can be specified + on this property. + + Conformance: This property can be specified once in "VEVENT" or + "VTODO" calendar component. + + Description: The property value is an arbitrary text. More than one + resource can be specified as a COMMA-separated list of resources. + + Format Definition: This property is defined by the following + notation: + + resources = "RESOURCES" resrcparam ":" text *("," text) CRLF + + resrcparam = *( + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + (";" altrepparam) / (";" languageparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + Example: The following is an example of this property: + + RESOURCES:EASEL,PROJECTOR,VCR + + RESOURCES;LANGUAGE=fr:Nettoyeur haute pression + + + + + + + + +Desruisseaux Standards Track [Page 91] + +RFC 5545 iCalendar September 2009 + + +3.8.1.11. Status + + Property Name: STATUS + + Purpose: This property defines the overall status or confirmation + for the calendar component. + + Value Type: TEXT + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property can be specified once in "VEVENT", + "VTODO", or "VJOURNAL" calendar components. + + Description: In a group-scheduled calendar component, the property + is used by the "Organizer" to provide a confirmation of the event + to the "Attendees". For example in a "VEVENT" calendar component, + the "Organizer" can indicate that a meeting is tentative, + confirmed, or cancelled. In a "VTODO" calendar component, the + "Organizer" can indicate that an action item needs action, is + completed, is in process or being worked on, or has been + cancelled. In a "VJOURNAL" calendar component, the "Organizer" + can indicate that a journal entry is draft, final, or has been + cancelled or removed. + + Format Definition: This property is defined by the following + notation: + + status = "STATUS" statparam ":" statvalue CRLF + + statparam = *(";" other-param) + + statvalue = (statvalue-event + / statvalue-todo + / statvalue-jour) + + statvalue-event = "TENTATIVE" ;Indicates event is tentative. + / "CONFIRMED" ;Indicates event is definite. + / "CANCELLED" ;Indicates event was cancelled. + ;Status values for a "VEVENT" + + statvalue-todo = "NEEDS-ACTION" ;Indicates to-do needs action. + / "COMPLETED" ;Indicates to-do completed. + / "IN-PROCESS" ;Indicates to-do in process of. + / "CANCELLED" ;Indicates to-do was cancelled. + ;Status values for "VTODO". + + + + +Desruisseaux Standards Track [Page 92] + +RFC 5545 iCalendar September 2009 + + + statvalue-jour = "DRAFT" ;Indicates journal is draft. + / "FINAL" ;Indicates journal is final. + / "CANCELLED" ;Indicates journal is removed. + ;Status values for "VJOURNAL". + + Example: The following is an example of this property for a "VEVENT" + calendar component: + + STATUS:TENTATIVE + + The following is an example of this property for a "VTODO" + calendar component: + + STATUS:NEEDS-ACTION + + The following is an example of this property for a "VJOURNAL" + calendar component: + + STATUS:DRAFT + +3.8.1.12. Summary + + Property Name: SUMMARY + + Purpose: This property defines a short summary or subject for the + calendar component. + + Value Type: TEXT + + Property Parameters: IANA, non-standard, alternate text + representation, and language property parameters can be specified + on this property. + + Conformance: The property can be specified in "VEVENT", "VTODO", + "VJOURNAL", or "VALARM" calendar components. + + Description: This property is used in the "VEVENT", "VTODO", and + "VJOURNAL" calendar components to capture a short, one-line + summary about the activity or journal entry. + + This property is used in the "VALARM" calendar component to + capture the subject of an EMAIL category of alarm. + + Format Definition: This property is defined by the following + notation: + + + + + + +Desruisseaux Standards Track [Page 93] + +RFC 5545 iCalendar September 2009 + + + summary = "SUMMARY" summparam ":" text CRLF + + summparam = *( + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + (";" altrepparam) / (";" languageparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + Example: The following is an example of this property: + + SUMMARY:Department Party + +3.8.2. Date and Time Component Properties + + The following properties specify date and time related information in + calendar components. + +3.8.2.1. Date-Time Completed + + Property Name: COMPLETED + + Purpose: This property defines the date and time that a to-do was + actually completed. + + Value Type: DATE-TIME + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: The property can be specified in a "VTODO" calendar + component. The value MUST be specified as a date with UTC time. + + Description: This property defines the date and time that a to-do + was actually completed. + + Format Definition: This property is defined by the following + notation: + + + + + + +Desruisseaux Standards Track [Page 94] + +RFC 5545 iCalendar September 2009 + + + completed = "COMPLETED" compparam ":" date-time CRLF + + compparam = *(";" other-param) + + Example: The following is an example of this property: + + COMPLETED:19960401T150000Z + +3.8.2.2. Date-Time End + + Property Name: DTEND + + Purpose: This property specifies the date and time that a calendar + component ends. + + Value Type: The default value type is DATE-TIME. The value type can + be set to a DATE value type. + + Property Parameters: IANA, non-standard, value data type, and time + zone identifier property parameters can be specified on this + property. + + Conformance: This property can be specified in "VEVENT" or + "VFREEBUSY" calendar components. + + Description: Within the "VEVENT" calendar component, this property + defines the date and time by which the event ends. The value type + of this property MUST be the same as the "DTSTART" property, and + its value MUST be later in time than the value of the "DTSTART" + property. Furthermore, this property MUST be specified as a date + with local time if and only if the "DTSTART" property is also + specified as a date with local time. + + Within the "VFREEBUSY" calendar component, this property defines + the end date and time for the free or busy time information. The + time MUST be specified in the UTC time format. The value MUST be + later in time than the value of the "DTSTART" property. + + Format Definition: This property is defined by the following + notation: + + + + + + + + + + + +Desruisseaux Standards Track [Page 95] + +RFC 5545 iCalendar September 2009 + + + dtend = "DTEND" dtendparam ":" dtendval CRLF + + dtendparam = *( + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + (";" "VALUE" "=" ("DATE-TIME" / "DATE")) / + (";" tzidparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + dtendval = date-time / date + ;Value MUST match value type + + Example: The following is an example of this property: + + DTEND:19960401T150000Z + + DTEND;VALUE=DATE:19980704 + +3.8.2.3. Date-Time Due + + Property Name: DUE + + Purpose: This property defines the date and time that a to-do is + expected to be completed. + + Value Type: The default value type is DATE-TIME. The value type can + be set to a DATE value type. + + Property Parameters: IANA, non-standard, value data type, and time + zone identifier property parameters can be specified on this + property. + + Conformance: The property can be specified once in a "VTODO" + calendar component. + + Description: This property defines the date and time before which a + to-do is expected to be completed. For cases where this property + is specified in a "VTODO" calendar component that also specifies a + "DTSTART" property, the value type of this property MUST be the + same as the "DTSTART" property, and the value of this property + + + +Desruisseaux Standards Track [Page 96] + +RFC 5545 iCalendar September 2009 + + + MUST be later in time than the value of the "DTSTART" property. + Furthermore, this property MUST be specified as a date with local + time if and only if the "DTSTART" property is also specified as a + date with local time. + + Format Definition: This property is defined by the following + notation: + + due = "DUE" dueparam ":" dueval CRLF + + dueparam = *( + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + (";" "VALUE" "=" ("DATE-TIME" / "DATE")) / + (";" tzidparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + dueval = date-time / date + ;Value MUST match value type + + Example: The following is an example of this property: + + DUE:19980430T000000Z + +3.8.2.4. Date-Time Start + + Property Name: DTSTART + + Purpose: This property specifies when the calendar component begins. + + Value Type: The default value type is DATE-TIME. The time value + MUST be one of the forms defined for the DATE-TIME value type. + The value type can be set to a DATE value type. + + Property Parameters: IANA, non-standard, value data type, and time + zone identifier property parameters can be specified on this + property. + + Conformance: This property can be specified once in the "VEVENT", + "VTODO", or "VFREEBUSY" calendar components as well as in the + + + +Desruisseaux Standards Track [Page 97] + +RFC 5545 iCalendar September 2009 + + + "STANDARD" and "DAYLIGHT" sub-components. This property is + REQUIRED in all types of recurring calendar components that + specify the "RRULE" property. This property is also REQUIRED in + "VEVENT" calendar components contained in iCalendar objects that + don't specify the "METHOD" property. + + Description: Within the "VEVENT" calendar component, this property + defines the start date and time for the event. + + Within the "VFREEBUSY" calendar component, this property defines + the start date and time for the free or busy time information. + The time MUST be specified in UTC time. + + Within the "STANDARD" and "DAYLIGHT" sub-components, this property + defines the effective start date and time for a time zone + specification. This property is REQUIRED within each "STANDARD" + and "DAYLIGHT" sub-components included in "VTIMEZONE" calendar + components and MUST be specified as a date with local time without + the "TZID" property parameter. + + Format Definition: This property is defined by the following + notation: + + dtstart = "DTSTART" dtstparam ":" dtstval CRLF + + dtstparam = *( + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + (";" "VALUE" "=" ("DATE-TIME" / "DATE")) / + (";" tzidparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + dtstval = date-time / date + ;Value MUST match value type + + Example: The following is an example of this property: + + DTSTART:19980118T073000Z + + + + + +Desruisseaux Standards Track [Page 98] + +RFC 5545 iCalendar September 2009 + + +3.8.2.5. Duration + + Property Name: DURATION + + Purpose: This property specifies a positive duration of time. + + Value Type: DURATION + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property can be specified in "VEVENT", "VTODO", or + "VALARM" calendar components. + + Description: In a "VEVENT" calendar component the property may be + used to specify a duration of the event, instead of an explicit + end DATE-TIME. In a "VTODO" calendar component the property may + be used to specify a duration for the to-do, instead of an + explicit due DATE-TIME. In a "VALARM" calendar component the + property may be used to specify the delay period prior to + repeating an alarm. When the "DURATION" property relates to a + "DTSTART" property that is specified as a DATE value, then the + "DURATION" property MUST be specified as a "dur-day" or "dur-week" + value. + + Format Definition: This property is defined by the following + notation: + + duration = "DURATION" durparam ":" dur-value CRLF + ;consisting of a positive duration of time. + + durparam = *(";" other-param) + + Example: The following is an example of this property that specifies + an interval of time of one hour and zero minutes and zero seconds: + + DURATION:PT1H0M0S + + The following is an example of this property that specifies an + interval of time of 15 minutes. + + DURATION:PT15M + + + + + + + + + +Desruisseaux Standards Track [Page 99] + +RFC 5545 iCalendar September 2009 + + +3.8.2.6. Free/Busy Time + + Property Name: FREEBUSY + + Purpose: This property defines one or more free or busy time + intervals. + + Value Type: PERIOD + + Property Parameters: IANA, non-standard, and free/busy time type + property parameters can be specified on this property. + + Conformance: The property can be specified in a "VFREEBUSY" calendar + component. + + Description: These time periods can be specified as either a start + and end DATE-TIME or a start DATE-TIME and DURATION. The date and + time MUST be a UTC time format. + + "FREEBUSY" properties within the "VFREEBUSY" calendar component + SHOULD be sorted in ascending order, based on start time and then + end time, with the earliest periods first. + + The "FREEBUSY" property can specify more than one value, separated + by the COMMA character. In such cases, the "FREEBUSY" property + values MUST all be of the same "FBTYPE" property parameter type + (e.g., all values of a particular "FBTYPE" listed together in a + single property). + + Format Definition: This property is defined by the following + notation: + + freebusy = "FREEBUSY" fbparam ":" fbvalue CRLF + + fbparam = *( + ; + ; The following is OPTIONAL, + ; but MUST NOT occur more than once. + ; + (";" fbtypeparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + + + +Desruisseaux Standards Track [Page 100] + +RFC 5545 iCalendar September 2009 + + + fbvalue = period *("," period) + ;Time value MUST be in the UTC time format. + + Example: The following are some examples of this property: + + FREEBUSY;FBTYPE=BUSY-UNAVAILABLE:19970308T160000Z/PT8H30M + + FREEBUSY;FBTYPE=FREE:19970308T160000Z/PT3H,19970308T200000Z/PT1H + + FREEBUSY;FBTYPE=FREE:19970308T160000Z/PT3H,19970308T200000Z/PT1H + ,19970308T230000Z/19970309T000000Z + +3.8.2.7. Time Transparency + + Property Name: TRANSP + + Purpose: This property defines whether or not an event is + transparent to busy time searches. + + Value Type: TEXT + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property can be specified once in a "VEVENT" + calendar component. + + Description: Time Transparency is the characteristic of an event + that determines whether it appears to consume time on a calendar. + Events that consume actual time for the individual or resource + associated with the calendar SHOULD be recorded as OPAQUE, + allowing them to be detected by free/busy time searches. Other + events, which do not take up the individual's (or resource's) time + SHOULD be recorded as TRANSPARENT, making them invisible to free/ + busy time searches. + + Format Definition: This property is defined by the following + notation: + + transp = "TRANSP" transparam ":" transvalue CRLF + + transparam = *(";" other-param) + + transvalue = "OPAQUE" + ;Blocks or opaque on busy time searches. + / "TRANSPARENT" + ;Transparent on busy time searches. + ;Default value is OPAQUE + + + +Desruisseaux Standards Track [Page 101] + +RFC 5545 iCalendar September 2009 + + + Example: The following is an example of this property for an event + that is transparent or does not block on free/busy time searches: + + TRANSP:TRANSPARENT + + The following is an example of this property for an event that is + opaque or blocks on free/busy time searches: + + TRANSP:OPAQUE + +3.8.3. Time Zone Component Properties + + The following properties specify time zone information in calendar + components. + +3.8.3.1. Time Zone Identifier + + Property Name: TZID + + Purpose: This property specifies the text value that uniquely + identifies the "VTIMEZONE" calendar component in the scope of an + iCalendar object. + + Value Type: TEXT + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property MUST be specified in a "VTIMEZONE" + calendar component. + + Description: This is the label by which a time zone calendar + component is referenced by any iCalendar properties whose value + type is either DATE-TIME or TIME and not intended to specify a UTC + or a "floating" time. The presence of the SOLIDUS character as a + prefix, indicates that this "TZID" represents an unique ID in a + globally defined time zone registry (when such registry is + defined). + + Note: This document does not define a naming convention for + time zone identifiers. Implementers may want to use the naming + conventions defined in existing time zone specifications such + as the public-domain TZ database [TZDB]. The specification of + globally unique time zone identifiers is not addressed by this + document and is left for future study. + + + + + + +Desruisseaux Standards Track [Page 102] + +RFC 5545 iCalendar September 2009 + + + Format Definition: This property is defined by the following + notation: + + tzid = "TZID" tzidpropparam ":" [tzidprefix] text CRLF + + tzidpropparam = *(";" other-param) + + ;tzidprefix = "/" + ; Defined previously. Just listed here for reader convenience. + + Example: The following are examples of non-globally unique time zone + identifiers: + + TZID:America/New_York + + TZID:America/Los_Angeles + + The following is an example of a fictitious globally unique time + zone identifier: + + TZID:/example.org/America/New_York + +3.8.3.2. Time Zone Name + + Property Name: TZNAME + + Purpose: This property specifies the customary designation for a + time zone description. + + Value Type: TEXT + + Property Parameters: IANA, non-standard, and language property + parameters can be specified on this property. + + Conformance: This property can be specified in "STANDARD" and + "DAYLIGHT" sub-components. + + Description: This property specifies a customary name that can be + used when displaying dates that occur during the observance + defined by the time zone sub-component. + + Format Definition: This property is defined by the following + notation: + + + + + + + + +Desruisseaux Standards Track [Page 103] + +RFC 5545 iCalendar September 2009 + + + tzname = "TZNAME" tznparam ":" text CRLF + + tznparam = *( + ; + ; The following is OPTIONAL, + ; but MUST NOT occur more than once. + ; + (";" languageparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + Example: The following are examples of this property: + + TZNAME:EST + + TZNAME;LANGUAGE=fr-CA:HNE + +3.8.3.3. Time Zone Offset From + + Property Name: TZOFFSETFROM + + Purpose: This property specifies the offset that is in use prior to + this time zone observance. + + Value Type: UTC-OFFSET + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property MUST be specified in "STANDARD" and + "DAYLIGHT" sub-components. + + Description: This property specifies the offset that is in use prior + to this time observance. It is used to calculate the absolute + time at which the transition to a given observance takes place. + This property MUST only be specified in a "VTIMEZONE" calendar + component. A "VTIMEZONE" calendar component MUST include this + property. The property value is a signed numeric indicating the + number of hours and possibly minutes from UTC. Positive numbers + represent time zones east of the prime meridian, or ahead of UTC. + Negative numbers represent time zones west of the prime meridian, + or behind UTC. + + + + +Desruisseaux Standards Track [Page 104] + +RFC 5545 iCalendar September 2009 + + + Format Definition: This property is defined by the following + notation: + + tzoffsetfrom = "TZOFFSETFROM" frmparam ":" utc-offset + CRLF + + frmparam = *(";" other-param) + + Example: The following are examples of this property: + + TZOFFSETFROM:-0500 + + TZOFFSETFROM:+1345 + +3.8.3.4. Time Zone Offset To + + Property Name: TZOFFSETTO + + Purpose: This property specifies the offset that is in use in this + time zone observance. + + Value Type: UTC-OFFSET + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property MUST be specified in "STANDARD" and + "DAYLIGHT" sub-components. + + Description: This property specifies the offset that is in use in + this time zone observance. It is used to calculate the absolute + time for the new observance. The property value is a signed + numeric indicating the number of hours and possibly minutes from + UTC. Positive numbers represent time zones east of the prime + meridian, or ahead of UTC. Negative numbers represent time zones + west of the prime meridian, or behind UTC. + + Format Definition: This property is defined by the following + notation: + + tzoffsetto = "TZOFFSETTO" toparam ":" utc-offset CRLF + + toparam = *(";" other-param) + + + + + + + + +Desruisseaux Standards Track [Page 105] + +RFC 5545 iCalendar September 2009 + + + Example: The following are examples of this property: + + TZOFFSETTO:-0400 + + TZOFFSETTO:+1245 + +3.8.3.5. Time Zone URL + + Property Name: TZURL + + Purpose: This property provides a means for a "VTIMEZONE" component + to point to a network location that can be used to retrieve an up- + to-date version of itself. + + Value Type: URI + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property can be specified in a "VTIMEZONE" + calendar component. + + Description: This property provides a means for a "VTIMEZONE" + component to point to a network location that can be used to + retrieve an up-to-date version of itself. This provides a hook to + handle changes government bodies impose upon time zone + definitions. Retrieval of this resource results in an iCalendar + object containing a single "VTIMEZONE" component and a "METHOD" + property set to PUBLISH. + + Format Definition: This property is defined by the following + notation: + + tzurl = "TZURL" tzurlparam ":" uri CRLF + + tzurlparam = *(";" other-param) + + Example: The following is an example of this property: + + TZURL:http://timezones.example.org/tz/America-Los_Angeles.ics + +3.8.4. Relationship Component Properties + + The following properties specify relationship information in calendar + components. + + + + + + +Desruisseaux Standards Track [Page 106] + +RFC 5545 iCalendar September 2009 + + +3.8.4.1. Attendee + + Property Name: ATTENDEE + + Purpose: This property defines an "Attendee" within a calendar + component. + + Value Type: CAL-ADDRESS + + Property Parameters: IANA, non-standard, language, calendar user + type, group or list membership, participation role, participation + status, RSVP expectation, delegatee, delegator, sent by, common + name, or directory entry reference property parameters can be + specified on this property. + + Conformance: This property MUST be specified in an iCalendar object + that specifies a group-scheduled calendar entity. This property + MUST NOT be specified in an iCalendar object when publishing the + calendar information (e.g., NOT in an iCalendar object that + specifies the publication of a calendar user's busy time, event, + to-do, or journal). This property is not specified in an + iCalendar object that specifies only a time zone definition or + that defines calendar components that are not group-scheduled + components, but are components only on a single user's calendar. + + Description: This property MUST only be specified within calendar + components to specify participants, non-participants, and the + chair of a group-scheduled calendar entity. The property is + specified within an "EMAIL" category of the "VALARM" calendar + component to specify an email address that is to receive the email + type of iCalendar alarm. + + The property parameter "CN" is for the common or displayable name + associated with the calendar address; "ROLE", for the intended + role that the attendee will have in the calendar component; + "PARTSTAT", for the status of the attendee's participation; + "RSVP", for indicating whether the favor of a reply is requested; + "CUTYPE", to indicate the type of calendar user; "MEMBER", to + indicate the groups that the attendee belongs to; "DELEGATED-TO", + to indicate the calendar users that the original request was + delegated to; and "DELEGATED-FROM", to indicate whom the request + was delegated from; "SENT-BY", to indicate whom is acting on + behalf of the "ATTENDEE"; and "DIR", to indicate the URI that + points to the directory information corresponding to the attendee. + These property parameters can be specified on an "ATTENDEE" + property in either a "VEVENT", "VTODO", or "VJOURNAL" calendar + component. They MUST NOT be specified in an "ATTENDEE" property + in a "VFREEBUSY" or "VALARM" calendar component. If the + + + +Desruisseaux Standards Track [Page 107] + +RFC 5545 iCalendar September 2009 + + + "LANGUAGE" property parameter is specified, the identified + language applies to the "CN" parameter. + + A recipient delegated a request MUST inherit the "RSVP" and "ROLE" + values from the attendee that delegated the request to them. + + Multiple attendees can be specified by including multiple + "ATTENDEE" properties within the calendar component. + + Format Definition: This property is defined by the following + notation: + + attendee = "ATTENDEE" attparam ":" cal-address CRLF + + attparam = *( + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + (";" cutypeparam) / (";" memberparam) / + (";" roleparam) / (";" partstatparam) / + (";" rsvpparam) / (";" deltoparam) / + (";" delfromparam) / (";" sentbyparam) / + (";" cnparam) / (";" dirparam) / + (";" languageparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + Example: The following are examples of this property's use for a + to-do: + + ATTENDEE;MEMBER="mailto:DEV-GROUP@example.com": + mailto:joecool@example.com + ATTENDEE;DELEGATED-FROM="mailto:immud@example.com": + mailto:ildoit@example.com + + + + + + + + + + + +Desruisseaux Standards Track [Page 108] + +RFC 5545 iCalendar September 2009 + + + The following is an example of this property used for specifying + multiple attendees to an event: + + ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=TENTATIVE;CN=Henry + Cabot:mailto:hcabot@example.com + ATTENDEE;ROLE=REQ-PARTICIPANT;DELEGATED-FROM="mailto:bob@ + example.com";PARTSTAT=ACCEPTED;CN=Jane Doe:mailto:jdoe@ + example.com + + The following is an example of this property with a URI to the + directory information associated with the attendee: + + ATTENDEE;CN=John Smith;DIR="ldap://example.com:6666/o=ABC% + 20Industries,c=US???(cn=Jim%20Dolittle)":mailto:jimdo@ + example.com + + The following is an example of this property with "delegatee" and + "delegator" information for an event: + + ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=TENTATIVE;DELEGATED-FROM= + "mailto:iamboss@example.com";CN=Henry Cabot:mailto:hcabot@ + example.com + ATTENDEE;ROLE=NON-PARTICIPANT;PARTSTAT=DELEGATED;DELEGATED-TO= + "mailto:hcabot@example.com";CN=The Big Cheese:mailto:iamboss + @example.com + ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=ACCEPTED;CN=Jane Doe + :mailto:jdoe@example.com + + Example: The following is an example of this property's use when + another calendar user is acting on behalf of the "Attendee": + + ATTENDEE;SENT-BY=mailto:jan_doe@example.com;CN=John Smith: + mailto:jsmith@example.com + +3.8.4.2. Contact + + Property Name: CONTACT + + Purpose: This property is used to represent contact information or + alternately a reference to contact information associated with the + calendar component. + + Value Type: TEXT + + Property Parameters: IANA, non-standard, alternate text + representation, and language property parameters can be specified + on this property. + + + + +Desruisseaux Standards Track [Page 109] + +RFC 5545 iCalendar September 2009 + + + Conformance: This property can be specified in a "VEVENT", "VTODO", + "VJOURNAL", or "VFREEBUSY" calendar component. + + Description: The property value consists of textual contact + information. An alternative representation for the property value + can also be specified that refers to a URI pointing to an + alternate form, such as a vCard [RFC2426], for the contact + information. + + Format Definition: This property is defined by the following + notation: + + contact = "CONTACT" contparam ":" text CRLF + + contparam = *( + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + (";" altrepparam) / (";" languageparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + Example: The following is an example of this property referencing + textual contact information: + + CONTACT:Jim Dolittle\, ABC Industries\, +1-919-555-1234 + + The following is an example of this property with an alternate + representation of an LDAP URI to a directory entry containing the + contact information: + + CONTACT;ALTREP="ldap://example.com:6666/o=ABC%20Industries\, + c=US???(cn=Jim%20Dolittle)":Jim Dolittle\, ABC Industries\, + +1-919-555-1234 + + The following is an example of this property with an alternate + representation of a MIME body part containing the contact + information, such as a vCard [RFC2426] embedded in a text/ + directory media type [RFC2425]: + + CONTACT;ALTREP="CID:part3.msg970930T083000SILVER@example.com": + Jim Dolittle\, ABC Industries\, +1-919-555-1234 + + + +Desruisseaux Standards Track [Page 110] + +RFC 5545 iCalendar September 2009 + + + The following is an example of this property referencing a network + resource, such as a vCard [RFC2426] object containing the contact + information: + + CONTACT;ALTREP="http://example.com/pdi/jdoe.vcf":Jim + Dolittle\, ABC Industries\, +1-919-555-1234 + +3.8.4.3. Organizer + + Property Name: ORGANIZER + + Purpose: This property defines the organizer for a calendar + component. + + Value Type: CAL-ADDRESS + + Property Parameters: IANA, non-standard, language, common name, + directory entry reference, and sent-by property parameters can be + specified on this property. + + Conformance: This property MUST be specified in an iCalendar object + that specifies a group-scheduled calendar entity. This property + MUST be specified in an iCalendar object that specifies the + publication of a calendar user's busy time. This property MUST + NOT be specified in an iCalendar object that specifies only a time + zone definition or that defines calendar components that are not + group-scheduled components, but are components only on a single + user's calendar. + + Description: This property is specified within the "VEVENT", + "VTODO", and "VJOURNAL" calendar components to specify the + organizer of a group-scheduled calendar entity. The property is + specified within the "VFREEBUSY" calendar component to specify the + calendar user requesting the free or busy time. When publishing a + "VFREEBUSY" calendar component, the property is used to specify + the calendar that the published busy time came from. + + The property has the property parameters "CN", for specifying the + common or display name associated with the "Organizer", "DIR", for + specifying a pointer to the directory information associated with + the "Organizer", "SENT-BY", for specifying another calendar user + that is acting on behalf of the "Organizer". The non-standard + parameters may also be specified on this property. If the + "LANGUAGE" property parameter is specified, the identified + language applies to the "CN" parameter value. + + + + + + +Desruisseaux Standards Track [Page 111] + +RFC 5545 iCalendar September 2009 + + + Format Definition: This property is defined by the following + notation: + + organizer = "ORGANIZER" orgparam ":" + cal-address CRLF + + orgparam = *( + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + (";" cnparam) / (";" dirparam) / (";" sentbyparam) / + (";" languageparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + Example: The following is an example of this property: + + ORGANIZER;CN=John Smith:mailto:jsmith@example.com + + The following is an example of this property with a pointer to the + directory information associated with the organizer: + + ORGANIZER;CN=JohnSmith;DIR="ldap://example.com:6666/o=DC%20Ass + ociates,c=US???(cn=John%20Smith)":mailto:jsmith@example.com + + The following is an example of this property used by another + calendar user who is acting on behalf of the organizer, with + responses intended to be sent back to the organizer, not the other + calendar user: + + ORGANIZER;SENT-BY="mailto:jane_doe@example.com": + mailto:jsmith@example.com + +3.8.4.4. Recurrence ID + + Property Name: RECURRENCE-ID + + Purpose: This property is used in conjunction with the "UID" and + "SEQUENCE" properties to identify a specific instance of a + recurring "VEVENT", "VTODO", or "VJOURNAL" calendar component. + The property value is the original value of the "DTSTART" property + of the recurrence instance. + + + +Desruisseaux Standards Track [Page 112] + +RFC 5545 iCalendar September 2009 + + + Value Type: The default value type is DATE-TIME. The value type can + be set to a DATE value type. This property MUST have the same + value type as the "DTSTART" property contained within the + recurring component. Furthermore, this property MUST be specified + as a date with local time if and only if the "DTSTART" property + contained within the recurring component is specified as a date + with local time. + + Property Parameters: IANA, non-standard, value data type, time zone + identifier, and recurrence identifier range parameters can be + specified on this property. + + Conformance: This property can be specified in an iCalendar object + containing a recurring calendar component. + + Description: The full range of calendar components specified by a + recurrence set is referenced by referring to just the "UID" + property value corresponding to the calendar component. The + "RECURRENCE-ID" property allows the reference to an individual + instance within the recurrence set. + + If the value of the "DTSTART" property is a DATE type value, then + the value MUST be the calendar date for the recurrence instance. + + The DATE-TIME value is set to the time when the original + recurrence instance would occur; meaning that if the intent is to + change a Friday meeting to Thursday, the DATE-TIME is still set to + the original Friday meeting. + + The "RECURRENCE-ID" property is used in conjunction with the "UID" + and "SEQUENCE" properties to identify a particular instance of a + recurring event, to-do, or journal. For a given pair of "UID" and + "SEQUENCE" property values, the "RECURRENCE-ID" value for a + recurrence instance is fixed. + + The "RANGE" parameter is used to specify the effective range of + recurrence instances from the instance specified by the + "RECURRENCE-ID" property value. The value for the range parameter + can only be "THISANDFUTURE" to indicate a range defined by the + given recurrence instance and all subsequent instances. + Subsequent instances are determined by their "RECURRENCE-ID" value + and not their current scheduled start time. Subsequent instances + defined in separate components are not impacted by the given + recurrence instance. When the given recurrence instance is + rescheduled, all subsequent instances are also rescheduled by the + same time difference. For instance, if the given recurrence + instance is rescheduled to start 2 hours later, then all + subsequent instances are also rescheduled 2 hours later. + + + +Desruisseaux Standards Track [Page 113] + +RFC 5545 iCalendar September 2009 + + + Similarly, if the duration of the given recurrence instance is + modified, then all subsequence instances are also modified to have + this same duration. + + Note: The "RANGE" parameter may not be appropriate to + reschedule specific subsequent instances of complex recurring + calendar component. Assuming an unbounded recurring calendar + component scheduled to occur on Mondays and Wednesdays, the + "RANGE" parameter could not be used to reschedule only the + future Monday instances to occur on Tuesday instead. In such + cases, the calendar application could simply truncate the + unbounded recurring calendar component (i.e., with the "COUNT" + or "UNTIL" rule parts), and create two new unbounded recurring + calendar components for the future instances. + + Format Definition: This property is defined by the following + notation: + + recurid = "RECURRENCE-ID" ridparam ":" ridval CRLF + + ridparam = *( + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + (";" "VALUE" "=" ("DATE-TIME" / "DATE")) / + (";" tzidparam) / (";" rangeparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + ridval = date-time / date + ;Value MUST match value type + + Example: The following are examples of this property: + + RECURRENCE-ID;VALUE=DATE:19960401 + + RECURRENCE-ID;RANGE=THISANDFUTURE:19960120T120000Z + + + + + + + + +Desruisseaux Standards Track [Page 114] + +RFC 5545 iCalendar September 2009 + + +3.8.4.5. Related To + + Property Name: RELATED-TO + + Purpose: This property is used to represent a relationship or + reference between one calendar component and another. + + Value Type: TEXT + + Property Parameters: IANA, non-standard, and relationship type + property parameters can be specified on this property. + + Conformance: This property can be specified in the "VEVENT", + "VTODO", and "VJOURNAL" calendar components. + + Description: The property value consists of the persistent, globally + unique identifier of another calendar component. This value would + be represented in a calendar component by the "UID" property. + + By default, the property value points to another calendar + component that has a PARENT relationship to the referencing + object. The "RELTYPE" property parameter is used to either + explicitly state the default PARENT relationship type to the + referenced calendar component or to override the default PARENT + relationship type and specify either a CHILD or SIBLING + relationship. The PARENT relationship indicates that the calendar + component is a subordinate of the referenced calendar component. + The CHILD relationship indicates that the calendar component is a + superior of the referenced calendar component. The SIBLING + relationship indicates that the calendar component is a peer of + the referenced calendar component. + + Changes to a calendar component referenced by this property can + have an implicit impact on the related calendar component. For + example, if a group event changes its start or end date or time, + then the related, dependent events will need to have their start + and end dates changed in a corresponding way. Similarly, if a + PARENT calendar component is cancelled or deleted, then there is + an implied impact to the related CHILD calendar components. This + property is intended only to provide information on the + relationship of calendar components. It is up to the target + calendar system to maintain any property implications of this + relationship. + + + + + + + + +Desruisseaux Standards Track [Page 115] + +RFC 5545 iCalendar September 2009 + + + Format Definition: This property is defined by the following + notation: + + related = "RELATED-TO" relparam ":" text CRLF + + relparam = *( + ; + ; The following is OPTIONAL, + ; but MUST NOT occur more than once. + ; + (";" reltypeparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + The following is an example of this property: + + RELATED-TO:jsmith.part7.19960817T083000.xyzMail@example.com + + RELATED-TO:19960401-080045-4000F192713-0052@example.com + +3.8.4.6. Uniform Resource Locator + + Property Name: URL + + Purpose: This property defines a Uniform Resource Locator (URL) + associated with the iCalendar object. + + Value Type: URI + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property can be specified once in the "VEVENT", + "VTODO", "VJOURNAL", or "VFREEBUSY" calendar components. + + Description: This property may be used in a calendar component to + convey a location where a more dynamic rendition of the calendar + information associated with the calendar component can be found. + This memo does not attempt to standardize the form of the URI, nor + the format of the resource pointed to by the property value. If + the URL property and Content-Location MIME header are both + specified, they MUST point to the same resource. + + + + +Desruisseaux Standards Track [Page 116] + +RFC 5545 iCalendar September 2009 + + + Format Definition: This property is defined by the following + notation: + + url = "URL" urlparam ":" uri CRLF + + urlparam = *(";" other-param) + + Example: The following is an example of this property: + + URL:http://example.com/pub/calendars/jsmith/mytime.ics + +3.8.4.7. Unique Identifier + + Property Name: UID + + Purpose: This property defines the persistent, globally unique + identifier for the calendar component. + + Value Type: TEXT + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: The property MUST be specified in the "VEVENT", + "VTODO", "VJOURNAL", or "VFREEBUSY" calendar components. + + Description: The "UID" itself MUST be a globally unique identifier. + The generator of the identifier MUST guarantee that the identifier + is unique. There are several algorithms that can be used to + accomplish this. A good method to assure uniqueness is to put the + domain name or a domain literal IP address of the host on which + the identifier was created on the right-hand side of an "@", and + on the left-hand side, put a combination of the current calendar + date and time of day (i.e., formatted in as a DATE-TIME value) + along with some other currently unique (perhaps sequential) + identifier available on the system (for example, a process id + number). Using a DATE-TIME value on the left-hand side and a + domain name or domain literal on the right-hand side makes it + possible to guarantee uniqueness since no two hosts should be + using the same domain name or IP address at the same time. Though + other algorithms will work, it is RECOMMENDED that the right-hand + side contain some domain identifier (either of the host itself or + otherwise) such that the generator of the message identifier can + guarantee the uniqueness of the left-hand side within the scope of + that domain. + + This is the method for correlating scheduling messages with the + referenced "VEVENT", "VTODO", or "VJOURNAL" calendar component. + + + +Desruisseaux Standards Track [Page 117] + +RFC 5545 iCalendar September 2009 + + + The full range of calendar components specified by a recurrence + set is referenced by referring to just the "UID" property value + corresponding to the calendar component. The "RECURRENCE-ID" + property allows the reference to an individual instance within the + recurrence set. + + This property is an important method for group-scheduling + applications to match requests with later replies, modifications, + or deletion requests. Calendaring and scheduling applications + MUST generate this property in "VEVENT", "VTODO", and "VJOURNAL" + calendar components to assure interoperability with other group- + scheduling applications. This identifier is created by the + calendar system that generates an iCalendar object. + + Implementations MUST be able to receive and persist values of at + least 255 octets for this property, but they MUST NOT truncate + values in the middle of a UTF-8 multi-octet sequence. + + Format Definition: This property is defined by the following + notation: + + uid = "UID" uidparam ":" text CRLF + + uidparam = *(";" other-param) + + Example: The following is an example of this property: + + UID:19960401T080045Z-4000F192713-0052@example.com + +3.8.5. Recurrence Component Properties + + The following properties specify recurrence information in calendar + components. + +3.8.5.1. Exception Date-Times + + Property Name: EXDATE + + Purpose: This property defines the list of DATE-TIME exceptions for + recurring events, to-dos, journal entries, or time zone + definitions. + + Value Type: The default value type for this property is DATE-TIME. + The value type can be set to DATE. + + Property Parameters: IANA, non-standard, value data type, and time + zone identifier property parameters can be specified on this + property. + + + +Desruisseaux Standards Track [Page 118] + +RFC 5545 iCalendar September 2009 + + + Conformance: This property can be specified in recurring "VEVENT", + "VTODO", and "VJOURNAL" calendar components as well as in the + "STANDARD" and "DAYLIGHT" sub-components of the "VTIMEZONE" + calendar component. + + Description: The exception dates, if specified, are used in + computing the recurrence set. The recurrence set is the complete + set of recurrence instances for a calendar component. The + recurrence set is generated by considering the initial "DTSTART" + property along with the "RRULE", "RDATE", and "EXDATE" properties + contained within the recurring component. The "DTSTART" property + defines the first instance in the recurrence set. The "DTSTART" + property value SHOULD match the pattern of the recurrence rule, if + specified. The recurrence set generated with a "DTSTART" property + value that doesn't match the pattern of the rule is undefined. + The final recurrence set is generated by gathering all of the + start DATE-TIME values generated by any of the specified "RRULE" + and "RDATE" properties, and then excluding any start DATE-TIME + values specified by "EXDATE" properties. This implies that start + DATE-TIME values specified by "EXDATE" properties take precedence + over those specified by inclusion properties (i.e., "RDATE" and + "RRULE"). When duplicate instances are generated by the "RRULE" + and "RDATE" properties, only one recurrence is considered. + Duplicate instances are ignored. + + The "EXDATE" property can be used to exclude the value specified + in "DTSTART". However, in such cases, the original "DTSTART" date + MUST still be maintained by the calendaring and scheduling system + because the original "DTSTART" value has inherent usage + dependencies by other properties such as the "RECURRENCE-ID". + + Format Definition: This property is defined by the following + notation: + + + + + + + + + + + + + + + + + + +Desruisseaux Standards Track [Page 119] + +RFC 5545 iCalendar September 2009 + + + exdate = "EXDATE" exdtparam ":" exdtval *("," exdtval) CRLF + + exdtparam = *( + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + (";" "VALUE" "=" ("DATE-TIME" / "DATE")) / + ; + (";" tzidparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + exdtval = date-time / date + ;Value MUST match value type + + Example: The following is an example of this property: + + EXDATE:19960402T010000Z,19960403T010000Z,19960404T010000Z + +3.8.5.2. Recurrence Date-Times + + Property Name: RDATE + + Purpose: This property defines the list of DATE-TIME values for + recurring events, to-dos, journal entries, or time zone + definitions. + + Value Type: The default value type for this property is DATE-TIME. + The value type can be set to DATE or PERIOD. + + Property Parameters: IANA, non-standard, value data type, and time + zone identifier property parameters can be specified on this + property. + + Conformance: This property can be specified in recurring "VEVENT", + "VTODO", and "VJOURNAL" calendar components as well as in the + "STANDARD" and "DAYLIGHT" sub-components of the "VTIMEZONE" + calendar component. + + Description: This property can appear along with the "RRULE" + property to define an aggregate set of repeating occurrences. + When they both appear in a recurring component, the recurrence + + + +Desruisseaux Standards Track [Page 120] + +RFC 5545 iCalendar September 2009 + + + instances are defined by the union of occurrences defined by both + the "RDATE" and "RRULE". + + The recurrence dates, if specified, are used in computing the + recurrence set. The recurrence set is the complete set of + recurrence instances for a calendar component. The recurrence set + is generated by considering the initial "DTSTART" property along + with the "RRULE", "RDATE", and "EXDATE" properties contained + within the recurring component. The "DTSTART" property defines + the first instance in the recurrence set. The "DTSTART" property + value SHOULD match the pattern of the recurrence rule, if + specified. The recurrence set generated with a "DTSTART" property + value that doesn't match the pattern of the rule is undefined. + The final recurrence set is generated by gathering all of the + start DATE-TIME values generated by any of the specified "RRULE" + and "RDATE" properties, and then excluding any start DATE-TIME + values specified by "EXDATE" properties. This implies that start + DATE-TIME values specified by "EXDATE" properties take precedence + over those specified by inclusion properties (i.e., "RDATE" and + "RRULE"). Where duplicate instances are generated by the "RRULE" + and "RDATE" properties, only one recurrence is considered. + Duplicate instances are ignored. + + Format Definition: This property is defined by the following + notation: + + rdate = "RDATE" rdtparam ":" rdtval *("," rdtval) CRLF + + rdtparam = *( + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + (";" "VALUE" "=" ("DATE-TIME" / "DATE" / "PERIOD")) / + (";" tzidparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + rdtval = date-time / date / period + ;Value MUST match value type + + + + + + +Desruisseaux Standards Track [Page 121] + +RFC 5545 iCalendar September 2009 + + + Example: The following are examples of this property: + + RDATE:19970714T123000Z + RDATE;TZID=America/New_York:19970714T083000 + + RDATE;VALUE=PERIOD:19960403T020000Z/19960403T040000Z, + 19960404T010000Z/PT3H + + RDATE;VALUE=DATE:19970101,19970120,19970217,19970421 + 19970526,19970704,19970901,19971014,19971128,19971129,19971225 + +3.8.5.3. Recurrence Rule + + Property Name: RRULE + + Purpose: This property defines a rule or repeating pattern for + recurring events, to-dos, journal entries, or time zone + definitions. + + Value Type: RECUR + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property can be specified in recurring "VEVENT", + "VTODO", and "VJOURNAL" calendar components as well as in the + "STANDARD" and "DAYLIGHT" sub-components of the "VTIMEZONE" + calendar component, but it SHOULD NOT be specified more than once. + The recurrence set generated with multiple "RRULE" properties is + undefined. + + Description: The recurrence rule, if specified, is used in computing + the recurrence set. The recurrence set is the complete set of + recurrence instances for a calendar component. The recurrence set + is generated by considering the initial "DTSTART" property along + with the "RRULE", "RDATE", and "EXDATE" properties contained + within the recurring component. The "DTSTART" property defines + the first instance in the recurrence set. The "DTSTART" property + value SHOULD be synchronized with the recurrence rule, if + specified. The recurrence set generated with a "DTSTART" property + value not synchronized with the recurrence rule is undefined. The + final recurrence set is generated by gathering all of the start + DATE-TIME values generated by any of the specified "RRULE" and + "RDATE" properties, and then excluding any start DATE-TIME values + specified by "EXDATE" properties. This implies that start DATE- + TIME values specified by "EXDATE" properties take precedence over + those specified by inclusion properties (i.e., "RDATE" and + "RRULE"). Where duplicate instances are generated by the "RRULE" + + + +Desruisseaux Standards Track [Page 122] + +RFC 5545 iCalendar September 2009 + + + and "RDATE" properties, only one recurrence is considered. + Duplicate instances are ignored. + + The "DTSTART" property specified within the iCalendar object + defines the first instance of the recurrence. In most cases, a + "DTSTART" property of DATE-TIME value type used with a recurrence + rule, should be specified as a date with local time and time zone + reference to make sure all the recurrence instances start at the + same local time regardless of time zone changes. + + If the duration of the recurring component is specified with the + "DTEND" or "DUE" property, then the same exact duration will apply + to all the members of the generated recurrence set. Else, if the + duration of the recurring component is specified with the + "DURATION" property, then the same nominal duration will apply to + all the members of the generated recurrence set and the exact + duration of each recurrence instance will depend on its specific + start time. For example, recurrence instances of a nominal + duration of one day will have an exact duration of more or less + than 24 hours on a day where a time zone shift occurs. The + duration of a specific recurrence may be modified in an exception + component or simply by using an "RDATE" property of PERIOD value + type. + + Format Definition: This property is defined by the following + notation: + + rrule = "RRULE" rrulparam ":" recur CRLF + + rrulparam = *(";" other-param) + + Example: All examples assume the Eastern United States time zone. + + Daily for 10 occurrences: + + DTSTART;TZID=America/New_York:19970902T090000 + RRULE:FREQ=DAILY;COUNT=10 + + ==> (1997 9:00 AM EDT) September 2-11 + + Daily until December 24, 1997: + + DTSTART;TZID=America/New_York:19970902T090000 + RRULE:FREQ=DAILY;UNTIL=19971224T000000Z + + ==> (1997 9:00 AM EDT) September 2-30;October 1-25 + (1997 9:00 AM EST) October 26-31;November 1-30;December 1-23 + + + + +Desruisseaux Standards Track [Page 123] + +RFC 5545 iCalendar September 2009 + + + Every other day - forever: + + DTSTART;TZID=America/New_York:19970902T090000 + RRULE:FREQ=DAILY;INTERVAL=2 + + ==> (1997 9:00 AM EDT) September 2,4,6,8...24,26,28,30; + October 2,4,6...20,22,24 + (1997 9:00 AM EST) October 26,28,30; + November 1,3,5,7...25,27,29; + December 1,3,... + + Every 10 days, 5 occurrences: + + DTSTART;TZID=America/New_York:19970902T090000 + RRULE:FREQ=DAILY;INTERVAL=10;COUNT=5 + + ==> (1997 9:00 AM EDT) September 2,12,22; + October 2,12 + + Every day in January, for 3 years: + + DTSTART;TZID=America/New_York:19980101T090000 + + RRULE:FREQ=YEARLY;UNTIL=20000131T140000Z; + BYMONTH=1;BYDAY=SU,MO,TU,WE,TH,FR,SA + or + RRULE:FREQ=DAILY;UNTIL=20000131T140000Z;BYMONTH=1 + + ==> (1998 9:00 AM EST)January 1-31 + (1999 9:00 AM EST)January 1-31 + (2000 9:00 AM EST)January 1-31 + + Weekly for 10 occurrences: + + DTSTART;TZID=America/New_York:19970902T090000 + RRULE:FREQ=WEEKLY;COUNT=10 + + ==> (1997 9:00 AM EDT) September 2,9,16,23,30;October 7,14,21 + (1997 9:00 AM EST) October 28;November 4 + + + + + + + + + + + + +Desruisseaux Standards Track [Page 124] + +RFC 5545 iCalendar September 2009 + + + Weekly until December 24, 1997: + + DTSTART;TZID=America/New_York:19970902T090000 + RRULE:FREQ=WEEKLY;UNTIL=19971224T000000Z + + ==> (1997 9:00 AM EDT) September 2,9,16,23,30; + October 7,14,21 + (1997 9:00 AM EST) October 28; + November 4,11,18,25; + December 2,9,16,23 + + Every other week - forever: + + DTSTART;TZID=America/New_York:19970902T090000 + RRULE:FREQ=WEEKLY;INTERVAL=2;WKST=SU + + ==> (1997 9:00 AM EDT) September 2,16,30; + October 14 + (1997 9:00 AM EST) October 28; + November 11,25; + December 9,23 + (1998 9:00 AM EST) January 6,20; + February 3, 17 + ... + + Weekly on Tuesday and Thursday for five weeks: + + DTSTART;TZID=America/New_York:19970902T090000 + RRULE:FREQ=WEEKLY;UNTIL=19971007T000000Z;WKST=SU;BYDAY=TU,TH + + or + + RRULE:FREQ=WEEKLY;COUNT=10;WKST=SU;BYDAY=TU,TH + + ==> (1997 9:00 AM EDT) September 2,4,9,11,16,18,23,25,30; + October 2 + + Every other week on Monday, Wednesday, and Friday until December + 24, 1997, starting on Monday, September 1, 1997: + + DTSTART;TZID=America/New_York:19970901T090000 + RRULE:FREQ=WEEKLY;INTERVAL=2;UNTIL=19971224T000000Z;WKST=SU; + BYDAY=MO,WE,FR + + ==> (1997 9:00 AM EDT) September 1,3,5,15,17,19,29; + October 1,3,13,15,17 + (1997 9:00 AM EST) October 27,29,31; + November 10,12,14,24,26,28; + + + +Desruisseaux Standards Track [Page 125] + +RFC 5545 iCalendar September 2009 + + + December 8,10,12,22 + + Every other week on Tuesday and Thursday, for 8 occurrences: + + DTSTART;TZID=America/New_York:19970902T090000 + RRULE:FREQ=WEEKLY;INTERVAL=2;COUNT=8;WKST=SU;BYDAY=TU,TH + + ==> (1997 9:00 AM EDT) September 2,4,16,18,30; + October 2,14,16 + + Monthly on the first Friday for 10 occurrences: + + DTSTART;TZID=America/New_York:19970905T090000 + RRULE:FREQ=MONTHLY;COUNT=10;BYDAY=1FR + + ==> (1997 9:00 AM EDT) September 5;October 3 + (1997 9:00 AM EST) November 7;December 5 + (1998 9:00 AM EST) January 2;February 6;March 6;April 3 + (1998 9:00 AM EDT) May 1;June 5 + + Monthly on the first Friday until December 24, 1997: + + DTSTART;TZID=America/New_York:19970905T090000 + RRULE:FREQ=MONTHLY;UNTIL=19971224T000000Z;BYDAY=1FR + + ==> (1997 9:00 AM EDT) September 5; October 3 + (1997 9:00 AM EST) November 7; December 5 + + Every other month on the first and last Sunday of the month for 10 + occurrences: + + DTSTART;TZID=America/New_York:19970907T090000 + RRULE:FREQ=MONTHLY;INTERVAL=2;COUNT=10;BYDAY=1SU,-1SU + + ==> (1997 9:00 AM EDT) September 7,28 + (1997 9:00 AM EST) November 2,30 + (1998 9:00 AM EST) January 4,25;March 1,29 + (1998 9:00 AM EDT) May 3,31 + + Monthly on the second-to-last Monday of the month for 6 months: + + DTSTART;TZID=America/New_York:19970922T090000 + RRULE:FREQ=MONTHLY;COUNT=6;BYDAY=-2MO + + ==> (1997 9:00 AM EDT) September 22;October 20 + (1997 9:00 AM EST) November 17;December 22 + (1998 9:00 AM EST) January 19;February 16 + + + + +Desruisseaux Standards Track [Page 126] + +RFC 5545 iCalendar September 2009 + + + Monthly on the third-to-the-last day of the month, forever: + + DTSTART;TZID=America/New_York:19970928T090000 + RRULE:FREQ=MONTHLY;BYMONTHDAY=-3 + + ==> (1997 9:00 AM EDT) September 28 + (1997 9:00 AM EST) October 29;November 28;December 29 + (1998 9:00 AM EST) January 29;February 26 + ... + + Monthly on the 2nd and 15th of the month for 10 occurrences: + + DTSTART;TZID=America/New_York:19970902T090000 + RRULE:FREQ=MONTHLY;COUNT=10;BYMONTHDAY=2,15 + + ==> (1997 9:00 AM EDT) September 2,15;October 2,15 + (1997 9:00 AM EST) November 2,15;December 2,15 + (1998 9:00 AM EST) January 2,15 + + Monthly on the first and last day of the month for 10 occurrences: + + DTSTART;TZID=America/New_York:19970930T090000 + RRULE:FREQ=MONTHLY;COUNT=10;BYMONTHDAY=1,-1 + + ==> (1997 9:00 AM EDT) September 30;October 1 + (1997 9:00 AM EST) October 31;November 1,30;December 1,31 + (1998 9:00 AM EST) January 1,31;February 1 + + Every 18 months on the 10th thru 15th of the month for 10 + occurrences: + + DTSTART;TZID=America/New_York:19970910T090000 + RRULE:FREQ=MONTHLY;INTERVAL=18;COUNT=10;BYMONTHDAY=10,11,12, + 13,14,15 + + ==> (1997 9:00 AM EDT) September 10,11,12,13,14,15 + (1999 9:00 AM EST) March 10,11,12,13 + + Every Tuesday, every other month: + + DTSTART;TZID=America/New_York:19970902T090000 + RRULE:FREQ=MONTHLY;INTERVAL=2;BYDAY=TU + + ==> (1997 9:00 AM EDT) September 2,9,16,23,30 + (1997 9:00 AM EST) November 4,11,18,25 + (1998 9:00 AM EST) January 6,13,20,27;March 3,10,17,24,31 + ... + + + + +Desruisseaux Standards Track [Page 127] + +RFC 5545 iCalendar September 2009 + + + Yearly in June and July for 10 occurrences: + + DTSTART;TZID=America/New_York:19970610T090000 + RRULE:FREQ=YEARLY;COUNT=10;BYMONTH=6,7 + + ==> (1997 9:00 AM EDT) June 10;July 10 + (1998 9:00 AM EDT) June 10;July 10 + (1999 9:00 AM EDT) June 10;July 10 + (2000 9:00 AM EDT) June 10;July 10 + (2001 9:00 AM EDT) June 10;July 10 + + Note: Since none of the BYDAY, BYMONTHDAY, or BYYEARDAY + components are specified, the day is gotten from "DTSTART". + + Every other year on January, February, and March for 10 + occurrences: + + DTSTART;TZID=America/New_York:19970310T090000 + RRULE:FREQ=YEARLY;INTERVAL=2;COUNT=10;BYMONTH=1,2,3 + + ==> (1997 9:00 AM EST) March 10 + (1999 9:00 AM EST) January 10;February 10;March 10 + (2001 9:00 AM EST) January 10;February 10;March 10 + (2003 9:00 AM EST) January 10;February 10;March 10 + + Every third year on the 1st, 100th, and 200th day for 10 + occurrences: + + DTSTART;TZID=America/New_York:19970101T090000 + RRULE:FREQ=YEARLY;INTERVAL=3;COUNT=10;BYYEARDAY=1,100,200 + + ==> (1997 9:00 AM EST) January 1 + (1997 9:00 AM EDT) April 10;July 19 + (2000 9:00 AM EST) January 1 + (2000 9:00 AM EDT) April 9;July 18 + (2003 9:00 AM EST) January 1 + (2003 9:00 AM EDT) April 10;July 19 + (2006 9:00 AM EST) January 1 + + Every 20th Monday of the year, forever: + + DTSTART;TZID=America/New_York:19970519T090000 + RRULE:FREQ=YEARLY;BYDAY=20MO + + ==> (1997 9:00 AM EDT) May 19 + (1998 9:00 AM EDT) May 18 + (1999 9:00 AM EDT) May 17 + ... + + + +Desruisseaux Standards Track [Page 128] + +RFC 5545 iCalendar September 2009 + + + Monday of week number 20 (where the default start of the week is + Monday), forever: + + DTSTART;TZID=America/New_York:19970512T090000 + RRULE:FREQ=YEARLY;BYWEEKNO=20;BYDAY=MO + + ==> (1997 9:00 AM EDT) May 12 + (1998 9:00 AM EDT) May 11 + (1999 9:00 AM EDT) May 17 + ... + + Every Thursday in March, forever: + + DTSTART;TZID=America/New_York:19970313T090000 + RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=TH + + ==> (1997 9:00 AM EST) March 13,20,27 + (1998 9:00 AM EST) March 5,12,19,26 + (1999 9:00 AM EST) March 4,11,18,25 + ... + + Every Thursday, but only during June, July, and August, forever: + + DTSTART;TZID=America/New_York:19970605T090000 + RRULE:FREQ=YEARLY;BYDAY=TH;BYMONTH=6,7,8 + + ==> (1997 9:00 AM EDT) June 5,12,19,26;July 3,10,17,24,31; + August 7,14,21,28 + (1998 9:00 AM EDT) June 4,11,18,25;July 2,9,16,23,30; + August 6,13,20,27 + (1999 9:00 AM EDT) June 3,10,17,24;July 1,8,15,22,29; + August 5,12,19,26 + ... + + Every Friday the 13th, forever: + + DTSTART;TZID=America/New_York:19970902T090000 + EXDATE;TZID=America/New_York:19970902T090000 + RRULE:FREQ=MONTHLY;BYDAY=FR;BYMONTHDAY=13 + + ==> (1998 9:00 AM EST) February 13;March 13;November 13 + (1999 9:00 AM EDT) August 13 + (2000 9:00 AM EDT) October 13 + ... + + + + + + + +Desruisseaux Standards Track [Page 129] + +RFC 5545 iCalendar September 2009 + + + The first Saturday that follows the first Sunday of the month, + forever: + + DTSTART;TZID=America/New_York:19970913T090000 + RRULE:FREQ=MONTHLY;BYDAY=SA;BYMONTHDAY=7,8,9,10,11,12,13 + + ==> (1997 9:00 AM EDT) September 13;October 11 + (1997 9:00 AM EST) November 8;December 13 + (1998 9:00 AM EST) January 10;February 7;March 7 + (1998 9:00 AM EDT) April 11;May 9;June 13... + ... + + Every 4 years, the first Tuesday after a Monday in November, + forever (U.S. Presidential Election day): + + DTSTART;TZID=America/New_York:19961105T090000 + RRULE:FREQ=YEARLY;INTERVAL=4;BYMONTH=11;BYDAY=TU; + BYMONTHDAY=2,3,4,5,6,7,8 + + ==> (1996 9:00 AM EST) November 5 + (2000 9:00 AM EST) November 7 + (2004 9:00 AM EST) November 2 + ... + + The third instance into the month of one of Tuesday, Wednesday, or + Thursday, for the next 3 months: + + DTSTART;TZID=America/New_York:19970904T090000 + RRULE:FREQ=MONTHLY;COUNT=3;BYDAY=TU,WE,TH;BYSETPOS=3 + + ==> (1997 9:00 AM EDT) September 4;October 7 + (1997 9:00 AM EST) November 6 + + The second-to-last weekday of the month: + + DTSTART;TZID=America/New_York:19970929T090000 + RRULE:FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-2 + + ==> (1997 9:00 AM EDT) September 29 + (1997 9:00 AM EST) October 30;November 27;December 30 + (1998 9:00 AM EST) January 29;February 26;March 30 + ... + + + + + + + + + +Desruisseaux Standards Track [Page 130] + +RFC 5545 iCalendar September 2009 + + + Every 3 hours from 9:00 AM to 5:00 PM on a specific day: + + DTSTART;TZID=America/New_York:19970902T090000 + RRULE:FREQ=HOURLY;INTERVAL=3;UNTIL=19970902T170000Z + + ==> (September 2, 1997 EDT) 09:00,12:00,15:00 + + Every 15 minutes for 6 occurrences: + + DTSTART;TZID=America/New_York:19970902T090000 + RRULE:FREQ=MINUTELY;INTERVAL=15;COUNT=6 + + ==> (September 2, 1997 EDT) 09:00,09:15,09:30,09:45,10:00,10:15 + + Every hour and a half for 4 occurrences: + + DTSTART;TZID=America/New_York:19970902T090000 + RRULE:FREQ=MINUTELY;INTERVAL=90;COUNT=4 + + ==> (September 2, 1997 EDT) 09:00,10:30;12:00;13:30 + + Every 20 minutes from 9:00 AM to 4:40 PM every day: + + DTSTART;TZID=America/New_York:19970902T090000 + RRULE:FREQ=DAILY;BYHOUR=9,10,11,12,13,14,15,16;BYMINUTE=0,20,40 + or + RRULE:FREQ=MINUTELY;INTERVAL=20;BYHOUR=9,10,11,12,13,14,15,16 + + ==> (September 2, 1997 EDT) 9:00,9:20,9:40,10:00,10:20, + ... 16:00,16:20,16:40 + (September 3, 1997 EDT) 9:00,9:20,9:40,10:00,10:20, + ...16:00,16:20,16:40 + ... + + An example where the days generated makes a difference because of + WKST: + + DTSTART;TZID=America/New_York:19970805T090000 + RRULE:FREQ=WEEKLY;INTERVAL=2;COUNT=4;BYDAY=TU,SU;WKST=MO + + ==> (1997 EDT) August 5,10,19,24 + + changing only WKST from MO to SU, yields different results... + + DTSTART;TZID=America/New_York:19970805T090000 + RRULE:FREQ=WEEKLY;INTERVAL=2;COUNT=4;BYDAY=TU,SU;WKST=SU + + ==> (1997 EDT) August 5,17,19,31 + + + +Desruisseaux Standards Track [Page 131] + +RFC 5545 iCalendar September 2009 + + + An example where an invalid date (i.e., February 30) is ignored. + + DTSTART;TZID=America/New_York:20070115T090000 + RRULE:FREQ=MONTHLY;BYMONTHDAY=15,30;COUNT=5 + + ==> (2007 EST) January 15,30 + (2007 EST) February 15 + (2007 EDT) March 15,30 + +3.8.6. Alarm Component Properties + + The following properties specify alarm information in calendar + components. + +3.8.6.1. Action + + Property Name: ACTION + + Purpose: This property defines the action to be invoked when an + alarm is triggered. + + Value Type: TEXT + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property MUST be specified once in a "VALARM" + calendar component. + + Description: Each "VALARM" calendar component has a particular type + of action with which it is associated. This property specifies + the type of action. Applications MUST ignore alarms with x-name + and iana-token values they don't recognize. + + Format Definition: This property is defined by the following + notation: + + action = "ACTION" actionparam ":" actionvalue CRLF + + actionparam = *(";" other-param) + + + actionvalue = "AUDIO" / "DISPLAY" / "EMAIL" + / iana-token / x-name + + Example: The following are examples of this property in a "VALARM" + calendar component: + + + + +Desruisseaux Standards Track [Page 132] + +RFC 5545 iCalendar September 2009 + + + ACTION:AUDIO + + ACTION:DISPLAY + +3.8.6.2. Repeat Count + + Property Name: REPEAT + + Purpose: This property defines the number of times the alarm should + be repeated, after the initial trigger. + + Value Type: INTEGER + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property can be specified in a "VALARM" calendar + component. + + Description: This property defines the number of times an alarm + should be repeated after its initial trigger. If the alarm + triggers more than once, then this property MUST be specified + along with the "DURATION" property. + + Format Definition: This property is defined by the following + notation: + + repeat = "REPEAT" repparam ":" integer CRLF + ;Default is "0", zero. + + repparam = *(";" other-param) + + Example: The following is an example of this property for an alarm + that repeats 4 additional times with a 5-minute delay after the + initial triggering of the alarm: + + REPEAT:4 + DURATION:PT5M + +3.8.6.3. Trigger + + Property Name: TRIGGER + + Purpose: This property specifies when an alarm will trigger. + + Value Type: The default value type is DURATION. The value type can + be set to a DATE-TIME value type, in which case the value MUST + specify a UTC-formatted DATE-TIME value. + + + +Desruisseaux Standards Track [Page 133] + +RFC 5545 iCalendar September 2009 + + + Property Parameters: IANA, non-standard, value data type, time zone + identifier, or trigger relationship property parameters can be + specified on this property. The trigger relationship property + parameter MUST only be specified when the value type is + "DURATION". + + Conformance: This property MUST be specified in the "VALARM" + calendar component. + + Description: This property defines when an alarm will trigger. The + default value type is DURATION, specifying a relative time for the + trigger of the alarm. The default duration is relative to the + start of an event or to-do with which the alarm is associated. + The duration can be explicitly set to trigger from either the end + or the start of the associated event or to-do with the "RELATED" + parameter. A value of START will set the alarm to trigger off the + start of the associated event or to-do. A value of END will set + the alarm to trigger off the end of the associated event or to-do. + + Either a positive or negative duration may be specified for the + "TRIGGER" property. An alarm with a positive duration is + triggered after the associated start or end of the event or to-do. + An alarm with a negative duration is triggered before the + associated start or end of the event or to-do. + + The "RELATED" property parameter is not valid if the value type of + the property is set to DATE-TIME (i.e., for an absolute date and + time alarm trigger). If a value type of DATE-TIME is specified, + then the property value MUST be specified in the UTC time format. + If an absolute trigger is specified on an alarm for a recurring + event or to-do, then the alarm will only trigger for the specified + absolute DATE-TIME, along with any specified repeating instances. + + If the trigger is set relative to START, then the "DTSTART" + property MUST be present in the associated "VEVENT" or "VTODO" + calendar component. If an alarm is specified for an event with + the trigger set relative to the END, then the "DTEND" property or + the "DTSTART" and "DURATION " properties MUST be present in the + associated "VEVENT" calendar component. If the alarm is specified + for a to-do with a trigger set relative to the END, then either + the "DUE" property or the "DTSTART" and "DURATION " properties + MUST be present in the associated "VTODO" calendar component. + + Alarms specified in an event or to-do that is defined in terms of + a DATE value type will be triggered relative to 00:00:00 of the + user's configured time zone on the specified date, or relative to + 00:00:00 UTC on the specified date if no configured time zone can + be found for the user. For example, if "DTSTART" is a DATE value + + + +Desruisseaux Standards Track [Page 134] + +RFC 5545 iCalendar September 2009 + + + set to 19980205 then the duration trigger will be relative to + 19980205T000000 America/New_York for a user configured with the + America/New_York time zone. + + Format Definition: This property is defined by the following + notation: + + trigger = "TRIGGER" (trigrel / trigabs) CRLF + + trigrel = *( + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + (";" "VALUE" "=" "DURATION") / + (";" trigrelparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) ":" dur-value + + trigabs = *( + ; + ; The following is REQUIRED, + ; but MUST NOT occur more than once. + ; + (";" "VALUE" "=" "DATE-TIME") / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) ":" date-time + + Example: A trigger set 15 minutes prior to the start of the event or + to-do. + + TRIGGER:-PT15M + + A trigger set five minutes after the end of an event or the due + date of a to-do. + + TRIGGER;RELATED=END:PT5M + + + + +Desruisseaux Standards Track [Page 135] + +RFC 5545 iCalendar September 2009 + + + A trigger set to an absolute DATE-TIME. + + TRIGGER;VALUE=DATE-TIME:19980101T050000Z + +3.8.7. Change Management Component Properties + + The following properties specify change management information in + calendar components. + +3.8.7.1. Date-Time Created + + Property Name: CREATED + + Purpose: This property specifies the date and time that the calendar + information was created by the calendar user agent in the calendar + store. + + Note: This is analogous to the creation date and time for a + file in the file system. + + Value Type: DATE-TIME + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: The property can be specified once in "VEVENT", + "VTODO", or "VJOURNAL" calendar components. The value MUST be + specified as a date with UTC time. + + Description: This property specifies the date and time that the + calendar information was created by the calendar user agent in the + calendar store. + + Format Definition: This property is defined by the following + notation: + + created = "CREATED" creaparam ":" date-time CRLF + + creaparam = *(";" other-param) + + Example: The following is an example of this property: + + CREATED:19960329T133000Z + + + + + + + + +Desruisseaux Standards Track [Page 136] + +RFC 5545 iCalendar September 2009 + + +3.8.7.2. Date-Time Stamp + + Property Name: DTSTAMP + + Purpose: In the case of an iCalendar object that specifies a + "METHOD" property, this property specifies the date and time that + the instance of the iCalendar object was created. In the case of + an iCalendar object that doesn't specify a "METHOD" property, this + property specifies the date and time that the information + associated with the calendar component was last revised in the + calendar store. + + Value Type: DATE-TIME + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property MUST be included in the "VEVENT", + "VTODO", "VJOURNAL", or "VFREEBUSY" calendar components. + + Description: The value MUST be specified in the UTC time format. + + This property is also useful to protocols such as [2447bis] that + have inherent latency issues with the delivery of content. This + property will assist in the proper sequencing of messages + containing iCalendar objects. + + In the case of an iCalendar object that specifies a "METHOD" + property, this property differs from the "CREATED" and "LAST- + MODIFIED" properties. These two properties are used to specify + when the particular calendar data in the calendar store was + created and last modified. This is different than when the + iCalendar object representation of the calendar service + information was created or last modified. + + In the case of an iCalendar object that doesn't specify a "METHOD" + property, this property is equivalent to the "LAST-MODIFIED" + property. + + Format Definition: This property is defined by the following + notation: + + dtstamp = "DTSTAMP" stmparam ":" date-time CRLF + + stmparam = *(";" other-param) + + + + + + +Desruisseaux Standards Track [Page 137] + +RFC 5545 iCalendar September 2009 + + + Example: + + DTSTAMP:19971210T080000Z + +3.8.7.3. Last Modified + + Property Name: LAST-MODIFIED + + Purpose: This property specifies the date and time that the + information associated with the calendar component was last + revised in the calendar store. + + Note: This is analogous to the modification date and time for a + file in the file system. + + Value Type: DATE-TIME + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property can be specified in the "VEVENT", + "VTODO", "VJOURNAL", or "VTIMEZONE" calendar components. + + Description: The property value MUST be specified in the UTC time + format. + + Format Definition: This property is defined by the following + notation: + + last-mod = "LAST-MODIFIED" lstparam ":" date-time CRLF + + lstparam = *(";" other-param) + + Example: The following is an example of this property: + + LAST-MODIFIED:19960817T133000Z + +3.8.7.4. Sequence Number + + Property Name: SEQUENCE + + Purpose: This property defines the revision sequence number of the + calendar component within a sequence of revisions. + + Value Type: INTEGER + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + + +Desruisseaux Standards Track [Page 138] + +RFC 5545 iCalendar September 2009 + + + Conformance: The property can be specified in "VEVENT", "VTODO", or + "VJOURNAL" calendar component. + + Description: When a calendar component is created, its sequence + number is 0. It is monotonically incremented by the "Organizer's" + CUA each time the "Organizer" makes a significant revision to the + calendar component. + + The "Organizer" includes this property in an iCalendar object that + it sends to an "Attendee" to specify the current version of the + calendar component. + + The "Attendee" includes this property in an iCalendar object that + it sends to the "Organizer" to specify the version of the calendar + component to which the "Attendee" is referring. + + A change to the sequence number is not the mechanism that an + "Organizer" uses to request a response from the "Attendees". The + "RSVP" parameter on the "ATTENDEE" property is used by the + "Organizer" to indicate that a response from the "Attendees" is + requested. + + Recurrence instances of a recurring component MAY have different + sequence numbers. + + Format Definition: This property is defined by the following + notation: + + seq = "SEQUENCE" seqparam ":" integer CRLF + ; Default is "0" + + seqparam = *(";" other-param) + + Example: The following is an example of this property for a calendar + component that was just created by the "Organizer": + + SEQUENCE:0 + + The following is an example of this property for a calendar + component that has been revised two different times by the + "Organizer": + + SEQUENCE:2 + +3.8.8. Miscellaneous Component Properties + + The following properties specify information about a number of + miscellaneous features of calendar components. + + + +Desruisseaux Standards Track [Page 139] + +RFC 5545 iCalendar September 2009 + + +3.8.8.1. IANA Properties + + Property Name: An IANA-registered property name + + Value Type: The default value type is TEXT. The value type can be + set to any value type. + + Property Parameters: Any parameter can be specified on this + property. + + Description: This specification allows other properties registered + with IANA to be specified in any calendar components. Compliant + applications are expected to be able to parse these other IANA- + registered properties but can ignore them. + + Format Definition: This property is defined by the following + notation: + + iana-prop = iana-token *(";" icalparameter) ":" value CRLF + + Example: The following are examples of properties that might be + registered to IANA: + + DRESSCODE:CASUAL + + NON-SMOKING;VALUE=BOOLEAN:TRUE + +3.8.8.2. Non-Standard Properties + + Property Name: Any property name with a "X-" prefix + + Purpose: This class of property provides a framework for defining + non-standard properties. + + Value Type: The default value type is TEXT. The value type can be + set to any value type. + + Property Parameters: IANA, non-standard, and language property + parameters can be specified on this property. + + Conformance: This property can be specified in any calendar + component. + + Description: The MIME Calendaring and Scheduling Content Type + provides a "standard mechanism for doing non-standard things". + This extension support is provided for implementers to "push the + envelope" on the existing version of the memo. Extension + properties are specified by property and/or property parameter + + + +Desruisseaux Standards Track [Page 140] + +RFC 5545 iCalendar September 2009 + + + names that have the prefix text of "X-" (the two-character + sequence: LATIN CAPITAL LETTER X character followed by the HYPHEN- + MINUS character). It is recommended that vendors concatenate onto + this sentinel another short prefix text to identify the vendor. + This will facilitate readability of the extensions and minimize + possible collision of names between different vendors. User + agents that support this content type are expected to be able to + parse the extension properties and property parameters but can + ignore them. + + At present, there is no registration authority for names of + extension properties and property parameters. The value type for + this property is TEXT. Optionally, the value type can be any of + the other valid value types. + + Format Definition: This property is defined by the following + notation: + + x-prop = x-name *(";" icalparameter) ":" value CRLF + + Example: The following might be the ABC vendor's extension for an + audio-clip form of subject property: + + X-ABC-MMSUBJ;VALUE=URI;FMTTYPE=audio/basic:http://www.example. + org/mysubj.au + +3.8.8.3. Request Status + + Property Name: REQUEST-STATUS + + Purpose: This property defines the status code returned for a + scheduling request. + + Value Type: TEXT + + Property Parameters: IANA, non-standard, and language property + parameters can be specified on this property. + + Conformance: The property can be specified in the "VEVENT", "VTODO", + "VJOURNAL", or "VFREEBUSY" calendar component. + + Description: This property is used to return status code information + related to the processing of an associated iCalendar object. The + value type for this property is TEXT. + + + + + + + +Desruisseaux Standards Track [Page 141] + +RFC 5545 iCalendar September 2009 + + + The value consists of a short return status component, a longer + return status description component, and optionally a status- + specific data component. The components of the value are + separated by the SEMICOLON character. + + The short return status is a PERIOD character separated pair or + 3-tuple of integers. For example, "3.1" or "3.1.1". The + successive levels of integers provide for a successive level of + status code granularity. + + The following are initial classes for the return status code. + Individual iCalendar object methods will define specific return + status codes for these classes. In addition, other classes for + the return status code may be defined using the registration + process defined later in this memo. + + +--------+----------------------------------------------------------+ + | Short | Longer Return Status Description | + | Return | | + | Status | | + | Code | | + +--------+----------------------------------------------------------+ + | 1.xx | Preliminary success. This class of status code | + | | indicates that the request has been initially processed | + | | but that completion is pending. | + | | | + | 2.xx | Successful. This class of status code indicates that | + | | the request was completed successfully. However, the | + | | exact status code can indicate that a fallback has been | + | | taken. | + | | | + | 3.xx | Client Error. This class of status code indicates that | + | | the request was not successful. The error is the result | + | | of either a syntax or a semantic error in the client- | + | | formatted request. Request should not be retried until | + | | the condition in the request is corrected. | + | | | + | 4.xx | Scheduling Error. This class of status code indicates | + | | that the request was not successful. Some sort of error | + | | occurred within the calendaring and scheduling service, | + | | not directly related to the request itself. | + +--------+----------------------------------------------------------+ + + + + + + + + + +Desruisseaux Standards Track [Page 142] + +RFC 5545 iCalendar September 2009 + + + Format Definition: This property is defined by the following + notation: + + rstatus = "REQUEST-STATUS" rstatparam ":" + statcode ";" statdesc [";" extdata] + + rstatparam = *( + ; + ; The following is OPTIONAL, + ; but MUST NOT occur more than once. + ; + (";" languageparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + statcode = 1*DIGIT 1*2("." 1*DIGIT) + ;Hierarchical, numeric return status code + + statdesc = text + ;Textual status description + + extdata = text + ;Textual exception data. For example, the offending property + ;name and value or complete property line. + + Example: The following are some possible examples of this property. + + The COMMA and SEMICOLON separator characters in the property value + are BACKSLASH character escaped because they appear in a text + value. + + REQUEST-STATUS:2.0;Success + + REQUEST-STATUS:3.1;Invalid property value;DTSTART:96-Apr-01 + + REQUEST-STATUS:2.8; Success\, repeating event ignored. Scheduled + as a single event.;RRULE:FREQ=WEEKLY\;INTERVAL=2 + + REQUEST-STATUS:4.1;Event conflict. Date-time is busy. + + REQUEST-STATUS:3.7;Invalid calendar user;ATTENDEE: + mailto:jsmith@example.com + + + + +Desruisseaux Standards Track [Page 143] + +RFC 5545 iCalendar September 2009 + + +4. iCalendar Object Examples + + The following examples are provided as an informational source of + illustrative iCalendar objects consistent with this content type. + + The following example specifies a three-day conference that begins at + 2:30 P.M. UTC, September 18, 1996 and ends at 10:00 P.M. UTC, + September 20, 1996. + + BEGIN:VCALENDAR + PRODID:-//xyz Corp//NONSGML PDA Calendar Version 1.0//EN + VERSION:2.0 + BEGIN:VEVENT + DTSTAMP:19960704T120000Z + UID:uid1@example.com + ORGANIZER:mailto:jsmith@example.com + DTSTART:19960918T143000Z + DTEND:19960920T220000Z + STATUS:CONFIRMED + CATEGORIES:CONFERENCE + SUMMARY:Networld+Interop Conference + DESCRIPTION:Networld+Interop Conference + and Exhibit\nAtlanta World Congress Center\n + Atlanta\, Georgia + END:VEVENT + END:VCALENDAR + + The following example specifies a group-scheduled meeting that begins + at 8:30 AM EST on March 12, 1998 and ends at 9:30 AM EST on March 12, + 1998. The "Organizer" has scheduled the meeting with one or more + calendar users in a group. A time zone specification for Eastern + United States has been specified. + + BEGIN:VCALENDAR + PRODID:-//RDU Software//NONSGML HandCal//EN + VERSION:2.0 + BEGIN:VTIMEZONE + TZID:America/New_York + BEGIN:STANDARD + DTSTART:19981025T020000 + TZOFFSETFROM:-0400 + TZOFFSETTO:-0500 + TZNAME:EST + END:STANDARD + BEGIN:DAYLIGHT + DTSTART:19990404T020000 + TZOFFSETFROM:-0500 + TZOFFSETTO:-0400 + + + +Desruisseaux Standards Track [Page 144] + +RFC 5545 iCalendar September 2009 + + + TZNAME:EDT + END:DAYLIGHT + END:VTIMEZONE + BEGIN:VEVENT + DTSTAMP:19980309T231000Z + UID:guid-1.example.com + ORGANIZER:mailto:mrbig@example.com + ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT;CUTYPE=GROUP: + mailto:employee-A@example.com + DESCRIPTION:Project XYZ Review Meeting + CATEGORIES:MEETING + CLASS:PUBLIC + CREATED:19980309T130000Z + SUMMARY:XYZ Project Review + DTSTART;TZID=America/New_York:19980312T083000 + DTEND;TZID=America/New_York:19980312T093000 + LOCATION:1CP Conference Room 4350 + END:VEVENT + END:VCALENDAR + + The following is an example of an iCalendar object passed in a MIME + message with a single body part consisting of a "text/calendar" + Content Type. + + TO:jsmith@example.com + FROM:jdoe@example.com + MIME-VERSION:1.0 + MESSAGE-ID: + CONTENT-TYPE:text/calendar; method="xyz"; component="VEVENT" + + BEGIN:VCALENDAR + METHOD:xyz + VERSION:2.0 + PRODID:-//ABC Corporation//NONSGML My Product//EN + BEGIN:VEVENT + DTSTAMP:19970324T120000Z + SEQUENCE:0 + UID:uid3@example.com + ORGANIZER:mailto:jdoe@example.com + ATTENDEE;RSVP=TRUE:mailto:jsmith@example.com + DTSTART:19970324T123000Z + DTEND:19970324T210000Z + CATEGORIES:MEETING,PROJECT + CLASS:PUBLIC + SUMMARY:Calendaring Interoperability Planning Meeting + DESCRIPTION:Discuss how we can test c&s interoperability\n + using iCalendar and other IETF standards. + LOCATION:LDB Lobby + + + +Desruisseaux Standards Track [Page 145] + +RFC 5545 iCalendar September 2009 + + + ATTACH;FMTTYPE=application/postscript:ftp://example.com/pub/ + conf/bkgrnd.ps + END:VEVENT + END:VCALENDAR + + The following is an example of a to-do due on April 15, 1998. An + audio alarm has been specified to remind the calendar user at noon, + the day before the to-do is expected to be completed and repeat + hourly, four additional times. The to-do definition has been + modified twice since it was initially created. + + BEGIN:VCALENDAR + VERSION:2.0 + PRODID:-//ABC Corporation//NONSGML My Product//EN + BEGIN:VTODO + DTSTAMP:19980130T134500Z + SEQUENCE:2 + UID:uid4@example.com + ORGANIZER:mailto:unclesam@example.com + ATTENDEE;PARTSTAT=ACCEPTED:mailto:jqpublic@example.com + DUE:19980415T000000 + STATUS:NEEDS-ACTION + SUMMARY:Submit Income Taxes + BEGIN:VALARM + ACTION:AUDIO + TRIGGER:19980403T120000Z + ATTACH;FMTTYPE=audio/basic:http://example.com/pub/audio- + files/ssbanner.aud + REPEAT:4 + DURATION:PT1H + END:VALARM + END:VTODO + END:VCALENDAR + + The following is an example of a journal entry: + + BEGIN:VCALENDAR + VERSION:2.0 + PRODID:-//ABC Corporation//NONSGML My Product//EN + BEGIN:VJOURNAL + DTSTAMP:19970324T120000Z + UID:uid5@example.com + ORGANIZER:mailto:jsmith@example.com + STATUS:DRAFT + CLASS:PUBLIC + CATEGORIES:Project Report,XYZ,Weekly Meeting + DESCRIPTION:Project xyz Review Meeting Minutes\n + Agenda\n1. Review of project version 1.0 requirements.\n2. + + + +Desruisseaux Standards Track [Page 146] + +RFC 5545 iCalendar September 2009 + + + Definition + of project processes.\n3. Review of project schedule.\n + Participants: John Smith\, Jane Doe\, Jim Dandy\n-It was + decided that the requirements need to be signed off by + product marketing.\n-Project processes were accepted.\n + -Project schedule needs to account for scheduled holidays + and employee vacation time. Check with HR for specific + dates.\n-New schedule will be distributed by Friday.\n- + Next weeks meeting is cancelled. No meeting until 3/23. + END:VJOURNAL + END:VCALENDAR + + The following is an example of published busy time information. The + iCalendar object might be placed in the network resource + http://www.example.com/calendar/busytime/jsmith.ifb. + + BEGIN:VCALENDAR + VERSION:2.0 + PRODID:-//RDU Software//NONSGML HandCal//EN + BEGIN:VFREEBUSY + ORGANIZER:mailto:jsmith@example.com + DTSTART:19980313T141711Z + DTEND:19980410T141711Z + FREEBUSY:19980314T233000Z/19980315T003000Z + FREEBUSY:19980316T153000Z/19980316T163000Z + FREEBUSY:19980318T030000Z/19980318T040000Z + URL:http://www.example.com/calendar/busytime/jsmith.ifb + END:VFREEBUSY + END:VCALENDAR + +5. Recommended Practices + + These recommended practices should be followed in order to assure + consistent handling of the following cases for an iCalendar object. + + 1. Content lines longer than 75 octets SHOULD be folded. + + 2. When the combination of the "RRULE" and "RDATE" properties in a + recurring component produces multiple instances having the same + start DATE-TIME value, they should be collapsed to, and + considered as, a single instance. If the "RDATE" property is + specified as a PERIOD value the duration of the recurrence + instance will be the one specified by the "RDATE" property, and + not the duration of the recurrence instance defined by the + "DTSTART" property. + + 3. When a calendar user receives multiple requests for the same + calendar component (e.g., REQUEST for a "VEVENT" calendar + + + +Desruisseaux Standards Track [Page 147] + +RFC 5545 iCalendar September 2009 + + + component) as a result of being on multiple mailing lists + specified by "ATTENDEE" properties in the request, they SHOULD + respond to only one of the requests. The calendar user SHOULD + also specify (using the "MEMBER" parameter of the "ATTENDEE" + property) of which mailing list they are a member. + + 4. An implementation can truncate a "SUMMARY" property value to 255 + octets, but it MUST NOT truncate the value in the middle of a + UTF-8 multi-octet sequence. + + 5. If seconds of the minute are not supported by an implementation, + then a value of "00" SHOULD be specified for the seconds + component in a time value. + + 6. "TZURL" values SHOULD NOT be specified as a file URI type. This + URI form can be useful within an organization, but is problematic + in the Internet. + + 7. Some possible English values for "CATEGORIES" property include: + "ANNIVERSARY", "APPOINTMENT", "BUSINESS", "EDUCATION", "HOLIDAY", + "MEETING", "MISCELLANEOUS", "NON-WORKING HOURS", "NOT IN OFFICE", + "PERSONAL", "PHONE CALL", "SICK DAY", "SPECIAL OCCASION", + "TRAVEL", "VACATION". Categories can be specified in any + registered language. + + 8. Some possible English values for the "RESOURCES" property + include: "CATERING", "CHAIRS", "COMPUTER PROJECTOR", "EASEL", + "OVERHEAD PROJECTOR", "SPEAKER PHONE", "TABLE", "TV", "VCR", + "VIDEO PHONE", "VEHICLE". Resources can be specified in any + registered language. + +6. Internationalization Considerations + + Applications MUST generate iCalendar streams in the UTF-8 charset and + MUST accept an iCalendar stream in the UTF-8 or US-ASCII charset. + +7. Security Considerations + + Because calendaring and scheduling information is very privacy- + sensitive, the protocol used for the transmission of calendaring and + scheduling information should have capabilities to protect the + information from possible threats, such as eavesdropping, replay, + message insertion, deletion, modification, and man-in-the-middle + attacks. + + As this document only defines the data format and media type of text/ + calendar that is independent of any calendar service or protocol, it + is up to the actual protocol specifications such as iTIP [2446bis], + + + +Desruisseaux Standards Track [Page 148] + +RFC 5545 iCalendar September 2009 + + + iMIP [2447bis], and "Calendaring Extensions to WebDAV (CalDAV)" + [RFC4791] to describe the threats that the above attacks present, as + well as ways in which to mitigate them. + +8. IANA Considerations + +8.1. iCalendar Media Type Registration + + The Calendaring and Scheduling Core Object Specification is intended + for use as a MIME content type. + + To: ietf-types@iana.org + + Subject: Registration of media type text/calendar + + Type name: text + + Subtype name: calendar + + Required parameters: none + + Optional parameters: charset, method, component, and optinfo + + The "charset" parameter is defined in [RFC2046] for subtypes of + the "text" media type. It is used to indicate the charset used in + the body part. The charset supported by this revision of + iCalendar is UTF-8. The use of any other charset is deprecated by + this revision of iCalendar; however, note that this revision + requires that compliant applications MUST accept iCalendar streams + using either the UTF-8 or US-ASCII charset. + + The "method" parameter is used to convey the iCalendar object + method or transaction semantics for the calendaring and scheduling + information. It also is an identifier for the restricted set of + properties and values of which the iCalendar object consists. The + parameter is to be used as a guide for applications interpreting + the information contained within the body part. It SHOULD NOT be + used to exclude or require particular pieces of information unless + the identified method definition specifically calls for this + behavior. Unless specifically forbidden by a particular method + definition, a text/calendar content type can contain any set of + properties permitted by the Calendaring and Scheduling Core Object + Specification. The "method" parameter MUST be specified and MUST + be set to the same value as the "METHOD" component property of the + iCalendar objects of the iCalendar stream if and only if the + iCalendar objects in the iCalendar stream all have a "METHOD" + component property set to the same value. + + + + +Desruisseaux Standards Track [Page 149] + +RFC 5545 iCalendar September 2009 + + + The value for the "method" parameter is defined as follows: + + method = 1*(ALPHA / DIGIT / "-") + ; IANA-registered iCalendar object method + + The "component" parameter conveys the type of iCalendar calendar + component within the body part. If the iCalendar object contains + more than one calendar component type, then multiple component + parameters MUST be specified. + + The value for the "component" parameter is defined as follows: + + component = "VEVENT" + / "VTODO" + / "VJOURNAL" + / "VFREEBUSY" + / "VTIMEZONE" + / iana-token + / x-name + + The "optinfo" parameter conveys optional information about the + iCalendar object within the body part. This parameter can only + specify semantics already specified by the iCalendar object and + that can be otherwise determined by parsing the body part. In + addition, the optional information specified by this parameter + MUST be consistent with that information specified by the + iCalendar object. For example, it can be used to convey the + "Attendee" response status to a meeting request. The parameter + value consists of a string value. + + The parameter can be specified multiple times. + + The value for the "optinfo" parameter is defined as follows: + + optinfo = infovalue / qinfovalue + + infovalue = iana-token / x-name + + qinfovalue = DQUOTE (infovalue) DQUOTE + + Encoding considerations: This media type can contain 8bit + characters, so the use of quoted-printable or base64 MIME Content- + Transfer-Encodings might be necessary when iCalendar objects are + transferred across protocols restricted to the 7bit repertoire. + Note that a text valued property in the content entity can also + have content encoding of special characters using a BACKSLASH + character escapement technique. This means that content values + can end up being encoded twice. + + + +Desruisseaux Standards Track [Page 150] + +RFC 5545 iCalendar September 2009 + + + Security considerations: See Section 7. + + Interoperability considerations: This media type is intended to + define a common format for conveying calendaring and scheduling + information between different systems. It is heavily based on the + earlier [VCAL] industry specification. + + Published specification: This specification. + + Applications that use this media type: This media type is designed + for widespread use by Internet calendaring and scheduling + applications. In addition, applications in the workflow and + document management area might find this content-type applicable. + The iTIP [2446bis], iMIP [2447bis], and CalDAV [RFC4791] Internet + protocols directly use this media type also. + + Additional information: + + Magic number(s): None. + + File extension(s): The file extension of "ics" is to be used to + designate a file containing (an arbitrary set of) calendaring + and scheduling information consistent with this MIME content + type. + + The file extension of "ifb" is to be used to designate a file + containing free or busy time information consistent with this + MIME content type. + + Macintosh file type code(s): The file type code of "iCal" is to + be used in Apple MacIntosh operating system environments to + designate a file containing calendaring and scheduling + information consistent with this MIME media type. + + The file type code of "iFBf" is to be used in Apple MacIntosh + operating system environments to designate a file containing + free or busy time information consistent with this MIME media + type. + + Person & email address to contact for further information: See the + "Author's Address" section of this document. + + 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. + + + +Desruisseaux Standards Track [Page 151] + +RFC 5545 iCalendar September 2009 + + + Change controller: IETF + +8.2. New iCalendar Elements Registration + + This section defines the process to register new or modified + iCalendar elements, that is, components, properties, parameters, + value data types, and values, with IANA. + +8.2.1. iCalendar Elements Registration Procedure + + The IETF will create a mailing list, icalendar@ietf.org, which can be + used for public discussion of iCalendar elements proposals prior to + registration. Use of the mailing list is strongly encouraged. The + IESG will appoint a designated expert who will monitor the + icalendar@ietf.org mailing list and review registrations. + + Registration of new iCalendar elements MUST be reviewed by the + designated expert and published in an RFC. A Standards Track RFC is + REQUIRED for the registration of new value data types that modify + existing properties, as well as for the registration of participation + status values to be used in "VEVENT" calendar components. A + Standards Track RFC is also REQUIRED for registration of iCalendar + elements that modify iCalendar elements previously documented in a + Standards Track RFC. + + The registration procedure begins when a completed registration + template, defined in the sections below, is sent to + icalendar@ietf.org and iana@iana.org. The designated expert is + expected to tell IANA and the submitter of the registration within + two weeks whether the registration is approved, approved with minor + changes, or rejected with cause. When a registration is rejected + with cause, it can be re-submitted if the concerns listed in the + cause are addressed. Decisions made by the designated expert can be + appealed to the IESG Applications Area Director, then to the IESG. + They follow the normal appeals procedure for IESG decisions. + +8.2.2. Registration Template for Components + + A component is defined by completing the following template. + + Component name: The name of the component. + + Purpose: The purpose of the component. Give a short but clear + description. + + Format definition: The ABNF for the component definition needs to be + specified. + + + + +Desruisseaux Standards Track [Page 152] + +RFC 5545 iCalendar September 2009 + + + Description: Any special notes about the component, how it is to be + used, etc. + + Example(s): One or more examples of instances of the component need + to be specified. + +8.2.3. Registration Template for Properties + + A property is defined by completing the following template. + + Property name: The name of the property. + + Purpose: The purpose of the property. Give a short but clear + description. + + Value type: Any of the valid value types for the property value need + to be specified. The default value type also needs to be + specified. + + Property parameters: Any of the valid property parameters for the + property MUST be specified. + + Conformance: The calendar components in which the property can + appear MUST be specified. + + Description: Any special notes about the property, how it is to be + used, etc. + + Format definition: The ABNF for the property definition needs to be + specified. + + Example(s): One or more examples of instances of the property need + to be specified. + +8.2.4. Registration Template for Parameters + + A parameter is defined by completing the following template. + + Parameter name: The name of the parameter. + + Purpose: The purpose of the parameter. Give a short but clear + description. + + Format definition: The ABNF for the parameter definition needs to be + specified. + + Description: Any special notes about the parameter, how it is to be + used, etc. + + + +Desruisseaux Standards Track [Page 153] + +RFC 5545 iCalendar September 2009 + + + Example(s): One or more examples of instances of the parameter need + to be specified. + +8.2.5. Registration Template for Value Data Types + + A value data type is defined by completing the following template. + + Value name: The name of the value type. + + Purpose: The purpose of the value type. Give a short but clear + description. + + Format definition: The ABNF for the value type definition needs to + be specified. + + Description: Any special notes about the value type, how it is to be + used, etc. + + Example(s): One or more examples of instances of the value type need + to be specified. + +8.2.6. Registration Template for Values + + A value is defined by completing the following template. + + Value: The value literal. + + Purpose: The purpose of the value. Give a short but clear + description. + + Conformance: The calendar properties and/or parameters that can take + this value need to be specified. + + Example(s): One or more examples of instances of the value need to + be specified. + + The following is a fictitious example of a registration of an + iCalendar value: + + Value: TOP-SECRET + + Purpose: This value is used to specify the access classification of + top-secret calendar components. + + Conformance: This value can be used with the "CLASS" property. + + + + + + +Desruisseaux Standards Track [Page 154] + +RFC 5545 iCalendar September 2009 + + + Example(s): The following is an example of this value used with the + "CLASS" property: + + CLASS:TOP-SECRET + +8.3. Initial iCalendar Elements Registries + + The IANA created and maintains the following registries for iCalendar + elements with pointers to appropriate reference documents. + +8.3.1. Components Registry + + The following table has been used to initialize the components + registry. + + +-----------+---------+-------------------------+ + | Component | Status | Reference | + +-----------+---------+-------------------------+ + | VCALENDAR | Current | RFC 5545, Section 3.4 | + | | | | + | VEVENT | Current | RFC 5545, Section 3.6.1 | + | | | | + | VTODO | Current | RFC 5545, Section 3.6.2 | + | | | | + | VJOURNAL | Current | RFC 5545, Section 3.6.3 | + | | | | + | VFREEBUSY | Current | RFC 5545, Section 3.6.4 | + | | | | + | VTIMEZONE | Current | RFC 5545, Section 3.6.5 | + | | | | + | VALARM | Current | RFC 5545, Section 3.6.6 | + | | | | + | STANDARD | Current | RFC 5545, Section 3.6.5 | + | | | | + | DAYLIGHT | Current | RFC 5545, Section 3.6.5 | + +-----------+---------+-------------------------+ + + + + + + + + + + + + + + + +Desruisseaux Standards Track [Page 155] + +RFC 5545 iCalendar September 2009 + + +8.3.2. Properties Registry + + The following table is has been used to initialize the properties + registry. + + +------------------+------------+----------------------------+ + | Property | Status | Reference | + +------------------+------------+----------------------------+ + | CALSCALE | Current | RFC 5545, Section 3.7.1 | + | METHOD | Current | RFC 5545, Section 3.7.2 | + | | | | + | PRODID | Current | RFC 5545, Section 3.7.3 | + | | | | + | VERSION | Current | RFC 5545, Section 3.7.4 | + | | | | + | ATTACH | Current | RFC 5545, Section 3.8.1.1 | + | | | | + | CATEGORIES | Current | RFC 5545, Section 3.8.1.2 | + | | | | + | CLASS | Current | RFC 5545, Section 3.8.1.3 | + | | | | + | COMMENT | Current | RFC 5545, Section 3.8.1.4 | + | | | | + | DESCRIPTION | Current | RFC 5545, Section 3.8.1.5 | + | | | | + | GEO | Current | RFC 5545, Section 3.8.1.6 | + | | | | + | LOCATION | Current | RFC 5545, Section 3.8.1.7 | + | | | | + | PERCENT-COMPLETE | Current | RFC 5545, Section 3.8.1.8 | + | | | | + | PRIORITY | Current | RFC 5545, Section 3.8.1.9 | + | | | | + | RESOURCES | Current | RFC 5545, Section 3.8.1.10 | + | | | | + | STATUS | Current | RFC 5545, Section 3.8.1.11 | + | | | | + | SUMMARY | Current | RFC 5545, Section 3.8.1.12 | + | | | | + | COMPLETED | Current | RFC 5545, Section 3.8.2.1 | + | | | | + | DTEND | Current | RFC 5545, Section 3.8.2.2 | + | | | | + | DUE | Current | RFC 5545, Section 3.8.2.3 | + | | | | + | DTSTART | Current | RFC 5545, Section 3.8.2.4 | + | | | | + | DURATION | Current | RFC 5545, Section 3.8.2.5 | + + + +Desruisseaux Standards Track [Page 156] + +RFC 5545 iCalendar September 2009 + + + | | | | + | FREEBUSY | Current | RFC 5545, Section 3.8.2.6 | + | | | | + | TRANSP | Current | RFC 5545, Section 3.8.2.7 | + | | | | + | TZID | Current | RFC 5545, Section 3.8.3.1 | + | | | | + | TZNAME | Current | RFC 5545, Section 3.8.3.2 | + | | | | + | TZOFFSETFROM | Current | RFC 5545, Section 3.8.3.3 | + | | | | + | TZOFFSETTO | Current | RFC 5545, Section 3.8.3.4 | + | | | | + | TZURL | Current | RFC 5545, Section 3.8.3.5 | + | | | | + | ATTENDEE | Current | RFC 5545, Section 3.8.4.1 | + | | | | + | CONTACT | Current | RFC 5545, Section 3.8.4.2 | + | | | | + | ORGANIZER | Current | RFC 5545, Section 3.8.4.3 | + | | | | + | RECURRENCE-ID | Current | RFC 5545, Section 3.8.4.4 | + | | | | + | RELATED-TO | Current | RFC 5545, Section 3.8.4.5 | + | | | | + | URL | Current | RFC 5545, Section 3.8.4.6 | + | | | | + | UID | Current | RFC 5545, Section 3.8.4.7 | + | | | | + | EXDATE | Current | RFC 5545, Section 3.8.5.1 | + | | | | + | EXRULE | Deprecated | [RFC2445], Section 4.8.5.2 | + | | | | + | RDATE | Current | RFC 5545, Section 3.8.5.2 | + | | | | + | RRULE | Current | RFC 5545, Section 3.8.5.3 | + | | | | + | ACTION | Current | RFC 5545, Section 3.8.6.1 | + | | | | + | REPEAT | Current | RFC 5545, Section 3.8.6.2 | + | | | | + | TRIGGER | Current | RFC 5545, Section 3.8.6.3 | + | | | | + | CREATED | Current | RFC 5545, Section 3.8.7.1 | + | | | | + | DTSTAMP | Current | RFC 5545, Section 3.8.7.2 | + | | | | + | LAST-MODIFIED | Current | RFC 5545, Section 3.8.7.3 | + + + +Desruisseaux Standards Track [Page 157] + +RFC 5545 iCalendar September 2009 + + + | | | | + | SEQUENCE | Current | RFC 5545, Section 3.8.7.4 | + | | | | + | REQUEST-STATUS | Current | RFC 5545, Section 3.8.8.3 | + +------------------+------------+----------------------------+ + +8.3.3. Parameters Registry + + The following table has been used to initialize the parameters + registry. + + +----------------+---------+--------------------------+ + | Parameter | Status | Reference | + +----------------+---------+--------------------------+ + | ALTREP | Current | RFC 5545, Section 3.2.1 | + | | | | + | CN | Current | RFC 5545, Section 3.2.2 | + | | | | + | CUTYPE | Current | RFC 5545, Section 3.2.3 | + | | | | + | DELEGATED-FROM | Current | RFC 5545, Section 3.2.4 | + | | | | + | DELEGATED-TO | Current | RFC 5545, Section 3.2.5 | + | | | | + | DIR | Current | RFC 5545, Section 3.2.6 | + | | | | + | ENCODING | Current | RFC 5545, Section 3.2.7 | + | | | | + | FMTTYPE | Current | RFC 5545, Section 3.2.8 | + | | | | + | FBTYPE | Current | RFC 5545, Section 3.2.9 | + | | | | + | LANGUAGE | Current | RFC 5545, Section 3.2.10 | + | | | | + | MEMBER | Current | RFC 5545, Section 3.2.11 | + | | | | + | PARTSTAT | Current | RFC 5545, Section 3.2.12 | + | | | | + | RANGE | Current | RFC 5545, Section 3.2.13 | + | | | | + | RELATED | Current | RFC 5545, Section 3.2.14 | + | | | | + | RELTYPE | Current | RFC 5545, Section 3.2.15 | + | | | | + | ROLE | Current | RFC 5545, Section 3.2.16 | + | | | | + | RSVP | Current | RFC 5545, Section 3.2.17 | + | | | | + + + +Desruisseaux Standards Track [Page 158] + +RFC 5545 iCalendar September 2009 + + + | SENT-BY | Current | RFC 5545, Section 3.2.18 | + | | | | + | TZID | Current | RFC 5545, Section 3.2.19 | + | | | | + | VALUE | Current | RFC 5545, Section 3.2.20 | + +----------------+---------+--------------------------+ + +8.3.4. Value Data Types Registry + + The following table has been used to initialize the value data types + registry. + + +-----------------+---------+--------------------------+ + | Value Data Type | Status | Reference | + +-----------------+---------+--------------------------+ + | BINARY | Current | RFC 5545, Section 3.3.1 | + | | | | + | BOOLEAN | Current | RFC 5545, Section 3.3.2 | + | | | | + | CAL-ADDRESS | Current | RFC 5545, Section 3.3.3 | + | | | | + | DATE | Current | RFC 5545, Section 3.3.4 | + | | | | + | DATE-TIME | Current | RFC 5545, Section 3.3.5 | + | | | | + | DURATION | Current | RFC 5545, Section 3.3.6 | + | | | | + | FLOAT | Current | RFC 5545, Section 3.3.7 | + | | | | + | INTEGER | Current | RFC 5545, Section 3.3.8 | + | | | | + | PERIOD | Current | RFC 5545, Section 3.3.9 | + | | | | + | RECUR | Current | RFC 5545, Section 3.3.10 | + | | | | + | TEXT | Current | RFC 5545, Section 3.3.11 | + | | | | + | TIME | Current | RFC 5545, Section 3.3.12 | + | | | | + | URI | Current | RFC 5545, Section 3.3.13 | + | | | | + | UTC-OFFSET | Current | RFC 5545, Section 3.3.14 | + +-----------------+---------+--------------------------+ + + + + + + + + +Desruisseaux Standards Track [Page 159] + +RFC 5545 iCalendar September 2009 + + +8.3.5. Calendar User Types Registry + + The following table has been used to initialize the calendar user + types registry. + + +--------------------+---------+-------------------------+ + | Calendar User Type | Status | Reference | + +--------------------+---------+-------------------------+ + | INDIVIDUAL | Current | RFC 5545, Section 3.2.3 | + | | | | + | GROUP | Current | RFC 5545, Section 3.2.3 | + | | | | + | RESOURCE | Current | RFC 5545, Section 3.2.3 | + | | | | + | ROOM | Current | RFC 5545, Section 3.2.3 | + | | | | + | UNKNOWN | Current | RFC 5545, Section 3.2.3 | + +--------------------+---------+-------------------------+ + +8.3.6. Free/Busy Time Types Registry + + The following table has been used to initialize the free/busy time + types registry. + + +---------------------+---------+-------------------------+ + | Free/Busy Time Type | Status | Reference | + +---------------------+---------+-------------------------+ + | FREE | Current | RFC 5545, Section 3.2.9 | + | | | | + | BUSY | Current | RFC 5545, Section 3.2.9 | + | | | | + | BUSY-UNAVAILABLE | Current | RFC 5545, Section 3.2.9 | + | | | | + | BUSY-TENTATIVE | Current | RFC 5545, Section 3.2.9 | + +---------------------+---------+-------------------------+ + + + + + + + + + + + + + + + + +Desruisseaux Standards Track [Page 160] + +RFC 5545 iCalendar September 2009 + + +8.3.7. Participation Statuses Registry + + The following table has been used to initialize the participation + statuses registry. + + +--------------------+---------+--------------------------+ + | Participant Status | Status | Reference | + +--------------------+---------+--------------------------+ + | NEEDS-ACTION | Current | RFC 5545, Section 3.2.12 | + | | | | + | ACCEPTED | Current | RFC 5545, Section 3.2.12 | + | | | | + | DECLINED | Current | RFC 5545, Section 3.2.12 | + | | | | + | TENTATIVE | Current | RFC 5545, Section 3.2.12 | + | | | | + | DELEGATED | Current | RFC 5545, Section 3.2.12 | + | | | | + | COMPLETED | Current | RFC 5545, Section 3.2.12 | + | | | | + | IN-PROCESS | Current | RFC 5545, Section 3.2.12 | + +--------------------+---------+--------------------------+ + +8.3.8. Relationship Types Registry + + The following table has been used to initialize the relationship + types registry. + + +-------------------+---------+--------------------------+ + | Relationship Type | Status | Reference | + +-------------------+---------+--------------------------+ + | CHILD | Current | RFC 5545, Section 3.2.15 | + | | | | + | PARENT | Current | RFC 5545, Section 3.2.15 | + | | | | + | SIBLING | Current | RFC 5545, Section 3.2.15 | + +-------------------+---------+--------------------------+ + + + + + + + + + + + + + + +Desruisseaux Standards Track [Page 161] + +RFC 5545 iCalendar September 2009 + + +8.3.9. Participation Roles Registry + + The following table has been used to initialize the participation + roles registry. + + +-----------------+---------+--------------------------+ + | Role Type | Status | Reference | + +-----------------+---------+--------------------------+ + | CHAIR | Current | RFC 5545, Section 3.2.16 | + | | | | + | REQ-PARTICIPANT | Current | RFC 5545, Section 3.2.16 | + | | | | + | OPT-PARTICIPANT | Current | RFC 5545, Section 3.2.16 | + | | | | + | NON-PARTICIPANT | Current | RFC 5545, Section 3.2.16 | + +-----------------+---------+--------------------------+ + +8.3.10. Actions Registry + + The following table has been used to initialize the actions registry. + + +-----------+------------+----------------------------+ + | Action | Status | Reference | + +-----------+------------+----------------------------+ + | AUDIO | Current | RFC 5545, Section 3.8.6.1 | + | | | | + | DISPLAY | Current | RFC 5545, Section 3.8.6.1 | + | | | | + | EMAIL | Current | RFC 5545, Section 3.8.6.1 | + | | | | + | PROCEDURE | Deprecated | [RFC2445], Section 4.8.6.1 | + +-----------+------------+----------------------------+ + +8.3.11. Classifications Registry + + The following table has been used to initialize the classifications + registry. + + +----------------+---------+---------------------------+ + | Classification | Status | Reference | + +----------------+---------+---------------------------+ + | PUBLIC | Current | RFC 5545, Section 3.8.1.3 | + | | | | + | PRIVATE | Current | RFC 5545, Section 3.8.1.3 | + | | | | + | CONFIDENTIAL | Current | RFC 5545, Section 3.8.1.3 | + +----------------+---------+---------------------------+ + + + + +Desruisseaux Standards Track [Page 162] + +RFC 5545 iCalendar September 2009 + + +8.3.12. Methods Registry + + No values are defined in this document for the "METHOD" property. + +9. Acknowledgments + + The editor of this document wishes to thank Frank Dawson and Derik + Stenerson, the original authors of RFC 2445, as well as the following + individuals who have participated in the drafting, review, and + discussion of this memo: + + Joe Abley, Hervey Allen, Steve Allen, Jay Batson, Oliver Block, + Stephane Bortzmeyer, Chris Bryant, Tantek Celik, Mark Crispin, Cyrus + Daboo, Mike Douglass, Andrew N. Dowden, Lisa Dusseault, Lars Eggert, + Gren Eliot, Pasi Eronen, Ben Fortuna, Ned Freed, Neal Gafter, Ted + Hardie, Tim Hare, Jeffrey Harris, Helge Hess, Paul B. Hill, Thomas + Hnetila, Russ Housley, Leif Johansson, Ciny Joy, Bruce Kahn, Reinhold + Kainhofer, Martin Kiff, Patrice Lapierre, Michiel van Leeuwen, + Jonathan Lennox, Jeff McCullough, Bill McQuillan, Alexey Melnikov, + John W. Noerenberg II, Chuck Norris, Mark Paterson, Simon Pilette, + Arnaud Quillaud, Robert Ransdell, Julian F. Reschke, Caleb + Richardson, Sam Roberts, Dan Romascanu, Mike Samuel, George Sexton, + Nigel Swinson, Clint Talbert, Simon Vaillancourt, Magnus Westerlund, + and Sandy Wills. + + A special thanks to the working group chairs Aki Niemi and Eliot Lear + for their support and guidance. + + The editor would also like to thank the Calendaring and Scheduling + Consortium for advice with this specification, and for organizing + interoperability testing events to help refine it. + + + + + + + + + + + + + + + + + + + + +Desruisseaux Standards Track [Page 163] + +RFC 5545 iCalendar September 2009 + + +10. References + +10.1. Normative References + + [ISO.8601.2004] International Organization for + Standardization, "Data elements and + interchange formats -- Information interchange + -- Representation of dates and times", 2004. + + [ISO.9070.1991] International Organization for + Standardization, "Information Technology_SGML + Support Facilities -- Registration Procedures + for Public Text Owner Identifiers, Second + Edition", April 1991. + + [RFC2045] Freed, N. and N. Borenstein, "Multipurpose + Internet Mail Extensions (MIME) Part One: + Format of Internet Message Bodies", RFC 2045, + November 1996. + + [RFC2046] Freed, N. and N. Borenstein, "Multipurpose + Internet Mail Extensions (MIME) Part Two: + Media Types", RFC 2046, November 1996. + + [RFC2119] Bradner, S., "Key words for use in RFCs to + Indicate Requirement Levels", BCP 14, + RFC 2119, March 1997. + + [RFC2368] Hoffman, P., Masinter, L., and J. Zawinski, + "The mailto URL scheme", RFC 2368, July 1998. + + [RFC3629] Yergeau, F., "UTF-8, a transformation format + of ISO 10646", STD 63, RFC 3629, + November 2003. + + [RFC3986] Berners-Lee, T., Fielding, R., and L. + Masinter, "Uniform Resource Identifier (URI): + Generic Syntax", STD 66, RFC 3986, + January 2005. + + [RFC4288] Freed, N. and J. Klensin, "Media Type + Specifications and Registration Procedures", + BCP 13, RFC 4288, December 2005. + + [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 + Data Encodings", RFC 4648, October 2006. + + + + + +Desruisseaux Standards Track [Page 164] + +RFC 5545 iCalendar September 2009 + + + [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", STD 68, + RFC 5234, January 2008. + + [RFC5646] Phillips, A., Ed., and M. Davis, Ed., "Tags + for Identifying Languages", BCP 47, RFC 5646, + September 2009. + + [US-ASCII] American National Standards Institute, "Coded + Character Set - 7-bit American Standard Code + for Information Interchange", ANSI X3.4, 1986. + +10.2. Informative References + + [2446bis] Daboo, C., "iCalendar Transport-Independent + Interoperability Protocol (iTIP)", Work + in Progress, April 2009. + + [2447bis] Melnikov, A., "iCalendar Message-Based + Interoperability Protocol (iMIP)", Work + in Progress, June 2008. + + [ANSI INCITS 61-1986] International Committee for Information + Technology, "Representation of Geographic + Point Locations for Information Interchange + (formerly ANSI X3.61-1986 (R1997))", ANSI + INCITS 61-1986 (R2007), 2007. + + [RFC1738] Berners-Lee, T., Masinter, L., and M. + McCahill, "Uniform Resource Locators (URL)", + RFC 1738, December 1994. + + [RFC2392] Levinson, E., "Content-ID and Message-ID + Uniform Resource Locators", RFC 2392, + August 1998. + + [RFC2397] Masinter, L., "The "data" URL scheme", + RFC 2397, August 1998. + + [RFC2425] Howes, T., Smith, M., and F. Dawson, "A MIME + Content-Type for Directory Information", + RFC 2425, September 1998. + + [RFC2426] Dawson, F. and T. Howes, "vCard MIME Directory + Profile", RFC 2426, September 1998. + + + + + + +Desruisseaux Standards Track [Page 165] + +RFC 5545 iCalendar September 2009 + + + [RFC2445] Dawson, F. and Stenerson, D., "Internet + Calendaring and Scheduling Core Object + Specification (iCalendar)", RFC 2445, + November 1998. + + [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, + H., Masinter, L., Leach, P., and T. Berners- + Lee, "Hypertext Transfer Protocol -- + HTTP/1.1", RFC 2616, June 1999. + + [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, + May 2000. + + [RFC4516] Smith, M. and T. Howes, "Lightweight Directory + Access Protocol (LDAP): Uniform Resource + Locator", RFC 4516, June 2006. + + [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, + "Calendaring Extensions to WebDAV (CalDAV)", + RFC 4791, March 2007. + + [TZDB] Eggert, P. and A.D. Olson, "Sources for Time + Zone and Daylight Saving Time Data", + July 2009, + . + + [VCAL] Internet Mail Consortium, "vCalendar: The + Electronic Calendaring and Scheduling Exchange + Format", September 1996, + . + + + + + + + + + + + + + + + + + + + + + +Desruisseaux Standards Track [Page 166] + +RFC 5545 iCalendar September 2009 + + +Appendix A. Differences from RFC 2445 + + This appendix contains a list of changes that have been made in the + Internet Calendaring and Scheduling Core Object Specification from + RFC 2445. + +A.1. New Restrictions + + 1. The "DTSTART" property SHOULD be synchronized with the recurrence + rule, if specified. + + 2. The "RRULE" property SHOULD NOT occur more than once in a + component. + + 3. The BYHOUR, BYMINUTE, and BYSECOND rule parts MUST NOT be + specified in the "RRULE" property when the "DTSTART" property is + specified as a DATE value. + + 4. The value type of the "DTEND" or "DUE" properties MUST match the + value type of "DTSTART" property. + + 5. The "DURATION" property can no longer appear in "VFREEBUSY" + components. + +A.2. Restrictions Removed + + 1. The "DTSTART" and "DTEND" properties are no longer required to be + specified as date with local time and time zone reference when + used with a recurrence rule. + +A.3. Deprecated Features + + 1. The "EXRULE" property can no longer be specified in a component. + + 2. The "THISANDPRIOR" value can no longer be used with the "RANGE" + parameter. + + 3. The "PROCEDURE" value can no longer be used with the "ACTION" + property. + + 4. The value type RECUR no longer allows multiple values to be + specified by a COMMA-separated list of values. + + 5. x-name rule parts can no longer be specified in properties of + RECUR value type (e.g., "RRULE"). x-param can be used on RECUR + value type properties instead. + + + + + +Desruisseaux Standards Track [Page 167] + +RFC 5545 iCalendar September 2009 + + +Author's Address + + Bernard Desruisseaux (editor) + Oracle Corporation + 600 blvd. de Maisonneuve West + Suite 1900 + Montreal, QC H3A 3J2 + CANADA + + EMail: bernard.desruisseaux@oracle.com + URI: http://www.oracle.com/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Desruisseaux Standards Track [Page 168] + diff --git a/specs/rfc6321-xcal.txt b/specs/rfc6321-xcal.txt new file mode 100644 index 0000000..c038c64 --- /dev/null +++ b/specs/rfc6321-xcal.txt @@ -0,0 +1,3027 @@ + + + + + + +Internet Engineering Task Force (IETF) C. Daboo +Request for Comments: 6321 Apple, Inc. +Category: Standards Track M. Douglass +ISSN: 2070-1721 RPI + S. Lees + Microsoft + August 2011 + + + xCal: The XML Format for iCalendar + +Abstract + + This specification defines "xCal", an XML format for iCalendar data. + +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/rfc6321. + +Copyright Notice + + Copyright (c) 2011 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, et al. Standards Track [Page 1] + +RFC 6321 xCal August 2011 + + +Table of Contents + + 1. Introduction ....................................................3 + 2. Conventions Used in This Document ...............................4 + 3. Converting from iCalendar to xCal ...............................4 + 3.1. Pre-Processing .............................................4 + 3.2. iCalendar Stream (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. Multi-Valued Properties ....................8 + 3.4.1.2. GEO Property ...............................9 + 3.4.1.3. REQUEST-STATUS Property ....................9 + 3.5. Parameters (RFC 5545, Section 3.2) ........................10 + 3.5.1. VALUE Parameter ....................................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) ....................13 + 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) ........14 + 3.6.11. Text (RFC 5545, Section 3.3.11) ...................15 + 3.6.12. Time (RFC 5545, Section 3.3.12) ...................15 + 3.6.13. URI (RFC 5545, Section 3.3.13) ....................15 + 3.6.14. UTC Offset (RFC 5545, Section 3.3.14) .............16 + 3.7. Extensions ................................................16 + 4. Converting from xCal into iCalendar ............................16 + 4.1. Converting XML Extensions into iCalendar ..................16 + 4.2. The XML Property for iCalendar ............................17 + 5. Handling Unrecognized Properties or Parameters .................18 + 6. Security Considerations ........................................19 + 7. IANA Considerations ............................................20 + 7.1. Namespace Registration ....................................20 + 7.2. Media Type ................................................20 + 7.3. iCalendar Property Registrations ..........................21 + 8. Acknowledgments ................................................22 + 9. References .....................................................22 + 9.1. Normative References ......................................22 + 9.2. Informative References ....................................22 + + + + + + + +Daboo, et al. Standards Track [Page 2] + +RFC 6321 xCal August 2011 + + + Appendix A. RELAX NG Schema .......................................23 + Appendix B. Examples ..............................................49 + B.1. Example 1 ..................................................49 + B.1.1. iCalendar Data .........................................49 + B.1.2. XML Data ...............................................49 + B.2. Example 2 ..................................................50 + B.2.1. iCalendar Data .........................................50 + B.2.2. XML Data ...............................................51 + +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, XML-based formats are widely used for interoperability + between applications, and the many tools that generate, parse, and + manipulate XML make it easier to work with than iCalendar. + + The purpose of this specification is to define "xCal", an XML format + for iCalendar data. xCal is defined as a straightforward mapping into + XML from iCalendar, so that iCalendar data can be converted to XML, + and then back to iCalendar, without losing any semantic meaning in + the data. Anyone creating xCal calendar data according to this + specification will know that their data can be converted to a valid + iCalendar representation as well. + + Key design considerations are: + + Round-tripping (converting an iCalendar instance to xCal and back) + will give the same semantic result as the starting point. That + is, all components, properties, and property parameters are + guaranteed to be preserved, with the exception of those that have + default values. + + xCal preserves the semantics of the iCalendar data. While a + simple consumer can easily browse the calendar data in xCal, a + full understanding of iCalendar is still required in order to + modify and/or fully comprehend the calendar data. + + xCal has the ability to handle many extensions to the underlying + iCalendar specification without requiring an update to this + document. + + + + + + + + +Daboo, et al. Standards Track [Page 3] + +RFC 6321 xCal August 2011 + + +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]. + + When XML element types in the namespace + "urn:ietf:params:xml:ns:icalendar-2.0" are referenced in this + document outside of the context of an XML fragment, the string "IC:" + will be prefixed to the element types. + + Some examples in this document contain "partial" XML 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 xCal + + This section describes how iCalendar data is converted to xCal using + a simple mapping between the iCalendar data model and XML elements. + +3.1. Pre-Processing + + 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 [RFC5545]. Prior + to converting iCalendar data into xCal, all folded lines MUST be + unfolded. + + iCalendar data uses an "escape" character sequence for text values + and property parameter values. When such text elements are converted + into xCal, the escaping MUST be removed. + + 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": + + 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 and decoding are used, they MUST conform to + Section 4 of [RFC4648], which is the base64 method used in [RFC5545]. + + + + +Daboo, et al. Standards Track [Page 4] + +RFC 6321 xCal August 2011 + + + One key difference in the formatting of values used in iCalendar and + xCal is that, in xCal, the specification uses date/time and UTC + offset values aligned with the syntax of + [W3C.REC-xmlschema-2-20041028] to aid with XML processing. + +3.2. iCalendar Stream (RFC 5545, Section 3.4) + + At the top level of the iCalendar object model is an "iCalendar + stream". This object encompasses multiple "iCalendar objects". In + xCal, the entire stream is contained in the root IC:icalendar XML + element. + + An iCalendar stream can contain one or more iCalendar objects. Each + iCalendar object, delimited by "BEGIN:VCALENDAR" and "END:VCALENDAR", + is enclosed by the IC:vcalendar XML element. + + Example: + + + + + ... + + + + 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". + + In xCal, component elements, for example, IC:vevent and IC:vtodo, are + contained within an IC:components XML element. Within the component + element, another IC:components element could appear (representing + components nested within components) or the IC:properties XML element + could appear. IC:properties is used to encapsulate iCalendar + properties. + + Each iCalendar property will be mapped to its own XML element as + described below. Within each of these elements, there is zero or one + IC:parameters XML element used to encapsulate any iCalendar property + parameters. Additionally there will be one or more XML elements + representing the value of the iCalendar property. + + + + + + + + + +Daboo, et al. Standards Track [Page 5] + +RFC 6321 xCal August 2011 + + + Example: + + + + + + ... + + + ... + + + + + +------------------+--------------+------------------+ + | Item | XML element | XML Definition | + +------------------+--------------+------------------+ + | iCalendar Stream | IC:icalendar | Appendix A # 3.4 | + | VCALENDAR | IC:vcalendar | Appendix A # 3.6 | + +------------------+--------------+------------------+ + +3.3. Components (RFC 5545, Section 3.6) + + Each calendar component in the "VCALENDAR" object, delimited by + "BEGIN" and "END", will be converted to an enclosing XML element with + the same name, but in lowercase. As an example, the table below + shows iCalendar-to-xCal mappings for current iCalendar components. + Any new iCalendar components added in the future will be converted in + the same way. + + +-----------+--------------+--------------------+ + | Component | XML element | XML Definition | + +-----------+--------------+--------------------+ + | VEVENT | IC:vevent | Appendix A # 3.6.1 | + | VTODO | IC:vtodo | Appendix A # 3.6.2 | + | VJOURNAL | IC:vjournal | Appendix A # 3.6.3 | + | VFREEBUSY | IC:vfreebusy | Appendix A # 3.6.4 | + | VTIMEZONE | IC:vtimezone | Appendix A # 3.6.5 | + | STANDARD | IC:standard | Appendix A # 3.6.5 | + | DAYLIGHT | IC:daylight | Appendix A # 3.6.5 | + | VALARM | IC:valarm | Appendix A # 3.6.6 | + +-----------+--------------+--------------------+ + +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 xCal format. + + + + +Daboo, et al. Standards Track [Page 6] + +RFC 6321 xCal August 2011 + + + iCalendar properties are enclosed in the XML element IC:properties. + + Each individual iCalendar property is represented in xCal by an + element of the same name as the iCalendar property, but in lowercase. + For example, the "CALSCALE" property is represented in xCal by the + IC:calscale element. + + Example: + + + + + + ... + ... + ... + + + ... + + + + + Each property can contain an IC:parameters XML element encapsulating + any iCalendar property parameters associated with the iCalendar + property. + + Each property will contain one or more "value" XML elements as + described below representing the value of the iCalendar property. + + As an example, the table below shows iCalendar-to-xCal mappings for + current iCalendar properties. Any new iCalendar properties added in + the future will be converted in the same way. + + +------------------+---------------------+-----------------------+ + | Property | XML element | XML Definition | + +------------------+---------------------+-----------------------+ + | CALSCALE | IC:calscale | Appendix A # 3.7.1 | + | METHOD | IC:method | Appendix A # 3.7.2 | + | PRODID | IC:prodid | Appendix A # 3.7.3 | + | VERSION | IC:version | Appendix A # 3.7.4 | + | ATTACH | IC:attach | Appendix A # 3.8.1.1 | + | CATEGORIES | IC:categories | Appendix A # 3.8.1.2 | + | CLASS | IC:class | Appendix A # 3.8.1.3 | + | COMMENT | IC:comment | Appendix A # 3.8.1.4 | + | DESCRIPTION | IC:description | Appendix A # 3.8.1.5 | + | GEO | IC:geo | Appendix A # 3.8.1.6 | + | LOCATION | IC:location | Appendix A # 3.8.1.7 | + + + +Daboo, et al. Standards Track [Page 7] + +RFC 6321 xCal August 2011 + + + | PERCENT-COMPLETE | IC:percent-complete | Appendix A # 3.8.1.8 | + | PRIORITY | IC:priority | Appendix A # 3.8.1.9 | + | RESOURCES | IC:resources | Appendix A # 3.8.1.10 | + | STATUS | IC:status | Appendix A # 3.8.1.11 | + | SUMMARY | IC:summary | Appendix A # 3.8.1.12 | + | COMPLETED | IC:completed | Appendix A # 3.8.2.1 | + | DTEND | IC:dtend | Appendix A # 3.8.2.2 | + | DUE | IC:due | Appendix A # 3.8.2.3 | + | DTSTART | IC:dtstart | Appendix A # 3.8.2.4 | + | DURATION | IC:duration | Appendix A # 3.8.2.5 | + | FREEBUSY | IC:freebusy | Appendix A # 3.8.2.6 | + | TRANSP | IC:transp | Appendix A # 3.8.2.7 | + | TZID | IC:tzid | Appendix A # 3.8.3.1 | + | TZNAME | IC:tzname | Appendix A # 3.8.3.2 | + | TZOFFSETFROM | IC:tzoffsetfrom | Appendix A # 3.8.3.3 | + | TZOFFSETTO | IC:tzoffsetto | Appendix A # 3.8.3.4 | + | TZURL | IC:tzurl | Appendix A # 3.8.3.5 | + | ATTENDEE | IC:attendee | Appendix A # 3.8.4.1 | + | CONTACT | IC:contact | Appendix A # 3.8.4.2 | + | ORGANIZER | IC:organizer | Appendix A # 3.8.4.3 | + | RECURRENCE-ID | IC:recurrence-id | Appendix A # 3.8.4.4 | + | RELATED-TO | IC:related-to | Appendix A # 3.8.4.5 | + | URL | IC:url | Appendix A # 3.8.4.6 | + | UID | IC:uid | Appendix A # 3.8.4.7 | + | EXDATE | IC:exdate | Appendix A # 3.8.5.1 | + | RDATE | IC:rdate | Appendix A # 3.8.5.2 | + | RRULE | IC:rrule | Appendix A # 3.8.5.3 | + | ACTION | IC:action | Appendix A # 3.8.6.1 | + | REPEAT | IC:repeat | Appendix A # 3.8.6.2 | + | TRIGGER | IC:trigger | Appendix A # 3.8.6.3 | + | CREATED | IC:created | Appendix A # 3.8.7.1 | + | DTSTAMP | IC:dtstamp | Appendix A # 3.8.7.2 | + | LAST-MODIFIED | IC:last-modified | Appendix A # 3.8.7.3 | + | SEQUENCE | IC:sequence | Appendix A # 3.8.7.4 | + | REQUEST-STATUS | IC:request-status | Appendix A # 3.8.8.3 | + +------------------+---------------------+-----------------------+ + +3.4.1. Special Cases for Properties + + This section describes some properties that have special handling + when converting to xCal. + +3.4.1.1. Multi-Valued Properties + + The following iCalendar properties can have values that consist of a + list of "standard" iCalendar values separated by a specific + delimiter. In xCal, these properties are represented by an XML + element that contains multiple "value" elements (Section 3.6). + + + +Daboo, et al. Standards Track [Page 8] + +RFC 6321 xCal August 2011 + + + +------------+---------------+-----------------------+ + | Property | XML element | XML Definition | + +------------+---------------+-----------------------+ + | CATEGORIES | IC:categories | Appendix A # 3.8.1.2 | + | RESOURCES | IC:resources | Appendix A # 3.8.1.10 | + | FREEBUSY | IC:freebusy | Appendix A # 3.8.2.6 | + | EXDATE | IC:exdate | Appendix A # 3.8.5.1 | + | RDATE | IC:rdate | Appendix A # 3.8.5.2 | + +------------+---------------+-----------------------+ + +3.4.1.2. GEO Property + + 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 xCal, the value for the IC:geo element is represented by two XML + elements. These are an IC:latitude element and an IC:longitude + element, each of which contains float values. See Appendix A # + 3.8.1.6. + + Example: + + + + ... + + 37.386013 + -122.082932 + + ... + + +3.4.1.3. REQUEST-STATUS Property + + 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 xCal, the value for the IC:request-status element is represented + by two or three XML elements. These are an IC:code element, an IC: + description element, and an IC:data element, each of which contains + the corresponding "TEXT" values. If there is no additional data in + the iCalendar value, the IC:data element (which would be empty) + SHOULD NOT be present. See Appendix A # 3.8.8.3. + + + + + +Daboo, et al. Standards Track [Page 9] + +RFC 6321 xCal August 2011 + + + Example: + + + + ... + + 2.0 + Success + + ... + + +3.5. Parameters (RFC 5545, Section 3.2) + + iCalendar property parameters are enclosed in the XML element IC: + parameters, which occurs in each property XML element. If there are + no iCalendar property parameters, the IC:parameters element (which + would be empty) SHOULD NOT be present. + + Each individual iCalendar property parameter is represented in xCal + by an element of the same name as the iCalendar property parameter, + but in lowercase. For example, the "PARTSTAT" property parameter is + represented in xCal by the IC:partstat element. + + Example: + + + + + ... + + ... + + + NEEDS-ACTION + + ... + + ... + + + + + Each XML parameter element contains one or more child XML elements + representing iCalendar value types. + + + + + + +Daboo, et al. Standards Track [Page 10] + +RFC 6321 xCal August 2011 + + + As an example, the table below shows iCalendar-to-xCal mappings for + current iCalendar parameters. Any new iCalendar parameters added in + the future will be converted in the same way. + + +----------------+-------------------+---------------------+ + | Parameter | XML element | XML Definition | + +----------------+-------------------+---------------------+ + | ALTREP | IC:altrep | Appendix A # 3.2.1 | + | CN | IC:cn | Appendix A # 3.2.2 | + | CUTYPE | IC:cutype | Appendix A # 3.2.3 | + | DELEGATED-FROM | IC:delegated-from | Appendix A # 3.2.4 | + | DELEGATED-TO | IC:delegated-to | Appendix A # 3.2.5 | + | DIR | IC:dir | Appendix A # 3.2.6 | + | ENCODING | IC:encoding | Appendix A # 3.2.7 | + | FMTTYPE | IC:fmttype | Appendix A # 3.2.8 | + | FBTYPE | IC:fbtype | Appendix A # 3.2.9 | + | LANGUAGE | IC:language | Appendix A # 3.2.10 | + | MEMBER | IC:member | Appendix A # 3.2.11 | + | PARTSTAT | IC:partstat | Appendix A # 3.2.12 | + | RANGE | IC:range | Appendix A # 3.2.13 | + | RELATED | IC:related | Appendix A # 3.2.14 | + | RELTYPE | IC:reltype | Appendix A # 3.2.15 | + | ROLE | IC:role | Appendix A # 3.2.16 | + | RSVP | IC:rsvp | Appendix A # 3.2.17 | + | SENT-BY | IC:sent-by | Appendix A # 3.2.18 | + | TZID | IC:tzid | Appendix A # 3.2.19 | + +----------------+-------------------+---------------------+ + +3.5.1. VALUE Parameter + + iCalendar defines a "VALUE" property parameter (Section 3.2.20 of + [RFC5545]). This property parameter is not mapped to an xCal XML + element. Instead, the value type is handled by having different XML + elements for each value, and these appear inside of property + elements. Thus, when converting from iCalendar to xCal, any "VALUE" + property parameters are skipped. When converting from xCal 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. + +3.6. Values (RFC 5545, Section 3.3) + + In the typical case, iCalendar value types are mapped into XML + elements with a matching name in all lowercase. In the case of the + value for a recurrence rule (see below), iCalendar defines + "structured" values, and these are mapped into separate child + elements for each value element. + + + + +Daboo, et al. Standards Track [Page 11] + +RFC 6321 xCal August 2011 + + +3.6.1. Binary (RFC 5545, Section 3.3.1) + + Description: iCalendar "BINARY" property values are represented by + the IC:binary XML element. The content of the element is base64 + encoded data, conforming to Section 4 of [RFC4648], which is the + base64 method used in [RFC5545]. Whitespace MAY be inserted into + the data at any point to "wrap" the data to reasonable line + lengths. When converting back to iCalendar, the whitespace MUST + first be removed. + + XML Definition: Appendix A # 3.3.1 + + Example: + + SGVsbG8gV29ybGQh + +3.6.2. Boolean (RFC 5545, Section 3.3.2) + + Description: iCalendar "BOOLEAN" property values are represented by + the IC:boolean XML element. The content of the element is a + boolean value. + + XML Definition: Appendix A # 3.3.2 + + Example: + + true + +3.6.3. Calendar User Address (RFC 5545, Section 3.3.3) + + Description: iCalendar "CAL-ADDRESS" property values are represented + by the IC:cal-address XML element. The content of the element is + a URI. + + XML Definition: Appendix A # 3.3.3 + + Example: + + mailto:cyrus@example.com + +3.6.4. Date (RFC 5545, Section 3.3.4) + + Description: iCalendar "DATE" property values are represented by the + IC:date XML element. The content of the element is the same date + value specified by [RFC5545], with the exception that the date + components are separated by "-" characters, for consistency with + [W3C.REC-xmlschema-2-20041028]. + + + + +Daboo, et al. Standards Track [Page 12] + +RFC 6321 xCal August 2011 + + + XML Definition: Appendix A # 3.3.4 + + Example: + + 2011-05-17 + +3.6.5. Date-Time (RFC 5545, Section 3.3.5) + + Description: iCalendar "DATE-TIME" property values are represented + by the IC:date-time XML element. The content of the element is + the same date-time value specified by [RFC5545], with the + exception that the date components are separated by "-" + characters, and the time components are separated by ":" + characters, for consistency with [W3C.REC-xmlschema-2-20041028]. + Note that while [W3C.REC-xmlschema-2-20041028] allows for a UTC + offset to be included in date/time values, xCal does not use that, + and instead follows the iCalendar behavior of using time zone + definitions via the "TZID" property parameter. + + XML Definition: Appendix A # 3.3.5 + + Example: + + 2011-05-17T12:00:00 + +3.6.6. Duration (RFC 5545, Section 3.3.6) + + Description: iCalendar "DURATION" property values are represented by + the IC:duration XML element. The content of the element is the + same duration value specified by [RFC5545]. + + XML Definition: Appendix A # 3.3.6 + + Example: + + P1D + +3.6.7. Float (RFC 5545, Section 3.3.7) + + Description: iCalendar "FLOAT" property values are represented by + the IC:float XML element. The content of the element is a text + representation of a floating point number. + + XML Definition: Appendix A # 3.3.7 + + Example: + + 0.5 + + + +Daboo, et al. Standards Track [Page 13] + +RFC 6321 xCal August 2011 + + +3.6.8. Integer (RFC 5545, Section 3.3.8) + + Description: iCalendar "INTEGER" property values are represented by + the IC:integer XML element. The content of the element is a text + representation of an integer number. + + XML Definition: Appendix A # 3.3.8 + + Examples: + + 50 + -100 + +3.6.9. Period of Time (RFC 5545, Section 3.3.9) + + Description: iCalendar "PERIOD" property values are represented by + the IC:period XML element. The content of the element is child + elements representing the start, end, or duration components of + the period. + + XML Definition: Appendix A # 3.3.9 + + Example: + + + 2011-05-17T12:00:00 + P1H + + +3.6.10. Recurrence Rule (RFC 5545, Section 3.3.10) + + Description: iCalendar "RECUR" property values are represented by + the IC:recur XML element. The content of the element is child + elements representing the various components of a recurrence rule. + + XML Definition: Appendix A # 3.3.10 + + Example: + + + YEARLY + 5 + -1SU + 10 + + + + + + + +Daboo, et al. Standards Track [Page 14] + +RFC 6321 xCal August 2011 + + +3.6.11. Text (RFC 5545, Section 3.3.11) + + Description: iCalendar "TEXT" property values are represented by the + IC:text XML element. The content of the element is simple text. + + XML Definition: Appendix A # 3.3.11 + + Example: + + Hello World! + +3.6.12. Time (RFC 5545, Section 3.3.12) + + Description: iCalendar "TIME" property values are represented by the + IC:time XML element. The content of the element is the same time + value specified by [RFC5545], with the exception that the time + components are separated by ":" characters, for consistency with + [W3C.REC-xmlschema-2-20041028]. Note that while + [W3C.REC-xmlschema-2-20041028] allows for a UTC offset to be + included in date/time values, xCal does not use that, and instead + follows the iCalendar behavior of using time zone definitions via + the "TZID" property parameter. + + XML Definition: Appendix A # 3.3.12 + + Example: + + + +3.6.13. URI (RFC 5545, Section 3.3.13) + + Description: iCalendar "URI" property values are represented by the + IC:uri XML element. The content of the element is a URI. + + XML Definition: Appendix A # 3.3.13 + + Example: + + http://calendar.example.com + + + + + + + + + + + + +Daboo, et al. Standards Track [Page 15] + +RFC 6321 xCal August 2011 + + +3.6.14. UTC Offset (RFC 5545, Section 3.3.14) + + Description: iCalendar "UTC-OFFSET" property values are represented + by the IC:utc-offset XML element. The content of the element is + the same UTC offset value specified by [RFC5545], with the + exception that the hour, minute, and second components are + separated by a ":" character, for consistency with + [W3C.REC-xmlschema-2-20041028]. + + XML Definition: Appendix A # 3.3.14 + + Example: + + -05:00 + +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 or property + parameter is represented by an XML element with the same name, but in + lowercase, e.g., the "X-FOO" property in iCalendar turns into the IC: + x-foo element in xCal. However, see Section 5 for how to deal with + default values for unrecognized extension properties or property + parameters. + +4. Converting from xCal into iCalendar + + 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 [RFC5545]. + + BACKSLASH character encoding and line folding MUST be applied to the + resulting iCalendar data as required by [RFC5545]. + + Non-binary value types MUST NOT be base64 encoded. + +4.1. Converting XML Extensions into iCalendar + + XML extensions are converted back to iCalendar in one of two ways, + depending on whether the extensions are in the iCalendar XML + namespace or in an external namespace. + + Extensions that are part of the iCalendar XML namespace MUST have + element names that begin with "x-", and will be converted back to the + equivalent extension property in iCalendar. For example, the "x-foo" + element will convert to the "X-FOO" iCalendar property. + + + +Daboo, et al. Standards Track [Page 16] + +RFC 6321 xCal August 2011 + + + Extensions that are in a namespace other than the iCalendar XML + namespace SHOULD be preserved in the iCalendar representation using + the "XML" iCalendar property described in Section 4.2. Only those + extension elements that are immediate child elements of the IC: + properties element are converted, any others are ignored. + +4.2. The XML Property for iCalendar + + This section describes an extension property for iCalendar, as + covered in Section 8.2.3 of [RFC5545]. + + Property name: XML + + Purpose: To embed extended XML-encoded iCalendar data in the + iCalendar format. + + Value type: The default value type is "TEXT". The value type can + also be set to "BINARY" to indicate base64 encoded content. + + Property parameters: IANA, non-standard, inline encoding, and value + data type property parameters can be specified on this property. + + Conformance: The property can be specified multiple times in any + calendar component. + + Description: The value of this property is a single XML 1.0 + [W3C.REC-xml-20081126] element. The "XML" property MUST NOT be used + to contain properties that are already defined in iCalendar. Since + all elements in the urn:ietf:params:xml:ns:icalendar-2.0 namespace + convert to a well-defined iCalendar object, the elements in this + property MUST NOT be in the urn:ietf:params:xml:ns:icalendar-2.0 + namespace. The XML element that is the value of this property MUST + have an XML namespace declaration. + + The default value type for this property is "TEXT", and normal + BACKSLASH character encoding rules for that value MUST be applied. + Note that the source XML can contain characters not allowed in "TEXT" + property values. If this is the case, then the XML data MUST be + base64 encoded. As required by [RFC5545], the "ENCODING" property + parameter MUST be present and set to "BASE64", and the "VALUE" + property parameter MUST be present and set to "BINARY". + + The ordering of "XML" properties is not preserved in the conversion + between xCal and iCalendar. + + Format definition: This property is defined by the following + notation: + + + + +Daboo, et al. Standards Track [Page 17] + +RFC 6321 xCal August 2011 + + + xml = "XML" xmlparam ( ":" text ) / + ( + ";" "ENCODING" "=" "BASE64" + ";" "VALUE" "=" "BINARY" + ":" binary + ) + CRLF + + xmlparam = *(";" other-param) + + Example: The following is an example of a location embedded in KML + markup inside the "XML" property. + + XML:\n + \n + KML Sample\n + 1\n + An incomplete example of a KML docum + ent - used as an example!\n + \n + + +5. Handling Unrecognized Properties or Parameters + + 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. + + When new properties are defined or "X-" properties are used, an + iCalendar<->xCal converter might not recognize them, and 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: + + o When converting iCalendar into xCal: + + * Any property that does not include a "VALUE" property parameter + and whose default value type is not known MUST be converted + using the value type XML element IC:unknown. The content of + that element is the unprocessed value text. + + * Any unrecognized property parameter MUST be converted using the + value type XML element IC:unknown, with its content set to the + property parameter value text, treated as if it were a "TEXT" + value or list of "TEXT" values. + + + +Daboo, et al. Standards Track [Page 18] + +RFC 6321 xCal August 2011 + + + o When converting xCal into iCalendar: + + * Any IC:unknown property value XML elements are converted + directly into iCalendar values. The containing property MUST + NOT have a "VALUE" property parameter. + + * Any IC:unknown parameter value XML elements are converted as if + they were IC:text value type XML elements. + + Example: The following is an example of an unrecognized iCalendar + property (that uses a "DATE-TIME" value as its default) and the + equivalent xCal representation of that property. + + iCalendar: + + X-PROPERTY:20110512T120000Z + + xCal: + + + 20110512T120000Z + + + Example: The following is an example of an unrecognized iCalendar + property parameter (that uses a "DURATION" value as its default) + specified on a recognized iCalendar property, and the equivalent xCal + representation of that property and property parameter. + + iCalendar: + + DTSTART;X-PARAM=PT30M:20110512T130000Z + + xCal: + + + + PT30M + + 2011-05-12T13:00:00Z + + +6. Security Considerations + + For security considerations specific to calendar data, see Section 7 + of [RFC5545]. Since this specification is a mapping from iCalendar, + no new security concerns are introduced related to calendar data. + + + + + +Daboo, et al. Standards Track [Page 19] + +RFC 6321 xCal August 2011 + + + The use of XML as a format does have security risks. Section 7 of + [RFC3470] discusses these risks. See also the security discussion + for the application/xml type in [RFC3023]. + +7. IANA Considerations + + This document defines a new URN to identify a new XML namespace for + iCalendar data. The URN conforms to a registry mechanism described + in [RFC3688]. + + This document defines a new media type. The registration is in + Section 7.2. + + This document defines a new property for iCalendar. The registration + is in Section 7.3. + +7.1. Namespace Registration + + Registration request for the iCalendar namespace: + + URI: urn:ietf:params:xml:ns:icalendar-2.0 + + Registrant Contact: See the "Authors' Addresses" section of this + document. + + XML: None. Namespace URIs do not represent an XML specification. + +7.2. Media Type + + This section defines the MIME media type for use with iCalendar in + XML data. + + Type name: application + + Subtype name: calendar+xml + + Required parameters: None + + Optional parameters: method, component, and optinfo as defined for + the text/calendar media type in [RFC5545]; charset as defined for + application/xml in [RFC3023]; per [RFC3023], use of the charset + property parameter with the value "utf-8" is STRONGLY RECOMMENDED. + + Encoding considerations: Same as encoding considerations of + application/xml as specified in [RFC3023]. + + + + + + +Daboo, et al. Standards Track [Page 20] + +RFC 6321 xCal August 2011 + + + Security considerations: See Section 6. + + Interoperability considerations: This media type provides an + alternative format for iCalendar data based on XML. + + 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. + + Additional information: + + Magic number(s): None + + File extension(s): xcs + + Macintosh file type code(s): None specified. + + Person & email address to contact for further information: + calsify@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.3. iCalendar Property Registrations + + This document defines the following new iCalendar property to be + added to the registry defined in Section 8.2.3 of [RFC5545]: + + +----------+---------+-----------------------+ + | Property | Status | Reference | + +----------+---------+-----------------------+ + | XML | Current | RFC 6321, Section 4.2 | + +----------+---------+-----------------------+ + + + + + + + + + + +Daboo, et al. Standards Track [Page 21] + +RFC 6321 xCal August 2011 + + +8. Acknowledgments + + The authors would like to thank the following for their valuable + contributions: Toby Considine, Bernard Desruisseaux, Keith Moore, + Filip Navara, Simon Perreault, Arnaud Quillaud, Peter Saint-Andre, + and Dave Thewlis. This specification originated from the work of the + XML technical committee of the Calendaring and Scheduling Consortium. + +9. References + +9.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media + Types", RFC 3023, January 2001. + + [RFC3470] Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines for + the Use of Extensible Markup Language (XML) + within IETF Protocols", BCP 70, RFC 3470, January 2003. + + [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, + January 2004. + + [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data + Encodings", RFC 4648, October 2006. + + [RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling + Core Object Specification (iCalendar)", RFC 5545, + September 2009. + + [W3C.REC-xml-20081126] + Sperberg-McQueen, C., Yergeau, F., Bray, T., Paoli, J., + and E. Maler, "Extensible Markup Language (XML) 1.0 (Fifth + Edition)", World Wide Web Consortium Recommendation REC- + xml-20081126, November 2008, + . + +9.2. Informative References + + [W3C.REC-xmlschema-2-20041028] + Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes + Second Edition", World Wide Web Consortium + Recommendation REC-xmlschema-2-20041028, October 2004, + . + + + + + +Daboo, et al. Standards Track [Page 22] + +RFC 6321 xCal August 2011 + + +Appendix A. RELAX NG Schema + + Below is a RELAX NG schema for iCalendar in XML. The schema is non- + normative and given for reference only. + + This schema uses the compact notation of RELAX NG. The numeric + section numbers given in the comments refer to sections in [RFC5545]. + The ordering of elements follows the section ordering of [RFC5545]. + + The RELAX NG compact notation "?" operator is used to indicate an + unordered list of items. However, that operator, as defined, allows + "mixing" each element that it operates on at any depth within the + other elements, rather than just allowing "mixing" of siblings only. + As a result, the schema provided allows certain constructs that are + not allowed in iCalendar. Given that there is no sibling-only + unordered list operator in RELAX NG, this is the best representation + that can be given. + + Patterns for date/time, duration, and UTC offset values are given + because those differ from the values used in iCalendar. More + restrictive schema with patterns and numerical limits could be + derived from the example schema here if more comprehensive schema + validation is required. + + # RELAX NG Schema for iCalendar in XML + + default namespace = "urn:ietf:params:xml:ns:icalendar-2.0" + + # 3.2 Property Parameters + + # 3.2.1 Alternate Text Representation + + altrepparam = element altrep { + value-uri + } + + # 3.2.2 Common Name + + cnparam = element cn { + value-text + } + + + + + + + + + + +Daboo, et al. Standards Track [Page 23] + +RFC 6321 xCal August 2011 + + + # 3.2.3 Calendar User Type + + cutypeparam = element cutype { + element text { + "INDIVIDUAL" | + "GROUP" | + "RESOURCE" | + "ROOM" | + "UNKNOWN" + } + } + + # 3.2.4 Delegators + + delfromparam = element delegated-from { + value-cal-address+ + } + + # 3.2.5 Delegatees + + deltoparam = element delegated-to { + value-cal-address+ + } + + # 3.2.6 Directory Entry Reference + + dirparam = element dir { + value-uri + } + + # 3.2.7 Inline Encoding + + encodingparam = element encoding { + element text { + "8BIT" | + "BASE64" + } + } + + # 3.2.8 Format Type + + fmttypeparam = element fmttype { + value-text + } + + + + + + + +Daboo, et al. Standards Track [Page 24] + +RFC 6321 xCal August 2011 + + + # 3.2.9 Free/Busy Time Type + + fbtypeparam = element fbtype { + element text { + "FREE" | + "BUSY" | + "BUSY-UNAVAILABLE" | + "BUSY-TENTATIVE" + } + } + + # 3.2.10 Language + + languageparam = element language { + value-text + } + + # 3.2.11 Group or List Membership + + memberparam = element member { + value-cal-address+ + } + + # 3.2.12 Participation Status + + partstatparam = element partstat { + type-partstat-event | + type-partstat-todo | + type-partstat-jour + } + + type-partstat-event = ( + element text { + "NEEDS-ACTION" | + "ACCEPTED" | + "DECLINED" | + "TENTATIVE" | + "DELEGATED" + } + ) + + + + + + + + + + + +Daboo, et al. Standards Track [Page 25] + +RFC 6321 xCal August 2011 + + + type-partstat-todo = ( + element text { + "NEEDS-ACTION" | + "ACCEPTED" | + "DECLINED" | + "TENTATIVE" | + "DELEGATED" | + "COMPLETED" | + "IN-PROCESS" + } + ) + + type-partstat-jour = ( + element text { + "NEEDS-ACTION" | + "ACCEPTED" | + "DECLINED" + } + ) + + # 3.2.13 Recurrence Identifier Range + + rangeparam = element range { + element text { + "THISANDFUTURE" + } + } + + # 3.2.14 Alarm Trigger Relationship + + trigrelparam = element related { + element text { + "START" | + "END" + } + } + + # 3.2.15 Relationship Type + + reltypeparam = element reltype { + element text { + "PARENT" | + "CHILD" | + "SIBLING" + } + } + + + + + +Daboo, et al. Standards Track [Page 26] + +RFC 6321 xCal August 2011 + + + # 3.2.16 Participation Role + + roleparam = element role { + element text { + "CHAIR" | + "REQ-PARTICIPANT" | + "OPT-PARTICIPANT" | + "NON-PARTICIPANT" + } + } + + # 3.2.17 RSVP Expectation + + rsvpparam = element rsvp { + value-boolean + } + + # 3.2.18 Sent By + + sentbyparam = element sent-by { + value-cal-address + } + + # 3.2.19 Time Zone Identifier + + tzidparam = element tzid { + value-text + } + + # 3.3 Property Value Data Types + + # 3.3.1 BINARY + + value-binary = element binary { + xsd:string + } + + # 3.3.2 BOOLEAN + + value-boolean = element boolean { + xsd:boolean + } + + # 3.3.3 CAL-ADDRESS + + value-cal-address = element cal-address { + xsd:anyURI + } + + + +Daboo, et al. Standards Track [Page 27] + +RFC 6321 xCal August 2011 + + + # 3.3.4 DATE + + pattern-date = xsd:string { + pattern = "\d\d\d\d-\d\d-\d\d" + } + + value-date = element date { + pattern-date + } + + # 3.3.5 DATE-TIME + + pattern-date-time = xsd:string { + pattern = "\d\d\d\d-\d\d-\d\dT\d\d:\d\d:\d\dZ?" + } + + value-date-time = element date-time { + pattern-date-time + } + + # 3.3.6 DURATION + + pattern-duration = xsd:string { + pattern = "(+|-)?P(\d+W)|(\d+D)?" + ~ "(T(\d+H(\d+M)?(\d+S)?)|" + ~ "(\d+M(\d+S)?)|" + ~ "(\d+S))?" + } + + value-duration = element duration { + pattern-duration + } + + # 3.3.7 FLOAT + + value-float = element float { + xsd:float + } + + # 3.3.8 INTEGER + + value-integer = element integer { + xsd:integer + } + + + + + + + +Daboo, et al. Standards Track [Page 28] + +RFC 6321 xCal August 2011 + + + # 3.3.9 PERIOD + + value-period = element period { + element start { + pattern-date-time + }, + ( + element end { + pattern-date-time + } | + element duration { + pattern-duration + } + ) + } + + # 3.3.10 RECUR + + value-recur = element recur { + 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-freq = element freq { + "SECONDLY" | + "MINUTELY" | + "HOURLY" | + "DAILY" | + "WEEKLY" | + "MONTHLY" | + "YEARLY" + } + + + + + + +Daboo, et al. Standards Track [Page 29] + +RFC 6321 xCal August 2011 + + + type-until = element until { + type-date | + type-date-time + } + + type-count = element count { + xsd:positiveInteger + } + + type-bysecond = element bysecond { + xsd:positiveInteger + } + + type-byminute = element byminute { + xsd:positiveInteger + } + + type-byhour = element byhour { + xsd:positiveInteger + } + + type-weekday = ( + "SU" | + "MO" | + "TU" | + "WE" | + "TH" | + "FR" | + "SA" + ) + + type-byday = element byday { + xsd:integer?, + type-weekday + } + + type-bymonthday = element bymonthday { + xsd:integer + } + + type-byyearday = element byyearday { + xsd:integer + } + + type-byweekno = element byweekno { + xsd:integer + } + + + + +Daboo, et al. Standards Track [Page 30] + +RFC 6321 xCal August 2011 + + + type-bymonth = element bymonth { + xsd:positiveInteger + } + + type-bysetpos = element bysetpos { + xsd:integer + } + + # 3.3.11 TEXT + + value-text = element text { + xsd:string + } + + # 3.3.12 TIME + + pattern-time = xsd:string { + pattern = "\d\d:\d\d:\d\dZ?" + } + + value-time = element time { + pattern-time + } + + # 3.3.13 URI + + value-uri = element uri { + xsd:anyURI + } + + # 3.3.14 UTC-OFFSET + + value-utc-offset = element utc-offset { + xsd:string { pattern = "(+|-)\d\d:\d\d(:\d\d)?" } + } + + # UNKNOWN + + value-unknown = element unknown { + xsd:string + } + + # 3.4 iCalendar Stream + + start = element icalendar { + vcalendar+ + } + + + + +Daboo, et al. Standards Track [Page 31] + +RFC 6321 xCal August 2011 + + + # 3.6 Calendar Components + + vcalendar = element vcalendar { + type-calprops, + type-component + } + + type-calprops = element properties { + property-prodid & + property-version & + property-calscale? & + property-method? + } + + type-component = element components { + ( + component-vevent | + component-vtodo | + component-vjournal | + component-vfreebusy | + component-vtimezone + )* + } + + # 3.6.1 Event Component + + component-vevent = element vevent { + type-eventprop, + element components { + component-valarm+ + }? + } + + type-eventprop = element properties { + property-dtstamp & + property-dtstart & + property-uid & + + property-class? & + property-created? & + property-description? & + property-geo? & + property-last-mod? & + property-location? & + property-organizer? & + property-priority? & + property-seq? & + property-status-event? & + + + +Daboo, et al. Standards Track [Page 32] + +RFC 6321 xCal August 2011 + + + property-summary? & + property-transp? & + property-url? & + property-recurid? & + + property-rrule? & + + (property-dtend | property-duration)? & + + property-attach* & + property-attendee* & + property-categories* & + property-comment* & + property-contact* & + property-exdate* & + property-rstatus* & + property-related* & + property-resources* & + property-rdate* + } + + # 3.6.2 To-do Component + + component-vtodo = element vtodo { + type-todoprop, + element components { + component-valarm+ + }? + } + + type-todoprop = element properties { + property-dtstamp & + property-uid & + + property-class? & + property-completed? & + property-created? & + property-description? & + property-geo? & + property-last-mod? & + property-location? & + property-organizer? & + property-percent? & + property-priority? & + property-recurid? & + property-seq? & + property-status-todo? & + property-summary? & + + + +Daboo, et al. Standards Track [Page 33] + +RFC 6321 xCal August 2011 + + + property-url? & + + property-rrule? & + + ( + (property-dtstart?, property-dtend? ) | + (property-dtstart, property-duration)? + ) & + + property-attach* & + property-attendee* & + property-categories* & + property-comment* & + property-contact* & + property-exdate* & + property-rstatus* & + property-related* & + property-resources* & + property-rdate* + } + + # 3.6.3 Journal Component + + component-vjournal = element vjournal { + type-jourprop + } + + type-jourprop = element properties { + property-dtstamp & + property-uid & + + property-class? & + property-created? & + property-dtstart? & + property-last-mod? & + property-organizer? & + property-recurid? & + property-seq? & + property-status-jour? & + property-summary? & + property-url? & + + property-rrule? & + + property-attach* & + property-attendee* & + property-categories* & + property-comment* & + + + +Daboo, et al. Standards Track [Page 34] + +RFC 6321 xCal August 2011 + + + property-contact* & + property-description? & + property-exdate* & + property-related* & + property-rdate* & + property-rstatus* + } + + # 3.6.4 Free/Busy Component + + component-vfreebusy = element vfreebusy { + type-fbprop + } + + type-fbprop = element properties { + property-dtstamp & + property-uid & + + property-contact? & + property-dtstart? & + property-dtend? & + property-duration? & + property-organizer? & + property-url? & + + property-attendee* & + property-comment* & + property-freebusy* & + property-rstatus* + } + + # 3.6.5 Time Zone Component + + component-vtimezone = element vtimezone { + element properties { + property-tzid & + + property-last-mod? & + property-tzuurl? + }, + element components { + (component-standard | component-daylight) & + component-standard* & + component-daylight* + } + } + + + + + +Daboo, et al. Standards Track [Page 35] + +RFC 6321 xCal August 2011 + + + component-standard = element standard { + type-tzprop + } + + component-daylight = element daylight { + type-tzprop + } + + type-tzprop = element properties { + property-dtstart & + property-tzoffsetto & + property-tzoffsetfrom & + + property-rrule? & + + property-comment* & + property-rdate* & + property-tzname* + } + + # 3.6.6 Alarm Component + + component-valarm = element valarm { + audioprop | dispprop | emailprop + } + + type-audioprop = element properties { + property-action & + + property-trigger & + + (property-duration, property-repeat)? & + + property-attach? + } + + type-dispprop = element properties { + property-action & + property-description & + property-trigger & + property-summary & + + property-attendee+ & + + (property-duration, property-repeat)? & + + property-attach* + } + + + +Daboo, et al. Standards Track [Page 36] + +RFC 6321 xCal August 2011 + + + type-emailprop = element properties { + property-action & + property-description & + property-trigger & + + (property-duration, property-repeat)? + } + + # 3.7 Calendar Properties + + # 3.7.1 Calendar Scale + + property-calscale = element calscale { + + element parameters { empty }?, + + element text { "GREGORIAN" } + } + + # 3.7.2 Method + + property-method = element method { + + element parameters { empty }?, + + value-text + } + + # 3.7.3 Product Identifier + + property-prodid = element prodid { + + element parameters { empty }?, + + value-text + } + + # 3.7.4 Version + + property-version = element version { + + element parameters { empty }?, + + element text { "2.0" } + } + + + + + + +Daboo, et al. Standards Track [Page 37] + +RFC 6321 xCal August 2011 + + + # 3.8 Component Properties + + # 3.8.1 Descriptive Component Properties + + # 3.8.1.1 Attachment + + property-attach = element attach { + + element parameters { + fmttypeparam? & + encodingparam? + }?, + + value-uri | value-binary + } + + # 3.8.1.2 Categories + + property-categories = element categories { + + element parameters { + languageparam? & + }?, + + value-text+ + } + + # 3.8.1.3 Classification + + property-class = element class { + + element parameters { empty }?, + + element text { + "PUBLIC" | + "PRIVATE" | + "CONFIDENTIAL" + } + } + + # 3.8.1.4 Comment + + property-comment = element comment { + + element parameters { + altrepparam? & + languageparam? + }?, + + + +Daboo, et al. Standards Track [Page 38] + +RFC 6321 xCal August 2011 + + + value-text + } + + # 3.8.1.5 Description + + property-description = element description { + + element parameters { + altrepparam? & + languageparam? + }?, + + value-text + } + + # 3.8.1.6 Geographic Position + + property-geo = element geo { + + element parameters { empty }?, + + element latitude { xsd:float }, + element longitude { xsd:float } + } + + # 3.8.1.7 Location + + property-location = element location { + + element parameters { + + altrepparam? & + languageparam? + }?, + + value-text + } + + # 3.8.1.8 Percent Complete + + property-percent = element percent-complete { + + element parameters { empty }?, + + value-integer + } + + + + + +Daboo, et al. Standards Track [Page 39] + +RFC 6321 xCal August 2011 + + + # 3.8.1.9 Priority + + property-priority = element priority { + + element parameters { empty }?, + + value-integer + } + + # 3.8.1.10 Resources + + property-resources = element resources { + + element parameters { + altrepparam? & + languageparam? + }?, + + value-text+ + } + + # 3.8.1.11 Status + + property-status-event = element status { + + element parameters { empty }?, + + element text { + "TENTATIVE" | + "CONFIRMED" | + "CANCELLED" + } + } + + property-status-todo = element status { + + element parameters { empty }?, + + element text { + "NEEDS-ACTION" | + "COMPLETED" | + "IN-PROCESS" | + "CANCELLED" + } + } + + + + + + +Daboo, et al. Standards Track [Page 40] + +RFC 6321 xCal August 2011 + + + property-status-jour = element status { + + element parameters { empty }?, + + element text { + "DRAFT" | + "FINAL" | + "CANCELLED" + } + } + + # 3.8.1.12 Summary + + property-summary = element summary { + + element parameters { + altrepparam? & + languageparam? + }?, + + value-text + } + + # 3.8.2 Date and Time Component Properties + + # 3.8.2.1 Date/Time Completed + + property-completed = element completed { + + element parameters { empty }?, + + value-date-time + } + + # 3.8.2.2 Date/Time End + + property-dtend = element dtend { + + element parameters { + tzidparam? + }?, + + value-date-time | + value-date + } + + + + + + +Daboo, et al. Standards Track [Page 41] + +RFC 6321 xCal August 2011 + + + # 3.8.2.3 Date/Time Due + + property-due = element due { + + element parameters { + tzidparam? + }?, + + value-date-time | + value-date + } + + # 3.8.2.4 Date/Time Start + + property-dtstart = element dtstart { + + element parameters { + tzidparam? + }?, + + value-date-time | + value-date + } + + # 3.8.2.5 Duration + + property-duration = element duration { + + element parameters { empty }?, + + value-duration + } + + # 3.8.2.6 Free/Busy Time + + property-freebusy = element freebusy { + + element parameters { + fbtypeparam? + }?, + + + value-period+ + } + + # 3.8.2.7 Time Transparency + + property-transp = element transp { + + + +Daboo, et al. Standards Track [Page 42] + +RFC 6321 xCal August 2011 + + + element parameters { empty }?, + + element text { + "OPAQUE" | + "TRANSPARENT" + } + } + + # 3.8.3 Time Zone Component Properties + + # 3.8.3.1 Time Zone Identifier + + property-tzid = element tzid { + + element parameters { empty }?, + + value-text + } + + # 3.8.3.2 Time Zone Name + + property-tzname = element tzname { + + element parameters { + languageparam? + }?, + + value-text + } + + # 3.8.3.3 Time Zone Offset From + + property-tzoffsetfrom = element tzoffsetfrom { + + element parameters { empty }?, + + value-utc-offset + } + + # 3.8.3.4 Time Zone Offset To + + property-tzoffsetto = element tzoffsetto { + + element parameters { empty }?, + + value-utc-offset + } + + + + +Daboo, et al. Standards Track [Page 43] + +RFC 6321 xCal August 2011 + + + # 3.8.3.5 Time Zone URL + + property-tzurl = element tzurl { + + element parameters { empty }?, + + value-uri + } + + # 3.8.4 Relationship Component Properties + + # 3.8.4.1 Attendee + + property-attendee = element attendee { + + element parameters { + cutypeparam? & + memberparam? & + roleparam? & + partstatparam? & + rsvpparam? & + deltoparam? & + delfromparam? & + sentbyparam? & + cnparam? & + dirparam? & + languageparam? + }?, + + value-cal-address + } + + # 3.8.4.2 Contact + + property-contact = element contact { + + element parameters { + altrepparam? & + languageparam? + }?, + + value-text + } + + # 3.8.4.3 Organizer + + property-organizer = element organizer { + + + + +Daboo, et al. Standards Track [Page 44] + +RFC 6321 xCal August 2011 + + + element parameters { + cnparam? & + dirparam? & + sentbyparam? & + languageparam? + }?, + + value-cal-address + } + + # 3.8.4.4 Recurrence ID + + property-recurid = element recurrence-id { + + element parameters { + tzidparam? & + rangeparam? + }?, + + value-date-time | + value-date + } + + # 3.8.4.5 Related-To + + property-related = element related-to { + + element parameters { + reltypeparam? + }?, + + value-text + } + + # 3.8.4.6 Uniform Resource Locator + + property-url = element url { + + element parameters { empty }?, + + value-uri + } + + # 3.8.4.7 Unique Identifier + + property-uid = element uid { + + element parameters { empty }?, + + + +Daboo, et al. Standards Track [Page 45] + +RFC 6321 xCal August 2011 + + + value-text + } + + # 3.8.5 Recurrence Component Properties + + # 3.8.5.1 Exception Date/Times + + property-exdate = element exdate { + + element parameters { + tzidparam? + }?, + + value-date-time+ | + value-date+ + } + + # 3.8.5.2 Recurrence Date/Times + + property-rdate = element rdate { + + element parameters { + tzidparam? + }?, + + value-date-time+ | + value-date+ | + value-period+ + } + + # 3.8.5.3 Recurrence Rule + + property-rrule = element rrule { + + element parameters { empty }?, + + value-recur + } + + # 3.8.6 Alarm Component Properties + + # 3.8.6.1 Action + + property-action = element action { + + element parameters { empty }?, + + + + + +Daboo, et al. Standards Track [Page 46] + +RFC 6321 xCal August 2011 + + + element text { + "AUDIO" | + "DISPLAY" | + "EMAIL" + } + } + + # 3.8.6.2 Repeat Count + + property-repeat = element repeat { + + element parameters { empty }?, + + value-integer + } + + # 3.8.6.3 Trigger + + property-trigger = element trigger { + + ( + element parameters { + trigrelparam? + }?, + + value-duration + ) | + ( + element parameters { empty }?, + + value-date-time + ) + } + + # 3.8.7 Change Management Component Properties + + # 3.8.7.1 Date/Time Created + + property-created = element created { + + element parameters { empty }?, + + value-date-time + } + + # 3.8.7.2 Date/Time Stamp + + property-dtstamp = element dtstamp { + + + +Daboo, et al. Standards Track [Page 47] + +RFC 6321 xCal August 2011 + + + element parameters { empty }?, + + value-date-time + } + + # 3.8.7.3 Last Modified + + property-last-mod = element last-modified { + + element parameters { empty }?, + + value-date-time + } + + # 3.8.7.4 Sequence Number + + property-seq = element sequence { + + element parameters { empty }?, + + value-integer + } + + # 3.8.8 Miscellaneous Component Properties + + # 3.8.8.3 Request Status + + property-rstatus = element request-status { + + element parameters { + languageparam? + }?, + + element code { xsd:string }, + element description { xsd:string }, + element data { xsd:string }? + } + + + + + + + + + + + + + + +Daboo, et al. Standards Track [Page 48] + +RFC 6321 xCal August 2011 + + +Appendix B. Examples + + This section contains two examples of iCalendar objects with their + xCal 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. XML Data + + + + + + + GREGORIAN + + + -//Example Inc.//Example Calendar//EN + + + 2.0 + + + + + + + 2008-02-05T19:12:24Z + + + 2008-10-06 + + + Planning meeting + + + +Daboo, et al. Standards Track [Page 49] + +RFC 6321 xCal August 2011 + + + + + 4088E990AD89CB3DBB484909 + + + + + + + +B.2. Example 2 + +B.2.1. iCalendar Data + + 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 + + + +Daboo, et al. Standards Track [Page 50] + +RFC 6321 xCal August 2011 + + + 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 + +B.2.2. XML Data + + + + + + + -//Example Inc.//Example Client//EN + + + 2.0 + + + + + + + 2004-01-10T03:28:45Z + + US/Eastern + + + + + + 2000-04-04T02:00:00 + + + + YEARLY + 1SU + 4 + + + + EDT + + + -05:00 + + + +Daboo, et al. Standards Track [Page 51] + +RFC 6321 xCal August 2011 + + + + + -04:00 + + + + + + + 2000-10-26T02:00:00 + + + + YEARLY + -1SU + 10 + + + + EST + + + -04:00 + + + -05:00 + + + + + + + + + 2006-02-06T00:11:21Z + + + + US/Eastern + + 2006-01-02T12:00:00 + + + PT1H + + + + DAILY + + + +Daboo, et al. Standards Track [Page 52] + +RFC 6321 xCal August 2011 + + + 5 + + + + + US/Eastern + + + 2006-01-02T15:00:00 + PT2H + + + + Event #2 + + + 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. Please bring your own lunch for the 12 pm + meetings. + + + 00959BC664CA650E933C892C@example.com + + + + + + + 2006-02-06T00:11:21Z + + + + US/Eastern + + 2006-01-04T14:00:00 + + + PT1H + + + + US/Eastern + + 2006-01-04T12:00:00 + + + Event #2 bis + + + +Daboo, et al. Standards Track [Page 53] + +RFC 6321 xCal August 2011 + + + + + 00959BC664CA650E933C892C@example.com + + + + + + + +Authors' Addresses + + Cyrus Daboo + Apple Inc. + 1 Infinite Loop + Cupertino, CA 95014 + USA + + EMail: cyrus@daboo.name + URI: http://www.apple.com/ + + + Mike Douglass + Rensselaer Polytechnic Institute + 110 8th Street + Troy, NY 12180 + USA + + EMail: douglm@rpi.edu + URI: http://www.rpi.edu/ + + + Steven Lees + Microsoft Corporation + One Microsoft Way + Redmond, WA 98052 + USA + + EMail: steven.lees@microsoft.com + URI: http://www.microsoft.com/ + + + + + + + + + + + +Daboo, et al. Standards Track [Page 54] + diff --git a/specs/rfc6350-vcard-4.0.txt b/specs/rfc6350-vcard-4.0.txt new file mode 100644 index 0000000..d853cbc --- /dev/null +++ b/specs/rfc6350-vcard-4.0.txt @@ -0,0 +1,4147 @@ + + + + + + +Internet Engineering Task Force (IETF) S. Perreault +Request for Comments: 6350 Viagenie +Obsoletes: 2425, 2426, 4770 August 2011 +Updates: 2739 +Category: Standards Track +ISSN: 2070-1721 + + + vCard Format Specification + +Abstract + + This document defines the vCard data format for representing and + exchanging a variety of information about individuals and other + entities (e.g., formatted and structured name and delivery addresses, + email address, multiple telephone numbers, photograph, logo, audio + clips, etc.). This document obsoletes RFCs 2425, 2426, and 4770, and + updates RFC 2739. + +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/rfc6350. + +Copyright Notice + + Copyright (c) 2011 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. + + + + +Perreault Standards Track [Page 1] + +RFC 6350 vCard August 2011 + + + This document may contain material from IETF Documents or IETF + Contributions published or made publicly available before November + 10, 2008. The person(s) controlling the copyright in some of this + material may not have granted the IETF Trust the right to allow + modifications of such material outside the IETF Standards Process. + Without obtaining an adequate license from the person(s) controlling + the copyright in such materials, this document may not be modified + outside the IETF Standards Process, and derivative works of it may + not be created outside the IETF Standards Process, except to format + it for publication as an RFC or to translate it into languages other + than English. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 3. vCard Format Specification . . . . . . . . . . . . . . . . . . 5 + 3.1. Charset . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 3.2. Line Delimiting and Folding . . . . . . . . . . . . . . . 5 + 3.3. ABNF Format Definition . . . . . . . . . . . . . . . . . . 6 + 3.4. Property Value Escaping . . . . . . . . . . . . . . . . . 9 + 4. Property Value Data Types . . . . . . . . . . . . . . . . . . 9 + 4.1. TEXT . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 4.2. URI . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 + 4.3. DATE, TIME, DATE-TIME, DATE-AND-OR-TIME, and TIMESTAMP . . 12 + 4.3.1. DATE . . . . . . . . . . . . . . . . . . . . . . . . . 12 + 4.3.2. TIME . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 4.3.3. DATE-TIME . . . . . . . . . . . . . . . . . . . . . . 13 + 4.3.4. DATE-AND-OR-TIME . . . . . . . . . . . . . . . . . . . 14 + 4.3.5. TIMESTAMP . . . . . . . . . . . . . . . . . . . . . . 14 + 4.4. BOOLEAN . . . . . . . . . . . . . . . . . . . . . . . . . 14 + 4.5. INTEGER . . . . . . . . . . . . . . . . . . . . . . . . . 15 + 4.6. FLOAT . . . . . . . . . . . . . . . . . . . . . . . . . . 15 + 4.7. UTC-OFFSET . . . . . . . . . . . . . . . . . . . . . . . . 15 + 4.8. LANGUAGE-TAG . . . . . . . . . . . . . . . . . . . . . . . 16 + 5. Property Parameters . . . . . . . . . . . . . . . . . . . . . 16 + 5.1. LANGUAGE . . . . . . . . . . . . . . . . . . . . . . . . . 16 + 5.2. VALUE . . . . . . . . . . . . . . . . . . . . . . . . . . 16 + 5.3. PREF . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 + 5.4. ALTID . . . . . . . . . . . . . . . . . . . . . . . . . . 18 + 5.5. PID . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 + 5.6. TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 + 5.7. MEDIATYPE . . . . . . . . . . . . . . . . . . . . . . . . 20 + 5.8. CALSCALE . . . . . . . . . . . . . . . . . . . . . . . . . 20 + 5.9. SORT-AS . . . . . . . . . . . . . . . . . . . . . . . . . 21 + 5.10. GEO . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 + 5.11. TZ . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 + + + + +Perreault Standards Track [Page 2] + +RFC 6350 vCard August 2011 + + + 6. vCard Properties . . . . . . . . . . . . . . . . . . . . . . . 23 + 6.1. General Properties . . . . . . . . . . . . . . . . . . . . 23 + 6.1.1. BEGIN . . . . . . . . . . . . . . . . . . . . . . . . 23 + 6.1.2. END . . . . . . . . . . . . . . . . . . . . . . . . . 23 + 6.1.3. SOURCE . . . . . . . . . . . . . . . . . . . . . . . . 24 + 6.1.4. KIND . . . . . . . . . . . . . . . . . . . . . . . . . 25 + 6.1.5. XML . . . . . . . . . . . . . . . . . . . . . . . . . 27 + 6.2. Identification Properties . . . . . . . . . . . . . . . . 28 + 6.2.1. FN . . . . . . . . . . . . . . . . . . . . . . . . . . 28 + 6.2.2. N . . . . . . . . . . . . . . . . . . . . . . . . . . 29 + 6.2.3. NICKNAME . . . . . . . . . . . . . . . . . . . . . . . 29 + 6.2.4. PHOTO . . . . . . . . . . . . . . . . . . . . . . . . 30 + 6.2.5. BDAY . . . . . . . . . . . . . . . . . . . . . . . . . 30 + 6.2.6. ANNIVERSARY . . . . . . . . . . . . . . . . . . . . . 31 + 6.2.7. GENDER . . . . . . . . . . . . . . . . . . . . . . . . 32 + 6.3. Delivery Addressing Properties . . . . . . . . . . . . . . 32 + 6.3.1. ADR . . . . . . . . . . . . . . . . . . . . . . . . . 32 + 6.4. Communications Properties . . . . . . . . . . . . . . . . 34 + 6.4.1. TEL . . . . . . . . . . . . . . . . . . . . . . . . . 34 + 6.4.2. EMAIL . . . . . . . . . . . . . . . . . . . . . . . . 36 + 6.4.3. IMPP . . . . . . . . . . . . . . . . . . . . . . . . . 36 + 6.4.4. LANG . . . . . . . . . . . . . . . . . . . . . . . . . 37 + 6.5. Geographical Properties . . . . . . . . . . . . . . . . . 37 + 6.5.1. TZ . . . . . . . . . . . . . . . . . . . . . . . . . . 37 + 6.5.2. GEO . . . . . . . . . . . . . . . . . . . . . . . . . 38 + 6.6. Organizational Properties . . . . . . . . . . . . . . . . 39 + 6.6.1. TITLE . . . . . . . . . . . . . . . . . . . . . . . . 39 + 6.6.2. ROLE . . . . . . . . . . . . . . . . . . . . . . . . . 39 + 6.6.3. LOGO . . . . . . . . . . . . . . . . . . . . . . . . . 40 + 6.6.4. ORG . . . . . . . . . . . . . . . . . . . . . . . . . 40 + 6.6.5. MEMBER . . . . . . . . . . . . . . . . . . . . . . . . 41 + 6.6.6. RELATED . . . . . . . . . . . . . . . . . . . . . . . 42 + 6.7. Explanatory Properties . . . . . . . . . . . . . . . . . . 43 + 6.7.1. CATEGORIES . . . . . . . . . . . . . . . . . . . . . . 43 + 6.7.2. NOTE . . . . . . . . . . . . . . . . . . . . . . . . . 44 + 6.7.3. PRODID . . . . . . . . . . . . . . . . . . . . . . . . 44 + 6.7.4. REV . . . . . . . . . . . . . . . . . . . . . . . . . 45 + 6.7.5. SOUND . . . . . . . . . . . . . . . . . . . . . . . . 45 + 6.7.6. UID . . . . . . . . . . . . . . . . . . . . . . . . . 46 + 6.7.7. CLIENTPIDMAP . . . . . . . . . . . . . . . . . . . . . 47 + 6.7.8. URL . . . . . . . . . . . . . . . . . . . . . . . . . 47 + 6.7.9. VERSION . . . . . . . . . . . . . . . . . . . . . . . 48 + 6.8. Security Properties . . . . . . . . . . . . . . . . . . . 48 + 6.8.1. KEY . . . . . . . . . . . . . . . . . . . . . . . . . 48 + 6.9. Calendar Properties . . . . . . . . . . . . . . . . . . . 49 + 6.9.1. FBURL . . . . . . . . . . . . . . . . . . . . . . . . 49 + 6.9.2. CALADRURI . . . . . . . . . . . . . . . . . . . . . . 50 + 6.9.3. CALURI . . . . . . . . . . . . . . . . . . . . . . . . 50 + + + +Perreault Standards Track [Page 3] + +RFC 6350 vCard August 2011 + + + 6.10. Extended Properties and Parameters . . . . . . . . . . . . 51 + 7. Synchronization . . . . . . . . . . . . . . . . . . . . . . . 51 + 7.1. Mechanisms . . . . . . . . . . . . . . . . . . . . . . . . 51 + 7.1.1. Matching vCard Instances . . . . . . . . . . . . . . . 51 + 7.1.2. Matching Property Instances . . . . . . . . . . . . . 52 + 7.1.3. PID Matching . . . . . . . . . . . . . . . . . . . . . 52 + 7.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 53 + 7.2.1. Creation . . . . . . . . . . . . . . . . . . . . . . . 53 + 7.2.2. Initial Sharing . . . . . . . . . . . . . . . . . . . 53 + 7.2.3. Adding and Sharing a Property . . . . . . . . . . . . 54 + 7.2.4. Simultaneous Editing . . . . . . . . . . . . . . . . . 54 + 7.2.5. Global Context Simplification . . . . . . . . . . . . 56 + 8. Example: Author's vCard . . . . . . . . . . . . . . . . . . . 56 + 9. Security Considerations . . . . . . . . . . . . . . . . . . . 57 + 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 58 + 10.1. Media Type Registration . . . . . . . . . . . . . . . . . 58 + 10.2. Registering New vCard Elements . . . . . . . . . . . . . . 59 + 10.2.1. Registration Procedure . . . . . . . . . . . . . . . . 59 + 10.2.2. Vendor Namespace . . . . . . . . . . . . . . . . . . . 60 + 10.2.3. Registration Template for Properties . . . . . . . . . 61 + 10.2.4. Registration Template for Parameters . . . . . . . . . 61 + 10.2.5. Registration Template for Value Data Types . . . . . . 62 + 10.2.6. Registration Template for Values . . . . . . . . . . . 62 + 10.3. Initial vCard Elements Registries . . . . . . . . . . . . 63 + 10.3.1. Properties Registry . . . . . . . . . . . . . . . . . 64 + 10.3.2. Parameters Registry . . . . . . . . . . . . . . . . . 65 + 10.3.3. Value Data Types Registry . . . . . . . . . . . . . . 65 + 10.3.4. Values Registries . . . . . . . . . . . . . . . . . . 66 + 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 69 + 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 69 + 12.1. Normative References . . . . . . . . . . . . . . . . . . . 69 + 12.2. Informative References . . . . . . . . . . . . . . . . . . 71 + Appendix A. Differences from RFCs 2425 and 2426 . . . . . . . . . 73 + A.1. New Structure . . . . . . . . . . . . . . . . . . . . . . 73 + A.2. Removed Features . . . . . . . . . . . . . . . . . . . . . 73 + A.3. New Properties and Parameters . . . . . . . . . . . . . . 73 + + + + + + + + + + + + + + + +Perreault Standards Track [Page 4] + +RFC 6350 vCard August 2011 + + +1. Introduction + + Electronic address books have become ubiquitous. Their increased + presence on portable, connected devices as well as the diversity of + platforms that exchange contact data call for a standard. This memo + defines the vCard format, which allows the capture and exchange of + information normally stored within an address book or directory + application. + + A high-level overview of the differences from RFCs 2425 and 2426 can + be found in Appendix A. + +2. Conventions + + 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]. + +3. vCard Format Specification + + The text/vcard MIME content type (hereafter known as "vCard"; see + Section 10.1) contains contact information, typically pertaining to a + single contact or group of contacts. The content consists of one or + more lines in the format given below. + +3.1. Charset + + The charset (see [RFC3536] for internationalization terminology) for + vCard is UTF-8 as defined in [RFC3629]. There is no way to override + this. It is invalid to specify a value other than "UTF-8" in the + "charset" MIME parameter (see Section 10.1). + +3.2. Line Delimiting and Folding + + Individual lines within vCard are delimited by the [RFC5322] line + break, which is a CRLF sequence (U+000D followed by U+000A). Long + logical lines of text can be split into a multiple-physical-line + representation using the following folding technique. Content lines + SHOULD be folded to a maximum width of 75 octets, excluding the line + break. Multi-octet characters MUST remain contiguous. The rationale + for this folding process can be found in [RFC5322], Section 2.1.1. + + A logical line MAY be continued on the next physical line anywhere + between two characters by inserting a CRLF immediately followed by a + single white space character (space (U+0020) or horizontal tab + (U+0009)). The folded line MUST contain at least one character. Any + sequence of CRLF followed immediately by a single white space + + + +Perreault Standards Track [Page 5] + +RFC 6350 vCard August 2011 + + + character is ignored (removed) when processing the content type. For + example, the line: + + NOTE:This is a long description that exists on a long line. + + can be represented as: + + NOTE:This is a long description + that exists on a long line. + + It could also be represented as: + + NOTE:This is a long descrip + tion that exists o + n a long line. + + The process of moving from this folded multiple-line representation + of a property definition to its single-line representation is called + unfolding. Unfolding is accomplished by regarding CRLF immediately + followed by a white space character (namely, HTAB (U+0009) or SPACE + (U+0020)) as equivalent to no characters at all (i.e., the CRLF and + single white space character are removed). + + Note: It is possible for very simple implementations to generate + improperly folded lines in the middle of a UTF-8 multi-octet + sequence. For this reason, implementations SHOULD unfold lines in + such a way as to properly restore the original sequence. + + Note: Unfolding is done differently than in [RFC5322]. Unfolding + in [RFC5322] only removes the CRLF, not the space following it. + + Folding is done after any content encoding of a type value. + Unfolding is done before any decoding of a type value in a content + line. + +3.3. ABNF Format Definition + + The following ABNF uses the notation of [RFC5234], which also defines + CRLF, WSP, DQUOTE, VCHAR, ALPHA, and DIGIT. + + vcard-entity = 1*vcard + + vcard = "BEGIN:VCARD" CRLF + "VERSION:4.0" CRLF + 1*contentline + "END:VCARD" CRLF + ; A vCard object MUST include the VERSION and FN properties. + ; VERSION MUST come immediately after BEGIN:VCARD. + + + +Perreault Standards Track [Page 6] + +RFC 6350 vCard August 2011 + + + contentline = [group "."] name *(";" param) ":" value CRLF + ; When parsing a content line, folded lines must first + ; be unfolded according to the unfolding procedure + ; described in Section 3.2. + ; When generating a content line, lines longer than 75 + ; characters SHOULD be folded according to the folding + ; procedure described in Section 3.2. + + group = 1*(ALPHA / DIGIT / "-") + name = "SOURCE" / "KIND" / "FN" / "N" / "NICKNAME" + / "PHOTO" / "BDAY" / "ANNIVERSARY" / "GENDER" / "ADR" / "TEL" + / "EMAIL" / "IMPP" / "LANG" / "TZ" / "GEO" / "TITLE" / "ROLE" + / "LOGO" / "ORG" / "MEMBER" / "RELATED" / "CATEGORIES" + / "NOTE" / "PRODID" / "REV" / "SOUND" / "UID" / "CLIENTPIDMAP" + / "URL" / "KEY" / "FBURL" / "CALADRURI" / "CALURI" / "XML" + / iana-token / x-name + ; Parsing of the param and value is based on the "name" as + ; defined in ABNF sections below. + ; Group and name are case-insensitive. + + iana-token = 1*(ALPHA / DIGIT / "-") + ; identifier registered with IANA + + x-name = "x-" 1*(ALPHA / DIGIT / "-") + ; Names that begin with "x-" or "X-" are + ; reserved for experimental use, not intended for released + ; products, or for use in bilateral agreements. + + param = language-param / value-param / pref-param / pid-param + / type-param / geo-parameter / tz-parameter / sort-as-param + / calscale-param / any-param + ; Allowed parameters depend on property name. + + param-value = *SAFE-CHAR / DQUOTE *QSAFE-CHAR DQUOTE + + any-param = (iana-token / x-name) "=" param-value *("," param-value) + + NON-ASCII = UTF8-2 / UTF8-3 / UTF8-4 + ; UTF8-{2,3,4} are defined in [RFC3629] + + QSAFE-CHAR = WSP / "!" / %x23-7E / NON-ASCII + ; Any character except CTLs, DQUOTE + + SAFE-CHAR = WSP / "!" / %x23-39 / %x3C-7E / NON-ASCII + ; Any character except CTLs, DQUOTE, ";", ":" + + VALUE-CHAR = WSP / VCHAR / NON-ASCII + ; Any textual character + + + +Perreault Standards Track [Page 7] + +RFC 6350 vCard August 2011 + + + A line that begins with a white space character is a continuation of + the previous line, as described in Section 3.2. The white space + character and immediately preceeding CRLF should be discarded when + reconstructing the original line. Note that this line-folding + convention differs from that found in [RFC5322], in that the sequence + found anywhere in the content indicates a continued line + and should be removed. + + Property names and parameter names are case-insensitive (e.g., the + property name "fn" is the same as "FN" and "Fn"). Parameter values + MAY be case-sensitive or case-insensitive, depending on their + definition. Parameter values that are not explicitly defined as + being case-sensitive are case-insensitive. Based on experience with + vCard 3 interoperability, it is RECOMMENDED that property and + parameter names be upper-case on output. + + The group construct is used to group related properties together. + The group name is a syntactic convention used to indicate that all + property names prefaced with the same group name SHOULD be grouped + together when displayed by an application. It has no other + significance. Implementations that do not understand or support + grouping MAY simply strip off any text before a "." to the left of + the type name and present the types and values as normal. + + Property cardinalities are indicated using the following notation, + which is based on ABNF (see [RFC5234], Section 3.6): + + +-------------+--------------------------------------------------+ + | Cardinality | Meaning | + +-------------+--------------------------------------------------+ + | 1 | Exactly one instance per vCard MUST be present. | + | *1 | Exactly one instance per vCard MAY be present. | + | 1* | One or more instances per vCard MUST be present. | + | * | One or more instances per vCard MAY be present. | + +-------------+--------------------------------------------------+ + + Properties defined in a vCard instance may have multiple values + depending on the property cardinality. The general rule for encoding + multi-valued properties is to simply create a new content line for + each value (including the property name). However, it should be + noted that some value types support encoding multiple values in a + single content line by separating the values with a comma ",". This + approach has been taken for several of the content types defined + below (date, time, integer, float). + + + + + + + +Perreault Standards Track [Page 8] + +RFC 6350 vCard August 2011 + + +3.4. Property Value Escaping + + Some properties may contain one or more values delimited by a COMMA + character (U+002C). Therefore, a COMMA character in a value MUST be + escaped with a BACKSLASH character (U+005C), even for properties that + don't allow multiple instances (for consistency). + + Some properties (e.g., N and ADR) comprise multiple fields delimited + by a SEMICOLON character (U+003B). Therefore, a SEMICOLON in a field + of such a "compound" property MUST be escaped with a BACKSLASH + character. SEMICOLON characters in non-compound properties MAY be + escaped. On input, an escaped SEMICOLON character is never a field + separator. An unescaped SEMICOLON character may be a field + separator, depending on the property in which it appears. + + Furthermore, some fields of compound properties may contain a list of + values delimited by a COMMA character. Therefore, a COMMA character + in one of a field's values MUST be escaped with a BACKSLASH + character, even for fields that don't allow multiple values (for + consistency). Compound properties allowing multiple instances MUST + NOT be encoded in a single content line. + + Finally, BACKSLASH characters in values MUST be escaped with a + BACKSLASH character. NEWLINE (U+000A) characters in values MUST be + encoded by two characters: a BACKSLASH followed by either an 'n' + (U+006E) or an 'N' (U+004E). + + In all other cases, escaping MUST NOT be used. + +4. Property Value Data Types + + Standard value types are defined below. + + value = text + / text-list + / date-list + / time-list + / date-time-list + / date-and-or-time-list + / timestamp-list + / boolean + / integer-list + / float-list + / URI ; from Section 3 of [RFC3986] + / utc-offset + / Language-Tag + / iana-valuespec + ; Actual value type depends on property name and VALUE parameter. + + + +Perreault Standards Track [Page 9] + +RFC 6350 vCard August 2011 + + + text = *TEXT-CHAR + + TEXT-CHAR = "\\" / "\," / "\n" / WSP / NON-ASCII + / %x21-2B / %x2D-5B / %x5D-7E + ; Backslashes, commas, and newlines must be encoded. + + component = "\\" / "\," / "\;" / "\n" / WSP / NON-ASCII + / %x21-2B / %x2D-3A / %x3C-5B / %x5D-7E + list-component = component *("," component) + + text-list = text *("," text) + date-list = date *("," date) + time-list = time *("," time) + date-time-list = date-time *("," date-time) + date-and-or-time-list = date-and-or-time *("," date-and-or-time) + timestamp-list = timestamp *("," timestamp) + integer-list = integer *("," integer) + float-list = float *("," float) + + boolean = "TRUE" / "FALSE" + integer = [sign] 1*DIGIT + float = [sign] 1*DIGIT ["." 1*DIGIT] + + sign = "+" / "-" + + year = 4DIGIT ; 0000-9999 + month = 2DIGIT ; 01-12 + day = 2DIGIT ; 01-28/29/30/31 depending on month and leap year + hour = 2DIGIT ; 00-23 + minute = 2DIGIT ; 00-59 + second = 2DIGIT ; 00-58/59/60 depending on leap second + zone = utc-designator / utc-offset + utc-designator = %x5A ; uppercase "Z" + + date = year [month day] + / year "-" month + / "--" month [day] + / "--" "-" day + date-noreduc = year month day + / "--" month day + / "--" "-" day + date-complete = year month day + + time = hour [minute [second]] [zone] + / "-" minute [second] [zone] + / "-" "-" second [zone] + time-notrunc = hour [minute [second]] [zone] + time-complete = hour minute second [zone] + + + +Perreault Standards Track [Page 10] + +RFC 6350 vCard August 2011 + + + time-designator = %x54 ; uppercase "T" + date-time = date-noreduc time-designator time-notrunc + timestamp = date-complete time-designator time-complete + + date-and-or-time = date-time / date / time-designator time + + utc-offset = sign hour [minute] + + Language-Tag = + + iana-valuespec = + ; a publicly defined valuetype format, registered + ; with IANA, as defined in Section 12 of this + ; document. + +4.1. TEXT + + "text": The "text" value type should be used to identify values that + contain human-readable text. As for the language, it is controlled + by the LANGUAGE property parameter defined in Section 5.1. + + Examples for "text": + + this is a text value + this is one value,this is another + this is a single value\, with a comma encoded + + A formatted text line break in a text value type MUST be represented + as the character sequence backslash (U+005C) followed by a Latin + small letter n (U+006E) or a Latin capital letter N (U+004E), that + is, "\n" or "\N". + + For example, a multiple line NOTE value of: + + Mythical Manager + Hyjinx Software Division + BabsCo, Inc. + + could be represented as: + + NOTE:Mythical Manager\nHyjinx Software Division\n + BabsCo\, Inc.\n + + demonstrating the \n literal formatted line break technique, the + CRLF-followed-by-space line folding technique, and the backslash + escape technique. + + + + + +Perreault Standards Track [Page 11] + +RFC 6350 vCard August 2011 + + +4.2. URI + + "uri": The "uri" value type should be used to identify values that + are referenced by a Uniform Resource Identifier (URI) instead of + encoded in-line. These value references might be used if the value + is too large, or otherwise undesirable to include directly. The + format for the URI is as defined in Section 3 of [RFC3986]. Note + that the value of a property of type "uri" is what the URI points to, + not the URI itself. + + Examples for "uri": + + http://www.example.com/my/picture.jpg + ldap://ldap.example.com/cn=babs%20jensen + +4.3. DATE, TIME, DATE-TIME, DATE-AND-OR-TIME, and TIMESTAMP + + "date", "time", "date-time", "date-and-or-time", and "timestamp": + Each of these value types is based on the definitions in + [ISO.8601.2004]. Multiple such values can be specified using the + comma-separated notation. + + Only the basic format is supported. + +4.3.1. DATE + + A calendar date as specified in [ISO.8601.2004], Section 4.1.2. + + Reduced accuracy, as specified in [ISO.8601.2004], Sections 4.1.2.3 + a) and b), but not c), is permitted. + + Expanded representation, as specified in [ISO.8601.2004], Section + 4.1.4, is forbidden. + + Truncated representation, as specified in [ISO.8601.2000], Sections + 5.2.1.3 d), e), and f), is permitted. + + Examples for "date": + + 19850412 + 1985-04 + 1985 + --0412 + ---12 + + + + + + + +Perreault Standards Track [Page 12] + +RFC 6350 vCard August 2011 + + + Note the use of YYYY-MM in the second example above. YYYYMM is + disallowed to prevent confusion with YYMMDD. Note also that + YYYY-MM-DD is disallowed since we are using the basic format instead + of the extended format. + +4.3.2. TIME + + A time of day as specified in [ISO.8601.2004], Section 4.2. + + Reduced accuracy, as specified in [ISO.8601.2004], Section 4.2.2.3, + is permitted. + + Representation with decimal fraction, as specified in + [ISO.8601.2004], Section 4.2.2.4, is forbidden. + + The midnight hour is always represented by 00, never 24 (see + [ISO.8601.2004], Section 4.2.3). + + Truncated representation, as specified in [ISO.8601.2000], Sections + 5.3.1.4 a), b), and c), is permitted. + + Examples for "time": + + 102200 + 1022 + 10 + -2200 + --00 + 102200Z + 102200-0800 + +4.3.3. DATE-TIME + + A date and time of day combination as specified in [ISO.8601.2004], + Section 4.3. + + Truncation of the date part, as specified in [ISO.8601.2000], Section + 5.4.2 c), is permitted. + + Examples for "date-time": + + 19961022T140000 + --1022T1400 + ---22T14 + + + + + + + +Perreault Standards Track [Page 13] + +RFC 6350 vCard August 2011 + + +4.3.4. DATE-AND-OR-TIME + + Either a DATE-TIME, a DATE, or a TIME value. To allow unambiguous + interpretation, a stand-alone TIME value is always preceded by a "T". + + Examples for "date-and-or-time": + + 19961022T140000 + --1022T1400 + ---22T14 + 19850412 + 1985-04 + 1985 + --0412 + ---12 + T102200 + T1022 + T10 + T-2200 + T--00 + T102200Z + T102200-0800 + +4.3.5. TIMESTAMP + + A complete date and time of day combination as specified in + [ISO.8601.2004], Section 4.3.2. + + Examples for "timestamp": + + 19961022T140000 + 19961022T140000Z + 19961022T140000-05 + 19961022T140000-0500 + +4.4. BOOLEAN + + "boolean": The "boolean" value type is used to express boolean + values. These values are case-insensitive. + + Examples: + + TRUE + false + True + + + + + + +Perreault Standards Track [Page 14] + +RFC 6350 vCard August 2011 + + +4.5. INTEGER + + "integer": The "integer" value type is used to express signed + integers in decimal format. If sign is not specified, the value is + assumed positive "+". Multiple "integer" values can be specified + using the comma-separated notation. The maximum value is + 9223372036854775807, and the minimum value is -9223372036854775808. + These limits correspond to a signed 64-bit integer using two's- + complement arithmetic. + + Examples: + + 1234567890 + -1234556790 + +1234556790,432109876 + +4.6. FLOAT + + "float": The "float" value type is used to express real numbers. If + sign is not specified, the value is assumed positive "+". Multiple + "float" values can be specified using the comma-separated notation. + Implementations MUST support a precision equal or better than that of + the IEEE "binary64" format [IEEE.754.2008]. + + Note: Scientific notation is disallowed. Implementers wishing to + use their favorite language's %f formatting should be careful. + + Examples: + + 20.30 + 1000000.0000001 + 1.333,3.14 + +4.7. UTC-OFFSET + + "utc-offset": The "utc-offset" value type specifies that the property + value is a signed offset from UTC. This value type can be specified + in the TZ property. + + The value type is an offset from Coordinated Universal Time (UTC). + It is specified as a positive or negative difference in units of + hours and minutes (e.g., +hhmm). The time is specified as a 24-hour + clock. Hour values are from 00 to 23, and minute values are from 00 + to 59. Hour and minutes are 2 digits with high-order zeroes required + to maintain digit count. The basic format for ISO 8601 UTC offsets + MUST be used. + + + + + +Perreault Standards Track [Page 15] + +RFC 6350 vCard August 2011 + + +4.8. LANGUAGE-TAG + + "language-tag": A single language tag, as defined in [RFC5646]. + +5. Property Parameters + + A property can have attributes associated with it. These "property + parameters" contain meta-information about the property or the + property value. In some cases, the property parameter can be multi- + valued in which case the property parameter value elements are + separated by a COMMA (U+002C). + + Property parameter value elements that contain the COLON (U+003A), + SEMICOLON (U+003B), or COMMA (U+002C) character separators MUST be + specified as quoted-string text values. Property parameter values + MUST NOT contain the DQUOTE (U+0022) character. The DQUOTE character + is used as a delimiter for parameter values that contain restricted + characters or URI text. + + Applications MUST ignore x-param and iana-param values they don't + recognize. + +5.1. LANGUAGE + + The LANGUAGE property parameter is used to identify data in multiple + languages. There is no concept of "default" language, except as + specified by any "Content-Language" MIME header parameter that is + present [RFC3282]. The value of the LANGUAGE property parameter is a + language tag as defined in Section 2 of [RFC5646]. + + Examples: + + ROLE;LANGUAGE=tr:hoca + + ABNF: + + language-param = "LANGUAGE=" Language-Tag + ; Language-Tag is defined in section 2.1 of RFC 5646 + +5.2. VALUE + + The VALUE parameter is OPTIONAL, used to identify the value type + (data type) and format of the value. The use of these predefined + formats is encouraged even if the value parameter is not explicitly + used. By defining a standard set of value types and their formats, + existing parsing and processing code can be leveraged. The + + + + + +Perreault Standards Track [Page 16] + +RFC 6350 vCard August 2011 + + + predefined data type values MUST NOT be repeated in COMMA-separated + value lists except within the N, NICKNAME, ADR, and CATEGORIES + properties. + + ABNF: + + value-param = "VALUE=" value-type + + value-type = "text" + / "uri" + / "date" + / "time" + / "date-time" + / "date-and-or-time" + / "timestamp" + / "boolean" + / "integer" + / "float" + / "utc-offset" + / "language-tag" + / iana-token ; registered as described in section 12 + / x-name + +5.3. PREF + + The PREF parameter is OPTIONAL and is used to indicate that the + corresponding instance of a property is preferred by the vCard + author. Its value MUST be an integer between 1 and 100 that + quantifies the level of preference. Lower values correspond to a + higher level of preference, with 1 being most preferred. + + When the parameter is absent, the default MUST be to interpret the + property instance as being least preferred. + + Note that the value of this parameter is to be interpreted only in + relation to values assigned to other instances of the same property + in the same vCard. A given value, or the absence of a value, MUST + NOT be interpreted on its own. + + This parameter MAY be applied to any property that allows multiple + instances. + + ABNF: + + pref-param = "PREF=" (1*2DIGIT / "100") + ; An integer between 1 and 100. + + + + + +Perreault Standards Track [Page 17] + +RFC 6350 vCard August 2011 + + +5.4. ALTID + + The ALTID parameter is used to "tag" property instances as being + alternative representations of the same logical property. For + example, translations of a property in multiple languages generates + multiple property instances having different LANGUAGE (Section 5.1) + parameter that are tagged with the same ALTID value. + + This parameter's value is treated as an opaque string. Its sole + purpose is to be compared for equality against other ALTID parameter + values. + + Two property instances are considered alternative representations of + the same logical property if and only if their names as well as the + value of their ALTID parameters are identical. Property instances + without the ALTID parameter MUST NOT be considered an alternative + representation of any other property instance. Values for the ALTID + parameter are not globally unique: they MAY be reused for different + property names. + + Property instances having the same ALTID parameter value count as 1 + toward cardinality. Therefore, since N (Section 6.2.2) has + cardinality *1 and TITLE (Section 6.6.1) has cardinality *, these + three examples would be legal: + + N;ALTID=1;LANGUAGE=jp:;;;; + N;ALTID=1;LANGUAGE=en:Yamada;Taro;;; + ( denotes a UTF8-encoded Unicode character.) + + TITLE;ALTID=1;LANGUAGE=fr:Patron + TITLE;ALTID=1;LANGUAGE=en:Boss + + TITLE;ALTID=1;LANGUAGE=fr:Patron + TITLE;ALTID=1;LANGUAGE=en:Boss + TITLE;ALTID=2;LANGUAGE=en:Chief vCard Evangelist + + while this one would not: + + N;ALTID=1;LANGUAGE=jp:;;;; + N:Yamada;Taro;;; + (Two instances of the N property.) + + and these three would be legal but questionable: + + TITLE;ALTID=1;LANGUAGE=fr:Patron + TITLE;ALTID=2;LANGUAGE=en:Boss + (Should probably have the same ALTID value.) + + + + +Perreault Standards Track [Page 18] + +RFC 6350 vCard August 2011 + + + TITLE;ALTID=1;LANGUAGE=fr:Patron + TITLE:LANGUAGE=en:Boss + (Second line should probably have ALTID=1.) + + N;ALTID=1;LANGUAGE=jp:;;;; + N;ALTID=1;LANGUAGE=en:Yamada;Taro;;; + N;ALTID=1;LANGUAGE=en:Smith;John;;; + (The last line should probably have ALTID=2. But that would be + illegal because N has cardinality *1.) + + The ALTID property MAY also be used in may contexts other than with + the LANGUAGE parameter. Here's an example with two representations + of the same photo in different file formats: + + PHOTO;ALTID=1:data:image/jpeg;base64,... + PHOTO;ALTID=1;data:image/jp2;base64,... + + ABNF: + + altid-param = "ALTID=" param-value + +5.5. PID + + The PID parameter is used to identify a specific property among + multiple instances. It plays a role analogous to the UID property + (Section 6.7.6) on a per-property instead of per-vCard basis. It MAY + appear more than once in a given property. It MUST NOT appear on + properties that may have only one instance per vCard. Its value is + either a single small positive integer or a pair of small positive + integers separated by a dot. Multiple values may be encoded in a + single PID parameter by separating the values with a comma ",". See + Section 7 for more details on its usage. + + ABNF: + + pid-param = "PID=" pid-value *("," pid-value) + pid-value = 1*DIGIT ["." 1*DIGIT] + +5.6. TYPE + + The TYPE parameter has multiple, different uses. In general, it is a + way of specifying class characteristics of the associated property. + Most of the time, its value is a comma-separated subset of a + predefined enumeration. In this document, the following properties + make use of this parameter: FN, NICKNAME, PHOTO, ADR, TEL, EMAIL, + IMPP, LANG, TZ, GEO, TITLE, ROLE, LOGO, ORG, RELATED, CATEGORIES, + + + + + +Perreault Standards Track [Page 19] + +RFC 6350 vCard August 2011 + + + NOTE, SOUND, URL, KEY, FBURL, CALADRURI, and CALURI. The TYPE + parameter MUST NOT be applied on other properties defined in this + document. + + The "work" and "home" values act like tags. The "work" value implies + that the property is related to an individual's work place, while the + "home" value implies that the property is related to an individual's + personal life. When neither "work" nor "home" is present, it is + implied that the property is related to both an individual's work + place and personal life in the case that the KIND property's value is + "individual", or to none in other cases. + + ABNF: + + type-param = "TYPE=" type-value *("," type-value) + + type-value = "work" / "home" / type-param-tel + / type-param-related / iana-token / x-name + ; This is further defined in individual property sections. + +5.7. MEDIATYPE + + The MEDIATYPE parameter is used with properties whose value is a URI. + Its use is OPTIONAL. It provides a hint to the vCard consumer + application about the media type [RFC2046] of the resource identified + by the URI. Some URI schemes do not need this parameter. For + example, the "data" scheme allows the media type to be explicitly + indicated as part of the URI [RFC2397]. Another scheme, "http", + provides the media type as part of the URI resolution process, with + the Content-Type HTTP header [RFC2616]. The MEDIATYPE parameter is + intended to be used with URI schemes that do not provide such + functionality (e.g., "ftp" [RFC1738]). + + ABNF: + + mediatype-param = "MEDIATYPE=" mediatype + mediatype = type-name "/" subtype-name *( ";" attribute "=" value ) + ; "attribute" and "value" are from [RFC2045] + ; "type-name" and "subtype-name" are from [RFC4288] + +5.8. CALSCALE + + The CALSCALE parameter is identical to the CALSCALE property in + iCalendar (see [RFC5545], Section 3.7.1). It is used to define the + calendar system in which a date or date-time value is expressed. The + only value specified by iCalendar is "gregorian", which stands for + the Gregorian system. It is the default when the parameter is + absent. Additional values may be defined in extension documents and + + + +Perreault Standards Track [Page 20] + +RFC 6350 vCard August 2011 + + + registered with IANA (see Section 10.3.4). A vCard implementation + MUST ignore properties with a CALSCALE parameter value that it does + not understand. + + ABNF: + + calscale-param = "CALSCALE=" calscale-value + + calscale-value = "gregorian" / iana-token / x-name + +5.9. SORT-AS + + The "sort-as" parameter is used to specify the string to be used for + national-language-specific sorting. Without this information, + sorting algorithms could incorrectly sort this vCard within a + sequence of sorted vCards. When this property is present in a vCard, + then the given strings are used for sorting the vCard. + + This parameter's value is a comma-separated list that MUST have as + many or fewer elements as the corresponding property value has + components. This parameter's value is case-sensitive. + + ABNF: + + sort-as-param = "SORT-AS=" sort-as-value + + sort-as-value = param-value *("," param-value) + + Examples: For the case of surname and given name sorting, the + following examples define common sort string usage with the N + property. + + FN:Rene van der Harten + N;SORT-AS="Harten,Rene":van der Harten;Rene,J.;Sir;R.D.O.N. + + FN:Robert Pau Shou Chang + N;SORT-AS="Pau Shou Chang,Robert":Shou Chang;Robert,Pau;; + + FN:Osamu Koura + N;SORT-AS="Koura,Osamu":Koura;Osamu;; + + FN:Oscar del Pozo + N;SORT-AS="Pozo,Oscar":del Pozo Triscon;Oscar;; + + FN:Chistine d'Aboville + N;SORT-AS="Aboville,Christine":d'Aboville;Christine;; + + + + + +Perreault Standards Track [Page 21] + +RFC 6350 vCard August 2011 + + + FN:H. James de Mann + N;SORT-AS="Mann,James":de Mann;Henry,James;; + + If sorted by surname, the results would be: + + Christine d'Aboville + Rene van der Harten + Osamu Koura + H. James de Mann + Robert Pau Shou Chang + Oscar del Pozo + + If sorted by given name, the results would be: + + Christine d'Aboville + H. James de Mann + Osamu Koura + Oscar del Pozo + Rene van der Harten + Robert Pau Shou Chang + +5.10. GEO + + The GEO parameter can be used to indicate global positioning + information that is specific to an address. Its value is the same as + that of the GEO property (see Section 6.5.2). + + ABNF: + + geo-parameter = "GEO=" DQUOTE URI DQUOTE + +5.11. TZ + + The TZ parameter can be used to indicate time zone information that + is specific to an address. Its value is the same as that of the TZ + property. + + ABNF: + + tz-parameter = "TZ=" (param-value / DQUOTE URI DQUOTE) + + + + + + + + + + + +Perreault Standards Track [Page 22] + +RFC 6350 vCard August 2011 + + +6. vCard Properties + + What follows is an enumeration of the standard vCard properties. + +6.1. General Properties + +6.1.1. BEGIN + + Purpose: To denote the beginning of a syntactic entity within a + text/vcard content-type. + + Value type: text + + Cardinality: 1 + + Special notes: The content entity MUST begin with the BEGIN property + with a value of "VCARD". The value is case-insensitive. + + The BEGIN property is used in conjunction with the END property to + delimit an entity containing a related set of properties within a + text/vcard content-type. This construct can be used instead of + including multiple vCards as body parts inside of a multipart/ + alternative MIME message. It is provided for applications that + wish to define content that can contain multiple entities within + the same text/vcard content-type or to define content that can be + identifiable outside of a MIME environment. + + ABNF: + + BEGIN-param = 0" " ; no parameter allowed + BEGIN-value = "VCARD" + + Example: + + BEGIN:VCARD + +6.1.2. END + + Purpose: To denote the end of a syntactic entity within a text/vcard + content-type. + + Value type: text + + Cardinality: 1 + + Special notes: The content entity MUST end with the END type with a + value of "VCARD". The value is case-insensitive. + + + + +Perreault Standards Track [Page 23] + +RFC 6350 vCard August 2011 + + + The END property is used in conjunction with the BEGIN property to + delimit an entity containing a related set of properties within a + text/vcard content-type. This construct can be used instead of or + in addition to wrapping separate sets of information inside + additional MIME headers. It is provided for applications that + wish to define content that can contain multiple entities within + the same text/vcard content-type or to define content that can be + identifiable outside of a MIME environment. + + ABNF: + + END-param = 0" " ; no parameter allowed + END-value = "VCARD" + + Example: + + END:VCARD + +6.1.3. SOURCE + + Purpose: To identify the source of directory information contained + in the content type. + + Value type: uri + + Cardinality: * + + Special notes: The SOURCE property is used to provide the means by + which applications knowledgable in the given directory service + protocol can obtain additional or more up-to-date information from + the directory service. It contains a URI as defined in [RFC3986] + and/or other information referencing the vCard to which the + information pertains. When directory information is available + from more than one source, the sending entity can pick what it + considers to be the best source, or multiple SOURCE properties can + be included. + + ABNF: + + SOURCE-param = "VALUE=uri" / pid-param / pref-param / altid-param + / mediatype-param / any-param + SOURCE-value = URI + + Examples: + + SOURCE:ldap://ldap.example.com/cn=Babs%20Jensen,%20o=Babsco,%20c=US + + + + + +Perreault Standards Track [Page 24] + +RFC 6350 vCard August 2011 + + + SOURCE:http://directory.example.com/addressbooks/jdoe/ + Jean%20Dupont.vcf + +6.1.4. KIND + + Purpose: To specify the kind of object the vCard represents. + + Value type: A single text value. + + Cardinality: *1 + + Special notes: The value may be one of the following: + + "individual" for a vCard representing a single person or entity. + This is the default kind of vCard. + + "group" for a vCard representing a group of persons or entities. + The group's member entities can be other vCards or other types + of entities, such as email addresses or web sites. A group + vCard will usually contain MEMBER properties to specify the + members of the group, but it is not required to. A group vCard + without MEMBER properties can be considered an abstract + grouping, or one whose members are known empirically (perhaps + "IETF Participants" or "Republican U.S. Senators"). + + All properties in a group vCard apply to the group as a whole, + and not to any particular MEMBER. For example, an EMAIL + property might specify the address of a mailing list associated + with the group, and an IMPP property might refer to a group + chat room. + + "org" for a vCard representing an organization. An organization + vCard will not (in fact, MUST NOT) contain MEMBER properties, + and so these are something of a cross between "individual" and + "group". An organization is a single entity, but not a person. + It might represent a business or government, a department or + division within a business or government, a club, an + association, or the like. + + All properties in an organization vCard apply to the + organization as a whole, as is the case with a group vCard. + For example, an EMAIL property might specify the address of a + contact point for the organization. + + + + + + + + +Perreault Standards Track [Page 25] + +RFC 6350 vCard August 2011 + + + "location" for a named geographical place. A location vCard will + usually contain a GEO property, but it is not required to. A + location vCard without a GEO property can be considered an + abstract location, or one whose definition is known empirically + (perhaps "New England" or "The Seashore"). + + All properties in a location vCard apply to the location + itself, and not with any entity that might exist at that + location. For example, in a vCard for an office building, an + ADR property might give the mailing address for the building, + and a TEL property might specify the telephone number of the + receptionist. + + An x-name. vCards MAY include private or experimental values for + KIND. Remember that x-name values are not intended for general + use and are unlikely to interoperate. + + An iana-token. Additional values may be registered with IANA (see + Section 10.3.4). A new value's specification document MUST + specify which properties make sense for that new kind of vCard + and which do not. + + Implementations MUST support the specific string values defined + above. If this property is absent, "individual" MUST be assumed + as the default. If this property is present but the + implementation does not understand its value (the value is an + x-name or iana-token that the implementation does not support), + the implementation SHOULD act in a neutral way, which usually + means treating the vCard as though its kind were "individual". + The presence of MEMBER properties MAY, however, be taken as an + indication that the unknown kind is an extension of "group". + + Clients often need to visually distinguish contacts based on what + they represent, and the KIND property provides a direct way for + them to do so. For example, when displaying contacts in a list, + an icon could be displayed next to each one, using distinctive + icons for the different kinds; a client might use an outline of a + single person to represent an "individual", an outline of multiple + people to represent a "group", and so on. Alternatively, or in + addition, a client might choose to segregate different kinds of + vCards to different panes, tabs, or selections in the user + interface. + + Some clients might also make functional distinctions among the + kinds, ignoring "location" vCards for some purposes and + considering only "location" vCards for others. + + + + + +Perreault Standards Track [Page 26] + +RFC 6350 vCard August 2011 + + + When designing those sorts of visual and functional distinctions, + client implementations have to decide how to fit unsupported kinds + into the scheme. What icon is used for them? The one for + "individual"? A unique one, such as an icon of a question mark? + Which tab do they go into? It is beyond the scope of this + specification to answer these questions, but these are things + implementers need to consider. + + ABNF: + + KIND-param = "VALUE=text" / any-param + KIND-value = "individual" / "group" / "org" / "location" + / iana-token / x-name + + Example: + + This represents someone named Jane Doe working in the marketing + department of the North American division of ABC Inc. + + BEGIN:VCARD + VERSION:4.0 + KIND:individual + FN:Jane Doe + ORG:ABC\, Inc.;North American Division;Marketing + END:VCARD + + This represents the department itself, commonly known as ABC + Marketing. + + BEGIN:VCARD + VERSION:4.0 + KIND:org + FN:ABC Marketing + ORG:ABC\, Inc.;North American Division;Marketing + END:VCARD + +6.1.5. XML + + Purpose: To include extended XML-encoded vCard data in a plain + vCard. + + Value type: A single text value. + + Cardinality: * + + Special notes: The content of this property is a single XML 1.0 + [W3C.REC-xml-20081126] element whose namespace MUST be explicitly + specified using the xmlns attribute and MUST NOT be the vCard 4 + + + +Perreault Standards Track [Page 27] + +RFC 6350 vCard August 2011 + + + namespace ("urn:ietf:params:xml:ns:vcard-4.0"). (This implies + that it cannot duplicate a standard vCard property.) The element + is to be interpreted as if it was contained in a element, + as defined in [RFC6351]. + + The fragment is subject to normal line folding and escaping, i.e., + replace all backslashes with "\\", then replace all newlines with + "\n", then fold long lines. + + Support for this property is OPTIONAL, but implementations of this + specification MUST preserve instances of this property when + propagating vCards. + + See [RFC6351] for more information on the intended use of this + property. + + ABNF: + + XML-param = "VALUE=text" / altid-param + XML-value = text + +6.2. Identification Properties + + These types are used to capture information associated with the + identification and naming of the entity associated with the vCard. + +6.2.1. FN + + Purpose: To specify the formatted text corresponding to the name of + the object the vCard represents. + + Value type: A single text value. + + Cardinality: 1* + + Special notes: This property is based on the semantics of the X.520 + Common Name attribute [CCITT.X520.1988]. The property MUST be + present in the vCard object. + + ABNF: + + FN-param = "VALUE=text" / type-param / language-param / altid-param + / pid-param / pref-param / any-param + FN-value = text + + Example: + + FN:Mr. John Q. Public\, Esq. + + + +Perreault Standards Track [Page 28] + +RFC 6350 vCard August 2011 + + +6.2.2. N + + Purpose: To specify the components of the name of the object the + vCard represents. + + Value type: A single structured text value. Each component can have + multiple values. + + Cardinality: *1 + + Special note: The structured property value corresponds, in + sequence, to the Family Names (also known as surnames), Given + Names, Additional Names, Honorific Prefixes, and Honorific + Suffixes. The text components are separated by the SEMICOLON + character (U+003B). Individual text components can include + multiple text values separated by the COMMA character (U+002C). + This property is based on the semantics of the X.520 individual + name attributes [CCITT.X520.1988]. The property SHOULD be present + in the vCard object when the name of the object the vCard + represents follows the X.520 model. + + The SORT-AS parameter MAY be applied to this property. + + ABNF: + + N-param = "VALUE=text" / sort-as-param / language-param + / altid-param / any-param + N-value = list-component 4(";" list-component) + + Examples: + + N:Public;John;Quinlan;Mr.;Esq. + + N:Stevenson;John;Philip,Paul;Dr.;Jr.,M.D.,A.C.P. + +6.2.3. NICKNAME + + Purpose: To specify the text corresponding to the nickname of the + object the vCard represents. + + Value type: One or more text values separated by a COMMA character + (U+002C). + + Cardinality: * + + + + + + + +Perreault Standards Track [Page 29] + +RFC 6350 vCard August 2011 + + + Special note: The nickname is the descriptive name given instead of + or in addition to the one belonging to the object the vCard + represents. It can also be used to specify a familiar form of a + proper name specified by the FN or N properties. + + ABNF: + + NICKNAME-param = "VALUE=text" / type-param / language-param + / altid-param / pid-param / pref-param / any-param + NICKNAME-value = text-list + + Examples: + + NICKNAME:Robbie + + NICKNAME:Jim,Jimmie + + NICKNAME;TYPE=work:Boss + +6.2.4. PHOTO + + Purpose: To specify an image or photograph information that + annotates some aspect of the object the vCard represents. + + Value type: A single URI. + + Cardinality: * + + ABNF: + + PHOTO-param = "VALUE=uri" / altid-param / type-param + / mediatype-param / pref-param / pid-param / any-param + PHOTO-value = URI + + Examples: + + PHOTO:http://www.example.com/pub/photos/jqpublic.gif + + PHOTO:data:image/jpeg;base64,MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhv + AQEEBQAwdzELMAkGA1UEBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bm + ljYXRpb25zIENvcnBvcmF0aW9uMRwwGgYDVQQLExNJbmZvcm1hdGlvbiBTeXN0 + <...remainder of base64-encoded data...> + +6.2.5. BDAY + + Purpose: To specify the birth date of the object the vCard + represents. + + + + +Perreault Standards Track [Page 30] + +RFC 6350 vCard August 2011 + + + Value type: The default is a single date-and-or-time value. It can + also be reset to a single text value. + + Cardinality: *1 + + ABNF: + + BDAY-param = BDAY-param-date / BDAY-param-text + BDAY-value = date-and-or-time / text + ; Value and parameter MUST match. + + BDAY-param-date = "VALUE=date-and-or-time" + BDAY-param-text = "VALUE=text" / language-param + + BDAY-param =/ altid-param / calscale-param / any-param + ; calscale-param can only be present when BDAY-value is + ; date-and-or-time and actually contains a date or date-time. + + Examples: + + BDAY:19960415 + BDAY:--0415 + BDAY;19531015T231000Z + BDAY;VALUE=text:circa 1800 + +6.2.6. ANNIVERSARY + + Purpose: The date of marriage, or equivalent, of the object the + vCard represents. + + Value type: The default is a single date-and-or-time value. It can + also be reset to a single text value. + + Cardinality: *1 + + ABNF: + + ANNIVERSARY-param = "VALUE=" ("date-and-or-time" / "text") + ANNIVERSARY-value = date-and-or-time / text + ; Value and parameter MUST match. + + ANNIVERSARY-param =/ altid-param / calscale-param / any-param + ; calscale-param can only be present when ANNIVERSARY-value is + ; date-and-or-time and actually contains a date or date-time. + + Examples: + + ANNIVERSARY:19960415 + + + +Perreault Standards Track [Page 31] + +RFC 6350 vCard August 2011 + + +6.2.7. GENDER + + Purpose: To specify the components of the sex and gender identity of + the object the vCard represents. + + Value type: A single structured value with two components. Each + component has a single text value. + + Cardinality: *1 + + Special notes: The components correspond, in sequence, to the sex + (biological), and gender identity. Each component is optional. + + Sex component: A single letter. M stands for "male", F stands + for "female", O stands for "other", N stands for "none or not + applicable", U stands for "unknown". + + Gender identity component: Free-form text. + + ABNF: + + GENDER-param = "VALUE=text" / any-param + GENDER-value = sex [";" text] + + sex = "" / "M" / "F" / "O" / "N" / "U" + + Examples: + + GENDER:M + GENDER:F + GENDER:M;Fellow + GENDER:F;grrrl + GENDER:O;intersex + GENDER:;it's complicated + +6.3. Delivery Addressing Properties + + These types are concerned with information related to the delivery + addressing or label for the vCard object. + +6.3.1. ADR + + Purpose: To specify the components of the delivery address for the + vCard object. + + Value type: A single structured text value, separated by the + SEMICOLON character (U+003B). + + + + +Perreault Standards Track [Page 32] + +RFC 6350 vCard August 2011 + + + Cardinality: * + + Special notes: The structured type value consists of a sequence of + address components. The component values MUST be specified in + their corresponding position. The structured type value + corresponds, in sequence, to + the post office box; + the extended address (e.g., apartment or suite number); + the street address; + the locality (e.g., city); + the region (e.g., state or province); + the postal code; + the country name (full name in the language specified in + Section 5.1). + + When a component value is missing, the associated component + separator MUST still be specified. + + Experience with vCard 3 has shown that the first two components + (post office box and extended address) are plagued with many + interoperability issues. To ensure maximal interoperability, + their values SHOULD be empty. + + The text components are separated by the SEMICOLON character + (U+003B). Where it makes semantic sense, individual text + components can include multiple text values (e.g., a "street" + component with multiple lines) separated by the COMMA character + (U+002C). + + The property can include the "PREF" parameter to indicate the + preferred delivery address when more than one address is + specified. + + The GEO and TZ parameters MAY be used with this property. + + The property can also include a "LABEL" parameter to present a + delivery address label for the address. Its value is a plain-text + string representing the formatted address. Newlines are encoded + as \n, as they are for property values. + + ABNF: + + label-param = "LABEL=" param-value + + ADR-param = "VALUE=text" / label-param / language-param + / geo-parameter / tz-parameter / altid-param / pid-param + / pref-param / type-param / any-param + + + + +Perreault Standards Track [Page 33] + +RFC 6350 vCard August 2011 + + + ADR-value = ADR-component-pobox ";" ADR-component-ext ";" + ADR-component-street ";" ADR-component-locality ";" + ADR-component-region ";" ADR-component-code ";" + ADR-component-country + ADR-component-pobox = list-component + ADR-component-ext = list-component + ADR-component-street = list-component + ADR-component-locality = list-component + ADR-component-region = list-component + ADR-component-code = list-component + ADR-component-country = list-component + + Example: In this example, the post office box and the extended + address are absent. + + ADR;GEO="geo:12.3457,78.910";LABEL="Mr. John Q. Public, Esq.\n + Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\n + U.S.A.":;;123 Main Street;Any Town;CA;91921-1234;U.S.A. + +6.4. Communications Properties + + These properties describe information about how to communicate with + the object the vCard represents. + +6.4.1. TEL + + Purpose: To specify the telephone number for telephony communication + with the object the vCard represents. + + Value type: By default, it is a single free-form text value (for + backward compatibility with vCard 3), but it SHOULD be reset to a + URI value. It is expected that the URI scheme will be "tel", as + specified in [RFC3966], but other schemes MAY be used. + + Cardinality: * + + Special notes: This property is based on the X.520 Telephone Number + attribute [CCITT.X520.1988]. + + The property can include the "PREF" parameter to indicate a + preferred-use telephone number. + + The property can include the parameter "TYPE" to specify intended + use for the telephone number. The predefined values for the TYPE + parameter are: + + + + + + +Perreault Standards Track [Page 34] + +RFC 6350 vCard August 2011 + + + +-----------+-------------------------------------------------------+ + | Value | Description | + +-----------+-------------------------------------------------------+ + | text | Indicates that the telephone number supports text | + | | messages (SMS). | + | voice | Indicates a voice telephone number. | + | fax | Indicates a facsimile telephone number. | + | cell | Indicates a cellular or mobile telephone number. | + | video | Indicates a video conferencing telephone number. | + | pager | Indicates a paging device telephone number. | + | textphone | Indicates a telecommunication device for people with | + | | hearing or speech difficulties. | + +-----------+-------------------------------------------------------+ + + The default type is "voice". These type parameter values can be + specified as a parameter list (e.g., TYPE=text;TYPE=voice) or as a + value list (e.g., TYPE="text,voice"). The default can be + overridden to another set of values by specifying one or more + alternate values. For example, the default TYPE of "voice" can be + reset to a VOICE and FAX telephone number by the value list + TYPE="voice,fax". + + If this property's value is a URI that can also be used for + instant messaging, the IMPP (Section 6.4.3) property SHOULD be + used in addition to this property. + + ABNF: + + TEL-param = TEL-text-param / TEL-uri-param + TEL-value = TEL-text-value / TEL-uri-value + ; Value and parameter MUST match. + + TEL-text-param = "VALUE=text" + TEL-text-value = text + + TEL-uri-param = "VALUE=uri" / mediatype-param + TEL-uri-value = URI + + TEL-param =/ type-param / pid-param / pref-param / altid-param + / any-param + + type-param-tel = "text" / "voice" / "fax" / "cell" / "video" + / "pager" / "textphone" / iana-token / x-name + ; type-param-tel MUST NOT be used with a property other than TEL. + + + + + + + +Perreault Standards Track [Page 35] + +RFC 6350 vCard August 2011 + + + Example: + + TEL;VALUE=uri;PREF=1;TYPE="voice,home":tel:+1-555-555-5555;ext=5555 + TEL;VALUE=uri;TYPE=home:tel:+33-01-23-45-67 + +6.4.2. EMAIL + + Purpose: To specify the electronic mail address for communication + with the object the vCard represents. + + Value type: A single text value. + + Cardinality: * + + Special notes: The property can include tye "PREF" parameter to + indicate a preferred-use email address when more than one is + specified. + + Even though the value is free-form UTF-8 text, it is likely to be + interpreted by a Mail User Agent (MUA) as an "addr-spec", as + defined in [RFC5322], Section 3.4.1. Readers should also be aware + of the current work toward internationalized email addresses + [RFC5335bis]. + + ABNF: + + EMAIL-param = "VALUE=text" / pid-param / pref-param / type-param + / altid-param / any-param + EMAIL-value = text + + Example: + + EMAIL;TYPE=work:jqpublic@xyz.example.com + + EMAIL;PREF=1:jane_doe@example.com + +6.4.3. IMPP + + Purpose: To specify the URI for instant messaging and presence + protocol communications with the object the vCard represents. + + Value type: A single URI. + + Cardinality: * + + Special notes: The property may include the "PREF" parameter to + indicate that this is a preferred address and has the same + semantics as the "PREF" parameter in a TEL property. + + + +Perreault Standards Track [Page 36] + +RFC 6350 vCard August 2011 + + + If this property's value is a URI that can be used for voice + and/or video, the TEL property (Section 6.4.1) SHOULD be used in + addition to this property. + + This property is adapted from [RFC4770], which is made obsolete by + this document. + + ABNF: + + IMPP-param = "VALUE=uri" / pid-param / pref-param / type-param + / mediatype-param / altid-param / any-param + IMPP-value = URI + + Example: + + IMPP;PREF=1:xmpp:alice@example.com + +6.4.4. LANG + + Purpose: To specify the language(s) that may be used for contacting + the entity associated with the vCard. + + Value type: A single language-tag value. + + Cardinality: * + + ABNF: + + LANG-param = "VALUE=language-tag" / pid-param / pref-param + / altid-param / type-param / any-param + LANG-value = Language-Tag + + Example: + + LANG;TYPE=work;PREF=1:en + LANG;TYPE=work;PREF=2:fr + LANG;TYPE=home:fr + +6.5. Geographical Properties + + These properties are concerned with information associated with + geographical positions or regions associated with the object the + vCard represents. + +6.5.1. TZ + + Purpose: To specify information related to the time zone of the + object the vCard represents. + + + +Perreault Standards Track [Page 37] + +RFC 6350 vCard August 2011 + + + Value type: The default is a single text value. It can also be + reset to a single URI or utc-offset value. + + Cardinality: * + + Special notes: It is expected that names from the public-domain + Olson database [TZ-DB] will be used, but this is not a + restriction. See also [IANA-TZ]. + + Efforts are currently being directed at creating a standard URI + scheme for expressing time zone information. Usage of such a + scheme would ensure a high level of interoperability between + implementations that support it. + + Note that utc-offset values SHOULD NOT be used because the UTC + offset varies with time -- not just because of the usual daylight + saving time shifts that occur in may regions, but often entire + regions will "re-base" their overall offset. The actual offset + may be +/- 1 hour (or perhaps a little more) than the one given. + + ABNF: + + TZ-param = "VALUE=" ("text" / "uri" / "utc-offset") + TZ-value = text / URI / utc-offset + ; Value and parameter MUST match. + + TZ-param =/ altid-param / pid-param / pref-param / type-param + / mediatype-param / any-param + + Examples: + + TZ:Raleigh/North America + + TZ;VALUE=utc-offset:-0500 + ; Note: utc-offset format is NOT RECOMMENDED. + +6.5.2. GEO + + Purpose: To specify information related to the global positioning of + the object the vCard represents. + + Value type: A single URI. + + Cardinality: * + + Special notes: The "geo" URI scheme [RFC5870] is particularly well + suited for this property, but other schemes MAY be used. + + + + +Perreault Standards Track [Page 38] + +RFC 6350 vCard August 2011 + + + ABNF: + + GEO-param = "VALUE=uri" / pid-param / pref-param / type-param + / mediatype-param / altid-param / any-param + GEO-value = URI + + Example: + + GEO:geo:37.386013,-122.082932 + +6.6. Organizational Properties + + These properties are concerned with information associated with + characteristics of the organization or organizational units of the + object that the vCard represents. + +6.6.1. TITLE + + Purpose: To specify the position or job of the object the vCard + represents. + + Value type: A single text value. + + Cardinality: * + + Special notes: This property is based on the X.520 Title attribute + [CCITT.X520.1988]. + + ABNF: + + TITLE-param = "VALUE=text" / language-param / pid-param + / pref-param / altid-param / type-param / any-param + TITLE-value = text + + Example: + + TITLE:Research Scientist + +6.6.2. ROLE + + Purpose: To specify the function or part played in a particular + situation by the object the vCard represents. + + Value type: A single text value. + + Cardinality: * + + + + + +Perreault Standards Track [Page 39] + +RFC 6350 vCard August 2011 + + + Special notes: This property is based on the X.520 Business Category + explanatory attribute [CCITT.X520.1988]. This property is + included as an organizational type to avoid confusion with the + semantics of the TITLE property and incorrect usage of that + property when the semantics of this property is intended. + + ABNF: + + ROLE-param = "VALUE=text" / language-param / pid-param / pref-param + / type-param / altid-param / any-param + ROLE-value = text + + Example: + + ROLE:Project Leader + +6.6.3. LOGO + + Purpose: To specify a graphic image of a logo associated with the + object the vCard represents. + + Value type: A single URI. + + Cardinality: * + + ABNF: + + LOGO-param = "VALUE=uri" / language-param / pid-param / pref-param + / type-param / mediatype-param / altid-param / any-param + LOGO-value = URI + + Examples: + + LOGO:http://www.example.com/pub/logos/abccorp.jpg + + LOGO:data:image/jpeg;base64,MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvc + AQEEBQAwdzELMAkGA1UEBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bm + ljYXRpb25zIENvcnBvcmF0aW9uMRwwGgYDVQQLExNJbmZvcm1hdGlvbiBTeXN0 + <...the remainder of base64-encoded data...> + +6.6.4. ORG + + Purpose: To specify the organizational name and units associated + with the vCard. + + Value type: A single structured text value consisting of components + separated by the SEMICOLON character (U+003B). + + + + +Perreault Standards Track [Page 40] + +RFC 6350 vCard August 2011 + + + Cardinality: * + + Special notes: The property is based on the X.520 Organization Name + and Organization Unit attributes [CCITT.X520.1988]. The property + value is a structured type consisting of the organization name, + followed by zero or more levels of organizational unit names. + + The SORT-AS parameter MAY be applied to this property. + + ABNF: + + ORG-param = "VALUE=text" / sort-as-param / language-param + / pid-param / pref-param / altid-param / type-param + / any-param + ORG-value = component *(";" component) + + Example: A property value consisting of an organizational name, + organizational unit #1 name, and organizational unit #2 name. + + ORG:ABC\, Inc.;North American Division;Marketing + +6.6.5. MEMBER + + Purpose: To include a member in the group this vCard represents. + + Value type: A single URI. It MAY refer to something other than a + vCard object. For example, an email distribution list could + employ the "mailto" URI scheme [RFC6068] for efficiency. + + Cardinality: * + + Special notes: This property MUST NOT be present unless the value of + the KIND property is "group". + + ABNF: + + MEMBER-param = "VALUE=uri" / pid-param / pref-param / altid-param + / mediatype-param / any-param + MEMBER-value = URI + + + + + + + + + + + + +Perreault Standards Track [Page 41] + +RFC 6350 vCard August 2011 + + + Examples: + + BEGIN:VCARD + VERSION:4.0 + KIND:group + FN:The Doe family + MEMBER:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af + MEMBER:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519 + END:VCARD + BEGIN:VCARD + VERSION:4.0 + FN:John Doe + UID:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af + END:VCARD + BEGIN:VCARD + VERSION:4.0 + FN:Jane Doe + UID:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519 + END:VCARD + + BEGIN:VCARD + VERSION:4.0 + KIND:group + FN:Funky distribution list + MEMBER:mailto:subscriber1@example.com + MEMBER:xmpp:subscriber2@example.com + MEMBER:sip:subscriber3@example.com + MEMBER:tel:+1-418-555-5555 + END:VCARD + +6.6.6. RELATED + + Purpose: To specify a relationship between another entity and the + entity represented by this vCard. + + Value type: A single URI. It can also be reset to a single text + value. The text value can be used to specify textual information. + + Cardinality: * + + Special notes: The TYPE parameter MAY be used to characterize the + related entity. It contains a comma-separated list of values that + are registered with IANA as described in Section 10.2. The + registry is pre-populated with the values defined in [xfn]. This + document also specifies two additional values: + + agent: an entity who may sometimes act on behalf of the entity + associated with the vCard. + + + +Perreault Standards Track [Page 42] + +RFC 6350 vCard August 2011 + + + emergency: indicates an emergency contact + + ABNF: + + RELATED-param = RELATED-param-uri / RELATED-param-text + RELATED-value = URI / text + ; Parameter and value MUST match. + + RELATED-param-uri = "VALUE=uri" / mediatype-param + RELATED-param-text = "VALUE=text" / language-param + + RELATED-param =/ pid-param / pref-param / altid-param / type-param + / any-param + + type-param-related = related-type-value *("," related-type-value) + ; type-param-related MUST NOT be used with a property other than + ; RELATED. + + related-type-value = "contact" / "acquaintance" / "friend" / "met" + / "co-worker" / "colleague" / "co-resident" + / "neighbor" / "child" / "parent" + / "sibling" / "spouse" / "kin" / "muse" + / "crush" / "date" / "sweetheart" / "me" + / "agent" / "emergency" + + Examples: + + RELATED;TYPE=friend:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 + RELATED;TYPE=contact:http://example.com/directory/jdoe.vcf + RELATED;TYPE=co-worker;VALUE=text:Please contact my assistant Jane + Doe for any inquiries. + +6.7. Explanatory Properties + + These properties are concerned with additional explanations, such as + that related to informational notes or revisions specific to the + vCard. + +6.7.1. CATEGORIES + + Purpose: To specify application category information about the + vCard, also known as "tags". + + Value type: One or more text values separated by a COMMA character + (U+002C). + + Cardinality: * + + + + +Perreault Standards Track [Page 43] + +RFC 6350 vCard August 2011 + + + ABNF: + + CATEGORIES-param = "VALUE=text" / pid-param / pref-param + / type-param / altid-param / any-param + CATEGORIES-value = text-list + + Example: + + CATEGORIES:TRAVEL AGENT + + CATEGORIES:INTERNET,IETF,INDUSTRY,INFORMATION TECHNOLOGY + +6.7.2. NOTE + + Purpose: To specify supplemental information or a comment that is + associated with the vCard. + + Value type: A single text value. + + Cardinality: * + + Special notes: The property is based on the X.520 Description + attribute [CCITT.X520.1988]. + + ABNF: + + NOTE-param = "VALUE=text" / language-param / pid-param / pref-param + / type-param / altid-param / any-param + NOTE-value = text + + Example: + + NOTE:This fax number is operational 0800 to 1715 + EST\, Mon-Fri. + +6.7.3. PRODID + + Purpose: To specify the identifier for the product that created the + vCard object. + + Type value: A single text value. + + Cardinality: *1 + + Special notes: Implementations SHOULD use a method such as that + specified for Formal Public Identifiers in [ISO9070] or for + Universal Resource Names in [RFC3406] to ensure that the text + value is unique. + + + +Perreault Standards Track [Page 44] + +RFC 6350 vCard August 2011 + + + ABNF: + + PRODID-param = "VALUE=text" / any-param + PRODID-value = text + + Example: + + PRODID:-//ONLINE DIRECTORY//NONSGML Version 1//EN + +6.7.4. REV + + Purpose: To specify revision information about the current vCard. + + Value type: A single timestamp value. + + Cardinality: *1 + + Special notes: The value distinguishes the current revision of the + information in this vCard for other renditions of the information. + + ABNF: + + REV-param = "VALUE=timestamp" / any-param + REV-value = timestamp + + Example: + + REV:19951031T222710Z + +6.7.5. SOUND + + Purpose: To specify a digital sound content information that + annotates some aspect of the vCard. This property is often used + to specify the proper pronunciation of the name property value of + the vCard. + + Value type: A single URI. + + Cardinality: * + + ABNF: + + SOUND-param = "VALUE=uri" / language-param / pid-param / pref-param + / type-param / mediatype-param / altid-param + / any-param + SOUND-value = URI + + + + + +Perreault Standards Track [Page 45] + +RFC 6350 vCard August 2011 + + + Example: + + SOUND:CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com + + SOUND:data:audio/basic;base64,MIICajCCAdOgAwIBAgICBEUwDQYJKoZIh + AQEEBQAwdzELMAkGA1UEBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bm + ljYXRpb25zIENvcnBvcmF0aW9uMRwwGgYDVQQLExNJbmZvcm1hdGlvbiBTeXN0 + <...the remainder of base64-encoded data...> + +6.7.6. UID + + Purpose: To specify a value that represents a globally unique + identifier corresponding to the entity associated with the vCard. + + Value type: A single URI value. It MAY also be reset to free-form + text. + + Cardinality: *1 + + Special notes: This property is used to uniquely identify the object + that the vCard represents. The "uuid" URN namespace defined in + [RFC4122] is particularly well suited to this task, but other URI + schemes MAY be used. Free-form text MAY also be used. + + ABNF: + + UID-param = UID-uri-param / UID-text-param + UID-value = UID-uri-value / UID-text-value + ; Value and parameter MUST match. + + UID-uri-param = "VALUE=uri" + UID-uri-value = URI + + UID-text-param = "VALUE=text" + UID-text-value = text + + UID-param =/ any-param + + Example: + + UID:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 + + + + + + + + + + +Perreault Standards Track [Page 46] + +RFC 6350 vCard August 2011 + + +6.7.7. CLIENTPIDMAP + + Purpose: To give a global meaning to a local PID source identifier. + + Value type: A semicolon-separated pair of values. The first field + is a small integer corresponding to the second field of a PID + parameter instance. The second field is a URI. The "uuid" URN + namespace defined in [RFC4122] is particularly well suited to this + task, but other URI schemes MAY be used. + + Cardinality: * + + Special notes: PID source identifiers (the source identifier is the + second field in a PID parameter instance) are small integers that + only have significance within the scope of a single vCard + instance. Each distinct source identifier present in a vCard MUST + have an associated CLIENTPIDMAP. See Section 7 for more details + on the usage of CLIENTPIDMAP. + + PID source identifiers MUST be strictly positive. Zero is not + allowed. + + As a special exception, the PID parameter MUST NOT be applied to + this property. + + ABNF: + + CLIENTPIDMAP-param = any-param + CLIENTPIDMAP-value = 1*DIGIT ";" URI + + Example: + + TEL;PID=3.1,4.2;VALUE=uri:tel:+1-555-555-5555 + EMAIL;PID=4.1,5.2:jdoe@example.com + CLIENTPIDMAP:1;urn:uuid:3df403f4-5924-4bb7-b077-3c711d9eb34b + CLIENTPIDMAP:2;urn:uuid:d89c9c7a-2e1b-4832-82de-7e992d95faa5 + +6.7.8. URL + + Purpose: To specify a uniform resource locator associated with the + object to which the vCard refers. Examples for individuals + include personal web sites, blogs, and social networking site + identifiers. + + Cardinality: * + + Value type: A single uri value. + + + + +Perreault Standards Track [Page 47] + +RFC 6350 vCard August 2011 + + + ABNF: + + URL-param = "VALUE=uri" / pid-param / pref-param / type-param + / mediatype-param / altid-param / any-param + URL-value = URI + + Example: + + URL:http://example.org/restaurant.french/~chezchic.html + +6.7.9. VERSION + + Purpose: To specify the version of the vCard specification used to + format this vCard. + + Value type: A single text value. + + Cardinality: 1 + + Special notes: This property MUST be present in the vCard object, + and it must appear immediately after BEGIN:VCARD. The value MUST + be "4.0" if the vCard corresponds to this specification. Note + that earlier versions of vCard allowed this property to be placed + anywhere in the vCard object, or even to be absent. + + ABNF: + + VERSION-param = "VALUE=text" / any-param + VERSION-value = "4.0" + + Example: + + VERSION:4.0 + +6.8. Security Properties + + These properties are concerned with the security of communication + pathways or access to the vCard. + +6.8.1. KEY + + Purpose: To specify a public key or authentication certificate + associated with the object that the vCard represents. + + Value type: A single URI. It can also be reset to a text value. + + Cardinality: * + + + + +Perreault Standards Track [Page 48] + +RFC 6350 vCard August 2011 + + + ABNF: + + KEY-param = KEY-uri-param / KEY-text-param + KEY-value = KEY-uri-value / KEY-text-value + ; Value and parameter MUST match. + + KEY-uri-param = "VALUE=uri" / mediatype-param + KEY-uri-value = URI + + KEY-text-param = "VALUE=text" + KEY-text-value = text + + KEY-param =/ altid-param / pid-param / pref-param / type-param + / any-param + + Examples: + + KEY:http://www.example.com/keys/jdoe.cer + + KEY;MEDIATYPE=application/pgp-keys:ftp://example.com/keys/jdoe + + KEY:data:application/pgp-keys;base64,MIICajCCAdOgAwIBAgICBE + UwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1UEBhMCVVMxLDAqBgNVBAoTI05l + <... remainder of base64-encoded data ...> + +6.9. Calendar Properties + + These properties are further specified in [RFC2739]. + +6.9.1. FBURL + + Purpose: To specify the URI for the busy time associated with the + object that the vCard represents. + + Value type: A single URI value. + + Cardinality: * + + Special notes: Where multiple FBURL properties are specified, the + default FBURL property is indicated with the PREF parameter. The + FTP [RFC1738] or HTTP [RFC2616] type of URI points to an iCalendar + [RFC5545] object associated with a snapshot of the next few weeks + or months of busy time data. If the iCalendar object is + represented as a file or document, its file extension should be + ".ifb". + + + + + + +Perreault Standards Track [Page 49] + +RFC 6350 vCard August 2011 + + + ABNF: + + FBURL-param = "VALUE=uri" / pid-param / pref-param / type-param + / mediatype-param / altid-param / any-param + FBURL-value = URI + + Examples: + + FBURL;PREF=1:http://www.example.com/busy/janedoe + FBURL;MEDIATYPE=text/calendar:ftp://example.com/busy/project-a.ifb + +6.9.2. CALADRURI + + Purpose: To specify the calendar user address [RFC5545] to which a + scheduling request [RFC5546] should be sent for the object + represented by the vCard. + + Value type: A single URI value. + + Cardinality: * + + Special notes: Where multiple CALADRURI properties are specified, + the default CALADRURI property is indicated with the PREF + parameter. + + ABNF: + + CALADRURI-param = "VALUE=uri" / pid-param / pref-param / type-param + / mediatype-param / altid-param / any-param + CALADRURI-value = URI + + Example: + + CALADRURI;PREF=1:mailto:janedoe@example.com + CALADRURI:http://example.com/calendar/jdoe + +6.9.3. CALURI + + Purpose: To specify the URI for a calendar associated with the + object represented by the vCard. + + Value type: A single URI value. + + Cardinality: * + + Special notes: Where multiple CALURI properties are specified, the + default CALURI property is indicated with the PREF parameter. The + property should contain a URI pointing to an iCalendar [RFC5545] + + + +Perreault Standards Track [Page 50] + +RFC 6350 vCard August 2011 + + + object associated with a snapshot of the user's calendar store. + If the iCalendar object is represented as a file or document, its + file extension should be ".ics". + + ABNF: + + CALURI-param = "VALUE=uri" / pid-param / pref-param / type-param + / mediatype-param / altid-param / any-param + CALURI-value = URI + + Examples: + + CALURI;PREF=1:http://cal.example.com/calA + CALURI;MEDIATYPE=text/calendar:ftp://ftp.example.com/calA.ics + +6.10. Extended Properties and Parameters + + The properties and parameters defined by this document can be + extended. Non-standard, private properties and parameters with a + name starting with "X-" may be defined bilaterally between two + cooperating agents without outside registration or standardization. + +7. Synchronization + + vCard data often needs to be synchronized between devices. In this + context, synchronization is defined as the intelligent merging of two + representations of the same object. vCard 4.0 includes mechanisms to + aid this process. + +7.1. Mechanisms + + Two mechanisms are available: the UID property is used to match + multiple instances of the same vCard, while the PID parameter is used + to match multiple instances of the same property. + + The term "matching" is used here to mean recognizing that two + instances are in fact representations of the same object. For + example, a single vCard that is shared with someone results in two + vCard instances. After they have evolved separately, they still + represent the same object, and therefore may be matched by a + synchronization engine. + +7.1.1. Matching vCard Instances + + vCard instances for which the UID properties (Section 6.7.6) are + equivalent MUST be matched. Equivalence is determined as specified + in [RFC3986], Section 6. + + + + +Perreault Standards Track [Page 51] + +RFC 6350 vCard August 2011 + + + In all other cases, vCard instances MAY be matched at the discretion + of the synchronization engine. + +7.1.2. Matching Property Instances + + Property instances belonging to unmatched vCards MUST NOT be matched. + + Property instances whose name (e.g., EMAIL, TEL, etc.) is not the + same MUST NOT be matched. + + Property instances whose name is CLIENTPIDMAP are handled separately + and MUST NOT be matched. The synchronization MUST ensure that there + is consistency of CLIENTPIDMAPs among matched vCard instances. + + Property instances belonging to matched vCards, whose name is the + same, and whose maximum cardinality is 1, MUST be matched. + + Property instances belonging to matched vCards, whose name is the + same, and whose PID parameters match, MUST be matched. See + Section 7.1.3 for details on PID matching. + + In all other cases, property instances MAY be matched at the + discretion of the synchronization engine. + +7.1.3. PID Matching + + Two PID values for which the first fields are equivalent represent + the same local value. + + Two PID values representing the same local value and for which the + second fields point to CLIENTPIDMAP properties whose second field + URIs are equivalent (as specified in [RFC3986], Section 6) also + represent the same global value. + + PID parameters for which at least one pair of their values represent + the same global value MUST be matched. + + In all other cases, PID parameters MAY be matched at the discretion + of the synchronization engine. + + For example, PID value "5.1", in the first vCard below, and PID value + "5.2", in the second vCard below, represent the same global value. + + + + + + + + + +Perreault Standards Track [Page 52] + +RFC 6350 vCard August 2011 + + + BEGIN:VCARD + VERSION:4.0 + EMAIL;PID=4.2,5.1:jdoe@example.com + CLIENTPIDMAP:1;urn:uuid:3eef374e-7179-4196-a914-27358c3e6527 + CLIENTPIDMAP:2;urn:uuid:42bcd5a7-1699-4514-87b4-056edf68e9cc + END:VCARD + + BEGIN:VCARD + VERSION:4.0 + EMAIL;PID=5.1,5.2:john@example.com + CLIENTPIDMAP:1;urn:uuid:0c75c629-6a8d-4d5e-a07f-1bb35846854d + CLIENTPIDMAP:2;urn:uuid:3eef374e-7179-4196-a914-27358c3e6527 + END:VCARD + +7.2. Example + +7.2.1. Creation + + The following simple vCard is first created on a given device. + + BEGIN:VCARD + VERSION:4.0 + UID:urn:uuid:4fbe8971-0bc3-424c-9c26-36c3e1eff6b1 + FN;PID=1.1:J. Doe + N:Doe;J.;;; + EMAIL;PID=1.1:jdoe@example.com + CLIENTPIDMAP:1;urn:uuid:53e374d9-337e-4727-8803-a1e9c14e0556 + END:VCARD + + This new vCard is assigned the UID + "urn:uuid:4fbe8971-0bc3-424c-9c26-36c3e1eff6b1" by the creating + device. The FN and EMAIL properties are assigned the same local + value of 1, and this value is given global context by associating it + with "urn:uuid:53e374d9-337e-4727-8803-a1e9c14e0556", which + represents the creating device. We are at liberty to reuse the same + local value since instances of different properties will never be + matched. The N property has no PID because it is forbidden by its + maximum cardinality of 1. + +7.2.2. Initial Sharing + + This vCard is shared with a second device. Upon inspecting the UID + property, the second device understands that this is a new vCard + (i.e., unmatched) and thus the synchronization results in a simple + copy. + + + + + + +Perreault Standards Track [Page 53] + +RFC 6350 vCard August 2011 + + +7.2.3. Adding and Sharing a Property + + A new phone number is created on the first device, then the vCard is + shared with the second device. This is what the second device + receives: + + BEGIN:VCARD + VERSION:4.0 + UID:urn:uuid:4fbe8971-0bc3-424c-9c26-36c3e1eff6b1 + FN;PID=1.1:J. Doe + N:Doe;J.;;; + EMAIL;PID=1.1:jdoe@example.com + TEL;PID=1.1;VALUE=uri:tel:+1-555-555-5555 + CLIENTPIDMAP:1;urn:uuid:53e374d9-337e-4727-8803-a1e9c14e0556 + END:VCARD + + Upon inspecting the UID property, the second device matches the vCard + it received to the vCard that it already has stored. It then starts + comparing the properties of the two vCards in same-named pairs. + + The FN properties are matched because the PID parameters have the + same global value. Since the property value is the same, no update + takes place. + + The N properties are matched automatically because their maximum + cardinality is 1. Since the property value is the same, no update + takes place. + + The EMAIL properties are matched because the PID parameters have the + same global value. Since the property value is the same, no update + takes place. + + The TEL property in the new vCard is not matched to any in the stored + vCard because no property in the stored vCard has the same name. + Therefore, this property is copied from the new vCard to the stored + vCard. + + The CLIENTPIDMAP property is handled separately by the + synchronization engine. It ensures that it is consistent with the + stored one. If it was not, the results would be up to the + synchronization engine, and thus undefined by this document. + +7.2.4. Simultaneous Editing + + A new email address and a new phone number are added to the vCard on + each of the two devices, and then a new synchronization event + happens. Here are the vCards that are communicated to each other: + + + + +Perreault Standards Track [Page 54] + +RFC 6350 vCard August 2011 + + + BEGIN:VCARD + VERSION:4.0 + UID:urn:uuid:4fbe8971-0bc3-424c-9c26-36c3e1eff6b1 + FN;PID=1.1:J. Doe + N:Doe;J.;;; + EMAIL;PID=1.1:jdoe@example.com + EMAIL;PID=2.1:boss@example.com + TEL;PID=1.1;VALUE=uri:tel:+1-555-555-5555 + TEL;PID=2.1;VALUE=uri:tel:+1-666-666-6666 + CLIENTPIDMAP:1;urn:uuid:53e374d9-337e-4727-8803-a1e9c14e0556 + END:VCARD + + BEGIN:VCARD + VERSION:4.0 + UID:urn:uuid:4fbe8971-0bc3-424c-9c26-36c3e1eff6b1 + FN;PID=1.1:J. Doe + N:Doe;J.;;; + EMAIL;PID=1.1:jdoe@example.com + EMAIL;PID=2.2:ceo@example.com + TEL;PID=1.1;VALUE=uri:tel:+1-555-555-5555 + TEL;PID=2.2;VALUE=uri:tel:+1-666-666-6666 + CLIENTPIDMAP:1;urn:uuid:53e374d9-337e-4727-8803-a1e9c14e0556 + CLIENTPIDMAP:2;urn:uuid:1f762d2b-03c4-4a83-9a03-75ff658a6eee + END:VCARD + + On the first device, the same PID source identifier (1) is reused for + the new EMAIL and TEL properties. On the second device, a new source + identifier (2) is generated, and a corresponding CLIENTPIDMAP + property is created. It contains the second device's identifier, + "urn:uuid:1f762d2b-03c4-4a83-9a03-75ff658a6eee". + + The new EMAIL properties are unmatched on both sides since the PID + global value is new in both cases. The sync thus results in a copy + on both sides. + + Although the situation appears to be the same for the TEL properties, + in this case, the synchronization engine is particularly smart and + matches the two new TEL properties even though their PID global + values are different. Note that in this case, the rules of + Section 7.1.2 state that two properties MAY be matched at the + discretion of the synchronization engine. Therefore, the two + properties are merged. + + All this results in the following vCard, which is stored on both + devices: + + + + + + +Perreault Standards Track [Page 55] + +RFC 6350 vCard August 2011 + + + BEGIN:VCARD + VERSION:4.0 + UID:urn:uuid:4fbe8971-0bc3-424c-9c26-36c3e1eff6b1 + FN:J. Doe + N:Doe;J.;;; + EMAIL;PID=1.1:jdoe@example.com + EMAIL;PID=2.1:boss@example.com + EMAIL;PID=2.2:ceo@example.com + TEL;PID=1.1;VALUE=uri:tel:+1-555-555-5555 + TEL;PID=2.1,2.2;VALUE=uri:tel:+1-666-666-6666 + CLIENTPIDMAP:1;urn:uuid:53e374d9-337e-4727-8803-a1e9c14e0556 + CLIENTPIDMAP:2;urn:uuid:1f762d2b-03c4-4a83-9a03-75ff658a6eee + END:VCARD + +7.2.5. Global Context Simplification + + The two devices finish their synchronization procedure by simplifying + their global contexts. Since they haven't talked to any other + device, the following vCard is for all purposes equivalent to the + above. It is also shorter. + + BEGIN:VCARD + VERSION:4.0 + UID:urn:uuid:4fbe8971-0bc3-424c-9c26-36c3e1eff6b1 + FN:J. Doe + N:Doe;J.;;; + EMAIL;PID=1.1:jdoe@example.com + EMAIL;PID=2.1:boss@example.com + EMAIL;PID=3.1:ceo@example.com + TEL;PID=1.1;VALUE=uri:tel:+1-555-555-5555 + TEL;PID=2.1;VALUE=uri:tel:+1-666-666-6666 + CLIENTPIDMAP:1;urn:uuid:53e374d9-337e-4727-8803-a1e9c14e0556 + END:VCARD + + The details of global context simplification are unspecified by this + document. They are left up to the synchronization engine. This + example is merely intended to illustrate the possibility, which + investigating would be, in the author's opinion, worthwhile. + +8. Example: Author's vCard + + BEGIN:VCARD + VERSION:4.0 + FN:Simon Perreault + N:Perreault;Simon;;;ing. jr,M.Sc. + BDAY:--0203 + ANNIVERSARY:20090808T1430-0500 + GENDER:M + + + +Perreault Standards Track [Page 56] + +RFC 6350 vCard August 2011 + + + LANG;PREF=1:fr + 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@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 + +9. Security Considerations + + o Internet mail is often used to transport vCards and is subject to + many well-known security attacks, including monitoring, replay, + and forgery. Care should be taken by any directory service in + allowing information to leave the scope of the service itself, + where any access controls or confidentiality can no longer be + guaranteed. Applications should also take care to display + directory data in a "safe" environment. + + o vCards can carry cryptographic keys or certificates, as described + in Section 6.8.1. + + o vCards often carry information that can be sensitive (e.g., + birthday, address, and phone information). Although vCards have + no inherent authentication or confidentiality provisions, they can + easily be carried by any security mechanism that transfers MIME + objects to address authentication or confidentiality (e.g., S/MIME + [RFC5751], OpenPGP [RFC4880]). In cases where the confidentiality + or authenticity of information contained in vCard is a concern, + the vCard SHOULD be transported using one of these secure + mechanisms. The KEY property (Section 6.8.1) can be used to + transport the public key used by these mechanisms. + + o The information in a vCard may become out of date. In cases where + the vitality of data is important to an originator of a vCard, the + SOURCE property (Section 6.1.3) SHOULD be specified. In addition, + the "REV" type described in Section 6.7.4 can be specified to + indicate the last time that the vCard data was updated. + + o Many vCard properties may be used to transport URIs. Please refer + to [RFC3986], Section 7, for considerations related to URIs. + + + + +Perreault Standards Track [Page 57] + +RFC 6350 vCard August 2011 + + +10. IANA Considerations + +10.1. Media Type Registration + + IANA has registered the following Media Type (in + ) and marked the text/directory Media Type as + DEPRECATED. + + To: ietf-types@iana.org + + Subject: Registration of media type text/vcard + + Type name: text + + Subtype name: vcard + + Required parameters: none + + Optional parameters: version + + The "version" parameter is to be interpreted identically as the + VERSION vCard property. If this parameter is present, all vCards + in a text/vcard body part MUST have a VERSION property with value + identical to that of this MIME parameter. + + "charset": as defined for text/plain [RFC2046]; encodings other + than UTF-8 [RFC3629] MUST NOT be used. + + Encoding considerations: 8bit + + Security considerations: See Section 9. + + Interoperability considerations: The text/vcard media type is + intended to identify vCard data of any version. There are older + specifications of vCard [RFC2426][vCard21] still in common use. + While these formats are similar, they are not strictly compatible. + In general, it is necessary to inspect the value of the VERSION + property (see Section 6.7.9) for identifying the standard to which + a given vCard object conforms. + + In addition, the following media types are known to have been used + to refer to vCard data. They should be considered deprecated in + favor of text/vcard. + + * text/directory + * text/directory; profile=vcard + * text/x-vcard + + + + +Perreault Standards Track [Page 58] + +RFC 6350 vCard August 2011 + + + Published specification: RFC 6350 + + Applications that use this media type: They are numerous, diverse, + and include mail user agents, instant messaging clients, address + book applications, directory servers, and customer relationship + management software. + + Additional information: + + Magic number(s): + + File extension(s): .vcf .vcard + + Macintosh file type code(s): + + Person & email address to contact for further information: vCard + discussion mailing list + + Intended usage: COMMON + + Restrictions on usage: none + + Author: Simon Perreault + + Change controller: IETF + +10.2. Registering New vCard Elements + + This section defines the process for registering new or modified + vCard elements (i.e., properties, parameters, value data types, and + values) with IANA. + +10.2.1. Registration Procedure + + The IETF has created a mailing list, vcarddav@ietf.org, which can be + used for public discussion of vCard element proposals prior to + registration. Use of the mailing list is strongly encouraged. The + IESG has appointed a designated expert who will monitor the + vcarddav@ietf.org mailing list and review registrations. + + Registration of new vCard elements MUST be reviewed by the designated + expert and published in an RFC. A Standards Track RFC is REQUIRED + for the registration of new value data types that modify existing + properties. A Standards Track RFC is also REQUIRED for registration + of vCard elements that modify vCard elements previously documented in + a Standards Track RFC. + + + + + +Perreault Standards Track [Page 59] + +RFC 6350 vCard August 2011 + + + The registration procedure begins when a completed registration + template, defined in the sections below, is sent to vcarddav@ietf.org + and iana@iana.org. Within two weeks, the designated expert is + expected to tell IANA and the submitter of the registration whether + the registration is approved, approved with minor changes, or + rejected with cause. When a registration is rejected with cause, it + can be re-submitted if the concerns listed in the cause are + addressed. Decisions made by the designated expert can be appealed + to the IESG Applications Area Director, then to the IESG. They + follow the normal appeals procedure for IESG decisions. + + Once the registration procedure concludes successfully, IANA creates + or modifies the corresponding record in the vCard registry. The + completed registration template is discarded. + + An RFC specifying new vCard elements MUST include the completed + registration templates, which MAY be expanded with additional + information. These completed templates are intended to go in the + body of the document, not in the IANA Considerations section. + + Finally, note that there is an XML representation for vCard defined + in [RFC6351]. An XML representation SHOULD be defined for new vCard + elements. + +10.2.2. Vendor Namespace + + The vendor namespace is used for vCard elements associated with + commercially available products. "Vendor" or "producer" are + construed as equivalent and very broadly in this context. + + A registration may be placed in the vendor namespace by anyone who + needs to interchange files associated with the particular product. + However, the registration formally belongs to the vendor or + organization handling the vCard elements in the namespace being + registered. Changes to the specification will be made at their + request, as discussed in subsequent sections. + + vCard elements belonging to the vendor namespace will be + distinguished by the "VND-" prefix. This is followed by an IANA- + registered Private Enterprise Number (PEN), a dash, and a vCard + element designation of the vendor's choosing (e.g., "VND-123456- + MUDPIE"). + + While public exposure and review of vCard elements to be registered + in the vendor namespace are not required, using the vcarddav@ietf.org + mailing list for review is strongly encouraged to improve the quality + of those specifications. Registrations in the vendor namespace may + be submitted directly to the IANA. + + + +Perreault Standards Track [Page 60] + +RFC 6350 vCard August 2011 + + +10.2.3. Registration Template for Properties + + A property is defined by completing the following template. + + Namespace: Empty for the global namespace, "VND-NNNN-" for a vendor- + specific property (where NNNN is replaced by the vendor's PEN). + + Property name: The name of the property. + + Purpose: The purpose of the property. Give a short but clear + description. + + Value type: Any of the valid value types for the property value + needs to be specified. The default value type also needs to be + specified. + + Cardinality: See Section 6. + + Property parameters: Any of the valid property parameters for the + property MUST be specified. + + Description: Any special notes about the property, how it is to be + used, etc. + + Format definition: The ABNF for the property definition needs to be + specified. + + Example(s): One or more examples of instances of the property need + to be specified. + +10.2.4. Registration Template for Parameters + + A parameter is defined by completing the following template. + + Namespace: Empty for the global namespace, "VND-NNNN-" for a vendor- + specific property (where NNNN is replaced by the vendor's PEN). + + Parameter name: The name of the parameter. + + Purpose: The purpose of the parameter. Give a short but clear + description. + + Description: Any special notes about the parameter, how it is to be + used, etc. + + Format definition: The ABNF for the parameter definition needs to be + specified. + + + + +Perreault Standards Track [Page 61] + +RFC 6350 vCard August 2011 + + + Example(s): One or more examples of instances of the parameter need + to be specified. + +10.2.5. Registration Template for Value Data Types + + A value data type is defined by completing the following template. + + Value name: The name of the value type. + + Purpose: The purpose of the value type. Give a short but clear + description. + + Description: Any special notes about the value type, how it is to be + used, etc. + + Format definition: The ABNF for the value type definition needs to + be specified. + + Example(s): One or more examples of instances of the value type need + to be specified. + +10.2.6. Registration Template for Values + + A value is defined by completing the following template. + + Value: The value literal. + + Purpose: The purpose of the value. Give a short but clear + description. + + Conformance: The vCard properties and/or parameters that can take + this value needs to be specified. + + Example(s): One or more examples of instances of the value need to + be specified. + + The following is a fictitious example of a registration of a vCard + value: + + Value: supervisor + + Purpose: It means that the related entity is the direct hierarchical + superior (i.e., supervisor or manager) of the entity this vCard + represents. + + Conformance: This value can be used with the "TYPE" parameter + applied on the "RELATED" property. + + + + +Perreault Standards Track [Page 62] + +RFC 6350 vCard August 2011 + + + Example(s): + + RELATED;TYPE=supervisor:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 + +10.3. Initial vCard Elements Registries + + The IANA has created and will maintain the following registries for + vCard elements with pointers to appropriate reference documents. The + registries are grouped together under the heading "vCard Elements". + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Perreault Standards Track [Page 63] + +RFC 6350 vCard August 2011 + + +10.3.1. Properties Registry + + The following table has been used to initialize the properties + registry. + + +-----------+--------------+-------------------------+ + | Namespace | Property | Reference | + +-----------+--------------+-------------------------+ + | | SOURCE | RFC 6350, Section 6.1.3 | + | | KIND | RFC 6350, Section 6.1.4 | + | | XML | RFC 6350, Section 6.1.5 | + | | FN | RFC 6350, Section 6.2.1 | + | | N | RFC 6350, Section 6.2.2 | + | | NICKNAME | RFC 6350, Section 6.2.3 | + | | PHOTO | RFC 6350, Section 6.2.4 | + | | BDAY | RFC 6350, Section 6.2.5 | + | | ANNIVERSARY | RFC 6350, Section 6.2.6 | + | | GENDER | RFC 6350, Section 6.2.7 | + | | ADR | RFC 6350, Section 6.3.1 | + | | TEL | RFC 6350, Section 6.4.1 | + | | EMAIL | RFC 6350, Section 6.4.2 | + | | IMPP | RFC 6350, Section 6.4.3 | + | | LANG | RFC 6350, Section 6.4.4 | + | | TZ | RFC 6350, Section 6.5.1 | + | | GEO | RFC 6350, Section 6.5.2 | + | | TITLE | RFC 6350, Section 6.6.1 | + | | ROLE | RFC 6350, Section 6.6.2 | + | | LOGO | RFC 6350, Section 6.6.3 | + | | ORG | RFC 6350, Section 6.6.4 | + | | MEMBER | RFC 6350, Section 6.6.5 | + | | RELATED | RFC 6350, Section 6.6.6 | + | | CATEGORIES | RFC 6350, Section 6.7.1 | + | | NOTE | RFC 6350, Section 6.7.2 | + | | PRODID | RFC 6350, Section 6.7.3 | + | | REV | RFC 6350, Section 6.7.4 | + | | SOUND | RFC 6350, Section 6.7.5 | + | | UID | RFC 6350, Section 6.7.6 | + | | CLIENTPIDMAP | RFC 6350, Section 6.7.7 | + | | URL | RFC 6350, Section 6.7.8 | + | | VERSION | RFC 6350, Section 6.7.9 | + | | KEY | RFC 6350, Section 6.8.1 | + | | FBURL | RFC 6350, Section 6.9.1 | + | | CALADRURI | RFC 6350, Section 6.9.2 | + | | CALURI | RFC 6350, Section 6.9.3 | + +-----------+--------------+-------------------------+ + + + + + + +Perreault Standards Track [Page 64] + +RFC 6350 vCard August 2011 + + +10.3.2. Parameters Registry + + The following table has been used to initialize the parameters + registry. + + +-----------+-----------+------------------------+ + | Namespace | Parameter | Reference | + +-----------+-----------+------------------------+ + | | LANGUAGE | RFC 6350, Section 5.1 | + | | VALUE | RFC 6350, Section 5.2 | + | | PREF | RFC 6350, Section 5.3 | + | | ALTID | RFC 6350, Section 5.4 | + | | PID | RFC 6350, Section 5.5 | + | | TYPE | RFC 6350, Section 5.6 | + | | MEDIATYPE | RFC 6350, Section 5.7 | + | | CALSCALE | RFC 6350, Section 5.8 | + | | SORT-AS | RFC 6350, Section 5.9 | + | | GEO | RFC 6350, Section 5.10 | + | | TZ | RFC 6350, Section 5.11 | + +-----------+-----------+------------------------+ + +10.3.3. Value Data Types Registry + + The following table has been used to initialize the parameters + registry. + + +------------------+-------------------------+ + | Value Data Type | Reference | + +------------------+-------------------------+ + | BOOLEAN | RFC 6350, Section 4.4 | + | DATE | RFC 6350, Section 4.3.1 | + | DATE-AND-OR-TIME | RFC 6350, Section 4.3.4 | + | DATE-TIME | RFC 6350, Section 4.3.3 | + | FLOAT | RFC 6350, Section 4.6 | + | INTEGER | RFC 6350, Section 4.5 | + | LANGUAGE-TAG | RFC 6350, Section 4.8 | + | TEXT | RFC 6350, Section 4.1 | + | TIME | RFC 6350, Section 4.3.2 | + | TIMESTAMP | RFC 6350, Section 4.3.5 | + | URI | RFC 6350, Section 4.2 | + | UTC-OFFSET | RFC 6350, Section 4.7 | + +------------------+-------------------------+ + + + + + + + + + +Perreault Standards Track [Page 65] + +RFC 6350 vCard August 2011 + + +10.3.4. Values Registries + + Separate tables are used for property and parameter values. + + The following table is to be used to initialize the property values + registry. + + +----------+------------+-------------------------+ + | Property | Value | Reference | + +----------+------------+-------------------------+ + | BEGIN | VCARD | RFC 6350, Section 6.1.1 | + | END | VCARD | RFC 6350, Section 6.1.2 | + | KIND | individual | RFC 6350, Section 6.1.4 | + | KIND | group | RFC 6350, Section 6.1.4 | + | KIND | org | RFC 6350, Section 6.1.4 | + | KIND | location | RFC 6350, Section 6.1.4 | + +----------+------------+-------------------------+ + + The following table has been used to initialize the parameter values + registry. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Perreault Standards Track [Page 66] + +RFC 6350 vCard August 2011 + + + +------------------------+-----------+--------------+---------------+ + | Property | Parameter | Value | Reference | + +------------------------+-----------+--------------+---------------+ + | FN, NICKNAME, PHOTO, | TYPE | work | RFC 6350, | + | ADR, TEL, EMAIL, IMPP, | | | Section 5.6 | + | LANG, TZ, GEO, TITLE, | | | | + | ROLE, LOGO, ORG, | | | | + | RELATED, CATEGORIES, | | | | + | NOTE, SOUND, URL, KEY, | | | | + | FBURL, CALADRURI, and | | | | + | CALURI | | | | + | FN, NICKNAME, PHOTO, | TYPE | home | RFC 6350, | + | ADR, TEL, EMAIL, IMPP, | | | Section 5.6 | + | LANG, TZ, GEO, TITLE, | | | | + | ROLE, LOGO, ORG, | | | | + | RELATED, CATEGORIES, | | | | + | NOTE, SOUND, URL, KEY, | | | | + | FBURL, CALADRURI, and | | | | + | CALURI | | | | + | TEL | TYPE | text | RFC 6350, | + | | | | Section 6.4.1 | + | TEL | TYPE | voice | RFC 6350, | + | | | | Section 6.4.1 | + | TEL | TYPE | fax | RFC 6350, | + | | | | Section 6.4.1 | + | TEL | TYPE | cell | RFC 6350, | + | | | | Section 6.4.1 | + | TEL | TYPE | video | RFC 6350, | + | | | | Section 6.4.1 | + | TEL | TYPE | pager | RFC 6350, | + | | | | Section 6.4.1 | + | TEL | TYPE | textphone | RFC 6350, | + | | | | Section 6.4.1 | + | BDAY, ANNIVERSARY | CALSCALE | gregorian | RFC 6350, | + | | | | Section 5.8 | + | RELATED | TYPE | contact | RFC 6350, | + | | | | Section 6.6.6 | + | | | | and [xfn] | + | RELATED | TYPE | acquaintance | RFC 6350, | + | | | | Section 6.6.6 | + | | | | and [xfn] | + | RELATED | TYPE | friend | RFC 6350, | + | | | | Section 6.6.6 | + | | | | and [xfn] | + | RELATED | TYPE | met | RFC 6350, | + | | | | Section 6.6.6 | + | | | | and [xfn] | + + + + +Perreault Standards Track [Page 67] + +RFC 6350 vCard August 2011 + + + | RELATED | TYPE | co-worker | RFC 6350, | + | | | | Section 6.6.6 | + | | | | and [xfn] | + | RELATED | TYPE | colleague | RFC 6350, | + | | | | Section 6.6.6 | + | | | | and [xfn] | + | RELATED | TYPE | co-resident | RFC 6350, | + | | | | Section 6.6.6 | + | | | | and [xfn] | + | RELATED | TYPE | neighbor | RFC 6350, | + | | | | Section 6.6.6 | + | | | | and [xfn] | + | RELATED | TYPE | child | RFC 6350, | + | | | | Section 6.6.6 | + | | | | and [xfn] | + | RELATED | TYPE | parent | RFC 6350, | + | | | | Section 6.6.6 | + | | | | and [xfn] | + | RELATED | TYPE | sibling | RFC 6350, | + | | | | Section 6.6.6 | + | | | | and [xfn] | + | RELATED | TYPE | spouse | RFC 6350, | + | | | | Section 6.6.6 | + | | | | and [xfn] | + | RELATED | TYPE | kin | RFC 6350, | + | | | | Section 6.6.6 | + | | | | and [xfn] | + | RELATED | TYPE | muse | RFC 6350, | + | | | | Section 6.6.6 | + | | | | and [xfn] | + | RELATED | TYPE | crush | RFC 6350, | + | | | | Section 6.6.6 | + | | | | and [xfn] | + | RELATED | TYPE | date | RFC 6350, | + | | | | Section 6.6.6 | + | | | | and [xfn] | + | RELATED | TYPE | sweetheart | RFC 6350, | + | | | | Section 6.6.6 | + | | | | and [xfn] | + | RELATED | TYPE | me | RFC 6350, | + | | | | Section 6.6.6 | + | | | | and [xfn] | + | RELATED | TYPE | agent | RFC 6350, | + | | | | Section 6.6.6 | + | RELATED | TYPE | emergency | RFC 6350, | + | | | | Section 6.6.6 | + +------------------------+-----------+--------------+---------------+ + + + + +Perreault Standards Track [Page 68] + +RFC 6350 vCard August 2011 + + +11. Acknowledgments + + The authors would like to thank Tim Howes, Mark Smith, and Frank + Dawson, the original authors of [RFC2425] and [RFC2426], Pete + Resnick, who got this effort started and provided help along the way, + as well as the following individuals who have participated in the + drafting, review, and discussion of this memo: + + Aki Niemi, Andy Mabbett, Alexander Mayrhofer, Alexey Melnikov, Anil + Srivastava, Barry Leiba, Ben Fortuna, Bernard Desruisseaux, Bernie + Hoeneisen, Bjoern Hoehrmann, Caleb Richardson, Chris Bryant, Chris + Newman, Cyrus Daboo, Daisuke Miyakawa, Dan Brickley, Dan Mosedale, + Dany Cauchie, Darryl Champagne, Dave Thewlis, Filip Navara, Florian + Zeitz, Helge Hess, Jari Urpalainen, Javier Godoy, Jean-Luc Schellens, + Joe Hildebrand, Jose Luis Gayosso, Joseph Smarr, Julian Reschke, + Kepeng Li, Kevin Marks, Kevin Wu Won, Kurt Zeilenga, Lisa Dusseault, + Marc Blanchet, Mark Paterson, Markus Lorenz, Michael Haardt, Mike + Douglass, Nick Levinson, Peter K. Sheerin, Peter Mogensen, Peter + Saint-Andre, Renato Iannella, Rohit Khare, Sly Gryphon, Stephane + Bortzmeyer, Tantek Celik, and Zoltan Ordogh. + +12. References + +12.1. Normative References + + [CCITT.X520.1988] + International Telephone and Telegraph Consultative + Committee, "Information Technology - Open Systems + Interconnection - The Directory: Selected Attribute + Types", CCITT Recommendation X.520, November 1988. + + [IEEE.754.2008] + Institute of Electrical and Electronics Engineers, + "Standard for Binary Floating-Point Arithmetic", + IEEE Standard 754, August 2008. + + [ISO.8601.2000] + International Organization for Standardization, "Data + elements and interchange formats - Information interchange + - Representation of dates and times", ISO Standard 8601, + December 2000. + + [ISO.8601.2004] + International Organization for Standardization, "Data + elements and interchange formats - Information interchange + - Representation of dates and times", ISO Standard 8601, + December 2004. + + + + +Perreault Standards Track [Page 69] + +RFC 6350 vCard August 2011 + + + [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail + Extensions (MIME) Part One: Format of Internet Message + Bodies", RFC 2045, November 1996. + + [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail + Extensions (MIME) Part Two: Media Types", RFC 2046, + November 1996. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2739] Small, T., Hennessy, D., and F. Dawson, "Calendar + Attributes for vCard and LDAP", RFC 2739, January 2000. + + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. + + [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", + RFC 3966, December 2004. + + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, + RFC 3986, January 2005. + + [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally + Unique IDentifier (UUID) URN Namespace", RFC 4122, + July 2005. + + [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and + Registration Procedures", BCP 13, RFC 4288, December 2005. + + [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + + [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, + October 2008. + + [RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling + Core Object Specification (iCalendar)", RFC 5545, + September 2009. + + [RFC5546] Daboo, C., "iCalendar Transport-Independent + Interoperability Protocol (iTIP)", RFC 5546, + December 2009. + + [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying + Languages", BCP 47, RFC 5646, September 2009. + + + + +Perreault Standards Track [Page 70] + +RFC 6350 vCard August 2011 + + + [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource + Identifier for Geographic Locations ('geo' URI)", + RFC 5870, June 2010. + + [RFC6351] Perreault, S., "xCard: vCard XML Representation", + RFC 6351, August 2011. + + [W3C.REC-xml-20081126] + Maler, E., Yergeau, F., Sperberg-McQueen, C., Paoli, J., + and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth + Edition)", World Wide Web Consortium Recommendation REC- + xml-20081126, November 2008, + . + + [xfn] Celik, T., Mullenweg, M., and E. Meyer, "XFN 1.1 profile", + . + +12.2. Informative References + + [IANA-TZ] Lear, E. and P. Eggert, "IANA Procedures for Maintaining + the Timezone Database", Work in Progress, May 2011. + + [ISO9070] International Organization for Standardization, + "Information Processing - SGML support facilities - + Registration Procedures for Public Text Owner + Identifiers", ISO 9070, April 1991. + + [RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform + Resource Locators (URL)", RFC 1738, December 1994. + + [RFC2397] Masinter, L., "The "data" URL scheme", RFC 2397, + August 1998. + + [RFC2425] Howes, T., Smith, M., and F. Dawson, "A MIME Content-Type + for Directory Information", RFC 2425, September 1998. + + [RFC2426] Dawson, F. and T. Howes, "vCard MIME Directory Profile", + RFC 2426, September 1998. + + [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., + Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext + Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. + + [RFC3282] Alvestrand, H., "Content Language Headers", RFC 3282, + May 2002. + + + + + + +Perreault Standards Track [Page 71] + +RFC 6350 vCard August 2011 + + + [RFC3406] Daigle, L., van Gulik, D., Iannella, R., and P. Faltstrom, + "Uniform Resource Names (URN) Namespace Definition + Mechanisms", BCP 66, RFC 3406, October 2002. + + [RFC3536] Hoffman, P., "Terminology Used in Internationalization in + the IETF", RFC 3536, May 2003. + + [RFC4770] Jennings, C. and J. Reschke, Ed., "vCard Extensions for + Instant Messaging (IM)", RFC 4770, January 2007. + + [RFC4880] Callas, J., Donnerhacke, L., Finney, H., Shaw, D., and R. + Thayer, "OpenPGP Message Format", RFC 4880, November 2007. + + [RFC5335bis] + Yang, A. and S. Steele, "Internationalized Email Headers", + Work in Progress, July 2011. + + [RFC5751] Ramsdell, B. and S. Turner, "Secure/Multipurpose Internet + Mail Extensions (S/MIME) Version 3.2 Message + Specification", RFC 5751, January 2010. + + [RFC6068] Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto' + URI Scheme", RFC 6068, October 2010. + + [TZ-DB] Olson, A., "Time zone code and data", + . + + [vCard21] Internet Mail Consortium, "vCard - The Electronic Business + Card Version 2.1", September 1996. + + + + + + + + + + + + + + + + + + + + + + +Perreault Standards Track [Page 72] + +RFC 6350 vCard August 2011 + + +Appendix A. Differences from RFCs 2425 and 2426 + + This appendix contains a high-level overview of the major changes + that have been made in the vCard specification from RFCs 2425 and + 2426. It is incomplete, as it only lists the most important changes. + +A.1. New Structure + + o [RFC2425] and [RFC2426] have been merged. + + o vCard is now not only a MIME type but a stand-alone format. + + o A proper MIME type registration form has been included. + + o UTF-8 is now the only possible character set. + + o New vCard elements can be registered from IANA. + +A.2. Removed Features + + o The CONTEXT and CHARSET parameters are no more. + + o The NAME, MAILER, LABEL, and CLASS properties are no more. + + o The "intl", "dom", "postal", and "parcel" TYPE parameter values + for the ADR property have been removed. + + o In-line vCards (such as the value of the AGENT property) are no + longer supported. + +A.3. New Properties and Parameters + + o The KIND, GENDER, LANG, ANNIVERSARY, XML, and CLIENTPIDMAP + properties have been added. + + o [RFC2739], which defines the FBURL, CALADRURI, CAPURI, and CALURI + properties, has been merged in. + + o [RFC4770], which defines the IMPP property, has been merged in. + + o The "work" and "home" TYPE parameter values are now applicable to + many more properties. + + o The "pref" value of the TYPE parameter is now a parameter of its + own, with a positive integer value indicating the level of + preference. + + o The ALTID and PID parameters have been added. + + + +Perreault Standards Track [Page 73] + +RFC 6350 vCard August 2011 + + + o The MEDIATYPE parameter has been added and replaces the TYPE + parameter when it was used for indicating the media type of the + property's content. + +Author's Address + + Simon Perreault + Viagenie + 2875 Laurier, suite D2-630 + Quebec, QC G1V 2M2 + Canada + + Phone: +1 418 656 9254 + EMail: simon.perreault@viagenie.ca + URI: http://www.viagenie.ca + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Perreault Standards Track [Page 74] + diff --git a/specs/rfc6868-param-value-encoding.txt b/specs/rfc6868-param-value-encoding.txt new file mode 100644 index 0000000..668f300 --- /dev/null +++ b/specs/rfc6868-param-value-encoding.txt @@ -0,0 +1,395 @@ + + + + + + +Internet Engineering Task Force (IETF) C. Daboo +Request for Comments: 6868 Apple +Updates: 5545, 6321, 6350, 6351 February 2013 +Category: Standards Track +ISSN: 2070-1721 + + + Parameter Value Encoding in iCalendar and vCard + +Abstract + + This specification updates the data formats for iCalendar (RFC 5545) + and vCard (RFC 6350) to allow parameter values to include certain + characters forbidden by the existing specifications. + +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/rfc6868. + +Copyright Notice + + Copyright (c) 2013 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 Standards Track [Page 1] + +RFC 6868 Parameter Encoding February 2013 + + +Table of Contents + + 1. Introduction ....................................................2 + 2. Conventions Used in This Document ...............................2 + 3. Parameter Value Encoding Scheme .................................3 + 3.1. iCalendar Example ..........................................4 + 3.2. vCard Example ..............................................4 + 4. Security Considerations .........................................4 + 5. Acknowledgments .................................................4 + 6. Normative References ............................................5 + Appendix A. Choice of Quoting Mechanism ............................6 + +1. Introduction + + The iCalendar [RFC5545] specification defines a standard way to + describe calendar data. The vCard [RFC6350] specification defines a + standard way to describe contact data. Both of these use a similar + text-based data format. Each iCalendar and vCard data object can + include "properties" that have "parameters" and a "value". The value + of a "parameter" is typically a token or URI value, but a "generic" + text value is also allowed. However, the syntax rules for both + iCalendar and vCard prevent the use of a double-quote character or + control characters in such values, though double-quote characters and + some subset of control characters are allowed in the actual property + values. + + As more and more extensions are being developed for these data + formats, there is a need to allow at least double-quotes and line + feeds to be included in parameter values. The \-escaping mechanism + used for property text values is not defined for use with parameter + values and cannot be easily used in a backwards-compatible manner. + This specification defines a new character escaping mechanism, + compatible with existing parsers and chosen to minimize any impact on + existing data. + +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 Standards Track [Page 2] + +RFC 6868 Parameter Encoding February 2013 + + +3. Parameter Value Encoding Scheme + + This specification defines the ^ character (U+005E -- Circumflex + Accent) as an escape character in parameter values whose value type + is defined using the "param-value" syntax element (Section 3.1 of + iCalendar [RFC5545] and Section 3.3 of vCard [RFC6350]). The + ^-escaping mechanism can be used when the value is either unquoted or + quoted (i.e., whether or not the value is surrounded by double- + quotes). + + When generating iCalendar or vCard parameter values, the following + apply: + + o formatted text line breaks are encoded into ^n (U+005E, U+006E) + + o the ^ character (U+005E) is encoded into ^^ (U+005E, U+005E) + + o the " character (U+0022) is encoded into ^' (U+005E, U+0027) + + When parsing iCalendar or vCard parameter values, the following + apply: + + o the character sequence ^n (U+005E, U+006E) is decoded into an + appropriate formatted line break according to the type of system + being used + + o the character sequence ^^ (U+005E, U+005E) is decoded into the ^ + character (U+005E) + + o the character sequence ^' (U+005E, U+0027) is decoded into the " + character (U+0022) + + o if a ^ (U+005E) character is followed by any character other than + the ones above, parsers MUST leave both the ^ and the following + character in place + + When converting between iCalendar and vCard text-based data formats + and alternative data-format representations such as XML (as described + in [RFC6321] and [RFC6351], respectively), implementations MUST + ensure that parameter value escape sequences are generated correctly + in the text-based format and are decoded when the parameter values + appear in the alternate data formats. + + + + + + + + + +Daboo Standards Track [Page 3] + +RFC 6868 Parameter Encoding February 2013 + + +3.1. iCalendar Example + + The following example is an "ATTENDEE" property with a "CN" parameter + whose value includes two double-quote characters. The parameter + value is not quoted, as there are no characters in the value that + would trigger quoting as required by iCalendar. + + ATTENDEE;CN=George Herman ^'Babe^' Ruth:mailto:babe@example.com + + The unescaped parameter value is + + George Herman "Babe" Ruth + +3.2. vCard Example + + The following example is a "GEO" property with an "X-ADDRESS" + parameter whose value includes several line feed characters. The + parameter value is also quoted, since it contains a comma, which + triggers quoting as required by vCard. + + GEO;X-ADDRESS="Pittsburgh Pirates^n115 Federal St^nPitt + sburgh, PA 15212":geo:40.446816,-80.00566 + + The unescaped parameter value (where each line is terminated by a + line break character sequence) is + + Pittsburgh Pirates + 115 Federal St + Pittsburgh, PA 15212 + +4. Security Considerations + + There are no additional security issues beyond those of iCalendar + [RFC5545] and vCard [RFC6350]. + +5. Acknowledgments + + Thanks to Michael Angstadt, Tim Bray, Mike Douglass, Barry Leiba, + Simon Perreault, and Pete Resnick for feedback on this specification. + + + + + + + + + + + + +Daboo Standards Track [Page 4] + +RFC 6868 Parameter Encoding February 2013 + + +6. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [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. + + [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, + August 2011. + + [RFC6351] Perreault, S., "xCard: vCard XML Representation", + RFC 6351, August 2011. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Daboo Standards Track [Page 5] + +RFC 6868 Parameter Encoding February 2013 + + +Appendix A. Choice of Quoting Mechanism + + Having recognized the need for escaping parameter values, the + question is what mechanism to use? One obvious choice would be to + adopt the \-escaping used for property values. However, that could + not be used as-is, because it escapes a double-quote as the sequence + of \ followed by double-quote. Consider what the example in + Section 3.1 might look like using \-escaping: + + ATTENDEE;CN="George Herman \"Babe\" Ruth":mailto:babe@example.com + + Existing iCalendar/vCard parsers know nothing about escape sequences + in parameters. So they would parse the parameter value as: + + George Herman \ + + i.e., the text between the first and second occurrence of a double- + quote. However, the text after the second double-quote ought to be + either a : or a ; (to delimit the parameter value from the following + parameter or property) but is not, so the parser could legitimately + throw an error at that point because the data is syntactically + invalid. Thus, for backwards-compatibility reasons, a double-quote + cannot be escaped using a sequence that itself includes a double- + quote, and hence the choice of using a single-quote in this + specification. + + Another option would be to use a form of \-escaping modified for use + in parameter values only. However, some incorrect, non-interoperable + use of \ in parameter values has been observed, and thus it is best + to steer clear of that to achieve guaranteed, reliable + interoperability. Also, given that double-quote gets changed to + single-quote in the escape sequence for a parameter, but not for a + value, it is better to not give the impression that the same escape + mechanism (and thus code) can be used for both (which could lead to + other issues, such as an implementation incorrectly escaping a ; as + \; as opposed to quoting the parameter value). + + The choice of ^ as the escape character was made based on the + requirement that an ASCII symbol (non-alphanumeric character) be + used, and it ought to be one least likely to be found in existing + data. + + + + + + + + + + +Daboo Standards Track [Page 6] + +RFC 6868 Parameter Encoding February 2013 + + +Author's Address + + Cyrus Daboo + Apple Inc. + 1 Infinite Loop + Cupertino, CA 95014 + USA + + EMail: cyrus@daboo.name + URI: http://www.apple.com/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Daboo Standards Track [Page 7] + diff --git a/specs/rfc7095-jcard.txt b/specs/rfc7095-jcard.txt new file mode 100644 index 0000000..f35acc6 --- /dev/null +++ b/specs/rfc7095-jcard.txt @@ -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@example.org + + jCard: + + ["x-complaint-uri", {}, "unknown", "mailto:abuse@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@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: + + 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", . + + + + + + + + + +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@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@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@kewis.ch + URI: http://www.mozilla.org/ + + + + + + + + + + + + + + + +Kewisch Standards Track [Page 29] + diff --git a/specs/rfc7265-jcal.txt b/specs/rfc7265-jcal.txt new file mode 100644 index 0000000..a78148f --- /dev/null +++ b/specs/rfc7265-jcal.txt @@ -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@example.com + ... + END:VEVENT + + jCal Example: + + ["vevent": + [ + ["request-status", {}, "text", ["2.0", "Success"] ], + ["request-status", {}, "text", + [ + "3.7", + "Invalid calendar user", + "ATTENDEE:mailto:jsmith@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@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@example.org", + "mailto:jqpublic@example.org"] + }, + "cal-address", + "mailto:jsmith@example.org" + ] + + Example 2: + + ["attendee", + { + "delegated-to": "mailto:jdoe@example.org" + }, + "cal-address", + "mailto:jsmith@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@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@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, + . + + [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", . + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +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@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 + + + + +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@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@example.com"] + ], + [] + ] + ] + ] + +Authors' Addresses + + Philipp Kewisch + Mozilla Corporation + 650 Castro Street, Suite 300 + Mountain View, CA 94041 + USA + + EMail: mozilla@kewis.ch + URI: http://www.mozilla.org/ + + + Cyrus Daboo + Apple Inc. + 1 Infinite Loop + Cupertino, CA 95014 + USA + + EMail: cyrus@daboo.name + URI: http://www.apple.com/ + + + Mike Douglass + Rensselaer Polytechnic Institute + 110 8th Street + Troy, NY 12180 + USA + + EMail: douglm@rpi.edu + URI: http://www.rpi.edu/ + + + + + + + + + + + + +Kewisch, et al. Standards Track [Page 31] + diff --git a/specs/rfc7529-non-greg-rrule.txt b/specs/rfc7529-non-greg-rrule.txt new file mode 100644 index 0000000..a54aa35 --- /dev/null +++ b/specs/rfc7529-non-greg-rrule.txt @@ -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 XML element in Section 3.6.10 + of [RFC6321] in the following manner: + + 1. A new XML element is defined as a child element of + . 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 XML element is defined as a child element of + . The content of this element MUST be a string whose + value is the "SKIP" element value of the "RRULE", with case + preserved. + + 3. The 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: + + + + GREGORIAN + YEARLY + FORWARD + + + +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: + + + + + + Example: + + + GREGORIAN + CHINESE + ISLAMIC-CIVIL + HEBREW + ETHIOPIC + + + + +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, + . + + [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, + "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, + March 2007, . + + [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed + Authoring and Versioning (WebDAV)", RFC 4918, June 2007, + . + + [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008, + . + + [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and + Scheduling Core Object Specification (iCalendar)", RFC + 5545, September 2009, + . + + [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent + Interoperability Protocol (iTIP)", RFC 5546, December + 2009, . + + [RFC6321] Daboo, C., Douglass, M., and S. Lees, "xCal: The XML + Format for iCalendar", RFC 6321, August 2011, + . + + [RFC7265] Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON + Format for iCalendar", RFC 7265, May 2014, + . + + [UNICODE.CLDR] + The Unicode Consortium, "CLDR calendar.xml Data", Unicode + Consortium CLDR, + . + + + +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, + . + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +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@daboo.name + URI: http://www.apple.com/ + + + Gregory Yakushev + Google Inc. + Brandschenkestrasse 100 + 8002 Zurich + Switzerland + + EMail: gyakushev@yahoo.com + URI: http://www.google.com/ + + + + + + + + + + + + + + + + + + + + +Daboo & Yakushev Standards Track [Page 21] + diff --git a/specs/rfc7953-availability.txt b/specs/rfc7953-availability.txt new file mode 100644 index 0000000..6348c23 --- /dev/null +++ b/specs/rfc7953-availability.txt @@ -0,0 +1,1347 @@ + + + + + + +Internet Engineering Task Force (IETF) C. Daboo +Request for Comments: 7953 Apple +Updates: 4791, 5545, 6638 M. Douglass +Category: Standards Track Spherical Cow Group +ISSN: 2070-1721 August 2016 + + + Calendar Availability + +Abstract + + This document specifies a new iCalendar (RFC 5545) component that + allows the publication of available and unavailable time periods + associated with a calendar user. This component can be used in + standard iCalendar free-busy lookups, including the iCalendar + Transport-independent Interoperability Protocol (iTIP; RFC 5546) + free-busy requests, to generate repeating blocks of available or busy + time with exceptions as needed. + + This document also defines extensions to the Calendaring Extensions + to WebDAV (CalDAV) calendar access protocol (RFC 4791) and the + associated scheduling protocol (RFC 6638) to specify how this new + calendar component can be used when evaluating free-busy time. + +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 7841. + + 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/rfc7953. + + + + + + + + + + + + + + +Daboo & Douglass Standards Track [Page 1] + +RFC 7953 Calendar Availability August 2016 + + +Copyright Notice + + Copyright (c) 2016 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. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 + 3. iCalendar Extensions . . . . . . . . . . . . . . . . . . . . 4 + 3.1. VAVAILABILITY Component . . . . . . . . . . . . . . . . . 4 + 3.2. Busy Time Type . . . . . . . . . . . . . . . . . . . . . 10 + 4. Combining VAVAILABILITY Components . . . . . . . . . . . . . 10 + 5. Calculating Free-Busy Time . . . . . . . . . . . . . . . . . 12 + 5.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 13 + 6. Use with iTIP . . . . . . . . . . . . . . . . . . . . . . . . 15 + 7. CalDAV Extensions . . . . . . . . . . . . . . . . . . . . . . 15 + 7.1. CalDAV Requirements Overview . . . . . . . . . . . . . . 15 + 7.2. New Features in CalDAV . . . . . . . . . . . . . . . . . 16 + 8. Security Considerations . . . . . . . . . . . . . . . . . . . 19 + 9. Privacy Considerations . . . . . . . . . . . . . . . . . . . 19 + 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 + 10.1. Component Registrations . . . . . . . . . . . . . . . . 20 + 10.2. Property Registrations . . . . . . . . . . . . . . . . . 20 + 11. Normative References . . . . . . . . . . . . . . . . . . . . 20 + Appendix A. Example Calendar #1 . . . . . . . . . . . . . . . . 22 + Appendix B. Example Calendar #2 . . . . . . . . . . . . . . . . 23 + Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 24 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 + + + + + + + + + + + + +Daboo & Douglass Standards Track [Page 2] + +RFC 7953 Calendar Availability August 2016 + + +1. Introduction + + Calendar users often have regular periods of time when they are + either available to be scheduled or always unavailable. For example, + an office worker will often wish only to appear free to their work + colleagues during normal 'office hours' (e.g., Monday through Friday, + 9 am through 5 pm). Or, a university professor might only be + available to students during a set period of time (e.g., Thursday + afternoons, 2 pm through 5 pm during term time only). Ideally, users + ought be able to specify such periods directly via their calendar + user agent and have them automatically considered as part of the + normal free-busy lookup for that user. In addition, it ought be + possible to present different periods of available time depending on + which user is making the request. + + iCalendar [RFC5545] defines a "VFREEBUSY" component that can be used + to represent fixed busy time periods, but it does not provide a way + to specify a repeating period of available or unavailable time. + Since repeating patterns are often the case, "VFREEBUSY" components + are not sufficient to solve this problem. + + This specification defines a new type of iCalendar component that can + be used to publish user availability. + + CalDAV [RFC4791] provides a way for calendar users to access and + manage calendar data and exchange this data via scheduling + operations. As part of this, the CalDAV calendar-access [RFC4791] + feature provides a CALDAV:free-busy-query REPORT that returns free- + busy information for a calendar collection or hierarchy of calendar + collections. Also, the CalDAV calendar-auto-schedule [RFC6638] + feature allows free-busy information for a calendar user to be + determined. Both of these operations involve examining user + calendars for events that 'block time', with the blocked out periods + being returned in a "VFREEBUSY" component. + + This specification extends the CalDAV calendar-access and CalDAV + calendar-auto-schedule features to allow the new iCalendar + availability components to be stored and manipulated and to allow + free-busy lookups to use the information from any such components, if + present. + +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 & Douglass Standards Track [Page 3] + +RFC 7953 Calendar Availability August 2016 + + + 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. + +3. iCalendar Extensions + + This specification adds a new "VAVAILABILITY" calendar component to + iCalendar. The "VAVAILABILITY" component is itself a container for + new "AVAILABLE" subcomponents. + + The purpose of the "VAVAILABILITY" calendar component is to provide a + grouping of available time information over a specific range of time. + Within that, there are specific time ranges that are marked as + available via a set of "AVAILABLE" calendar subcomponents. Together + these can be used to specify available time that can repeat over set + periods of time, and which can vary over time. + + An illustration of how "VAVAILABILITY" and "AVAILABLE" components + work is shown below. + + Time Range + <=========================================================> + + +-------------------------------------------------+ + | VAVAILABILITY | + +-------------------------------------------------+ + +------------+ +------------+ + | AVAILABLE | | AVAILABLE | + +------------+ +------------+ + + <-> <-----> <-----------> Busy Time + + The overall time range is shown at the top. A "VAVAILABILITY" + component spans part of the range. The time range covered by the + "VAVAILABILITY" component is considered to be busy, except for the + ranges covered by the "AVAILABLE" components within the + "VAVAILABILITY" component. + +3.1. VAVAILABILITY Component + + Component Name: VAVAILABILITY + + Purpose: Provide a grouping of component properties and + subcomponents that describe the availability associated with a + calendar user. + + + + + +Daboo & Douglass Standards Track [Page 4] + +RFC 7953 Calendar Availability August 2016 + + + Format Definition: A "VAVAILABILITY" calendar component is defined + by the following notation: + + availabilityc = "BEGIN" ":" "VAVAILABILITY" CRLF + availabilityprop *availablec + "END" ":" "VAVAILABILITY" CRLF + + availabilityprop = *( + ; + ; the following are REQUIRED + ; but MUST NOT occur more than once + ; + dtstamp / uid + ; + ; the following are OPTIONAL + ; but MUST NOT occur more than once + ; + busytype / class / created / description / + dtstart / last-mod / location / organizer / + priority /seq / summary / url / + ; + ; Either 'dtend' or 'duration' MAY appear + ; in an 'availableprop', but 'dtend' and + ; 'duration' MUST NOT occur in the same + ; 'availabilityprop'. + ; 'duration' MUST NOT be present if + ; 'dtstart' is not present + ; + dtend / duration / + ; + ; the following are OPTIONAL + ; and MAY occur more than once + ; + categories / comment / contact / + x-prop / iana-prop + ; + ) + + availablec = "BEGIN" ":" "AVAILABLE" CRLF + availableprop + "END" ":" "AVAILABLE" CRLF + + + + + + + + + + +Daboo & Douglass Standards Track [Page 5] + +RFC 7953 Calendar Availability August 2016 + + + availableprop = *( + ; + ; the following are REQUIRED + ; but MUST NOT occur more than once + ; + dtstamp / dtstart / uid / + ; + ; Either 'dtend' or 'duration' MAY appear in + ; an 'availableprop', but 'dtend' and + ; 'duration' MUST NOT occur in the same + ; 'availableprop'. + ; + dtend / duration / + ; + ; the following are OPTIONAL + ; but MUST NOT occur more than once + ; + created / description / last-mod / + location / recurid / rrule / summary / + ; + ; the following are OPTIONAL + ; and MAY occur more than once + ; + categories / comment / contact / exdate / + rdate / x-prop / iana-prop + ; + ) + + Description: A "VAVAILABILITY" component indicates a period of time + within which availability information is provided. A + "VAVAILABILITY" component can specify a start time and an end time + or duration. If "DTSTART" is not present, then the start time is + unbounded. If "DTEND" or "DURATION" are not present, then the end + time is unbounded. Within the specified time period, availability + defaults to a free-busy type of "BUSY-UNAVAILABLE" (see + Section 3.2), except for any time periods corresponding to + "AVAILABLE" subcomponents. + + "AVAILABLE" subcomponents are used to indicate periods of free + time within the time range of the enclosing "VAVAILABILITY" + component. "AVAILABLE" subcomponents MAY include recurrence + properties to specify recurring periods of time, which can be + overridden using normal iCalendar recurrence behavior (i.e., use + of the "RECURRENCE-ID" property). + + + + + + + +Daboo & Douglass Standards Track [Page 6] + +RFC 7953 Calendar Availability August 2016 + + + If specified, the "DTSTART" and "DTEND" properties in + "VAVAILABILITY" components and "AVAILABLE" subcomponents MUST be + "DATE-TIME" values specified as either the date with UTC time or + the date with local time and a time zone reference. + + The iCalendar object containing the "VAVAILABILITY" component MUST + contain appropriate "VTIMEZONE" components corresponding to each + unique "TZID" parameter value used in any DATE-TIME properties in + all components, unless [RFC7809] is in effect. + + When used to publish available time, the "ORGANIZER" property + specifies the calendar user associated with the published + available time. + + If the "PRIORITY" property is specified in "VAVAILABILITY" + components, it is used to determine how that component is combined + with other "VAVAILABILITY" components. See Section 4. + + Other calendar properties MAY be specified in "VAVAILABILITY" or + "AVAILABLE" components and are considered attributes of the marked + block of time. Their usage is application specific. For example, + the "LOCATION" property might be used to indicate that a person is + available in one location for part of the week and a different + location for another part of the week (but see Section 9 for when + it is appropriate to add additional data like this). + + Example: The following is an example of a "VAVAILABILITY" calendar + component used to represent the availability of a user, always + available Monday through Friday, 9:00 am to 5:00 pm in the + America/Montreal time zone: + + BEGIN:VAVAILABILITY + ORGANIZER:mailto:bernard@example.com + UID:0428C7D2-688E-4D2E-AC52-CD112E2469DF + DTSTAMP:20111005T133225Z + BEGIN:AVAILABLE + UID:34EDA59B-6BB1-4E94-A66C-64999089C0AF + SUMMARY:Monday to Friday from 9:00 to 17:00 + DTSTART;TZID=America/Montreal:20111002T090000 + DTEND;TZID=America/Montreal:20111002T170000 + RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR + END:AVAILABLE + END:VAVAILABILITY + + + + + + + + +Daboo & Douglass Standards Track [Page 7] + +RFC 7953 Calendar Availability August 2016 + + + The following is an example of a "VAVAILABILITY" calendar + component used to represent the availability of a user available + Monday through Thursday, 9:00 am to 5:00 pm, at the main office, + and Friday, 9:00 am to 12:00 pm, in the branch office in the + America/Montreal time zone between October 2nd and December 2nd + 2011: + + BEGIN:VAVAILABILITY + ORGANIZER:mailto:bernard@example.com + UID:84D0F948-7FC6-4C1D-BBF3-BA9827B424B5 + DTSTAMP:20111005T133225Z + DTSTART;TZID=America/Montreal:20111002T000000 + DTEND;TZID=America/Montreal:20111202T000000 + BEGIN:AVAILABLE + UID:7B33093A-7F98-4EED-B381-A5652530F04D + SUMMARY:Monday to Thursday from 9:00 to 17:00 + DTSTART;TZID=America/Montreal:20111002T090000 + DTEND;TZID=America/Montreal:20111002T170000 + RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH + LOCATION:Main Office + END:AVAILABLE + BEGIN:AVAILABLE + UID:DF39DC9E-D8C3-492F-9101-0434E8FC1896 + SUMMARY:Friday from 9:00 to 12:00 + DTSTART;TZID=America/Montreal:20111006T090000 + DTEND;TZID=America/Montreal:20111006T120000 + RRULE:FREQ=WEEKLY + LOCATION:Branch Office + END:AVAILABLE + END:VAVAILABILITY + + The following is an example of three "VAVAILABILITY" calendar + components used to represent the availability of a traveling + worker: Monday through Friday, 9:00 am to 5:00 pm each day. + However, for three weeks the calendar user is working in Montreal, + then one week in Denver, then back to Montreal. Note that each + overall period is covered by separate "VAVAILABILITY" components. + The last of these has no DTEND so it continues on "forever". This + example shows one way "blocks" of available time can be + represented. See Section 4 for another approach using priorities. + + + + + + + + + + + +Daboo & Douglass Standards Track [Page 8] + +RFC 7953 Calendar Availability August 2016 + + + BEGIN:VAVAILABILITY + ORGANIZER:mailto:bernard@example.com + UID:BE082249-7BDD-4FE0-BDBA-DE6598C32FC9 + DTSTAMP:20111005T133225Z + DTSTART;TZID=America/Montreal:20111002T000000 + DTEND;TZID=America/Montreal:20111023T030000 + BEGIN:AVAILABLE + UID:54602321-CEDB-4620-9099-757583263981 + SUMMARY:Monday to Friday from 9:00 to 17:00 + DTSTART;TZID=America/Montreal:20111002T090000 + DTEND;TZID=America/Montreal:20111002T170000 + RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR + LOCATION:Montreal + END:AVAILABLE + END:VAVAILABILITY + BEGIN:VAVAILABILITY + ORGANIZER:mailto:bernard@example.com + UID:A1FF55E3-555C-433A-8548-BF4864B5621E + DTSTAMP:20111005T133225Z + DTSTART;TZID=America/Denver:20111023T000000 + DTEND;TZID=America/Denver:20111030T000000 + BEGIN:AVAILABLE + UID:57DD4AAF-3835-46B5-8A39-B3B253157F01 + SUMMARY:Monday to Friday from 9:00 to 17:00 + DTSTART;TZID=America/Denver:20111023T090000 + DTEND;TZID=America/Denver:20111023T170000 + RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR + LOCATION:Denver + END:AVAILABLE + END:VAVAILABILITY + BEGIN:VAVAILABILITY + ORGANIZER:mailto:bernard@example.com + UID:1852F9E1-E0AA-4572-B4C4-ED1680A4DA40 + DTSTAMP:20111005T133225Z + DTSTART;TZID=America/Montreal:20111030T030000 + BEGIN:AVAILABLE + UID:D27C421F-16C2-4ECB-8352-C45CA352C72A + SUMMARY:Monday to Friday from 9:00 to 17:00 + DTSTART;TZID=America/Montreal:20111030T090000 + DTEND;TZID=America/Montreal:20111030T170000 + RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR + LOCATION:Montreal + END:AVAILABLE + END:VAVAILABILITY + + + + + + + +Daboo & Douglass Standards Track [Page 9] + +RFC 7953 Calendar Availability August 2016 + + +3.2. Busy Time Type + + Property Name: BUSYTYPE + + Purpose: This property specifies the default busy time type. + + Value Type: TEXT + + Property Parameters: IANA and nonstandard property parameters can be + specified on this property. + + Conformance: This property can be specified within "VAVAILABILITY" + calendar components. + + Format Definition: This property is defined by the following + notation: + + busytype = "BUSYTYPE" busytypeparam ":" busytypevalue CRLF + + busytypeparam = *(";" other-param) + + busytypevalue = "BUSY" / "BUSY-UNAVAILABLE" / + "BUSY-TENTATIVE" / iana-token / x-name + ; Default is "BUSY-UNAVAILABLE". + + Description: This property is used to specify the default busy time + type. The values correspond to those used by the "FBTYPE" + parameter used on a "FREEBUSY" property, with the exception that + the "FREE" value is not used in this property. If not specified + on a component that allows this property, the default is "BUSY- + UNAVAILABLE". + + Example: The following is an example of this property: + + BUSYTYPE:BUSY + +4. Combining VAVAILABILITY Components + + The "VAVAILABILITY" component allows a calendar user to describe + their availability over extended periods of time through the use of + recurrence patterns. This availability might be relatively constant + from year to year. + + However, there is usually some degree of irregularity, as people take + vacations or perhaps spend a few weeks at a different office. For + that period of time there is a need to redefine their availability. + Rather than modify their existing availability, the "PRIORITY" + property allows new "VAVAILABILITY" components to override others of + + + +Daboo & Douglass Standards Track [Page 10] + +RFC 7953 Calendar Availability August 2016 + + + lower ordinal priority. Note that iCalendar [RFC5545] defines the + "PRIORITY" property such that a value of 0 is undefined, 1 is the + highest priority, and 9 is the lowest. + + When combining "VAVAILABILITY" components, an absence of a "PRIORITY" + property or a value of 0 implies the lowest level of priority. When + two or more VAVAILABILITY components overlap, and they have the same + PRIORITY value, the overlapping busy time type is determined by the + following order: BUSY > BUSY-UNAVAILABLE > BUSY-TENTATIVE. That is, + if one component has a BUSYTYPE set to BUSY and the other has + BUSYTYPE set to BUSY-UNAVAILABLE, then the effective busy time type + over the time range that they overlap would be BUSY. It is up to the + creator of such components to ensure that combining them produces a + consistent and expected result. + + To calculate the available time, order the intersecting + "VAVAILABILITY" components by priority (the lowest to highest + "PRIORITY" values are 0, 9, 8, 7, 6, 5, 4, 3, 2, 1). + + Step through the resulting list of "VAVAILABILITY" components. For + each, the time range covered by the "VAVAILABILITY" component is set + to busy and then portions of it defined by the "AVAILABLE" components + in the "VAVAILABILITY" component are set to free. + + Note that, if any "VAVAILABILITY" component completely covers the + date range of interest, then any lower priority "VAVAILABILITY" + components can be ignored. + + Typically, a calendar user's "default" availability (e.g., business + hours of Monday through Friday, 9:00 am to 5:00 pm) would use the + lowest level of priority: zero. Any overrides to the "default" would + use higher levels as needed. To avoid having to keep readjusting the + "PRIORITY" property value when an override has to be "inserted" + between two existing components, priority values SHOULD be "spaced + out" over the full range of values. The table below illustrates this + via an example. The first row shows the priority range from low to + high, the second row shows the corresponding "PRIORITY" property + value, and the third row shows which "VAVAILABILITY" component has + that priority. The "default" availability is created with priority + zero (shown as {a} in the table), then the first override created + with priority 5 (shown as {b} in the table), a subsequent + availability can be inserted between the two by using priority 7 + (shown as {c} in the table), and another, taking precedence over all + existing ones, with priority 3 (shown as {d} in the table). As seen + in the table, additional "slots" are open for more "VAVAILABILITY" + components to be added with other priorities if needed. + + + + + +Daboo & Douglass Standards Track [Page 11] + +RFC 7953 Calendar Availability August 2016 + + + +-----+----+----+-----+----+-----+----+-----+----+------+ + | Low | | | | | | | | | High | + +-----+----+----+-----+----+-----+----+-----+----+------+ + | 0 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | + +-----+----+----+-----+----+-----+----+-----+----+------+ + | {a} | | | {c} | | {b} | | {d} | | | + +-----+----+----+-----+----+-----+----+-----+----+------+ + +5. Calculating Free-Busy Time + + This section describes how free-busy time information for a calendar + user is calculated in the presence of "VAVAILABILITY" calendar + components. + + An iCalendar "VFREEBUSY" component is used to convey "rolled-up" + free-busy time information for a calendar user. This can be + generated as the result of an iTIP [RFC5546] free-busy request or + through some other mechanism (e.g., a CalDAV calendar-access + CALDAV:free-busy-query REPORT). + + When one or more "VAVAILABILITY" components are present and intersect + the time range for the free-busy request, first the available time is + calculated, as outlined in Section 4. Once that is done, regular + "VEVENT" and "VFREEBUSY" components can be "overlaid" in the usual + way to block out time. + + An example procedure for this is as follows: + + 1. Initially mark the entire period of the free-busy request as + free. + + 2. For each "VAVAILABILITY" component ordered by PRIORITY (lowest to + highest): + + A. Determine if the "VAVAILABILITY" intersects the time range of + the free-busy request. If not, ignore it. + + B. Determine if the "VAVAILABILITY" is completely overridden by + a higher priority component. If so, ignore it. + + C. For the time period covered by the "VAVAILABILITY" component, + mark time in the free-busy request result set as busy, using + the busy time type derived from the "BUSYTYPE" property in + the "VAVAILABILITY" component. + + D. Append the "VAVAILABILITY" component to a list of components + for further processing in step 3, if it has not been ignored. + + + + +Daboo & Douglass Standards Track [Page 12] + +RFC 7953 Calendar Availability August 2016 + + + 3. For each "VAVAILABILITY" component in the list resulting from + step 2, in order from the first item to the last item: + + A. For each "AVAILABLE" component in the "VAVAILABILITY" + component: + + i. Expand all recurring instances, taking into account + overridden instances, ignoring instances or parts of + instances that fall outside of the free-busy request + time range or the time period specified by the + "VAVAILABILITY" component. + + ii. For each instance, mark the corresponding time in the + free-busy request result set as free. + + 4. For each "VEVENT" or "VFREEBUSY" component, apply normal free- + busy processing within the free-busy request time range. + +5.1. Examples + + In the examples below, a table is used to represent time slots for + the period of a free-busy request. Each time slot is two hours long. + The column header represents the hours from midnight local time. + Each row below the column headers represents a step in the free-busy + result set determination, following the procedure outlined above. + + Each cell in the rows below the column header contains a single + character that represents the free-busy type for the corresponding + time period at the end of the process step represented by the row. + The characters in the row are: + + F Represents "FREE" time in that slot. + + B Represents "BUSY" time in that slot. + + U Represents "BUSY-UNAVAILABLE" time in that slot. + + T Represents "BUSY-TENTATIVE" time in that slot. + + I Represents data to be ignored in that slot (as per step 2.B + above). + +5.1.1. Simple Example + + Appendix A shows the user's calendar. This includes one + "VAVAILABILITY" component giving available time within the requested + time range of 8:00 am to 6:00 pm, together with one "VEVENT" + component representing a two hour meeting starting at 12:00 pm. + + + +Daboo & Douglass Standards Track [Page 13] + +RFC 7953 Calendar Availability August 2016 + + + A free-busy request for Monday, 6th November 2011, midnight to + midnight in the America/Montreal time zone would be calculated as + follows using the steps described above. + + +------+----+----+----+----+----+----+----+----+----+----+----+----+ + | Step | 0 | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 | 22 | + +------+----+----+----+----+----+----+----+----+----+----+----+----+ + | 1. | F | F | F | F | F | F | F | F | F | F | F | F | + | 2. | U | U | U | U | U | U | U | U | U | U | U | U | + | 3. | U | U | U | U | F | F | F | F | F | U | U | U | + | 4. | U | U | U | U | F | F | B | F | F | U | U | U | + +------+----+----+----+----+----+----+----+----+----+----+----+----+ + +5.1.2. Further Example + + Appendix B shows another way to represent the availability of the + traveling worker shown above. Here we represent their base + availability of Monday through Friday, 8:00 am to 6:00 pm each day + with a "VAVAILABILITY" with default "PRIORITY" (there is no "DTEND" + property so that this availability is unbounded). For the week the + calendar user is working in Denver (October 23rd through October + 30th), we represent their availability with a "VAVAILABILITY" + component with priority 1, which overrides the base availability. + There is also a two hour meeting starting at 12:00 pm (in the + America/Denver time zone). + + A free-busy request for Monday, 24th October 2011, midnight to + midnight in the America/Montreal time zone, would be calculated as + follows using the steps described above. Note that there is a two + hour offset in the in the available time, compared to the previous + example, due to the two hour difference between the time zone of the + free-busy request and the time zone of the user's availability and + meeting. "2.P0" shows the base availability, and "2.P1" shows the + higher priority availability. "3.P1" only shows the higher priority + availability contributing to the overall free-busy since the default + availability is ignored (as per step 2.B described above). + + +------+----+----+----+----+----+----+----+----+----+----+----+----+ + | Step | 0 | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 18 | 20 | 22 | + +------+----+----+----+----+----+----+----+----+----+----+----+----+ + | 1. | F | F | F | F | F | F | F | F | F | F | F | F | + | 2.P0 | I | I | I | I | I | I | I | I | I | I | I | I | + | 2.P1 | U | U | U | U | U | U | U | U | U | U | U | U | + | 3.P1 | U | U | U | U | U | F | F | F | F | F | U | U | + | 4. | U | U | U | U | U | F | F | B | F | F | U | U | + +------+----+----+----+----+----+----+----+----+----+----+----+----+ + + + + + +Daboo & Douglass Standards Track [Page 14] + +RFC 7953 Calendar Availability August 2016 + + +6. Use with iTIP + + This specification does not define how "VAVAILABILITY" components are + used in scheduling messages sent using the iTIP [RFC5546] protocol. + It is expected that future specifications will define how iTIP + scheduling can make use of "VAVAILABILITY" components. + +7. CalDAV Extensions + +7.1. CalDAV Requirements Overview + + This section lists what functionality is required of a CalDAV server, + which supports "VAVAILABILITY" components in stored calendar data. A + server: + + o MUST advertise support for "VAVAILABILITY" components in + CALDAV:supported-calendar-component-set properties on calendars + that allow storing of such components; + + o MUST support CALDAV:free-busy-query REPORTs that aggregate the + information in any "VAVAILABILITY" components in the calendar + collections targeted by the request; + + o MUST support "VAVAILABILITY" components stored in a + CALDAV:calendar-availability Web Distributed Authoring and + Versioning (WebDAV) property on a CalDAV scheduling Inbox + collection, if the CalDAV calendar-auto-schedule feature is + supported; + + o MUST support iTIP [RFC5546] free-busy requests that aggregate the + information in any "VAVAILABILITY" components in calendar + collections that contribute to free-busy, or in any + "VAVAILABILITY" components stored in the CALDAV:calendar- + availability property on the CalDAV scheduling Inbox collection of + the calendar user targeted by the iTIP free-busy request, if the + CalDAV calendar-auto-schedule feature is available. + + Processing of "VAVAILABILITY" components MUST conform to all the + requirements CalDAV imposes on calendar object resources (see + Section 4.1 of [RFC4791]). + + + + + + + + + + + +Daboo & Douglass Standards Track [Page 15] + +RFC 7953 Calendar Availability August 2016 + + +7.2. New Features in CalDAV + +7.2.1. Calendar Availability Support + + A server supporting the features described in this document MUST + include "calendar-availability" as a field in the DAV response header + from an OPTIONS request. A value of "calendar-availability" in the + DAV response header indicates to clients that the server supports all + the requirements specified in this document. + +7.2.1.1. Example: Using OPTIONS for the Discovery of Calendar + Availability Support + + >> Request << + + OPTIONS /home/bernard/calendars/ HTTP/1.1 + Host: cal.example.com + + >> Response << + + HTTP/1.1 200 OK + Allow: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, COPY, MOVE + Allow: PROPFIND, PROPPATCH, LOCK, UNLOCK, REPORT, ACL + DAV: 1, 2, 3, access-control, calendar-access, + calendar-availability + Date: Fri, 11 Nov 2005 09:32:12 GMT + Content-Length: 0 + + In this example, the OPTIONS method returns the value "calendar- + availability" in the DAV response header to indicate that the + collection "/home/bernard/calendars/" supports the new features + defined in this specification. + +7.2.2. CalDAV Time Range Queries + + Section 9.9 of [RFC4791] describes how to specify time ranges to + limit the set of calendar components returned by the server. This + specification extends [RFC4791] to describe how to apply time range + filtering to "VAVAILABILITY" components. + + A "VAVAILABILITY" component is said to overlap a given time range if + the condition for the corresponding component state specified in the + table below is satisfied. The conditions depend on the presence of + the "DTSTART", "DTEND", and "DURATION" properties in the + "VAVAILABILITY" component. Note that, as specified above, the + "DTEND" value MUST be a "DATE-TIME" value equal to or after the + "DTSTART" value, if specified. + + + + +Daboo & Douglass Standards Track [Page 16] + +RFC 7953 Calendar Availability August 2016 + + + +------------------------------------------------------------+ + | VAVAILABILITY has the DTSTART property? | + | +--------------------------------------------------------+ + | | VAVAILABILITY has the DTEND property? | + | | +----------------------------------------------------+ + | | | VAVAILABILITY has the DURATION property? | + | | | +------------------------------------------------+ + | | | | Condition to evaluate | + +---+---+---+------------------------------------------------+ + | Y | Y | N | (start < DTEND AND end > DTSTART) | + +---+---+---+------------------------------------------------+ + | Y | N | Y | (start < DTSTART+DURATION AND end > DTSTART) | + +---+---+---+------------------------------------------------+ + | Y | N | N | (end > DTSTART) | + +---+---+---+------------------------------------------------+ + | N | Y | N | (start < DTEND) | + +---+---+---+------------------------------------------------+ + | N | N | * | TRUE | + +---+---+---+------------------------------------------------+ + +7.2.3. CALDAV:free-busy-query REPORT + + A CALDAV:free-busy-query REPORT can be executed on a calendar + collection that contains iCalendar "VAVAILABILITY" components. When + that occurs, the server MUST aggregate the information in any + "VAVAILABILITY" components when generating the free-busy response, as + described in Section 5. + +7.2.4. CALDAV:calendar-availability Property + + Name: calendar-availability + + Namespace: urn:ietf:params:xml:ns:caldav + + Purpose: Defines a "VAVAILABILITY" component that will be used in + calculating free-busy time when an iTIP free-busy request is + targeted at the calendar user who owns the Inbox. + + Conformance: This property MAY be protected and SHOULD NOT be + returned by a PROPFIND DAV:allprop request. Support for this + property is REQUIRED. The value of this property MUST be a valid + iCalendar object containing only one "VAVAILABILITY" component, + and optionally, "VTIMEZONE" components - other iCalendar + components MUST NOT be present. "VTIMEZONE" components SHOULD NOT + be present if [RFC7809] is in effect. For more complex + availability scenarios, clients can store multiple "VAVAILABILITY" + components in the calendar user's calendar collections. + + + + +Daboo & Douglass Standards Track [Page 17] + +RFC 7953 Calendar Availability August 2016 + + + Description: This property allows a user to specify their + availability by including an "VAVAILABILITY" component in the + value of this property. If present, the server MUST use this + "VAVAILABILITY" component when determining free-busy information + as part of an iTIP free-busy request being handled by the server. + + Definition: + + + ; Data value MUST be an iCalendar object containing + ; "VAVAILABILITY" or "VTIMEZONE" components. + + Example: + + BEGIN:VCALENDAR + CALSCALE:GREGORIAN + PRODID:-//example.com//iCalendar 2.0//EN + VERSION:2.0 + BEGIN:VAVAILABILITY + UID:9BADC1F6-0FC4-44BF-AC3D-993BEC8C962A + DTSTAMP:20111005T133225Z + DTSTART;TZID=America/Montreal:20111002T000000 + BEGIN:AVAILABLE + UID:6C9F69C3-BDA8-424E-B2CB-7012E796DDF7 + SUMMARY:Monday to Friday from 9:00 to 18:00 + DTSTART;TZID=America/Montreal:20111002T090000 + DTEND;TZID=America/Montreal:20111002T180000 + RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR + END:AVAILABLE + END:VAVAILABILITY + END:VCALENDAR + + +7.2.5. iTIP Free-Busy Requests + + The CalDAV calendar-auto-schedule feature (see Section 5 of + [RFC6638]) includes a mechanism for free-busy information to be + requested via the CalDAV protocol. Any "VAVAILABILITY" components in + any calendar collections targeted during such a request MUST be + included as part of the calculation of the overall free-busy + information. In addition, the "VAVAILABILITY" component specified in + the CALDAV:calendar-availability property on the owner's Inbox MUST + also be included in the free-busy calculation. Processing of all + such "VAVAILABILITY" components is done as per Section 5. + + + + + +Daboo & Douglass Standards Track [Page 18] + +RFC 7953 Calendar Availability August 2016 + + +8. Security Considerations + + Calculation of availability information, particularly with multiple + overlapping time ranges, can be complex, and CalDAV servers MUST + limit the complexity of such data stored by a client. + + An attacker able to "inject" availability information into a calendar + user's calendar data could ensure that the user never appears free + for meetings or appears free at inappropriate times. Calendar + systems MUST ensure that availability information for a calendar user + can only be modified by authorized users. + + Security considerations in [RFC5545], [RFC5546], [RFC4791], + [RFC6638], and [RFC7809] MUST also be adhered to. + +9. Privacy Considerations + + Free-busy and availability information can be used by attackers to + infer the whereabouts or overall level of "activity" of the + corresponding calendar user. Any calendar system that allows a user + to expose their free-busy and availability information MUST limit + access to that information to only authorized users. + + When "VAVAILABILITY" components are sent to or shared with other + calendar users, care has to be taken not to expose more information + than is needed by each recipient. For example, a business owner will + likely not want their customers to know where they might be or what + they might be doing, but family members might be willing to expose + such information to each other. Thus, calendaring systems allowing + "VAVAILABILITY" components to be sent or shared to other calendar + users MUST provide a way for nonessential properties to be removed + (e.g., "SUMMARY", "LOCATION", and "DESCRIPTION"). + + iCalendar "VFREEBUSY" information generated from "VAVAILABILITY" + components MUST NOT include information other than busy or free time + periods. In particular, user specified property values such as + "SUMMARY", "LOCATION", and "DESCRIPTION" MUST NOT be copied into the + free-busy result data. + + Privacy considerations in [RFC5545], [RFC5546], [RFC4791], [RFC6638], + and [RFC7809] MUST also be adhered to. + + + + + + + + + + +Daboo & Douglass Standards Track [Page 19] + +RFC 7953 Calendar Availability August 2016 + + +10. IANA Considerations + +10.1. Component Registrations + + This document defines the following new iCalendar components, which + have been added to the registry defined in Section 8.3.1 of + [RFC5545]: + + +---------------+---------+------------------------+ + | Component | Status | Reference | + +---------------+---------+------------------------+ + | VAVAILABILITY | Current | RFC 7953, Section 3.1 | + | AVAILABLE | Current | RFC 7953, Section 3.1 | + +---------------+---------+------------------------+ + +10.2. Property Registrations + + This documents defines the following new iCalendar properties, which + have been added to the registry defined in Section 8.3.2 of + [RFC5545]: + + +----------+---------+------------------------+ + | Property | Status | Reference | + +----------+---------+------------------------+ + | BUSYTYPE | Current | RFC 7953, Section 3.2 | + +----------+---------+------------------------+ + +11. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, + "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, + DOI 10.17487/RFC4791, March 2007, + . + + [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and + Scheduling Core Object Specification (iCalendar)", + RFC 5545, DOI 10.17487/RFC5545, September 2009, + . + + [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent + Interoperability Protocol (iTIP)", RFC 5546, + DOI 10.17487/RFC5546, December 2009, + . + + + +Daboo & Douglass Standards Track [Page 20] + +RFC 7953 Calendar Availability August 2016 + + + [RFC6638] Daboo, C. and B. Desruisseaux, "Scheduling Extensions to + CalDAV", RFC 6638, DOI 10.17487/RFC6638, June 2012, + . + + [RFC7809] Daboo, C., "Calendaring Extensions to WebDAV (CalDAV): + Time Zones by Reference", RFC 7809, DOI 10.17487/RFC7809, + March 2016, . + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Daboo & Douglass Standards Track [Page 21] + +RFC 7953 Calendar Availability August 2016 + + +Appendix A. Example Calendar #1 + + BEGIN:VCALENDAR + CALSCALE:GREGORIAN + PRODID:-//example.com//iCalendar 2.0//EN + VERSION:2.0 + BEGIN:VEVENT + DTSTAMP:20111113T044111Z + DTSTART;TZID=America/Montreal:20111106T120000 + DURATION:PT2H + SUMMARY:Meeting + UID:768CB0C2-8642-43F7-A6C4-F8BB04B829B4 + END:VEVENT + BEGIN:VAVAILABILITY + UID:452DFCA7-3203-4A3D-9A9A-99753A383B41 + DTSTAMP:20111005T133225Z + DTSTART;TZID=America/Montreal:20111002T000000 + BEGIN:AVAILABLE + UID:466D5C68-5C4A-4078-AF5D-9C55EA9145D7 + SUMMARY:Monday to Friday from 8:00 to 18:00 + DTSTART;TZID=America/Montreal:20111002T080000 + DTEND;TZID=America/Montreal:20111002T180000 + RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR + END:AVAILABLE + END:VAVAILABILITY + END:VCALENDAR + + + + + + + + + + + + + + + + + + + + + + + + + +Daboo & Douglass Standards Track [Page 22] + +RFC 7953 Calendar Availability August 2016 + + +Appendix B. Example Calendar #2 + + BEGIN:VCALENDAR + CALSCALE:GREGORIAN + PRODID:-//example.com//iCalendar 2.0//EN + VERSION:2.0 + BEGIN:VEVENT + DTSTAMP:20111113T044111Z + DTSTART;TZID=America/Denver:20111106T120000 + DURATION:PT2H + SUMMARY:Lunch meeting in Denver + UID:2346C09A-42BF-439E-916C-FC83AF869171 + END:VEVENT + BEGIN:VAVAILABILITY + ORGANIZER:mailto:bernard@example.com + UID:627A87FA-E5F1-43C0-B3B1-567DA10F2A83 + DTSTAMP:20111005T133225Z + DTSTART;TZID=America/Montreal:20111002T000000 + BEGIN:AVAILABLE + UID:A833E850-892B-43F6-98B6-C15A6BFC5D27 + SUMMARY:Monday to Friday from 9:00 to 17:00 + DTSTART;TZID=America/Montreal:20111002T080000 + DTEND;TZID=America/Montreal:20111002T180000 + RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR + LOCATION:Montreal + END:AVAILABLE + END:VAVAILABILITY + BEGIN:VAVAILABILITY + ORGANIZER:mailto:bernard@example.com + UID:F01411E3-38B8-4490-8A1F-0CCEC57A0943 + DTSTAMP:20111005T133225Z + DTSTART;TZID=America/Denver:20111023T000000 + DTEND;TZID=America/Denver:20111030T000000 + PRIORITY:1 + BEGIN:AVAILABLE + UID:A35AA091-3846-48ED-96F6-881E8A0D0A93 + SUMMARY:Monday to Friday from 9:00 to 17:00 + DTSTART;TZID=America/Denver:20111023T080000 + DTEND;TZID=America/Denver:20111023T180000 + RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR + LOCATION:Denver + END:AVAILABLE + END:VAVAILABILITY + END:VCALENDAR + + + + + + + +Daboo & Douglass Standards Track [Page 23] + +RFC 7953 Calendar Availability August 2016 + + +Acknowledgements + + Thanks to the following for providing feedback: Toby Considine, + Bernard Desruisseaux, Alexey Melnikov, Daniel Migault, Ken Murchison, + Evert Pot, and Dave Thewlis. This specification came about via + discussions at the Calendaring and Scheduling Consortium. + +Authors' Addresses + + Cyrus Daboo + Apple Inc. + 1 Infinite Loop + Cupertino, CA 95014 + United States of America + + Email: cyrus@daboo.name + URI: http://www.apple.com/ + + + Michael Douglass + Spherical Cow Group + 226 3rd Street + Troy, NY 12180 + United States of America + + Email: mdouglass@sphericalcowgroup.com + URI: http://sphericalcowgroup.com + + + + + + + + + + + + + + + + + + + + + + + + +Daboo & Douglass Standards Track [Page 24] + diff --git a/specs/rfc7986-new-ical-props.txt b/specs/rfc7986-new-ical-props.txt new file mode 100644 index 0000000..a06d53f --- /dev/null +++ b/specs/rfc7986-new-ical-props.txt @@ -0,0 +1,1291 @@ + + + + + + +Internet Engineering Task Force (IETF) C. Daboo +Request for Comments: 7986 Apple Inc. +Updates: 5545 October 2016 +Category: Standards Track +ISSN: 2070-1721 + + + New Properties for iCalendar + +Abstract + + This document defines a set of new properties for iCalendar data and + extends the use of some existing properties to the entire iCalendar + object. + +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 7841. + + 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/rfc7986. + +Copyright Notice + + Copyright (c) 2016 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 Standards Track [Page 1] + +RFC 7986 iCalendar Property Extensions October 2016 + + +Table of Contents + + 1. Introduction ....................................................3 + 2. Conventions Used in This Document ...............................3 + 3. Backwards-Compatible Extension Properties .......................3 + 4. Modifications to Calendar Components ............................4 + 5. Properties ......................................................5 + 5.1. NAME Property ..............................................5 + 5.2. DESCRIPTION Property .......................................6 + 5.3. UID Property ...............................................7 + 5.4. LAST-MODIFIED Property .....................................8 + 5.5. URL Property ...............................................8 + 5.6. CATEGORIES Property ........................................8 + 5.7. REFRESH-INTERVAL Property ..................................9 + 5.8. SOURCE Property ...........................................10 + 5.9. COLOR Property ............................................10 + 5.10. IMAGE Property ...........................................11 + 5.11. CONFERENCE Property ......................................13 + 6. Property Parameters ............................................14 + 6.1. DISPLAY Property Parameter ................................14 + 6.2. EMAIL Property Parameter ..................................15 + 6.3. FEATURE Property Parameter ................................16 + 6.4. LABEL Property Parameter ..................................17 + 7. Security Considerations ........................................18 + 8. Privacy Considerations .........................................18 + 9. IANA Considerations ............................................19 + 9.1. Property Registrations ....................................19 + 9.2. Parameter Registrations ...................................20 + 9.3. Property Parameter Value Registries .......................20 + 10. References ....................................................21 + 10.1. Normative References .....................................21 + 10.2. Informative References ...................................22 + Acknowledgments ...................................................23 + Author's Address ..................................................23 + + + + + + + + + + + + + + + + + +Daboo Standards Track [Page 2] + +RFC 7986 iCalendar Property Extensions October 2016 + + +1. Introduction + + The iCalendar [RFC5545] data format is used to represent calendar + data and is used with the iCalendar Transport-Independent + Interoperability Protocol (iTIP) [RFC5546] to handle scheduling + operations between calendar users. iCalendar is in widespread use, + and in accordance with provisions in that specification, extension + elements have been added by various vendors to the data format in + order to support and enhance capabilities. This specification + collects a number of these ad hoc extensions and uses the new IANA + registry capability defined in [RFC5545] to register standard + variants with clearly defined definitions and semantics. In + addition, some new elements are introduced for features that vendors + have recently been requesting. + +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]. + + 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]. + +3. Backwards-Compatible Extension Properties + + iCalendar defines properties that can have different value types + indicated by a "VALUE" parameter. The definition of a property + specifies a "default" value type that is assumed to be used when no + "VALUE" parameter is present. However, this poses a problem to the + iCalendar parser/generator software that does not know about the + default values for new properties. For example, if a new property + "FOO" were defined with a default value type of URI and a URI value + with a comma was used, an iCalendar generator not aware of this fact + would likely treat the property value as "TEXT" and apply backslash + escaping to the comma in the value, effectively making it an invalid + URI value. + + To avoid this problem, this specification recommends that all + properties not defined in [RFC5545] always include a "VALUE" + parameter if the type is other than "TEXT". That is, in the example + above, the "FOO" property would have a "VALUE=URI" parameter. This + allows iCalendar parser/generator software to track the correct types + of unknown properties. + + + + +Daboo Standards Track [Page 3] + +RFC 7986 iCalendar Property Extensions October 2016 + + + New properties defined in this specification use the term "no + default" in the "Value Type" definition to indicate that the "VALUE" + parameter has to be included. + +4. Modifications to Calendar Components + + This section details changes to the syntax defined in iCalendar + [RFC5545]. New elements are defined in subsequent sections. + + calprops =/ *( + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + uid / last-mod / url / + refresh / source / color + ; + ; The following are OPTIONAL, + ; and MAY occur more than once. + ; + name / description / categories / + image + ; + ) + + eventprop =/ *( + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + color / + ; + ; The following are OPTIONAL, + ; and MAY occur more than once. + ; + conference / image + ; + ) + + todoprop =/ *( + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + color / + ; + ; The following are OPTIONAL, + ; and MAY occur more than once. + + + +Daboo Standards Track [Page 4] + +RFC 7986 iCalendar Property Extensions October 2016 + + + ; + conference / image + ; + ) + + jourprop =/ *( + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + color / + ; + ; The following are OPTIONAL, + ; and MAY occur more than once. + ; + image + ; + ) + +5. Properties + +5.1. NAME Property + + Property Name: NAME + + Purpose: This property specifies the name of the calendar. + + Value Type: TEXT + + Property Parameters: IANA, non-standard, alternate text + representation, and language property parameters can be specified + on this property. + + Conformance: This property can be specified multiple times in an + iCalendar object. However, each property MUST represent the name + of the calendar in a different language. + + Description: This property is used to specify a name of the + iCalendar object that can be used by calendar user agents when + presenting the calendar data to a user. Whilst a calendar only + has a single name, multiple language variants can be specified by + including this property multiple times with different "LANGUAGE" + parameter values on each. + + + + + + + + +Daboo Standards Track [Page 5] + +RFC 7986 iCalendar Property Extensions October 2016 + + + Format Definition: This property is defined by the following + notation: + + name = "NAME" nameparam ":" text CRLF + + nameparam = *( + ; + ; The following are OPTIONAL, + ; but MUST NOT occur more than once. + ; + (";" altrepparam) / (";" languageparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + Example: The following is an example of this property: + + NAME:Company Vacation Days + +5.2. DESCRIPTION Property + + This specification modifies the definition of the "DESCRIPTION" + property to allow it to be defined in an iCalendar object. The + following additions are made to the definition of this property, + originally specified in Section 3.8.1.5 of [RFC5545]. + + Purpose: This property specifies the description of the calendar. + + Conformance: This property can be specified multiple times in an + iCalendar object. However, each property MUST represent the + description of the calendar in a different language. + + Description: This property is used to specify a lengthy textual + description of the iCalendar object that can be used by calendar + user agents when describing the nature of the calendar data to a + user. Whilst a calendar only has a single description, multiple + language variants can be specified by including this property + multiple times with different "LANGUAGE" parameter values on each. + + + + + + + + + +Daboo Standards Track [Page 6] + +RFC 7986 iCalendar Property Extensions October 2016 + + +5.3. UID Property + + This specification modifies the definition of the "UID" property to + allow it to be defined in an iCalendar object. The following + additions are made to the definition of this property, originally + specified in Section 3.8.4.7 of [RFC5545]. + + Purpose: This property specifies the persistent, globally unique + identifier for the iCalendar object. This can be used, for + example, to identify duplicate calendar streams that a client may + have been given access to. It can be used in conjunction with the + "LAST-MODIFIED" property also specified on the "VCALENDAR" object + to identify the most recent version of a calendar. + + Conformance: This property can be specified once in an iCalendar + object. + + The description of the "UID" property in [RFC5545] contains some + recommendations on how the value can be constructed. In particular, + it suggests use of host names, IP addresses, and domain names to + construct the value. However, this is no longer considered good + practice, particularly from a security and privacy standpoint, since + use of such values can leak key information about a calendar user or + their client and network environment. This specification updates + [RFC5545] by stating that "UID" values MUST NOT include any data that + might identify a user, host, domain, or any other security- or + privacy-sensitive information. It is RECOMMENDED that calendar user + agents now generate "UID" values that are hex-encoded random + Universally Unique Identifier (UUID) values as defined in + Sections 4.4 and 4.5 of [RFC4122]. + + The following is an example of such a property value: + + UID:5FC53010-1267-4F8E-BC28-1D7AE55A7C99 + + Additionally, if calendar user agents choose to use other forms of + opaque identifiers for the "UID" value, they MUST have a length less + than 255 octets and MUST conform to the "iana-token" ABNF syntax + defined in Section 3.1 of [RFC5545]. + + + + + + + + + + + + +Daboo Standards Track [Page 7] + +RFC 7986 iCalendar Property Extensions October 2016 + + +5.4. LAST-MODIFIED Property + + This specification modifies the definition of the "LAST-MODIFIED" + property to allow it to be defined in an iCalendar object. The + following additions are made to the definition of this property, + originally specified in Section 3.8.7.3 of [RFC5545]. + + Purpose: This property specifies the date and time that the + information associated with the calendar was last revised. + + Conformance: This property can be specified once in an iCalendar + object. + +5.5. URL Property + + This specification modifies the definition of the "URL" property to + allow it to be defined in an iCalendar object. The following + additions are made to the definition of this property, originally + specified in Section 3.8.4.6 of [RFC5545]. + + Purpose: This property may be used to convey a location where a more + dynamic rendition of the calendar information can be found. + + Conformance: This property can be specified once in an iCalendar + object. + +5.6. CATEGORIES Property + + This specification modifies the definition of the "CATEGORIES" + property to allow it to be defined in an iCalendar object. The + following additions are made to the definition of this property, + originally specified in Section 3.8.1.2 of [RFC5545]. + + Purpose: This property defines the categories for an entire + calendar. + + Conformance: This property can be specified multiple times in an + iCalendar object. + + Description: When multiple properties are present, the set of + categories that apply to the iCalendar object are the union of all + the categories listed in each property value. + + + + + + + + + +Daboo Standards Track [Page 8] + +RFC 7986 iCalendar Property Extensions October 2016 + + +5.7. REFRESH-INTERVAL Property + + Property Name: REFRESH-INTERVAL + + Purpose: This property specifies a suggested minimum interval for + polling for changes of the calendar data from the original source + of that data. + + Value Type: DURATION -- no default + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property can be specified once in an iCalendar + object. + + Description: This property specifies a positive duration that gives + a suggested minimum polling interval for checking for updates to + the calendar data. The value of this property SHOULD be used by + calendar user agents to limit the polling interval for calendar + data updates to the minimum interval specified. + + Format Definition: This property is defined by the following + notation: + + refresh = "REFRESH-INTERVAL" refreshparam + ":" dur-value CRLF + ;consisting of a positive duration of time. + + refreshparam = *( + ; + ; The following is REQUIRED, + ; but MUST NOT occur more than once. + ; + (";" "VALUE" "=" "DURATION") / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + Example: The following is an example of this property: + + REFRESH-INTERVAL;VALUE=DURATION:P1W + + + + + +Daboo Standards Track [Page 9] + +RFC 7986 iCalendar Property Extensions October 2016 + + +5.8. SOURCE Property + + Property Name: SOURCE + + Purpose: This property identifies a URI where calendar data can be + refreshed from. + + Value Type: URI -- no default + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property can be specified once in an iCalendar + object. + + Description: This property identifies a location where a client can + retrieve updated data for the calendar. Clients SHOULD honor any + specified "REFRESH-INTERVAL" value when periodically retrieving + data. Note that this property differs from the "URL" property in + that "URL" is meant to provide an alternative representation of + the calendar data rather than the original location of the data. + + Format Definition: This property is defined by the following + notation: + + source = "SOURCE" sourceparam ":" uri CRLF + + sourceparam = *(";" other-param) + + Example: The following is an example of this property: + + SOURCE;VALUE=URI:https://example.com/holidays.ics + +5.9. COLOR Property + + Property Name: COLOR + + Purpose: This property specifies a color used for displaying the + calendar, event, todo, or journal data. + + Value Type: TEXT + + Property Parameters: IANA and non-standard property parameters can + be specified on this property. + + Conformance: This property can be specified once in an iCalendar + object or in "VEVENT", "VTODO", or "VJOURNAL" calendar components. + + + + +Daboo Standards Track [Page 10] + +RFC 7986 iCalendar Property Extensions October 2016 + + + Description: This property specifies a color that clients MAY use + when presenting the relevant data to a user. Typically, this + would appear as the "background" color of events or tasks. The + value is a case-insensitive color name taken from the CSS3 set of + names, defined in Section 4.3 of [W3C.REC-css3-color-20110607]. + + Format Definition: This property is defined by the following + notation: + + color = "COLOR" colorparam ":" text CRLF + ; Value is CSS3 color name + + colorparam = *(";" other-param) + + Example: The following is an example of this property: + + COLOR:turquoise + +5.10. IMAGE Property + + Property Name: IMAGE + + Purpose: This property specifies an image associated with the + calendar or a calendar component. + + Value Type: URI or BINARY -- no default. The value MUST be data + with a media type of "image" or refer to such data. + + Property Parameters: IANA, non-standard, display, inline encoding, + and value data type property parameters can be specified on this + property. The format type parameter can be specified on this + property and is RECOMMENDED for inline binary-encoded content + information. + + Conformance: This property can be specified multiple times in an + iCalendar object or in "VEVENT", "VTODO", or "VJOURNAL" calendar + components. + + Description: This property specifies an image for an iCalendar + object or a calendar component via a URI or directly with inline + data that can be used by calendar user agents when presenting the + calendar data to a user. Multiple properties MAY be used to + specify alternative sets of images with, for example, varying + media subtypes, resolutions, or sizes. When multiple properties + are present, calendar user agents SHOULD display only one of them, + picking one that provides the most appropriate image quality, or + display none. The "DISPLAY" parameter is used to indicate the + intended display mode for the image. The "ALTREP" parameter, + + + +Daboo Standards Track [Page 11] + +RFC 7986 iCalendar Property Extensions October 2016 + + + defined in [RFC5545], can be used to provide a "clickable" image + where the URI in the parameter value can be "launched" by a click + on the image in the calendar user agent. + + Format Definition: This property is defined by the following + notation: + + image = "IMAGE" imageparam + ( + ( + ";" "VALUE" "=" "URI" + ":" uri + ) / + ( + ";" "ENCODING" "=" "BASE64" + ";" "VALUE" "=" "BINARY" + ":" binary + ) + ) + CRLF + + imageparam = *( + ; + ; The following is OPTIONAL for a URI value, + ; RECOMMENDED for a BINARY value, + ; and MUST NOT occur more than once. + ; + (";" fmttypeparam) / + ; + ; The following are OPTIONAL, + ; and MUST NOT occur more than once. + ; + (";" altrepparam) / (";" displayparam) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + Example: The following is an example of this property: + + IMAGE;VALUE=URI;DISPLAY=BADGE;FMTTYPE=image/png:h + ttp://example.com/images/party.png + + + + + + +Daboo Standards Track [Page 12] + +RFC 7986 iCalendar Property Extensions October 2016 + + +5.11. CONFERENCE Property + + Property Name: CONFERENCE + + Purpose: This property specifies information for accessing a + conferencing system. + + Value Type: URI -- no default. + + Property Parameters: IANA, non-standard, feature, and label property + parameters can be specified on this property. + + Conformance: This property can be specified multiple times in a + "VEVENT" or "VTODO" calendar component. + + Description: This property specifies information for accessing a + conferencing system for attendees of a meeting or task. This + might be for a telephone-based conference number dial-in with + access codes included (such as a tel: URI [RFC3966] or a sip: or + sips: URI [RFC3261]), for a web-based video chat (such as an http: + or https: URI [RFC7230]), or for an instant messaging group chat + room (such as an xmpp: URI [RFC5122]). If a specific URI for a + conferencing system is not available, a data: URI [RFC2397] + containing a text description can be used. + + A conference system can be a bidirectional communication channel + or a uni-directional "broadcast feed". + + The "FEATURE" property parameter is used to describe the key + capabilities of the conference system to allow a client to choose + the ones that give the required level of interaction from a set of + multiple properties. + + The "LABEL" property parameter is used to convey additional + details on the use of the URI. For example, the URIs or access + codes for the moderator and attendee of a teleconference system + could be different, and the "LABEL" property parameter could be + used to "tag" each "CONFERENCE" property to indicate which is + which. + + The "LANGUAGE" property parameter can be used to specify the + language used for text values used with this property (as per + Section 3.2.10 of [RFC5545]). + + + + + + + + +Daboo Standards Track [Page 13] + +RFC 7986 iCalendar Property Extensions October 2016 + + + Format Definition: This property is defined by the following + notation: + + conference = "CONFERENCE" confparam ":" uri CRLF + + confparam = *( + ; + ; The following is REQUIRED, + ; but MUST NOT occur more than once. + ; + (";" "VALUE" "=" "URI") / + ; + ; The following are OPTIONAL, + ; and MUST NOT occur more than once. + ; + (";" featureparam) / (";" labelparam) / + (";" languageparam ) / + ; + ; The following is OPTIONAL, + ; and MAY occur more than once. + ; + (";" other-param) + ; + ) + + Example: The following are examples of this property: + + CONFERENCE;VALUE=URI;FEATURE=PHONE,MODERATOR; + LABEL=Moderator dial-in:tel:+1-412-555-0123,,,654321 + CONFERENCE;VALUE=URI;FEATURE=PHONE; + LABEL=Attendee dial-in:tel:+1-412-555-0123,,,555123 + CONFERENCE;VALUE=URI;FEATURE=PHONE; + LABEL=Attendee dial-in:tel:+1-888-555-0456,,,555123 + CONFERENCE;VALUE=URI;FEATURE=CHAT; + LABEL=Chat room:xmpp:chat-123@conference.example.com + CONFERENCE;VALUE=URI;FEATURE=AUDIO,VIDEO; + LABEL=Attendee dial-in:https://chat.example.com/audio?id=123456 + +6. Property Parameters + +6.1. DISPLAY Property Parameter + + Parameter Name: DISPLAY + + Purpose: To specify different ways in which an image for a calendar + or component can be displayed. + + + + + +Daboo Standards Track [Page 14] + +RFC 7986 iCalendar Property Extensions October 2016 + + + Format Definition: This property parameter is defined by the + following notation: + + displayparam = "DISPLAY" "=" displayval *("," displayval) + + displayval = ("BADGE" / ; image inline with the title of the + ; event + "GRAPHIC" / ; a full image replacement for the event + ; itself + "FULLSIZE" / ; an image that is used to enhance the + ; event + "THUMBNAIL" / ; a smaller variant of "FULLSIZE" to be + ; used when space for the image is + ; constrained + x-name / ; Experimental type + iana-token) ; Other IANA-registered type + ; + ; Default is BADGE + + Description: This property parameter MAY be specified on "IMAGE" + properties. In the absence of this parameter, the default value + "BADGE" MUST be used. The value determines how a client ought to + present an image supplied in iCalendar data to the user. + + Values for this parameter are registered with IANA as per + Section 9.3.1. New values can be added to this registry following + the procedure outlined in Section 8.2.1 of [RFC5545]. + + Servers and clients MUST handle x-name and iana-token values they + don't recognize by not displaying any image at all. + + Example: + + IMAGE;VALUE=URI;DISPLAY=BADGE,THUMBNAIL;FMTTYPE=image/png:https://exa + mple.com/images/weather-cloudy.png + +6.2. EMAIL Property Parameter + + Parameter Name: EMAIL + + Purpose: To specify an email address that is used to identify or + contact an organizer or attendee. + + Format Definition: This property parameter is defined by the + following notation: + + emailparam = "EMAIL" "=" param-value + + + + +Daboo Standards Track [Page 15] + +RFC 7986 iCalendar Property Extensions October 2016 + + + Description: This property parameter MAY be specified on "ORGANIZER" + or "ATTENDEE" properties. This property can be used in situations + where the calendar user address value of the "ORGANIZER" and + "ATTENDEE" properties is not likely to be an identifier that + recipients of scheduling messages could use to match the calendar + user with, for example, an address book entry. The value of this + property is an email address that can easily be matched by + recipients. Recipients can also use this value as an alternative + means of contacting the calendar user via email. If a recipient's + calendar user agent allows the recipient to save contact + information based on the "ORGANIZER" or "ATTENDEE" properties, + those calendar user agents SHOULD use any "EMAIL" property + parameter value for the email address of the contact over any + mailto: calendar user address specified as the value of the + property. Calendar user agents SHOULD NOT include an "EMAIL" + property parameter when its value matches the calendar user + address specified as the value of the property. + + Example: + + ATTENDEE;CN=Cyrus Daboo;EMAIL=cyrus@example.com:mailto:opaque-toke + n-1234@example.com + +6.3. FEATURE Property Parameter + + Parameter Name: FEATURE + + Purpose: To specify a feature or features of a conference or + broadcast system. + + Format Definition: This property parameter is defined by the + following notation: + + featureparam = "FEATURE" "=" featuretext *("," featuretext) + featuretext = ("AUDIO" / ; Audio capability + "CHAT" / ; Chat or instant messaging + "FEED" / ; Blog or Atom feed + "MODERATOR" / ; Moderator dial-in code + "PHONE" / ; Phone conference + "SCREEN" / ; Screen sharing + "VIDEO" / ; Video capability + x-name / ; Experimental type + iana-token) ; Other IANA-registered type + + + + + + + + +Daboo Standards Track [Page 16] + +RFC 7986 iCalendar Property Extensions October 2016 + + + Description: This property parameter MAY be specified on the + "CONFERENCE" property. Multiple values can be specified. The + "MODERATOR" value is used to indicate that the property value is + specific to the owner/initiator of the conference and contains a + URI that "activates" the system (e.g., a "moderator" access code + for a phone conference system that is different from the "regular" + access code). + + Example: + + CONFERENCE;VALUE=URI;FEATURE=AUDIO:rtsp://audio.example.com/ + event + CONFERENCE;VALUE=URI;FEATURE=AUDIO,VIDEO:https://video-chat.exam + ple.com/;group-id=1234 + +6.4. LABEL Property Parameter + + Parameter Name: LABEL + + Purpose: To provide a human-readable label. + + Format Definition: This property parameter is defined by the + following notation: + + labelparam = "LABEL" "=" param-value + + Description: This property parameter MAY be specified on the + "CONFERENCE" property. It is anticipated that other extensions to + iCalendar will reuse this property parameter on new properties + that they define. As a result, clients MUST expect to find this + property parameter present on many different properties. It + provides a human-readable label that can be presented to calendar + users to allow them to discriminate between properties that might + be similar or provide additional information for properties that + are not self-describing. The "LANGUAGE" property parameter can be + used to specify the language of the text in the parameter value + (as per Section 3.2.10 of [RFC5545]). + + Example: + + CONFERENCE;VALUE=URI;FEATURE=VIDEO; + LABEL="Web video chat, access code=76543"; + :https://video-chat.example.com/;group-id=1234 + + + + + + + + +Daboo Standards Track [Page 17] + +RFC 7986 iCalendar Property Extensions October 2016 + + +7. Security Considerations + + Several of the new properties or parameters defined by this + specification allow reference to "external" URIs. Care MUST be taken + when accessing data at external URIs as malicious content could be + present. Clients SHOULD ensure that suitable permission is granted + by calendar users before such URIs are dereferenced. + + The "REFRESH-INTERVAL" property could be used by an attacker to make + a client carry out rapid requests to the server hosting the calendar + by specifying a very short duration (e.g., one second). This could + lead to resource consumption on the client or server and to denial- + of-service attacks against the server. Clients MUST ensure that they + throttle requests to the server to a reasonable rate. In most cases, + updating a public calendar once per day would suffice. If the + "REFRESH-INTERVAL" is any less than that, clients SHOULD warn the + calendar user and allow them to override it with a longer value. + + The "CONFERENCE" property can include a "FEATURE" property parameter + with a "MODERATOR" value. In some cases, the access code used by the + owner/initiator of a conference might be private to an individual, + and clients and servers MUST ensure that such properties are not sent + to attendees of a scheduled component. + + Both the "COLOR" and "IMAGE" properties are likely to be used by + calendar users to express their own personal view of the calendar + data. In addition, these properties could be used by attackers to + produce a confusing display in a calendar user agent. When such + properties are encountered in calendar data that has come from other + calendar users (e.g., via a scheduling message, "public" calendar + subscription, etc.), it is advisable for the client to give the + receiving calendar user the option to remove (or adjust) these + properties as the data is imported into their calendar system. + + This specification changes the recommendations on how "UID" property + values are constructed to minimize leaking any information that might + be security sensitive. + + Security considerations in [RFC5545] and [RFC5546] MUST also be + adhered to. + +8. Privacy Considerations + + Several of the new properties or parameters defined by this + specification allow reference to "external" URIs. Access to those + URIs could be tracked, leading to loss of privacy. Clients SHOULD + ensure that suitable permission is granted by calendar users before + such URIs are dereferenced. In particular, calendar publishers + + + +Daboo Standards Track [Page 18] + +RFC 7986 iCalendar Property Extensions October 2016 + + + wishing to help protect the privacy of their subscribers MUST use + HTTP with Transport Layer Security [RFC7230] ("https:" URIs instead + of "http:" URIs) for access to calendar data or ancillary data such + as images. + + In general, for their own privacy protection, users have to rely on + the privacy policies of any conferencing system being accessed via + the "CONFERENCE" property. It is entirely possible for such systems + to uniquely identify and log the activity and participation (or lack + thereof) of calendar users in the conference. Calendar user agents + SHOULD track which conferencing systems are used and warn users the + first time a new one is about to be used. This is particularly + important if the client automatically "dials in" to the conference + when the event start time occurs. + + By giving different calendar users different values for the "REFRESH- + INTERVAL" property, it is possible for a publisher of calendar data + to uniquely identify each refresh from each calendar users' clients + and thereby track user activity and IP address over time. To address + this, clients SHOULD add or subtract some random amount of time from + the published "REFRESH-INTERVAL" value when doing actual refreshes. + + This specification changes the recommendations on how "UID" property + values are constructed to minimize leaking any information that might + be privacy sensitive. + + Privacy considerations in [RFC5545] and [RFC5546] MUST also be + adhered to. + +9. IANA Considerations + +9.1. Property Registrations + + This document defines the following new iCalendar properties. IANA + has registered the new properties in the "Properties" registry + defined in Section 8.3.2 of [RFC5545]. IANA has also added a + reference to this document where the properties originally defined in + RFC 5545 have been updated by this document. + + + + + + + + + + + + + +Daboo Standards Track [Page 19] + +RFC 7986 iCalendar Property Extensions October 2016 + + + +------------------+---------+--------------------------------------+ + | Property | Status | Reference | + +------------------+---------+--------------------------------------+ + | NAME | Current | RFC 7986, Section 5.1 | + | DESCRIPTION | Current | RFC 5545, Section 3.8.1.5; RFC 7986, | + | | | Section 5.2 | + | UID | Current | RFC 5545, Section 3.8.4.7; RFC 7986, | + | | | Section 5.3 | + | LAST-MODIFIED | Current | RFC 5545, Section 3.8.7.3 RFC 7986, | + | | | Section 5.4 | + | URL | Current | RFC 5545, Section 3.8.4.6; RFC 7986, | + | | | Section 5.5 | + | CATEGORIES | Current | RFC 5545, Section 3.8.1.2; RFC 7986, | + | | | Section 5.6 | + | REFRESH-INTERVAL | Current | RFC 7986, Section 5.7 | + | SOURCE | Current | RFC 7986, Section 5.8 | + | COLOR | Current | RFC 7986, Section 5.9 | + | IMAGE | Current | RFC 7986, Section 5.10 | + | CONFERENCE | Current | RFC 7986, Section 5.11 | + +------------------+---------+--------------------------------------+ + +9.2. Parameter Registrations + + This document defines the following new iCalendar property + parameters. IANA has registered these in the "Parameters" registry + defined in Section 8.3.3 of [RFC5545]. + + +--------------------+---------+-----------------------+ + | Property Parameter | Status | Reference | + +--------------------+---------+-----------------------+ + | DISPLAY | Current | RFC 7986, Section 6.1 | + | EMAIL | Current | RFC 7986, Section 6.2 | + | FEATURE | Current | RFC 7986, Section 6.3 | + | LABEL | Current | RFC 7986, Section 6.4 | + +--------------------+---------+-----------------------+ + +9.3. Property Parameter Value Registries + + IANA has created two new registries for iCalendar elements: the + "Display Types" registry and the "Feature Types" registry. + Additional codes MAY be used, provided the process and template + described in Sections 8.2.1 and 8.2.6 of [RFC5545] are used to + register them. + + + + + + + + +Daboo Standards Track [Page 20] + +RFC 7986 iCalendar Property Extensions October 2016 + + +9.3.1. Display Types Registry + + The following table has been used to initialize the "Display Types" + registry. + + +--------------+---------+-----------------------+ + | Display Type | Status | Reference | + +--------------+---------+-----------------------+ + | BADGE | Current | RFC 7986, Section 6.1 | + | GRAPHIC | Current | RFC 7986, Section 6.1 | + | FULLSIZE | Current | RFC 7986, Section 6.1 | + | THUMBNAIL | Current | RFC 7986, Section 6.1 | + +--------------+---------+-----------------------+ + +9.3.2. Feature Types Registry + + The following table has been used to initialize the "Feature Types" + registry. + + +--------------+---------+-----------------------+ + | Feature Type | Status | Reference | + +--------------+---------+-----------------------+ + | AUDIO | Current | RFC 7986, Section 6.3 | + | CHAT | Current | RFC 7986, Section 6.3 | + | FEED | Current | RFC 7986, Section 6.3 | + | MODERATOR | Current | RFC 7986, Section 6.3 | + | PHONE | Current | RFC 7986, Section 6.3 | + | SCREEN | Current | RFC 7986, Section 6.3 | + | VIDEO | Current | RFC 7986, Section 6.3 | + +--------------+---------+-----------------------+ + +10. References + +10.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally + Unique IDentifier (UUID) URN Namespace", RFC 4122, + DOI 10.17487/RFC4122, July 2005, + . + + + + + + + +Daboo Standards Track [Page 21] + +RFC 7986 iCalendar Property Extensions October 2016 + + + [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, + DOI 10.17487/RFC5234, January 2008, + . + + [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and + Scheduling Core Object Specification (iCalendar)", + RFC 5545, DOI 10.17487/RFC5545, September 2009, + . + + [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent + Interoperability Protocol (iTIP)", RFC 5546, + DOI 10.17487/RFC5546, December 2009, + . + + [W3C.REC-css3-color-20110607] + Celik, T., Lilley, C., and D. Baron, "CSS Color Module + Level 3", World Wide Web Consortium Recommendation + REC-css3-color-20110607, June 2011, + . + +10.2. Informative References + + [RFC2397] Masinter, L., "The "data" URL scheme", RFC 2397, + DOI 10.17487/RFC2397, August 1998, + . + + [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, + A., Peterson, J., Sparks, R., Handley, M., and E. + Schooler, "SIP: Session Initiation Protocol", RFC 3261, + DOI 10.17487/RFC3261, June 2002, + . + + [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", + RFC 3966, DOI 10.17487/RFC3966, December 2004, + . + + [RFC5122] Saint-Andre, P., "Internationalized Resource Identifiers + (IRIs) and Uniform Resource Identifiers (URIs) for the + Extensible Messaging and Presence Protocol (XMPP)", + RFC 5122, DOI 10.17487/RFC5122, February 2008, + . + + [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer + Protocol (HTTP/1.1): Message Syntax and Routing", + RFC 7230, DOI 10.17487/RFC7230, June 2014, + . + + + + +Daboo Standards Track [Page 22] + +RFC 7986 iCalendar Property Extensions October 2016 + + +Acknowledgments + + Thanks to the following individuals for feedback: Bernard + Desruisseaux, Mike Douglass, Lucia Fedorova, Ken Murchison, Arnaud + Quillaud, and Dave Thewlis. + + This specification came about via discussions at the Calendaring and + Scheduling Consortium. + +Author's Address + + Cyrus Daboo + Apple Inc. + 1 Infinite Loop + Cupertino, CA 95014 + United States of America + + Email: cyrus@daboo.name + URI: http://www.apple.com/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Daboo Standards Track [Page 23] + diff --git a/specs/rfc9074-valarm-ext.txt b/specs/rfc9074-valarm-ext.txt new file mode 100644 index 0000000..ea6b151 --- /dev/null +++ b/specs/rfc9074-valarm-ext.txt @@ -0,0 +1,847 @@ + + + + +Internet Engineering Task Force (IETF) C. Daboo +Request for Comments: 9074 Apple +Updates: 5545 K. Murchison, Ed. +Category: Standards Track Fastmail +ISSN: 2070-1721 August 2021 + + + "VALARM" Extensions for iCalendar + +Abstract + + This document defines a set of extensions to the iCalendar "VALARM" + component to enhance the use of alarms and improve interoperability + between clients and servers. + + This document updates RFC 5545. + +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 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc9074. + +Copyright Notice + + Copyright (c) 2021 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 + (https://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. + +Table of Contents + + 1. Introduction + 2. Conventions Used in This Document + 3. Extensible Syntax for VALARM + 4. Alarm Unique Identifier + 5. Alarm Related To + 6. Alarm Acknowledgement + 6.1. Acknowledged Property + 7. Snoozing Alarms + 7.1. Relationship Type Property Parameter + 7.2. Example + 8. Alarm Proximity Trigger + 8.1. Proximity Property + 8.2. Example + 9. Security Considerations + 10. Privacy Considerations + 11. IANA Considerations + 11.1. Property Registrations + 11.2. Relationship Types Registry + 11.3. Proximity Values Registry + 12. References + 12.1. Normative References + 12.2. Informative References + Acknowledgements + Authors' Addresses + +1. Introduction + + The iCalendar specification [RFC5545] defines a set of components + used to describe calendar data. One of those is the "VALARM" + component, which appears as a subcomponent of the "VEVENT" and + "VTODO" components. The "VALARM" component is used to specify a + reminder for an event or task. Different alarm actions are possible, + as are different ways to specify how the alarm is triggered. + + As iCalendar has become more widely used and as client-server + protocols, such as Calendaring Extensions to WebDAV (CalDAV) + [RFC4791], have become more prevalent, several issues with "VALARM" + components have arisen. Most of these relate to the need to extend + the existing "VALARM" component with new properties and behaviors to + allow clients and servers to accomplish specific tasks in an + interoperable manner. For example, clients typically need a way to + specify that an alarm has been dismissed by a calendar user or has + been "snoozed" by a set amount of time. To date, this has been done + through the use of custom "X-" properties specific to each client + implementation, leading to poor interoperability. + + This specification defines a set of extensions to "VALARM" components + to cover common requirements for alarms not currently addressed in + iCalendar. Each extension is defined in a separate section below. + For the most part, each extension can be supported independently of + the others; though, in some cases, one extension will require + another. In addition, this specification describes mechanisms by + which clients can interoperably implement common features, such as + "snoozing". + +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 + BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + + The notation used in this memo to (re-)define iCalendar elements is + the ABNF notation of [RFC5234] as used by [RFC5545]. Any syntax + elements shown below that are not explicitly defined in this + specification come from iCalendar [RFC5545]. + + 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. + +3. Extensible Syntax for VALARM + + Section 3.6.6 of [RFC5545] defines the syntax for "VALARM" components + and properties within them. However, as written, it is hard to + extend this, e.g., by adding a new property common to all types of + alarms. Since many of the extensions defined in this document need + to extend the base syntax, an alternative form for the base syntax is + defined here, with the goal of simplifying specification of the + extensions while augmenting the existing functionality defined in + [RFC5545] to allow for nested subcomponents (as required by proximity + alarm triggers (Section 8)). + + A "VALARM" calendar component is redefined by the following notation: + + alarmcext = "BEGIN" ":" "VALARM" CRLF + *alarmprop *alarm-subcomp + "END" ":" "VALARM" CRLF + + alarmprop = ( + ; + ; the following are REQUIRED + ; but MUST NOT occur more than once + ; + action / trigger / + ; + ; one set of action properties MUST be + ; present and MUST match the action specified + ; in the ACTION property + ; + actionprops / + ; + ; the following are OPTIONAL + ; and MAY occur more than once + ; + x-prop / iana-prop + ; + ) + + actionprops = *audiopropext / *disppropext / *emailpropext + + audiopropext = ( + ; + ; 'duration' and 'repeat' are both OPTIONAL + ; and MUST NOT occur more than once each, + ; but if one occurs, so MUST the other + ; + duration / repeat / + ; + ; the following is OPTIONAL + ; but MUST NOT occur more than once + ; + attach + ; + ) + + disppropext = ( + ; + ; the following are REQUIRED + ; but MUST NOT occur more than once + ; + description / + ; + ; 'duration' and 'repeat' are both OPTIONAL + ; and MUST NOT occur more than once each, + ; but if one occurs, so MUST the other + ; + duration / repeat + ; + ) + + emailpropext = ( + ; + ; the following are all REQUIRED + ; but MUST NOT occur more than once + ; + description / summary / + ; + ; the following is REQUIRED + ; and MAY occur more than once + ; + attendee / + ; + ; 'duration' and 'repeat' are both OPTIONAL + ; and MUST NOT occur more than once each, + ; but if one occurs, so MUST the other + ; + duration / repeat + ; + ; the following is OPTIONAL + ; and MAY occur more than once + ; + attach + ; + ) + + alarm-subcomp = ( + ; + ; the following are OPTIONAL + ; and MAY occur more than once + ; + x-comp / iana-comp + ; + ) + +4. Alarm Unique Identifier + + This extension adds a "UID" property to "VALARM" components to allow + a unique identifier to be specified. The value of this property can + then be used to refer uniquely to the "VALARM" component. + + The "UID" property defined here follows the definition in + Section 3.8.4.7 of [RFC5545] with the security and privacy updates in + Section 5.3 of [RFC7986]. In particular, it MUST be a globally + unique identifier that does not contain any security- or privacy- + sensitive information. + + The "VALARM" component defined in Section 3 is extended here as: + + alarmprop =/ ( + ; + ; the following is OPTIONAL + ; but MUST NOT occur more than once + ; + uid + ; + ) + +5. Alarm Related To + + It is often convenient to relate one or more "VALARM" components to + other "VALARM" components (e.g., see Section 7). This can be + accomplished if the "VALARM" components each have their own "UID" + property (as per Section 4). + + This specification updates the usage of the "RELATED-TO" property + defined in Section 3.8.4.5 of [RFC5545] to enable its use with + "VALARM" components. Specific types of relationships between + "VALARM" components can be identified by registering new values for + the "RELTYPE" property parameter defined in Section 3.2.15 of + [RFC5545]. + + The "VALARM" component defined in Section 3 is extended here as: + + alarmprop =/ ( + ; + ; the following is OPTIONAL + ; and MAY occur more than once + ; + related + ; + ) + +6. Alarm Acknowledgement + + There is currently no way for a "VALARM" component to indicate + whether it has been triggered and acknowledged. With the advent of a + standard client/server protocol for calendaring and scheduling data + ([RFC4791]), it is quite possible for an event with an alarm to exist + on multiple clients in addition to the server. If each of those is + responsible for performing the action when an alarm triggers, then + multiple "alerts" are generated by different devices. In such a + situation, a calendar user would like to be able to "dismiss" the + alarm on one device and have it automatically dismissed on the + others, too. + + Also, with recurring events that have alarms, it is important to know + when the last alarm in the recurring set was acknowledged so that the + client can determine whether past alarms have been missed. + + To address these needs, this specification adds an "ACKNOWLEDGED" + property to "VALARM" components to indicate when the alarm was last + acknowledged (or sent, if acknowledgement is not possible). This is + defined by the syntax below. + + alarmprop =/ ( + ; + ; the following is OPTIONAL + ; but MUST NOT occur more than once + ; + acknowledged + ; + ) + +6.1. Acknowledged Property + + Property Name: ACKNOWLEDGED + + Purpose: This property specifies the UTC date and time at which the + corresponding alarm was last sent or acknowledged. + + Value Type: DATE-TIME + + Property Parameters: IANA and nonstandard property parameters can be + specified on this property. + + Conformance: This property can be specified within "VALARM" calendar + components. + + Description: This property is used to specify when an alarm was last + sent or acknowledged. This allows clients to determine when a + pending alarm has been acknowledged by a calendar user so that any + alerts can be dismissed across multiple devices. It also allows + clients to track repeating alarms or alarms on recurring events or + to-dos to ensure that the right number of missed alarms can be + tracked. + + Clients SHOULD set this property to the current date-time value in + UTC when a calendar user acknowledges a pending alarm. Certain + kinds of alarms, such as email-based alerts, might not provide + feedback as to when the calendar user sees them. For those kinds + of alarms, the client SHOULD set this property when the alarm is + triggered and the action is successfully carried out. + + When an alarm is triggered on a client, clients can check to see + if an "ACKNOWLEDGED" property is present. If it is, and the value + of that property is greater than or equal to the computed trigger + time for the alarm, then the client SHOULD NOT trigger the alarm. + Similarly, if an alarm has been triggered and an "alert" has been + presented to a calendar user, clients can monitor the iCalendar + data to determine whether an "ACKNOWLEDGED" property is added or + changed in the alarm component. If the value of any + "ACKNOWLEDGED" property in the alarm changes and is greater than + or equal to the trigger time of the alarm, then clients SHOULD + dismiss or cancel any "alert" presented to the calendar user. + + Format Definition: This property is defined by the following + notation: + + acknowledged = "ACKNOWLEDGED" *acknowledgedparam ":" datetime CRLF + + acknowledgedparam = ( + ; + ; the following is OPTIONAL + ; and MAY occur more than once + ; + (";" other-param) + ; + ) + + Example: The following is an example of this property: + + ACKNOWLEDGED:20090604T084500Z + +7. Snoozing Alarms + + Users often want to "snooze" an alarm, and this specification defines + a standard approach to accomplish that. + + To "snooze" an alarm that has been triggered, clients MUST do the + following: + + 1. Set the "ACKNOWLEDGED" property (see Section 6.1) on the + triggered alarm. + + 2. Create a new "VALARM" component (the "snooze" alarm) within the + parent component of the triggered alarm (i.e., as a "sibling" + component of the triggered alarm). + + a. The new "snooze" alarm MUST be set to trigger at the user's + chosen "snooze" interval after the original alarm is + triggered. Clients SHOULD use an absolute "TRIGGER" property + with a "DATE-TIME" value specified in UTC. + + b. The new "snooze" alarm MUST have a "RELATED-TO" property (see + Section 5) with a value set to the "UID" property value of + the original "VALARM" component that was triggered. If the + triggered "VALARM" component does not already have a "UID" + property, the client MUST add one. The "RELATED-TO" property + added to the new "snooze" alarm MUST include a "RELTYPE" + property parameter with a value set to "SNOOZE" (see + Section 7.1). + + 3. When the "snooze" alarm is triggered, the client MUST do the + following: + + a. Update the "ACKNOWLEDGED" property on the original related + alarm. + + b. If the "snooze" alarm is itself "snoozed", the client MUST + remove the "snooze" alarm component and return to step 2. + + Otherwise, if the "snooze" alarm is dismissed, the client + MUST do one of the following: + + * Set the "ACKNOWLEDGED" property on the "snooze" alarm. + + * Remove the "snooze" alarm component. + + Note that regardless of the final disposition of the "snooze" alarm + when triggered, the original "VALARM" component is left unchanged + other than updating its "ACKNOWLEDGED" property. + +7.1. Relationship Type Property Parameter + + This specification adds the "SNOOZE" relationship type for use with + the "RELTYPE" property defined in Section 3.2.15 of [RFC5545]. This + is used when relating a "snoozed" "VALARM" component to the original + alarm that the "snooze" was generated for. + +7.2. Example + + The following example shows the "snoozing", "re-snoozing", and + dismissal of an alarm. Note that the encompassing "VCALENDAR" + component has been omitted for brevity and that the line breaks + surrounding the "VALARM" components are for clarity only and would + not be present in the actual iCalendar data. + + Assume that we have the following event with an alarm set to trigger + 15 minutes before the meeting: + + BEGIN:VEVENT + CREATED:20210302T151004Z + UID:AC67C078-CED3-4BF5-9726-832C3749F627 + DTSTAMP:20210302T151004Z + DTSTART;TZID=America/New_York:20210302T103000 + DTEND;TZID=America/New_York:20210302T113000 + SUMMARY:Meeting + + BEGIN:VALARM + UID:8297C37D-BA2D-4476-91AE-C1EAA364F8E1 + TRIGGER:-PT15M + DESCRIPTION:Event reminder + ACTION:DISPLAY + END:VALARM + + END:VEVENT + + When the alarm is triggered, the user decides to "snooze" it for 5 + minutes. The client acknowledges the original alarm and creates a + new "snooze" alarm as a sibling of, and relates it to, the original + alarm (note that both occurrences of "VALARM" reside within the same + "parent" VEVENT): + + BEGIN:VEVENT + CREATED:20210302T151004Z + UID:AC67C078-CED3-4BF5-9726-832C3749F627 + DTSTAMP:20210302T151516Z + DTSTART;TZID=America/New_York:20210302T103000 + DTEND;TZID=America/New_York:20210302T113000 + SUMMARY:Meeting + + BEGIN:VALARM + UID:8297C37D-BA2D-4476-91AE-C1EAA364F8E1 + TRIGGER:-PT15M + DESCRIPTION:Event reminder + ACTION:DISPLAY + ACKNOWLEDGED:20210302T151514Z + END:VALARM + + BEGIN:VALARM + UID:DE7B5C34-83FF-47FE-BE9E-FF41AE6DD097 + TRIGGER;VALUE=DATE-TIME:20210302T152000Z + RELATED-TO;RELTYPE=SNOOZE:8297C37D-BA2D-4476-91AE-C1EAA364F8E1 + DESCRIPTION:Event reminder + ACTION:DISPLAY + END:VALARM + + END:VEVENT + + When the "snooze" alarm is triggered, the user decides to "snooze" it + again for an additional 5 minutes. The client once again + acknowledges the original alarm, removes the triggered "snooze" + alarm, and creates another new "snooze" alarm as a sibling of, and + relates it to, the original alarm (note the different UID for the new + "snooze" alarm): + + BEGIN:VEVENT + CREATED:20210302T151004Z + UID:AC67C078-CED3-4BF5-9726-832C3749F627 + DTSTAMP:20210302T152026Z + DTSTART;TZID=America/New_York:20210302T103000 + DTEND;TZID=America/New_York:20210302T113000 + SUMMARY:Meeting + + BEGIN:VALARM + UID:8297C37D-BA2D-4476-91AE-C1EAA364F8E1 + TRIGGER:-PT15M + DESCRIPTION:Event reminder + ACTION:DISPLAY + ACKNOWLEDGED:20210302T152024Z + END:VALARM + + BEGIN:VALARM + UID:87D690A7-B5E8-4EB4-8500-491F50AFE394 + TRIGGER;VALUE=DATE-TIME:20210302T152500Z + RELATED-TO;RELTYPE=SNOOZE:8297C37D-BA2D-4476-91AE-C1EAA364F8E1 + DESCRIPTION:Event reminder + ACTION:DISPLAY + END:VALARM + + END:VEVENT + + When the second "snooze" alarm is triggered, the user decides to + dismiss it. The client acknowledges both the original alarm and the + second "snooze" alarm: + + BEGIN:VEVENT + CREATED:20210302T151004Z + UID:AC67C078-CED3-4BF5-9726-832C3749F627 + DTSTAMP:20210302T152508Z + DTSTART;TZID=America/New_York:20210302T103000 + DTEND;TZID=America/New_York:20210302T113000 + SUMMARY:Meeting + + BEGIN:VALARM + UID:8297C37D-BA2D-4476-91AE-C1EAA364F8E1 + TRIGGER:-PT15M + DESCRIPTION:Event reminder + ACTION:DISPLAY + ACKNOWLEDGED:20210302T152507Z + END:VALARM + + BEGIN:VALARM + UID:87D690A7-B5E8-4EB4-8500-491F50AFE394 + TRIGGER;VALUE=DATE-TIME:20210302T152500Z + RELATED-TO;RELTYPE=SNOOZE:8297C37D-BA2D-4476-91AE-C1EAA364F8E1 + DESCRIPTION:Event reminder + ACTION:DISPLAY + ACKNOWLEDGED:20210302T152507Z + END:VALARM + + END:VEVENT + +8. Alarm Proximity Trigger + + Currently, a "VALARM" is triggered when a specific date-time value is + reached. It is also desirable to be able to trigger alarms based on + location, e.g., when arriving at or departing from a particular + location. + + This specification adds the following elements to "VALARM" components + to indicate when an alarm can be triggered based on location. + + "PROXIMITY" property: indicates that a location-based trigger is to + be used and which action is used for the trigger + + "VLOCATION" component(s) [RFC9073]: used to indicate the actual + location(s) to trigger off of, specified with a URL property + containing a 'geo' URI [RFC5870], which allows for two or three + coordinate values with an optional uncertainty + + alarmprop =/ ( + ; + ; the following is OPTIONAL + ; but MUST NOT occur more than once + ; + proximity + ; + ) + + alarm-subcomp =/ ( + ; + ; the following is OPTIONAL + ; and MAY occur more than once but only + ; when a PROXIMITY property is also present + ; + locationc + ; + ) + + Typically, when a "PROXIMITY" property is used, there is no need to + specify a time-based trigger using the "TRIGGER" property. However, + since "TRIGGER" is defined as a required property for a "VALARM" + component, for backwards compatibility, it has to be present but + ignored. To indicate a "TRIGGER" that is to be ignored, clients + SHOULD use a value a long time in the past. A value of + "19760401T005545Z" has been commonly used for this purpose. + +8.1. Proximity Property + + Property Name: PROXIMITY + + Purpose: This property indicates that a location-based trigger is + applied to an alarm. + + Value Type: TEXT + + Property Parameters: IANA and nonstandard property parameters can be + specified on this property. + + Conformance: This property can be specified within "VALARM" calendar + components. + + Description: This property is used to indicate that an alarm has a + location-based trigger. Its value identifies the action that will + trigger the alarm. + + When the property value is set to "ARRIVE", the alarm is triggered + when the calendar user agent arrives in the vicinity of one or + more locations. When set to "DEPART", the alarm is triggered when + the calendar user agent departs from the vicinity of one or more + locations. Each location MUST be specified with a "VLOCATION" + component. Note that the meaning of "vicinity" in this context is + implementation defined. + + When the property value is set to "CONNECT", the alarm is + triggered when the calendar user agent connects to an automobile + to which it has been paired via Bluetooth [BTcore]. When set to + "DISCONNECT", the alarm is triggered when the calendar user agent + disconnects from an automobile to which it has been paired via + Bluetooth. Note that neither current implementations of proximity + alarms nor this document have a mechanism to target a particular + automobile. Such a mechanism may be specified in a future + extension. + + Format Definition: This property is defined by the following + notation: + + proximity = "PROXIMITY" *proximityparam ":" proximityvalue CRLF + + proximityparam = ( + ; + ; the following is OPTIONAL + ; and MAY occur more than once + ; + (";" other-param) + ; + ) + + proximityvalue = "ARRIVE" / "DEPART" / + "CONNECT" / "DISCONNECT" / iana-token / x-name + +8.2. Example + + The following example shows a "VALARM" component with a proximity + trigger set to trigger when the device running the calendar user + agent leaves the vicinity defined by the URL property in the + "VLOCATION" component. Note use of the "u=" parameter with the 'geo' + URI to define the uncertainty of the location determination. + + BEGIN:VALARM + UID:77D80D14-906B-4257-963F-85B1E734DBB6 + ACTION:DISPLAY + TRIGGER;VALUE=DATE-TIME:19760401T005545Z + DESCRIPTION:Remember to buy milk + PROXIMITY:DEPART + BEGIN:VLOCATION + UID:123456-abcdef-98765432 + NAME:Office + URL:geo:40.443,-79.945;u=10 + END:VLOCATION + END:VALARM + +9. Security Considerations + + In addition to the security properties of iCalendar (see Section 7 of + [RFC5545]), a "VALARM", if not monitored properly, can be used to + disturb users and/or leak personal information. For instance, an + undesirable audio alert could cause embarrassment; an unwanted + display alert could be considered an annoyance; or an email alert + could be used to leak a user's location to a third party or to send + unsolicited email to multiple users. Therefore, CalDAV clients and + servers that accept iCalendar data from a third party (e.g., via + iCalendar Transport-Independent Interoperability Protocol (iTIP) + [RFC5546], a subscription feed, or a shared calendar) SHOULD remove + each "VALARM" from the data prior to storing in their calendar + system. + + Security considerations related to unique identifiers for "VALARM" + are discussed in Section 4. + +10. Privacy Considerations + + A proximity "VALARM", if not used carefully, can leak a user's past, + present, or future location. For instance, storing an iCalendar + resource containing proximity "VALARM"s to a shared calendar on + CalDAV server can expose to anyone that has access to that calendar + the user's intent to leave from or arrive at a particular location at + some future time. Furthermore, if a CalDAV client updates the shared + iCalendar resource with an "ACKNOWLEDGED" property when the alarm is + triggered, this will leak the exact date and time that the user left + from or arrived at the location. Therefore, CalDAV clients that + implement proximity alarms SHOULD give users the option of storing + and/or acknowledging the alarms on the local device only and not + storing the alarm and/or acknowledgement on a remote server. + + Privacy considerations related to unique identifiers for "VALARM" are + discussed in Section 4. + +11. IANA Considerations + +11.1. Property Registrations + + This document defines the following new iCalendar properties that + have been added to the "Properties" registry defined in Section 8.2.3 + of [RFC5545] and located here: . + + +==============+=========+=======================+ + | Property | Status | Reference | + +==============+=========+=======================+ + | ACKNOWLEDGED | Current | RFC 9074, Section 6.1 | + +--------------+---------+-----------------------+ + | PROXIMITY | Current | RFC 9074, Section 8.1 | + +--------------+---------+-----------------------+ + + Table 1: Additions to the Properties Registry + +11.2. Relationship Types Registry + + This document defines the following new iCalendar relationship type + that has been added to the "Relationship Types" registry defined in + Section 8.3.8 of [RFC5545] and located here: + . + + +===================+=========+=======================+ + | Relationship Type | Status | Reference | + +===================+=========+=======================+ + | SNOOZE | Current | RFC 9074, Section 7.1 | + +-------------------+---------+-----------------------+ + + Table 2: Addition to the Relationship Types Registry + +11.3. Proximity Values Registry + + A new iCalendar registry for values of the "PROXIMITY" property has + been created and is located here: . + + Additional values MAY be used, provided the process described in + Section 8.2.1 of [RFC5545] is used to register them, using the + template in Section 8.2.6 of [RFC5545]. + + The following table has been used to initialize the Proximity Value + Registry. + + +============+=========+=======================+ + | Value | Status | Reference | + +============+=========+=======================+ + | ARRIVE | Current | RFC 9074, Section 8.1 | + +------------+---------+-----------------------+ + | DEPART | Current | RFC 9074, Section 8.1 | + +------------+---------+-----------------------+ + | CONNECT | Current | RFC 9074, Section 8.1 | + +------------+---------+-----------------------+ + | DISCONNECT | Current | RFC 9074, Section 8.1 | + +------------+---------+-----------------------+ + + Table 3: Initial Contents of the Proximity + Values Registry + +12. References + +12.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, + DOI 10.17487/RFC5234, January 2008, + . + + [RFC5545] Desruisseaux, B., Ed., "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, + . + + [RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, + DOI 10.17487/RFC7986, October 2016, + . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + + [RFC9073] Douglass, M., "Event Publishing Extensions to iCalendar", + RFC 9073, DOI 10.17487/RFC9073, August 2021, + . + +12.2. Informative References + + [BTcore] Bluetooth Special Interest Group, "Bluetooth Core + Specification Version 5.0 Feature Overview", December + 2016, . + + [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, + "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, + DOI 10.17487/RFC4791, March 2007, + . + + [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent + Interoperability Protocol (iTIP)", RFC 5546, + DOI 10.17487/RFC5546, December 2009, + . + +Acknowledgements + + This specification came about via discussions at The Calendaring and + Scheduling Consortium. Also, thanks to the following for providing + feedback: Bernard Desruisseaux, Mike Douglass, Jacob Farkas, Jeffrey + Harris, Ciny Joy, Barry Leiba, and Daniel Migault. + +Authors' Addresses + + Cyrus Daboo + Apple Inc. + 1 Infinite Loop + Cupertino, CA 95014 + United States of America + + Email: cyrus@daboo.name + URI: http://www.apple.com/ + + + Kenneth Murchison (editor) + Fastmail US LLC + Suite 1201 + 1429 Walnut St + Philadelphia, PA 19102 + United States of America + + Email: murch@fastmailteam.com + URI: http://www.fastmail.com/ diff --git a/specs/rfc9253-ical-relationships.txt b/specs/rfc9253-ical-relationships.txt new file mode 100644 index 0000000..e2f881d --- /dev/null +++ b/specs/rfc9253-ical-relationships.txt @@ -0,0 +1,959 @@ + + + + +Internet Engineering Task Force (IETF) M. Douglass +Request for Comments: 9253 Bedework +Updates: 5545 August 2022 +Category: Standards Track +ISSN: 2070-1721 + + + Support for iCalendar Relationships + +Abstract + + This specification updates the iCalendar RELATED-TO property defined + in RFC 5545 by adding new relation types and introduces new iCalendar + properties (LINK, CONCEPT, and REFID) to allow better linking and + grouping of iCalendar components and related data. + +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 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc9253. + +Copyright Notice + + Copyright (c) 2022 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 + (https://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 Revised BSD License text as described in Section 4.e of the + Trust Legal Provisions and are provided without warranty as described + in the Revised BSD License. + +Table of Contents + + 1. Introduction + 1.1. Structured iCalendar Relationships + 1.2. Grouped iCalendar Relationships + 1.3. Concept Relationships + 1.4. Linked Relationships + 1.5. Caching and Offline Use + 1.6. Conventions Used in This Document + 2. LINK Property Reference Types + 3. Link Relation Types + 4. New Temporal RELTYPE Parameter Values + 5. Additional New RELTYPE Parameter Values + 6. New Property Parameters + 6.1. Link Relation + 6.2. Gap + 7. New Value Data Types + 8. New Properties + 8.1. Concept + 8.2. Link + 8.3. Refid + 9. Updates to RFC 5545 + 9.1. RELATED-TO + 10. Security Considerations + 11. IANA Considerations + 11.1. iCalendar Property Registrations + 11.2. iCalendar Property Parameter Registrations + 11.3. iCalendar Value Data Type Registrations + 11.4. iCalendar RELTYPE Value Registrations + 12. References + 12.1. Normative References + 12.2. Informative References + Acknowledgements + Author's Address + +1. Introduction + + iCalendar entities defined in [RFC5545] often need to be related to + each other or to associated metadata. The specifications below + support relationships of the following forms: + + Structured iCalendar: iCalendar entities can be related to each + other in some structured way, for example, as parent, sibling, + before, or after. + + Grouped iCalendar: iCalendar entities can be related to each other + as a group. CATEGORIES are often used for this purpose but are + problematic for application developers due to their lack of + consistency and use as a free-form tag. + + Linked: Entities can be linked to other entities, such as vCards, + through a URI and associated REL and FMTTYPE parameters. + +1.1. Structured iCalendar Relationships + + The iCalendar [RFC5545] RELATED-TO property has no support for + temporal relationships as used by project management tools. + + The RELTYPE parameter is extended to take new values defining + temporal relationships, a GAP parameter is defined to provide lead + and lag values, and RELATED-TO is extended to allow URI values. + These changes allow the RELATED-TO property to define a richer set of + relationships useful for project management. + +1.2. Grouped iCalendar Relationships + + This specification defines a new REFID property, which allows + arbitrary groups of entities to be associated with the same key + value. + + REFID is used to identify a key allowing the association of + components that are all related to the referring, aggregating + component and the retrieval of components based on this key. For + example, this may be used to identify the tasks associated with a + given project without having to communicate the task structure of the + project. A further example is the grouping of all sub-tasks + associated with the delivery of a specific package in a package + delivery system. + + As such, the presence of a REFID property imparts no meaning to the + component. It is merely a key to allow retrieval. This is distinct + from categorization, which, while allowing grouping, also adds + meaning to the component to which it is attached. + +1.3. Concept Relationships + + The name CONCEPT is used by the Simple Knowledge Organization System, + as defined in [W3C.REC-skos-reference-20090818]. The term "concept" + more accurately defines what we often mean by a category. It's not + the text string that is important but the meaning attached to it. + For example, the term "football" can mean very different sports. + + The introduction of CONCEPT allows a more structured approach to + categorization, with the possibility of namespaced and path-like + values. Unlike REFID, the CONCEPT property imparts some meaning. It + is assumed that the value of this property will reference a well- + defined category. + + The current CATEGORIES property defined in [RFC5545] is used as a + free-form 'tagging' field. These values have some meaning to those + who apply them but not necessarily to any consumer. As such, it is + difficult to establish formal relationships between components based + on their category. + + Rather than attempt to add semantics to the CATEGORIES property, it + seems best to continue its usage as an informal tag and establish a + new CONCEPT property with more constraints. + +1.4. Linked Relationships + + The currently existing iCalendar standard [RFC5545] lacks a general + purpose method for referencing additional, external information + relating to calendar components. + + This document proposes a method for referencing typed external + information that can provide additional information about an + iCalendar component. This new LINK property is closely aligned to + [RFC8288], which defines the generic concept of Web Linking, as well + as its expression in the HTTP LINK header field. + + The LINK property defines a typed reference or relation to external + metadata or related resources. By providing type and format + information as parameters, clients and servers are able to discover + interesting references and make use of them, perhaps for indexing or + the presentation of interesting links for the user. + + Calendar components are often grouped into collections to represent a + calendar or a series of tasks, for example, Calendaring Extensions to + WebDAV (CalDAV) calendar collections [RFC4791]. + + It is also often necessary to reference calendar components in other + collections. For example, a VEVENT might refer to a VTODO from which + it was derived. The PARENT, SIBLING, and CHILD relationships defined + for the RELATED-TO property only allow for a unique identifier (UID), + which is inadequate for many purposes. Allowing other value types + for those relationships may help but would cause backward- + compatibility issues. The LINK property can link components in + different collections or even on different servers. + + When publishing events, it is useful to be able to refer back to the + source of that information. The actual event may have been consumed + from a feed or an ics file on a website. A LINK property can provide + a reference to the originator of the event. + + Beyond the need to relate elements temporally, project management + tools often need to be able to specify the relationships between the + various events and tasks that make up a project. The LINK property + provides such a mechanism. + + The LINK property MUST NOT be treated as just another attachment. + The ATTACH property defined in [RFC5545] has been extended by + [RFC8607] to handle server-side management and stripping of inline + data and to provide additional data about the attachment (size, + filename, etc.). + + Additionally, clients may choose to handle attachments differently + from the LINK property, as attachments are often an integral part of + the message, for example, the agenda. + +1.5. Caching and Offline Use + + In general, the calendar entity should be self explanatory without + the need to download referenced metadata, such as a web page. + + However, to facilitate offline display, the link type may identify + important pieces of data that should be downloaded in advance. + +1.6. 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 + BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + + The notation used in this memo to (re-)define iCalendar elements is + the ABNF notation of [RFC5234], as used by [RFC5545]. Any syntax + elements shown below that are not explicitly defined in this + specification come from iCalendar [RFC5545]. + +2. LINK Property Reference Types + + The reference value in the LINK property defined below can take three + forms specified by the VALUE parameter: + + URI: This is a URI referring to the target. + + UID: This allows for linking within a single collection of calendar + components, and the value MUST refer to another component within + the same collection. + + XML-REFERENCE: In an XML environment, it may be necessary to refer + to a fragment of an external XML artifact. This value is a URI + with an XPointer anchor value. The XPointer is defined in + [W3C.WD-xptr-xpointer-20021219], and its use as an anchor is + defined in [W3C.REC-xptr-framework-20030325]. + + Note that UID references may need updating on import. An example is + data to be imported from a file containing VTODO and VEVENT + components, with a VTODO referring to VEVENT components by UID. When + imported into a CalDAV system, the VTODO components are typically + placed in a different collection from the VEVENT components. This + would require the UID reference to be replaced with a URI. + +3. Link Relation Types + + Two forms of relation types are defined in [RFC8288]: registered and + extension. Registered relation types are added to the "Link + Relations" registry, as specified in Section 2.1.1 of [RFC8288]. + Extension relation types, defined in Section 2.1.2 of [RFC8288], are + specified as unique URIs that are not registered in the registry. + + The relation types defined in Section 6.1 will be registered with + IANA in accordance with the specifications in [RFC8288]. + +4. New Temporal RELTYPE Parameter Values + + This section defines the usual temporal relationships for use with + the RELTYPE parameter defined in Section 3.2.15 of [RFC5545]: + FINISHTOSTART, FINISHTOFINISH, STARTTOFINISH, or STARTTOSTART. + + The [RFC5545] RELATED-TO property with one or more of these temporal + relationships will be present in the predecessor entity and will + refer to the successor entity. + + The GAP parameter (see Section 6.2) specifies the lead (a negative + value) or lag (a positive value) time between the predecessor and the + successor. + + In the description of each temporal relationship below, we refer to + Task-A, which contains and controls the relationship, and Task-B, + which is the target of the relationship. This is indicated by the + direction of the arrows in the diagrams below. + + Also, each relationship may be modified by the addition of a GAP + parameter to the relationship that applies to the targeted component. + + RELTYPE=FINISHTOSTART: Task-B cannot start until Task-A finishes. + For example, when painting is complete, carpet laying can begin. + + ============ + | Task-A | + ============ + | + V + ============ + | Task-B | + ============ + + Figure 1: Finish-to-Start Relationship + + RELTYPE=FINISHTOFINISH: Task-B can only be completed after Task-A is + finished. The related tasks may run in parallel before + completion. + + For example, in the development of two related pieces of software + (e.g., the API and the implementation), the design of the + implementation (Task-B) cannot be completed until the design of + the API (Task-A) has been completed. + + ================== + | Task-A |--+ + ================== | + | + ============ | + | Task-B |<-+ + ============ + + Figure 2: Finish-to-Finish Relationship + + RELTYPE=STARTTOFINISH: The start of Task-A (which occurs after Task- + B) controls the finish of Task-B. For example, ticket sales + (Task-B) end after the game starts (Task-A). + + ============ + +--| Task-A | + | ============ + +---------+ + ============ | + | Task-B |<-+ + ============ + + Figure 3: Start-to-Finish Relationship + + RELTYPE=STARTTOSTART: The start of Task-A triggers the start of + Task-B, that is, Task-B can start anytime after Task-A starts. + + ============ + +--| Task-A | + | ============ + | + | ============ + +->| Task-B | + ============ + + Figure 4: Start-to-Start Relationship + +5. Additional New RELTYPE Parameter Values + + This section defines the additional relationships below: + + RELTYPE=FIRST: This indicates that the referenced calendar component + is the first in a series the referencing calendar component is + part of. + + RELTYPE=NEXT: This indicates that the referenced calendar component + is the next in a series the referencing calendar component is part + of. + + RELTYPE=DEPENDS-ON: This indicates that the current calendar + component depends on the referenced calendar component in some + manner. For example, a task may be blocked waiting on the other, + referenced, task. + + RELTYPE=REFID: This establishes a reference from the current + component to components with a REFID property that matches the + value given in the associated RELATED-TO property. + + RELTYPE=CONCEPT: This establishes a reference from the current + component to components with a CONCEPT property that matches the + value given in the associated RELATED-TO property. + + Note that the relationship types of PARENT, CHILD, and SIBLING + establish a hierarchical relationship. The new types of FIRST and + NEXT are an ordering relationship. + +6. New Property Parameters + +6.1. Link Relation + + Parameter name: LINKREL + + Purpose: This property specifies the relationship of data referenced + by a LINK property. + + Format Definition: This parameter is defined by the following + notation: + + linkrelparam = "LINKREL" "=" + (DQUOTE uri DQUOTE + / iana-token) ; Other IANA registered type + + Description: This parameter MUST be specified on all LINK properties + and define the type of reference. This allows programs consuming + this data to automatically scan for references they support. + There is no default relation type. + + Any link relation in the link registry established by [RFC8288], + or new link relations, may be used. It is expected that link + relation types seeing significant usage in calendaring will have + the calendaring usage described in an RFC. + + LINKREL=latest-version: This identifies the latest version of the + event information. + + Registration: These relation types are registered in [RFC8288]. + +6.2. Gap + + Parameter name: GAP + + Purpose: This property specifies the length of the gap, positive or + negative, between two components with a temporal relationship. + + Format Definition: This parameter is defined by the following + notation, where dur-value is defined in Section 3.3.6 of + [RFC5545]. : + + gapparam = "GAP" "=" dur-value + + Description: This parameter MAY be specified on the RELATED-TO + property and defines the duration of time between the predecessor + and successor in an interval. When positive, it defines the lag + time between a task and its logical successor. When negative, it + defines the lead time. + + An example of lag time might be if Task-A is "paint the room" and + Task-B is "lay the carpets". Then, Task-A may be related to + Task-B with RELTYPE=FINISHTOSTART with a gap of 1 day -- long + enough for the paint to dry. + + ==================== + | paint the room |--+ + ==================== | + |(lag of one day) + | + | =================== + +->| lay the carpet | + =================== + + Figure 5: Finish-to-Start Relationship with Lag + + For an example of lead time, in constructing a two-story building, + the electrical work must be done before painting. However, the + painter can move in to the first floor as the electricians move + upstairs. + + ===================== + | electrical work |--+ + ===================== | + +-------------+ + |(lead of estimated time) + | ================== + +->| painting | + ================== + + Figure 6: Finish-to-Start Relationship with Lead + +7. New Value Data Types + + This specification defines the following new value types to be used + with the VALUE property parameter: + + UID: VALUE=UID indicates that the associated value is the UID for a + component. + + XML-REFERENCE: VALUE=XML-REFERENCE indicates that the associated + value references an associated XML artifact and is a URI with an + XPointer anchor value. The XPointer is defined in + [W3C.WD-xptr-xpointer-20021219], and its use as an anchor is + defined in [W3C.REC-xptr-framework-20030325]. + +8. New Properties + +8.1. Concept + + Property name: CONCEPT + + Purpose: This property defines the formal categories for a calendar + component. + + Value type: URI + + Property Parameters: IANA and non-standard parameters can be + specified on this property. + + Conformance: This property can be specified zero or more times in + any iCalendar component. + + Description: This property is used to specify formal categories or + classifications of the calendar component. The values are useful + in searching for a calendar component of a particular type and + category. + + This categorization is distinct from the more informal "tagging" + of components provided by the existing CATEGORIES property. It is + expected that the value of the CONCEPT property will reference an + external resource that provides information about the + categorization. + + In addition, a structured URI value allows for hierarchical + categorization of events. + + Possible category resources are the various proprietary systems, + for example, the Library of Congress, or an open source of + categorization data. + + Format Definition: This property is defined by the following + notation: + + concept = "CONCEPT" conceptparam ":" + uri CRLF + + conceptparam = *(";" other-param) + + Example: The following is an example of this property. It points to + a server acting as the source for the calendar object. + + CONCEPT:https://example.com/event-types/arts/music + +8.2. Link + + Property name: LINK + + Purpose: This property provides a reference to external information + related to a component. + + Value type: URI, UID, or XML-REFERENCE + + Property Parameters: The VALUE parameter is required. Non-standard, + link relation type, format type, label, and language parameters + can also be specified on this property. The LABEL parameter is + defined in [RFC7986]. + + Conformance: This property can be specified zero or more times in + any iCalendar component. + + Description: When used in a component, the value of this property + points to additional information related to the component. For + example, it may reference the originating web server. + + Format Definition: This property is defined by the following + notation: + + link = "LINK" linkparam ":" + ( uri / ; for VALUE=XML-REFERENCE + uri / ; for VALUE=URI + text ) ; for VALUE=UID + CRLF + + linkparam = (";" "VALUE" "=" ("XML-REFERENCE" / + "URI" / + "UID")) + 1*(";" linkrelparam) + 1*(";" fmttypeparam) + 1*(";" labelparam) + 1*(";" languageparam) + *(";" other-param) + ; the elements herein may appear in any order, + ; and the order is not significant. + + This property is a serialization of the model in [RFC8288], where + the link target is carried in the property value, the link context + is the containing calendar entity, and the link relation type and + any target attributes are carried in iCalendar property + parameters. + + The LINK property parameters map to [RFC8288] attributes as + follows: + + LABEL: This parameter maps to the "title" attribute defined in + Section 3.4.1 of [RFC8288]. + + LANGUAGE: This parameter maps to the "hreflang" attribute defined + in Section 3.4.1 of [RFC8288]. + + LINKREL: This parameter maps to the link relation type defined in + Section 2.1 of [RFC8288]. + + FMTTYPE: This parameter maps to the "type" attribute defined in + Section 3.4.1 of [RFC8288]. + + There is no mapping for "title*", "anchor", "rev", or "media" + [RFC8288]. + + Example: The following is an example of this property, which + provides a reference to the source for the calendar object. + + LINK;LINKREL=SOURCE;LABEL=Venue;VALUE=URI: + https://example.com/events + + Example: The following is an example of this property, which + provides a reference to an entity from which this one was derived. + The link relation is a vendor-defined value. + + LINK;LINKREL="https://example.com/linkrel/derivedFrom"; + VALUE=URI: + https://example.com/tasks/01234567-abcd1234.ics + + Example: The following is an example of this property, which + provides a reference to a fragment of an XML document. The link + relation is a vendor-defined value. + + LINK;LINKREL="https://example.com/linkrel/costStructure"; + VALUE=XML-REFERENCE: + https://example.com/xmlDocs/bidFramework.xml + #xpointer(descendant::CostStruc/range-to( + following::CostStrucEND[1])) + +8.3. Refid + + Property name: REFID + + Purpose: This property value acts as a key for associated iCalendar + entities. + + Value type: TEXT + + Property Parameters: Non-standard parameters can be specified on + this property. + + Conformance: This property can be specified zero or more times in + any iCalendar component. + + Description: The value of this property is free-form text that + creates an identifier for associated components. All components + that use the same REFID value are associated through that value + and can be located or retrieved as a group. For example, all of + the events in a travel itinerary would have the same REFID value, + so as to be grouped together. + + Format Definition: This property is defined by the following + notation: + + refid = "REFID" refidparam ":" text CRLF + + + refidparam = *(";" other-param) + + Example: The following is an example of this property. + + REFID:itinerary-2014-11-17 + +9. Updates to RFC 5545 + + This specification updates the RELATED-TO property defined in + Section 3.8.4.5 of [RFC5545]. The contents of Section 9.1 replace + that section. + + The RELTYPE parameter is extended to take new values defining + temporal relationships, a GAP parameter is defined to provide lead + and lag values, and RELATED-TO is extended to allow URI values. + These changes allow the RELATED-TO property to define a richer set of + relationships useful for project management. + +9.1. RELATED-TO + + Property name: RELATED-TO + + Purpose: This property is used to represent a relationship or + reference between one calendar component and another. The + definition here extends the definition in Section 3.8.4.5 of + [RFC5545] by allowing URI or UID values and a GAP parameter. + + Value Type: URI, UID, or TEXT + + Property Parameters: Relationship type, IANA, and non-standard + property parameters can be specified on this property. + + Conformance: This property MAY be specified in any iCalendar + component. + + Description: By default or when VALUE=UID is specified, the property + value consists of the persistent, globally unique identifier of + another calendar component. This value would be represented in a + calendar component by the UID property. + + By default, the property value points to another calendar + component that has a PARENT relationship to the referencing + object. The RELTYPE property parameter is used to either + explicitly state the default PARENT relationship type to the + referenced calendar component or to override the default PARENT + relationship type and specify either a CHILD or SIBLING + relationship or a temporal relationship. + + The PARENT relationship indicates that the calendar component is a + subordinate of the referenced calendar component. The CHILD + relationship indicates that the calendar component is a superior + of the referenced calendar component. The SIBLING relationship + indicates that the calendar component is a peer of the referenced + calendar component. + + To preserve backwards compatibility, the value type MUST be UID + when the PARENT, SIBLING, or CHILD relationships are specified. + + The FINISHTOSTART, FINISHTOFINISH, STARTTOFINISH, or STARTTOSTART + relationships define temporal relationships, as specified in the + RELTYPE parameter definition. + + The FIRST and NEXT define ordering relationships between calendar + components. + + The DEPENDS-ON relationship indicates that the current calendar + component depends on the referenced calendar component in some + manner. For example, a task may be blocked waiting on the other, + referenced, task. + + The REFID and CONCEPT relationships establish a reference from the + current component to the referenced component. + + Changes to a calendar component referenced by this property can + have an implicit impact on the related calendar component. For + example, if a group event changes its start or end date or time, + then the related, dependent events will need to have their start + and end dates and times changed in a corresponding way. + Similarly, if a PARENT calendar component is canceled or deleted, + then there is an implied impact to the related CHILD calendar + components. This property is intended only to provide information + on the relationship of calendar components. + + Deletion of the target component, for example, the target of a + FIRST, NEXT, or temporal relationship, can result in broken links. + + It is up to the target calendar system to maintain any property + implications of these relationships. + + Format Definition: This property is defined by the following + notation: + + related = "RELATED-TO" relparam ":" + ( text / ; for VALUE=UID + uri / ; for VALUE=URI + text ) ; for VALUE=TEXT or default + CRLF + + relparam = ; the elements herein may appear in any order, + ; and the order is not significant. + [";" "VALUE" "=" ("UID" / + "URI" / + "TEXT")] + [";" reltypeparam] + [";" gapparam] + *(";" other-param) + + Example: The following are examples of this property. + + RELATED-TO:jsmith.part7.19960817T083000.xyzMail@example.com + + RELATED-TO:19960401-080045-4000F192713-0052@example.com + + RELATED-TO;VALUE=URI;RELTYPE=STARTTOFINISH: + https://example.com/caldav/user/jb/cal/ + 19960401-080045-4000F192713.ics + +10. Security Considerations + + All of the security considerations of Section 7 of [RFC5545] apply to + this specification. + + Applications using the LINK property need to be aware of the risks + entailed in using the URIs provided as values. See Section 7 of + [RFC3986] for a discussion of the security considerations relating to + URIs. + + In particular, note Section 7.1 (Reliability and Consistency) of + [RFC3986], which points out the lack of a stability guarantee for + referenced resources. + + When the value is an XML-REFERENCE type, the targeted data is an XML + document or portion thereof. Consumers need to be aware of the + security issues related to XML processing -- in particular, those + related to XML entities. See Section 20.6 of [RFC4918]. + Additionally, note that the reference may be invalid or become so + over time. + + The CONCEPT and redefined RELATED-TO properties have the same issues + in that values may be URIs. + + Extremely large values for the GAP parameter may lead to unexpected + behavior. + +11. IANA Considerations + +11.1. iCalendar Property Registrations + + The following iCalendar property names have been added to the + iCalendar "Properties" registry defined in Section 8.3.2 of + [RFC5545]. IANA has also added a reference to this document, where + the properties originally defined in [RFC5545] have been updated by + this document. + + +============+=========+=============================+ + | Property | Status | Reference | + +============+=========+=============================+ + | CONCEPT | Current | Section 8.1 | + +------------+---------+-----------------------------+ + | LINK | Current | Section 8.2 | + +------------+---------+-----------------------------+ + | REFID | Current | Section 8.3 | + +------------+---------+-----------------------------+ + | RELATED-TO | Current | [RFC5545], Section 3.8.4.5; | + | | | RFC 9253, Section 9.1 | + +------------+---------+-----------------------------+ + + Table 1 + +11.2. iCalendar Property Parameter Registrations + + The following iCalendar property parameter names have been added to + the iCalendar "Parameters" registry defined in Section 8.3.3 of + [RFC5545]. + + +===========+=========+=============+ + | Parameter | Status | Reference | + +===========+=========+=============+ + | GAP | Current | Section 6.2 | + +-----------+---------+-------------+ + | LINKREL | Current | Section 6.1 | + +-----------+---------+-------------+ + + Table 2 + +11.3. iCalendar Value Data Type Registrations + + The following iCalendar property parameter names have been added to + the iCalendar "Value Data Types" registry defined in Section 8.3.4 of + [RFC5545]. + + +=================+=========+===========+ + | Value Data Type | Status | Reference | + +=================+=========+===========+ + | XML-REFERENCE | Current | Section 7 | + +-----------------+---------+-----------+ + | UID | Current | Section 7 | + +-----------------+---------+-----------+ + + Table 3 + +11.4. iCalendar RELTYPE Value Registrations + + The following iCalendar "RELTYPE" values have been added to the + iCalendar "Relationship Types" registry defined in Section 8.3.8 of + [RFC5545]. + + +===================+=========+===========+ + | Relationship Type | Status | Reference | + +===================+=========+===========+ + | CONCEPT | Current | Section 5 | + +-------------------+---------+-----------+ + | DEPENDS-ON | Current | Section 5 | + +-------------------+---------+-----------+ + | FINISHTOFINISH | Current | Section 4 | + +-------------------+---------+-----------+ + | FINISHTOSTART | Current | Section 4 | + +-------------------+---------+-----------+ + | FIRST | Current | Section 5 | + +-------------------+---------+-----------+ + | NEXT | Current | Section 5 | + +-------------------+---------+-----------+ + | REFID | Current | Section 5 | + +-------------------+---------+-----------+ + | STARTTOFINISH | Current | Section 4 | + +-------------------+---------+-----------+ + | STARTTOSTART | Current | Section 4 | + +-------------------+---------+-----------+ + + Table 4 + +12. References + +12.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [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, + . + + [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed + Authoring and Versioning (WebDAV)", RFC 4918, + DOI 10.17487/RFC4918, June 2007, + . + + [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, + DOI 10.17487/RFC5234, January 2008, + . + + [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and + Scheduling Core Object Specification (iCalendar)", + RFC 5545, DOI 10.17487/RFC5545, September 2009, + . + + [RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, + DOI 10.17487/RFC7986, October 2016, + . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + + [RFC8288] Nottingham, M., "Web Linking", RFC 8288, + DOI 10.17487/RFC8288, October 2017, + . + + [W3C.REC-skos-reference-20090818] + Miles, A. and S. Bechhofer, "SKOS Simple Knowledge + Organization System Reference", W3C Recommendation REC- + skos-reference-20090818, 18 August 2009, + . + + [W3C.REC-xptr-framework-20030325] + Grosso, P., Maler, E., Marsh, J., and N. Walsh, "XPointer + Framework", W3C Recommendation REC-xptr-framework- + 20030325, 25 March 2003, + . + + [W3C.WD-xptr-xpointer-20021219] + DeRose, S., Maler, E., and R. Daniel, "XPointer xpointer() + Scheme", W3C WD WD-xptr-xpointer-20021219, 19 December + 2002, + . + +12.2. Informative References + + [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, + "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, + DOI 10.17487/RFC4791, March 2007, + . + + [RFC8607] Daboo, C., Quillaud, A., and K. Murchison, Ed., + "Calendaring Extensions to WebDAV (CalDAV): Managed + Attachments", RFC 8607, DOI 10.17487/RFC8607, June 2019, + . + +Acknowledgements + + The author would like to thank the members of CalConnect, the + Calendaring and Scheduling Consortium technical committees, and the + following individuals for contributing their ideas, support, and + comments: + + Adrian Apthorp, Cyrus Daboo, Marten Gajda, and Ken Murchison + + The author would also like to thank CalConnect and the Calendaring + and Scheduling Consortium for advice with this specification. + +Author's Address + + Michael Douglass + Bedework + 226 3rd Street + Troy, NY 12180 + United States of America + Email: mdouglass@bedework.com + URI: https://bedework.com diff --git a/vobject/__init__.py b/vobject/__init__.py index fe13acd..516df75 100644 --- a/vobject/__init__.py +++ b/vobject/__init__.py @@ -80,6 +80,9 @@ from .base import newFromBehavior, readComponents, readOne +__version__ = "0.9.8" + + def iCalendar(): return newFromBehavior("vcalendar", "2.0") diff --git a/vobject/base.py b/vobject/base.py index f46ea5f..dbefc63 100644 --- a/vobject/base.py +++ b/vobject/base.py @@ -20,13 +20,14 @@ # One more problem ... in python2 the str operator breaks on unicode # objects containing non-ascii characters try: - unicode # noqa # todo: check this + # Should raise NameError on Python 3.x + unicode # noqa: F821 def str_(s): """ Return byte string with correct encoding """ - if type(s) is unicode: # noqa + if isinstance(s, unicode): # noqa: F821 return s.encode("utf-8") else: return str(s) @@ -400,12 +401,12 @@ def __setattr__(self, name, value): which are legal in IANA tokens. """ if name.endswith("_param"): - if type(value) is list: + if isinstance(value, list): # FIXME: should this be Sequence? self.params[toVName(name, 6, True)] = value else: self.params[toVName(name, 6, True)] = [value] elif name.endswith("_paramlist"): - if type(value) is list: + if isinstance(value, list): # FIXME: should this be Sequence? self.params[toVName(name, 10, True)] = value else: raise VObjectError("Parameter list set to a non-list") @@ -551,7 +552,7 @@ def __setattr__(self, name, value): which are legal in IANA tokens. """ if name not in self.normal_attributes and name.lower() == name: - if type(value) is list: + if isinstance(value, list): # FIXME: should this be Sequence? if name.endswith("_list"): name = name[:-5] self.contents[toVName(name)] = value diff --git a/vobject/behavior.py b/vobject/behavior.py index 53739ff..790656f 100644 --- a/vobject/behavior.py +++ b/vobject/behavior.py @@ -1,7 +1,8 @@ from . import base -# ------------------------ Abstract class for behavior -------------------------- +# ----------------------- Abstract class for behavior -------------------------- + class Behavior(object): """ Behavior (validation, encoding, and transformations) for vobjects. diff --git a/vobject/hcalendar.py b/vobject/hcalendar.py index 88abc11..1f4141b 100644 --- a/vobject/hcalendar.py +++ b/vobject/hcalendar.py @@ -1,4 +1,4 @@ -""" +r""" hCalendar: A microformat for serializing iCalendar data (http://microformats.org/wiki/hcalendar) @@ -77,12 +77,13 @@ def out(s): # DTSTART dtstart = event.getChildValue("dtstart") if dtstart: - if type(dtstart) is date: - timeformat = "%A, %B %e" - machine = "%Y%m%d" - elif type(dtstart) is datetime: + # Careful of ordering: datetime derives from date, so MUST check it first. + if isinstance(dtstart, datetime): timeformat = "%A, %B %e, %H:%M" machine = "%Y%m%dT%H%M%S%z" + elif isinstance(dtstart, date): + timeformat = "%A, %B %e" + machine = "%Y%m%d" # TODO: Handle non-datetime formats? # TODO: Spec says we should handle when dtstart isn't included @@ -99,12 +100,12 @@ def out(s): duration = event.getChildValue("duration") if duration: dtend = duration + dtstart - # TODO: If lacking dtend & duration? + # FIXME: If lacking dtend & duration? if dtend: human = dtend - # TODO: Human readable part could be smarter, excluding repeated data - if type(dtend) is date: + # FIXME: Human readable part could be smarter, excluding repeated data + if isinstance(dtend, date): human = dtend - timedelta(days=1) out( diff --git a/vobject/icalendar.py b/vobject/icalendar.py index 0ca21f8..351e625 100644 --- a/vobject/icalendar.py +++ b/vobject/icalendar.py @@ -331,8 +331,8 @@ def fromLastWeek(dt): endString = ";UNTIL=" + dateTimeToString(endDate) else: endString = "" - new_rule = "FREQ=YEARLY{0!s};BYMONTH={1!s}{2!s}".format(dayString, rule["month"], endString) + new_rule = "FREQ=YEARLY{0!s};BYMONTH={1!s}{2!s}".format(dayString, rule["month"], endString) comp.add("rrule").value = new_rule tzinfo = property(gettzinfo, settzinfo) @@ -445,9 +445,10 @@ def getrruleset(self, addRDate=False): return None if name in DATENAMES: - if type(line.value[0]) is datetime.datetime: + # Note: careful of order: datetime derives from date. + if isinstance(line.value[0], datetime.datetime): list(map(addfunc, line.value)) - elif type(line.value[0]) is datetime.date: + elif isinstance(line.value[0], datetime.date): for dt in line.value: addfunc(datetime.datetime(dt.year, dt.month, dt.day)) else: @@ -842,7 +843,8 @@ def transformFromNative(obj): """ Replace the date or datetime in obj.value with an ISO 8601 string. """ - if type(obj.value) is datetime.date: + # Careful: datetime derives from date + if isinstance(obj.value, datetime.date) and not isinstance(obj.value, datetime.datetime): obj.isNative = False obj.value_param = "DATE" obj.value = dateToString(obj.value) @@ -888,7 +890,7 @@ def transformFromNative(obj): Replace the date, datetime or period tuples in obj.value with appropriate strings. """ - if obj.value and type(obj.value[0]) is datetime.date: + if obj.value and isinstance(obj.value[0], datetime.date): obj.isNative = False obj.value_param = "DATE" obj.value = ",".join([dateToString(val) for val in obj.value]) @@ -900,7 +902,7 @@ def transformFromNative(obj): transformed = [] tzid = None for val in obj.value: - if tzid is None and type(val) is datetime.datetime: + if tzid is None and isinstance(val, datetime.datetime): tzid = TimezoneComponent.registerTzinfo(val.tzinfo) if tzid is not None: obj.tzid_param = tzid @@ -1027,7 +1029,7 @@ def serialize(cls, obj, buf, lineLength, validate=True): transformed = obj.transformFromNative() undoTransform = True else: - transformed = obj + transformed = obj # FIXME: never used undoTransform = False out = None print(transformed, out) # todo: remove unused vars @@ -1048,7 +1050,6 @@ def serialize(cls, obj, buf, lineLength, validate=True): ] except Exception: first_props = first_components = [] - # first_components = [] prop_keys = sorted( list( @@ -1572,13 +1573,13 @@ def transformToNative(obj): @staticmethod def transformFromNative(obj): - if type(obj.value) is datetime.datetime: + if isinstance(obj.value, datetime.datetime): obj.value_param = "DATE-TIME" return UTCDateTimeBehavior.transformFromNative(obj) - elif type(obj.value) is datetime.timedelta: + elif isinstance(obj.value, datetime.timedelta): return Duration.transformFromNative(obj) else: - raise NativeError("Native TRIGGER values must be timedelta or " "datetime") + raise NativeError("Native TRIGGER values must be timedelta or datetime") registerBehavior(Trigger) @@ -1648,6 +1649,7 @@ class RRule(behavior.Behavior): registerBehavior(RRule, "RRULE") registerBehavior(RRule, "EXRULE") + # ------------------------ Registration of common classes ---------------------- utcDateTimeList = ["LAST-MODIFIED", "CREATED", "COMPLETED", "DTSTAMP"] list(map(lambda x: registerBehavior(UTCDateTimeBehavior, x), utcDateTimeList)) @@ -1690,7 +1692,7 @@ def numToDigits(num, places): if len(s) < places: return ("0" * (places - len(s))) + s elif len(s) > places: - return s[len(s) - places :] + return s[len(s) - places:] else: return s diff --git a/vobject/ics_diff.py b/vobject/ics_diff.py index 3433890..abc4bea 100644 --- a/vobject/ics_diff.py +++ b/vobject/ics_diff.py @@ -203,7 +203,7 @@ def main(): def getOptions(): - # ----Configuration options---- # + # Configuration options usage = "usage: %prog [options] ics_file1 ics_file2" parser = OptionParser(usage=usage, version=version) diff --git a/vobject/win32tz.py b/vobject/win32tz.py index 242a38d..c924841 100644 --- a/vobject/win32tz.py +++ b/vobject/win32tz.py @@ -89,7 +89,7 @@ def __init__(self, path): self.dstname = keydict["Dlt"] self.stdname = keydict["Std"] - # see http://ww_winreg.jsiinc.com/SUBA/tip0300/rh0398.htm + # See http://ww_winreg.jsiinc.com/SUBA/tip0300/rh0398.htm tup = struct.unpack("=3l16h", keydict["TZI"]) self.stdoffset = -tup[0] - tup[1] # Bias + StandardBias * -1 self.dstoffset = self.stdoffset - tup[2] # + DaylightBias * -1 @@ -120,7 +120,7 @@ def __init__(self, path): self.stdoffset = -keydict["Bias"] - keydict["StandardBias"] self.dstoffset = self.stdoffset - keydict["DaylightBias"] - # see http://ww_winreg.jsiinc.com/SUBA/tip0300/rh0398.htm + # See http://ww_winreg.jsiinc.com/SUBA/tip0300/rh0398.htm tup = struct.unpack("=8h", keydict["StandardStart"]) offset = 0 @@ -146,9 +146,7 @@ def valuesToDict(key): def _test(): import doctest - import win32tz - doctest.testmod(win32tz, verbose=False)