This specification updates RELATED-TO and introduces new iCalendar properties LINK and RELATED-ID to allow better linking and grouping of iCalendar components and related data.

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

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

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

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

1. Introduction

Icalendar entities often need to be related to each other or to associated meta-data. These relationships can take the following forms

1.1. Structured iCalendar relationships

The currently existing iCalendar [RFC5545] RELATED-TO property has no support for temporal relationships as used by standard 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 allows 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 RELATED-ID property which allows arbitrary groups of entities to be created. This provides a more structured approach to categorization, allowing namespaced values and providing some assurance for applications that these groupings will be preserved.

1.3. 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 the LINK header defined in [RFC5988]

The LINK property defines a typed reference or relation to external meta-data 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.

It is often necessary to relate calendar components. The current RELATED-TO property only allows for a UID which is inadequate for many purposes. Allowing other types may help but might raise a number of 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 web site. 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 which make up a project. The LINK property provides such a mechanism.

1.4. Caching and offline use

A section about offline use. Use the link type to identify important pieces of data.

Client may load subset of data due to e.g. a time-range query. Should it pull in all the related data?

1.5. 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].

2. Qualified Name Syntax

Some property and parameter values need a more "structured" value than simple text to be defined within a namespace. The syntax defined here creates a new syntactic element that incorporates a namespace component and a token component, that togther form a "qualified" name.

3. Reference Types

4. Link Relation Types

[RFC5988] defines two form of relation types, registered and extension. Registered relation types are added to a registry defined by [RFC5988] while extension relation types are specified as unique unregistered URIs, (at least unregistered in the [RFC5988] registry).

The relation types defined here will be registered with IANA in accordance with the specifications in [RFC5988].

5. Redefined Relation Type Value

Relationship parameter type values are defined in section 3.2.15. of [RFC5545]. This specification redefines that type to include the new temporal relationship values FINISHTOSTART, FINISHTOFINISH, STARTTOFINISH and STARTTOSTART. It also adds the DEPENDS-ON value to provide a link to an component upon which the current component depends.


            ============
            |  Task-A  |--+
            ============  |
                          |
                          V
                          ============
                          |  Task-B  |
                          ============

Figure 1: Finish to start relationship


                    ============
                    |  Task-A  |--+
                    ============  |
                                  |
                    ============  |
                    |  Task-B  |<-+
                    ============

Figure 2: Finish to finish relationship


                                     ============
                                  +--|  Task-A  |
                                  |  ============
                                  |
                    ============  |
                    |  Task-B  |<-+
                    ============

Figure 3: Start to finish relationship


                    ============
                 +--|  Task-A  |
                 |  ============
                 |
                 |  ============
                 +->|  Task-B  |
                    ============

Figure 4: Start to start relationship

Format Definition:
Description:: This parameter can be specified on a property that references another related calendar component. The parameter may specify the hierarchical relationship type of the calendar component referenced by the property when the value is PARENT, CHILD or SIBLING. 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.
: It defines the temporal relationship when the value is one of the project management standard relationships FINISHTOSTART, FINISHTOFINISH, STARTTOFINISH or STARTTOSTART. This property will be present in the predecessor entity and will refer to the successor entity. The GAP parameter specifies the lead or lag 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 the target of the relationship.
RELTYPE=PARENT:: Identifies the referenced calendar component is a superior of calendar component
RELTYPE=CHILD:: Indicates that the referenced calendar component is a subordinate of the calendar component.
RELTYPE=SIBLING:: Indicates that the referenced calendar component is a peer of the calendar component.
RELTYPE=DEPENDS-ON:: 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:: Establishes a reference from the current component to components with a REFID property which matches the value given in the associated RELATED-TO property.
RELTYPE=FINISHTOSTART:: Task-B cannot start until Task-A finishes. For example, when sanding is complete, painting can begin.
RELTYPE=FINISHTOFINISH:: Task-B cannot finish before Task-A is finished, that is the end of Task-A defines the end of Task-B. For example, we start the potatoes, then the meat then the peas but they should all be cooked at the same time.
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 when the game starts (Task-A).
RELTYPE=STARTTOSTART:: The start of Task-A triggers the start of Task-B, that is Task-B can start anytime after Task-A starts.

6. New Property Parameters

6.1. Rel

This parameter is defined by the following notation:

  relparam      = "REL" "="
                  ("SOURCE"      ; Link to source of this component
                 / DQUOTE uri DQUOTE
                 / x-name        ; Experimental reference type
                 / iana-token)   ; Other IANA registered type

Parameter name:: REL
Purpose:: To specify the relationship of data referenced by a LINK property.
Format Definition:
Description:: This parameter MUST be specified on all LINK properties, and defines the type of reference. This allows programs consuming this data to automatically scan for references they support. In addition to the values defined here any value defined in [RFC5988] may be used. There is no default relation type.
REL=SOURCE:: identifies the source of the event information.
Registration:: These relation types are registered in [RFC5988]

6.2. Gap

This parameter is defined by the following notation:

  gapparam      = "GAP" "=" dur-value

Parameter name:: GAP
Purpose:: To specify the length of the gap, positive or negative between two temporally related components.
Format Definition:
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 "hang the drapes" then task A may be related to task B with RELTYPE=FINISHTOSTART with a gap long enough for the paint to dry.
: An example of lead time might be to relate a 1 week task A to the end of task B with RELTYPE=STARTTOFINISH and a negative gap of 1 week so they finish at the same time.

6.3. Title

This parameter is defined by the following notation:

  titleparam     = "TITLE" "=" text

Parameter name:: TITLE
Purpose:: To provide a human readable title.
Format Definition:
Description:: This parameter MAY be specified on all LINK properties, and provides a human readable label, perhaps for icons or links..

7. New Parameter Values

This specification defines a new value to be used with the VALUE property parameter:

UID: VALUE=UID indicates that the associated value is the UID for a component.
REFERENCE: VALUE=REFERENCE indicates that the associated value is an xpointer referencing an associated XML artifact.

8. New Properties

8.1. Link

This property is defined by the following notation:

  link            = "LINK" linkparam ":" ( ":" uri ) /
                    (
                      ";" "VALUE" "=" "REFERENCE"
                      ":" text
                    )
                    CRLF


  linkparam       = *(

                  ; the following is MANDATORY
                  ; and MAY occur more than once

                  (";" relparam) /

                  ; the following are MANDATORY
                  ; but MUST NOT occur more than once

                  (";" fmttypeparam) /
                  (";" titleparam) /

                  ; the following is OPTIONAL
                  ; and MAY occur more than once

                  (";" xparam)

                  )

The following is an example of this property. It points to a server acting as the source for the calendar object.

                 LINK;REL=SOURCE;TITLE=The Egg:
                   http://example.com/events

Property name:: LINK
Purpose:: This property provides a reference to external information about a component.
Value type:: URI, TEXT or REFERENCE
Property Parameters:: Non-standard, reference type or format type parameters can be specified on this property.
Conformance:: This property MAY be specified 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:
Example:

8.2. Refid

This property is defined by the following notation:

  refid      = "REFID" refidparam ":" q-name CRLF


  refidparam      = *(

                  ; the following is OPTIONAL
                  ; and MAY occur more than once

                  (";" xparam)

                  )

The following is an example of this property. It defines an id in the org.calconnect namespace.

  REFID:{org.calconnect.project}Main-Project

Property name:: REFID
Purpose:: This property allows iCalendar entities to be grouped.
Value type:: Q-NAME
Property Parameters:: Non-standard parameters can be specified on this property.
Conformance:: This property MAY be specified multiple times in any iCalendar component.
Description:: The value of this property is a namespaced value using Clark notation, that is the namespace is enclosed in braces, "{", "}". The part following the namespace is defined by the owner of that namespace and may be simple text, a path or any appropriate text value.
: In effect this property provides a more controlled categorization of calendar entities.
: A CUA MUST preserve any REFID property with a namespace it does not recognize or own. This allows other CUAs to use the REFID to define groups which only have significance to that application. For example, a project management tool may flag all tasks that form part of a specific project, or an itinerary tool may flag all events that are part of an itinerary.
Format Definition:
Example:

9. Redefined RELATED-TO Property

9.1. RELATED-TO

This property is defined by the following notation:

   related    = "RELATED-TO" relparam ( ":" text ) /
                (
                  ";" "VALUE" "=" "UID"
                  ":" uid
                )
                (
                  ";" "VALUE" "=" "URI"
                  ":" uri
                )
                CRLF

   relparam   = *(
              ;
              ; The following are OPTIONAL,
              ; but MUST NOT occur more than once.
              ;
              (";" reltypeparam) /
              (";" gapparam) /
              ;
              ; The following is OPTIONAL,
              ; and MAY occur more than once.
              ;
              (";" other-param)
              ;
              )

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:
        http://example.com/caldav/user/jb/cal/
        19960401-080045-4000F192713.ics

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 values adn a GAP parameter.
Value type:: URI or TEXT
Property Parameters:: Non-standard, reference type, gap, value or format type 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.
: The FINISHTOSTART, FINISHTOFINISH, STARTTOFINISH or STARTTOSTART relationships define temporal relationships as specified in the reltype parameter definition.
: 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.
Format Definition:
Example:

10. Security Considerations

Applications using the LINK property need to be aware of the risks entailed in using the URIs provided as values. See [RFC3986] for a discussion of the security considerations relating to URIs.

11. IANA Considerations

12. Acknowledgements

The author would like to thank the members of the Calendaring and Scheduling Consortium technical committees and the following individuals for contributing their ideas, support and comments:

Adrian Apthorp, Cyrus Daboo, Marten Gajda

The authors would also like to thank the Calendaring and Scheduling Consortium for advice with this specification.

13. Normative References

[RFC2119]	Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3688]	Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004.
[RFC3986]	Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005.
[RFC5545]	Desruisseaux, B., "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 5545, September 2009.
[RFC5988]	Nottingham, M., "Web Linking", RFC 5988, October 2010.
[W3C.REC-xml-20060816]	Yergeau, F., Paoli, J., Bray, T., Maler, E. and C. Sperberg-McQueen, "Extensible Markup Language (XML) 1.0 (Fourth Edition)", World Wide Web Consortium FirstEdition REC-xml-20060816, August 2006.
[W3C.WD-xptr-xpointer-20021219]	DeRose, S., Daniel, R. and E. Maler, "XPointer xpointer() Scheme", World Wide Web Consortium WD WD-xptr-xpointer-20021219, December 2002.

Appendix A. Change log

V02: 2013-11-22 MD

Added more description to GAP

V01: 2013-09-26 MD

Removed "Improved" from title
Fixed typos and examples
Removed gap param from link

2013-06-02 MD Initial version

Author's Address

Michael Douglass Rensselaer Polytechnic Institute 110 8th Street Troy, NY 12180 USA EMail: douglm@rpi.edu URI: http://www.rpi.edu/

Abstract

Status of This Memo

Copyright Notice

Table of Contents

1. Introduction

1.1. Structured iCalendar relationships

1.2. Grouped iCalendar relationships

1.3. Linked relationships

1.4. Caching and offline use

1.5. Conventions Used in This Document

2. Qualified Name Syntax

3. Reference Types

4. Link Relation Types

5. Redefined Relation Type Value

6. New Property Parameters

6.1. Rel

6.2. Gap

6.3. Title

7. New Parameter Values

8. New Properties

8.1. Link

8.2. Refid

9. Redefined RELATED-TO Property

9.1. RELATED-TO

10. Security Considerations

11. IANA Considerations

12. Acknowledgements

13. Normative References

Appendix A. Change log

Author's Address