RFC 9073

Event Publishing Extensions to iCalendar

📅 published August 2021, from ietf

RFC 9073: Event Publishing Extensions to iCalendar 🎀📅

Okay bestie, this one is from the IETF, written by M. Douglass of Bedework, and it's dated August 2021. It's a Standards Track document, so it's official Internet standard stuff 👑. It's also ISSN 2070-1721, and it updates RFC 5545, the main iCalendar spec, which means it's adding onto that one without replacing it ✨.

Abstract ✨

This spec updates RFC 5545 by adding a bunch of new iCalendar properties and components that are super useful for event publishers and social networking 🦋.

It also defines a brand new STRUCTURED-DATA property for iCalendar (RFC 5545). This lets you attach data that's directly relevant to an event or task right inside the calendar data 💖.

Status of This Memo 📜

This is an Internet Standards Track document 💅.

It's a product of the Internet Engineering Task Force (IETF), and it represents the consensus of the IETF community 🫶. It went through public review and got approved for publication by the Internet Engineering Steering Group (IESG). If you want more on Internet Standards, check Section 2 of RFC 7841 🌸.

Info about the document's current status, any errata, and how to send feedback is at https://www.rfc-editor.org/info/rfc9073 🧚.

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) as they stand on the publication date. Please actually read these, because they spell out your rights and restrictions for this doc 🙈. Any Code Components pulled out of this document must include the Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions. They're also provided without warranty, as the Simplified BSD License describes 💀.

Table of Contents 🍓

   1.  Introduction
     1.1.  Conventions Used in This Document
     1.2.  Terms Used in This Document
   2.  Components and Properties
   3.  Typed References
     3.1.  Use Cases
       3.1.1.  Piano Concert Performance
       3.1.2.  Itineraries
         3.1.2.1.  Reserving Facilities
   4.  Modifications to Calendar Components
   5.  New Property Parameters
     5.1.  Order
     5.2.  Schema
     5.3.  Derived
   6.  New Properties
     6.1.  Location Type
     6.2.  Participant Type
     6.3.  Resource Type
     6.4.  Calendar Address
     6.5.  Styled-Description
     6.6.  Structured-Data
   7.  New Components
     7.1.  Participant
       7.1.1.  Schedulable Participant
     7.2.  Location
     7.3.  Resource
   8.  Extended Examples
     8.1.  Example 1
     8.2.  Example 2
   9.  Security Considerations
     9.1.  URIs
     9.2.  Malicious Content
     9.3.  HTML Content
   10. Privacy Considerations
     10.1.  Tracking
     10.2.  Revealing Locations
   11. IANA Considerations
     11.1.  Additional iCalendar Registrations
       11.1.1.  Properties
       11.1.2.  Parameters
       11.1.3.  Components
     11.2.  Participant Types and Resource Types Registries
       11.2.1.  Participant Types
       11.2.2.  Resource Types
   12. Normative References
   Acknowledgements
   Author's Address

1. Introduction ✨

Here's the tea: iCalendar as defined in RFC 5545 [RFC5545] doesn't have good ways to reference extra external info about calendar components 😭. There's also no standard way to attach rich-text descriptions or metadata to an event, which is kind of a vibe killer 💀.

So people currently just stuff links into the description, or make up nonstandard properties, as covered in Section 3.8.8.2 of [RFC5545] 🙈.

This document updates [RFC5545] to define a bunch of properties and components that reference that external info, so they can give extra details about an iCalendar component 🦋. The goal is letting applications or systems swap this info around, whether that's clients talking to each other, a client and a server, or servers talking to servers 🫶. Formats like vCard [RFC6350] are probably the most useful for the people receiving these events, because they can be used in other apps, like address books 📇.

1.1. Conventions Used in This Document 🎀

Here's how the keywords work: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be read as described in BCP 14 [RFC2119] [RFC8174], but only when they show up in all capitals, exactly like shown here 💅.

The notation in this memo is the ABNF notation of [RFC5234], as iCalendar [RFC5545] uses it. Any syntax elements shown below that aren't explicitly defined in this specification come from iCalendar [RFC5545] 🧚.

1.2. Terms Used in This Document 💜

Event: When the word 'event' (maybe with a capital 'E') shows up, we mean gatherings, formal or informal. Think a sports event, a party, or a concert 🎉.

Social Calendaring: Historically, calendar data and scheduling has been super biased toward meetings in corporate environments 💼. Some features in this document support a more informal, social model. For example, we might want to record who's participating in a public event 🌈.

2. Components and Properties 🦋

Previous extensions to the calendaring standards were mostly limited to adding properties or parameters 🙄. That's partly because iCalendar libraries struggled with components nested deeper than the ones RFC 5545 [RFC5545] defines 😩.

This specification breaks from that 'convention' and defines a bunch of components instead of properties 💅. That's a better match for how [W3C.REC-xml-20081126] and JSON [RFC8259] handle these kinds of structures, and it allows richer definitions ✨.

It also lets you add extra properties inside the components, and it fixes some problems you run into when you try to cram detailed info into a parameter 🫶.

3. Typed References 🌸

The properties and components defined here can all reference external metadata. Applications can use that metadata to give users more info 🧚. With type info, clients and servers can find interesting references and use them, maybe for indexing or for showing extra related info to the user 🔥.

As always, clients should be careful when following references to external data 🫣.

The LOCATION property [RFC5545] only gives you one unstructured text value for where an event (or task) happens 🙃. That's not enough when you need structured location info, like address, region, country, or postal code, and it's a big reason iCalendar hasn't caught on as much in those settings 😤.

With the VLOCATION component, you can share rich info about multiple locations inside a STRUCTURED-DATA property. Examples include address, region, country, postal code, parking availability, nearby restaurants, and the venue, among others 🍓. Servers and clients can fetch those objects when they store the event and use them to index by geographic location 🗺️.

When a calendar client gets a calendar component, it can search through the locations for the ones it cares about 🔍. If it's supplied, the LOCATION-TYPE property and the FMTTYPE parameter applied to the STRUCTURED-DATA property can help with that selection 💖.

The PARTICIPANT component is built for common event publishing use cases 📣. It's usually important to give info about the organizers of these events 👑. Sponsors want to be referenced in a prominent way ✨. For social calendaring, it's often important to identify both the active participants (e.g., a school sports team) and the inactive participants (e.g., the parents) 🥹.

The PARTICIPANT component can also give useful extra data about an attendee. For example, a location inside the PARTICIPANT gives the actual location of a remote attendee 📍. (But see the note about privacy 🙈.)

Alternatively, the PARTICIPANT component can point to a reference, like the address for a mailing list 📬.

3.1. Use Cases 🎀

The main motivation for these changes was event publication, but there are chances to use this elsewhere too 🌟. The following use cases describe some possible scenarios 🦋.

3.1.1. Piano Concert Performance 🎹

Putting together a concert means lots of participants: a piano tuner, the performer, stage hands, and so on 🎶. There are also sponsors and various contacts to provide, plus a bunch of related locations 📍. A number of events can be created, and they all relate to the performance in different ways 💜.

There may be an iCalendar Transport-independent Interoperability Protocol (iTIP) [RFC5546] meeting request for the piano tuner, who'll arrive before the performance 🔧. Other staff members may also get meeting requests 📨.

An event can also be created for publication. It'll have a PARTICIPANT component for the pianist, giving a reference to vCard information ([RFC6350]) about the performer 🎹✨. This event would also hold info about parking, local subway stations, and the venue itself 🚇. There might also be sponsorship info for the event's sponsors, and maybe paid sponsorship properties, which are basically ads for local businesses 📢💅.

3.1.2. Itineraries ✈️

These additions open doors for the travel industry too 🧳. When you book a flight, the PARTICIPANT component can reference businesses at the airports and rental car businesses at the destination 🚗.

The embedded location info can guide the traveler around the airport itself or to their final destination 🗺️. The contact info can give detailed info about the booking agent, airlines, car hire companies, and hotel 🏨.

3.1.2.1. Reserving Facilities 🏢

For a meeting, the size of the room and the equipment needed depend, to some extent, on how many attendees are actually in the room 🪑.

A meeting may have lots of attendees, none of whom are in the same place 🌍. The current ATTENDEE property doesn't let you add that kind of metadata 🙅. The PARTICIPANT component lets attendees specify their location 💖.

4. Modifications to Calendar Components ✨

okay bestie, so this section is basically the "what's new in the iCalendar grammar" update 💖 The changes are made to the syntax defined in iCalendar [RFC5545], and the new stuff gets explained in the sections after this one 🎀

; Addition of PARTICIPANT, VLOCATION, and VRESOURCE
; as valid components
eventc     = "BEGIN" ":" "VEVENT" CRLF
             eventprop *alarmc *participantc *locationc *resourcec
             "END" ":" "VEVENT" CRLF

; Addition of properties STYLED-DESCRIPTION and STRUCTURED-DATA
eventprop  =/ *styleddescription
              *sdataprop

; Addition of PARTICIPANT, VLOCATION, and VRESOURCE
; as valid components
todoc      = "BEGIN" ":" "VTODO" CRLF
             todoprop *alarmc *participantc *locationc *resourcec
             "END" ":" "VTODO" CRLF

; Addition of properties STYLED-DESCRIPTION and STRUCTURED-DATA
todoprop =/ *styleddescription
            *sdataprop

; Addition of PARTICIPANT, VLOCATION, and VRESOURCE
; as valid components
journalc   = "BEGIN" ":" "VJOURNAL" CRLF
             jourprop *participantc *locationc *resourcec
             "END" ":" "VJOURNAL" CRLF

; Addition of properties STYLED-DESCRIPTION and STRUCTURED-DATA
jourprop =/ *styleddescription
            *sdataprop

; Addition of PARTICIPANT, VLOCATION, and VRESOURCE
; as valid components
freebusyc  = "BEGIN" ":" "VFREEBUSY" CRLF
             fbprop *participantc *locationc *resourcec
             "END" ":" "VFREEBUSY" CRLF

; Addition of property STYLED-DESCRIPTION
fbprop     =/ *styleddescription

5. New Property Parameters 🦋

5.1. Order 🌸

Parameter name: ORDER

Purpose: This parameter defines ordering for the associated property.

Format Definition: This parameter is defined by the following notation:

orderparam    = "ORDER" "=" integer
                ;           Must be greater than or equal to 1

Description: The ORDER parameter is OPTIONAL and is used to indicate the relative ordering of the corresponding instance of a property. Its value MUST be an integer greater than or equal to 1 that specifies the order, with 1 being the first in the ordering.

When the parameter is absent, the default MUST be to interpret the property instance as being ordered last, that is, the property will appear after any other instances of the same property with any value of ORDER.

When any ORDER parameters have the same value, all the associated properties appear as a group within which there is no defined order.

Note that the value of this parameter is to be interpreted only in relation to values assigned to other corresponding instances of the same property in the same entity.

This parameter MUST NOT be applied to a property that does not allow multiple instances.

Example uses: The ORDER may be applied to the PARTICIPANT-TYPE property to indicate the relative importance of the participant, for example, as a sponsor or a performer. For example, ORDER=1 could define the principal performer or soloist.

5.2. Schema 💜

Parameter Name: SCHEMA

Purpose: This parameter specifies the schema used for the content of a STRUCTURED-DATA property value.

Format Definition: This parameter is defined by the following notation:

schemaparam    = "SCHEMA" "=" DQUOTE uri DQUOTE

Description: This property parameter SHOULD be specified on STRUCTURED-DATA properties. When present, it provides identifying information about the nature of the content of the corresponding STRUCTURED-DATA property value. This can be used to supplement the media type information provided by the FMTTYPE parameter on the corresponding property.

Example:

        STRUCTURED-DATA;FMTTYPE=application/ld+json;
         SCHEMA="https://schema.org/FlightReservation";
         ENCODING=BASE64;VALUE=BINARY:ICAgIDxzY3JpcHQgdHlwZT0iYXBwb
         GljYXRpb24vbGQranNvbiI+CiAgICB7CiAgICAgICJAY29
         udGV4dCI6ICJodHRwOi8vc2NoZW1hLm9yZyIsCiAgICAgICJAdHlwZSI
         6ICJGbGlnaHRSZXNlcnZhdGlvbiIsCiAgICAgICJyZXNlcnZhdGlvbkl
         kIjogIlJYSjM0UCIsCiAgICAgICJyZXNlcnZhdGlvblN0YXR1cyI6ICJ
         odHRwOi8vc2NoZW1hLm9yZy9SZXNlcnZhdGlvbkNvbmZpcm1lZCIsCiA
         gICAgICJwYXNzZW5nZXJQcmlvcml0eVN0YXR1cyI6ICJGYXN0IFRyYWN
         rIiwKICAgICAgInBhc3NlbmdlclNlcXVlbmNlTnVtYmVyIjogIkFCQzE
         yMyIsCiAgICAgICJzZWN1cml0eVNjcmVlbmluZyI6ICJUU0EgUHJlQ2h
         lY2siLAogICAgICAidW5kZXJOYW1lIjogewogICAgICAgICJAdHlwZSI
         6ICJQZXJzb24iLAogICAgICAgICJuYW1lIjogIkV2YSBHcmVlbiIKICA
         gICAgfSwKICAgICAgInJlc2VydmF0aW9uRm9yIjogewogICAgICAgICJ
         AdHlwZSI6ICJGbGlnaHQiLAogICAgICAgICJmbGlnaHROdW1iZXIiOiA
         iVUExMTAiLAogICAgICAgICJwcm92aWRlciI6IHsKICAgICAgICAgICJ
         AdHlwZSI6ICJBaXJsaW5lIiwKICAgICAgICAgICJuYW1lIjogIkNvbnR
         pbmVudGFsIiwKICAgICAgICAgICJpYXRhQ29kZSI6ICJDTyIsCiAgICA
         gICAgICAiYm9hcmRpbmdQb2xpY3kiOiAiaHR0cDovL3NjaGVtYS5vcmc
         vWm9uZUJvYXJkaW5nUG9saWN5IgogICAgICAgIH0sCiAgICAgICAgInN
         lbGxlciI6IHsKICAgICAgICAgICJAdHlwZSI6ICJBaXJsaW5lIiwKICA
         gICAgICAgICJuYW1lIjogIlVuaXRlZCIsCiAgICAgICAgICAiaWF0YUN
         vZGUiOiAiVUEiCiAgICAgICAgfSwKICAgICAgICAiZGVwYXJ0dXJlQWl
         ycG9ydCI6IHsKICAgICAgICAgICJAdHlwZSI6ICJBaXJwb3J0IiwKICA
         gICAgICAgICJuYW1lIjogIlNhbiBGcmFuY2lzY28gQWlycG9ydCIsCiA
         gICAgICAgICAiaWF0YUNvZGUiOiAiU0ZPIgogICAgICAgIH0sCiAgICA
         gICAgImRlcGFydHVyZVRpbWUiOiAiMjAxNy0wMy0wNFQyMDoxNTowMC0
         wODowMCIsCiAgICAgICAgImFycml2YWxBaXJwb3J0IjogewogICAgICA
         gICAgIkB0eXBlIjogIkFpcnBvcnQiLAogICAgICAgICAgIm5hbWUiOiA
         iSm9obiBGLiBLZW5uZWR5IEludGVybmF0aW9uYWwgQWlycG9ydCIsCiA
         gICAgICAgICAiaWF0YUNvZGUiOiAiSkZLIgogICAgICAgIH0sCiAgICA
         gICAgImFycml2YWxUaW1lIjogIjIwMTctMDMtMDVUMDY6MzA6MDAtMDU
         6MDAiCiAgICAgIH0KICAgIH0KICAgIDwvc2NyaXB0Pg==

5.3. Derived 🧚

Parameter Name: DERIVED

Purpose: This parameter specifies that the value of the associated property is derived from some other property value or values.

Format Definition: This parameter is defined by the following notation:

derivedparam    = "DERIVED" "=" ("TRUE" / "FALSE")
; Default is FALSE

Description: This property parameter MAY be specified on any property when the value is derived from some other property or properties. When present with a value of TRUE, clients MUST NOT update the property.

As an example, if a STYLED-DESCRIPTION property is present with FMTTYPE="application/rtf", then there may be an additional STYLED-DESCRIPTION property with FMTTYPE="text/html" and DERIVED=TRUE, as well as a value created from the rtf value.

Example:

STYLED-DESCRIPTION;FMTTYPE=text/html;
 DERIVED=TRUE:<html>...</html>

6. New Properties 🌈

This specification makes use of the NAME property, which is defined in [RFC7986]. It's giving organized 💅

6.1. Location Type 📍

Property Name: LOCATION-TYPE

Purpose: This property specifies the type(s) of a location.

Value Type: The value type for this property is TEXT. The allowable values are defined below.

Description: This property MAY be specified in VLOCATION components and provides a way to differentiate multiple locations. For example, it allows event producers to provide location information for the venue and the parking.

Format Definition: This property is defined by the following notation:

loctype      = "LOCATION-TYPE" loctypeparam ":"
               text *("," text)
               CRLF

loctypeparam   = *(";" other-param)

Multiple values may be used if the location has multiple purposes, for example, a hotel and a restaurant.

Values for this parameter are taken from the values defined in Section 3 of [RFC4589]. New location types SHOULD be registered in the manner laid down in Section 5 of [RFC4589].

6.2. Participant Type 🎭

Property Name: PARTICIPANT-TYPE

Purpose: This property specifies the type of participant.

Value Type: The value type for this property is TEXT. The allowable values are defined below.

Property Parameters: Nonstandard parameters can be specified on this property.

Conformance: This property MUST be specified once within a PARTICIPANT component.

Description: This property defines the type of participation in events or tasks. Participants can be individuals or organizations, for example, a soccer team, the spectators, or the musicians.

Format Definition: This property is defined by the following notation:

participanttype   = "PARTICIPANT-TYPE" partvalueparam ":"
                    partvalue CRLF

partvalue    = ("ACTIVE"
               / "INACTIVE"
               / "SPONSOR"
               / "CONTACT"
               / "BOOKING-CONTACT"
               / "EMERGENCY-CONTACT"
               / "PUBLICITY-CONTACT"
               / "PLANNER-CONTACT"
               / "PERFORMER"
               / "SPEAKER"
               / iana-token)     ; Other IANA-registered
                                 ; values

partvalueparam   = *(";" other-param)

Example: The following is an example of this property.

PARTICIPANT-TYPE:SPEAKER

The registered values for the PARTICIPANT-TYPE property have the meanings described here:

ACTIVE: A participant taking an active role -- for example, a team member.

INACTIVE: A participant taking an inactive role -- for example, an audience member.

SPONSOR: A sponsor of the event. The ORDER parameter may be used with this participant type to define the relative order of multiple sponsors.

CONTACT: Contact information for the event. The ORDER parameter may be used with this participant type to define the relative order of multiple contacts.

BOOKING-CONTACT: Contact information for reservations or payment.

EMERGENCY-CONTACT: Contact in case of emergency.

PUBLICITY-CONTACT: Contact for publicity.

PLANNER-CONTACT: Contact for the event planner or organizer.

PERFORMER: A performer -- for example, the soloist or the accompanist. The ORDER parameter may be used with this participant type to define the relative order of multiple performers. For example, ORDER=1 could define the principal performer or soloist.

SPEAKER: Speaker at an event.

6.3. Resource Type 🖥️

Property Name: RESOURCE-TYPE

Purpose: This property specifies the type of resource.

Value Type: The value type for this property is TEXT. The allowable values are defined below.

Format Definition: This property is defined by the following notation:

restypeprop   = "RESOURCE-TYPE" restypeparam ":"
                restypevalue CRLF

restypevalue  = ("ROOM"
                / "PROJECTOR"
                / "REMOTE-CONFERENCE-AUDIO"
                / "REMOTE-CONFERENCE-VIDEO"
                / iana-token)     ; Other IANA-registered
                ; values

restypeparam   = *(";" other-param)

Description: This property MAY be specified in VRESOURCE components and provides a way to differentiate multiple resources.

The registered values are described below. New resource types SHOULD be registered in the manner laid down in this specification.

ROOM: A room for the event/meeting.

PROJECTOR: Projection equipment.

REMOTE-CONFERENCE-AUDIO: Audio remote conferencing facilities.

REMOTE-CONFERENCE-VIDEO: Video remote conferencing facilities.

6.4. Calendar Address 💌

Property Name: CALENDAR-ADDRESS 🎀

Purpose: okay so this one specifies the calendar address for a participant. It's giving identity 🪪

Value Type: CAL-ADDRESS

Property Parameters: IANA-registered or nonstandard property parameters can be specified on this property ✨

Conformance: this property MAY be specified once within a PARTICIPANT component 🫶

Description: this provides a calendar user address for the participant. If there is an ATTENDEE property with the same value, then the participant is schedulable 🧚

Format Definition: here's the notation, bestie 👑

calendaraddress   = "CALENDAR-ADDRESS" caladdressparam ":"
               cal-address CRLF

caladdressparam   = *(";" other-param)

6.5. Styled-Description 🌈

Property Name: STYLED-DESCRIPTION 💅

Purpose: this one is for one or more rich-text descriptions that replace the one provided by the DESCRIPTION property. Glow-up energy fr 🔥

Value Type: there is no default value type for this property. The value type can be set to URI or TEXT. Other text-based value types can be used when defined in the future. Clients MUST ignore any properties with value types they do not understand. Not me ignoring stuff I don't understand, but okay 🙈

Property Parameters: IANA-registered, nonstandard, id, alternate text representation, format type, derived, and language property parameters can be specified on this property 🎀

Conformance: the property can be specified multiple times in the VEVENT, VTODO, VJOURNAL, VFREEBUSY, PARTICIPANT, or VALARM calendar components.

If it does appear more than once, there MUST be exactly one instance of the property with no DERIVED parameter or DERIVED=FALSE. All others MUST have DERIVED=TRUE.

Additionally, if there is one or more STYLED-DESCRIPTION property, then the DESCRIPTION property should either be absent or have the parameter DERIVED=TRUE ✨

Description: this property supports rich-text descriptions, for example, HTML. Event publishers usually want to give people more and better-formatted info about the event, so this is their moment 💖

This property is used in the VEVENT and VTODO components to capture lengthy textual descriptions associated with the activity. It's used in the VJOURNAL component to capture one or more textual journal entries. In the VALARM component it captures the display text for a DISPLAY category of alarm, and the body text for an EMAIL category of alarm. In the PARTICIPANT component, it gives a detailed description of the participant 🧁

VALUE=TEXT is used to provide rich text inline as the property value 📝

VALUE=URI is used to provide a link to rich-text content, which is expected to be displayed inline as part of the event 🔗

In either case, the DESCRIPTION property should be absent or contain a plain-text rendering of the styled text.

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 "text/html" and process the content as defined in [W3C.REC-html51-20171003] 🌸

Multiple STYLED-DESCRIPTION properties may be used to provide different formats or different language variants. However, all but one MUST have DERIVED=TRUE 🦋

Format Definition: the notation, lowkey iconic 👑

styleddescription = "STYLED-DESCRIPTION" styleddescparam ":"
                   styleddescval CRLF

styleddescparam   = *(
                   ; The following is REQUIRED
                   ; but MUST NOT occur more than once.
                   ;
                   (";" "VALUE" "=" ("URI" / "TEXT")) /
                   ;
                   ; The following are OPTIONAL
                   ; but MUST NOT occur more than once.
                   ;
                   (";" altrepparam) / (";" languageparam) /
                   (";" fmttypeparam) / (";" derivedparam) /
                   ;
                   ; The following is OPTIONAL
                   ; and MAY occur more than once.
                   ;
                   (";" other-param)
                   )

styleddescval   = ( uri / text )
;Value MUST match value type

Example: here's an example, and it points to an HTML description 💻

STYLED-DESCRIPTION;VALUE=URI:http://example.org/desc001.html

6.6. Structured-Data 🧚‍♀️

Property Name: STRUCTURED-DATA 🍓

Purpose: this one specifies ancillary data associated with the calendar component. Extra details, but make them structured 📦

Value Type: there is no default value type for this property. The value type can be set to TEXT, BINARY, or URI.

Property Parameters: IANA-registered, nonstandard, inline encoding, and value data type property parameters can be specified on this property. The format type and schema parameters can be specified on this property and MUST be present for text or inline binary encoded content information 🔐

Conformance: this property can be specified multiple times in an iCalendar object. Typically, it would be used in the VEVENT, VTODO, or VJOURNAL calendar components 🗓️

Description: okay, the existing properties in iCalendar cover the key stuff of events and tasks, like start time, end time, location, summary, etc. But different types of events often have other specific "fields" that are useful to include in the calendar data 🥹

For example, an event representing an airline flight could include the airline, flight number, departure and arrival airport codes, check-in and gate-closing times, etc. ✈️ As another example, a sporting event might contain information about the type of sport, the home and away teams, the league the teams are in, information about nearby parking, etc. 🏟️

This property is used to specify ancillary data in some structured format, either directly (inline) as a "TEXT" or "BINARY" value, or as a link via a "URI" value 🫧

Rather than define new iCalendar properties for the variety of event types that might occur, it would be better to leverage existing schemas for such data. For example, schemas available at https://schema.org include different event types. By using standard schemas, interoperability can be improved between calendar clients and noncalendaring systems that wish to generate or process the data 🤝

This property allows the direct inclusion of ancillary data whose schema is defined elsewhere. This property also includes parameters to clearly identify the type of the schema being used, so that clients can quickly and easily spot what is relevant within the calendar data and present that to users or process it within the calendaring system 🎯

iCalendar does support an "ATTACH" property, which can be used to include documents or links to documents within the calendar data. However, that property does not allow data to be included as a "TEXT" value (a feature that "STRUCTURED-DATA" does allow). Plus, attachments are often treated as "opaque" data to be processed by some other system rather than the calendar client. Thus, the existing "ATTACH" property is not sufficient to cover the specific needs of inclusion of schema data. Extending the "ATTACH" property to support a new value type would likely cause interoperability problems. Additionally, some implementations manage attachments by stripping them out and replacing them with a link to the resource. Thus, a new property to support inclusion of schema data is warranted 🍒

Format Definition: the notation is right here, bestie 💜

sdataprop    = "STRUCTURED-DATA" sdataparam
                 (
                   ";" "VALUE" "=" "TEXT"
                   ":" text
                 ) /
                 (
                   ";" "ENCODING" "=" "BASE64"
                   ";" "VALUE" "=" "BINARY"
                   ";" binary
                 ) /
                 (
                   ";" "VALUE" "=" "URI"
                   ":" uri
                 )
                 CRLF

sdataparam  = *(
                 ;
                 ; The following is OPTIONAL for a URI value,
                 ; REQUIRED for a TEXT or BINARY value,
                 ; and MUST NOT occur more than once.
                 ;
                 (";" fmttypeparam) /
                 (";" schemaparam) /
                 ;
                 ; The following is OPTIONAL
                 ; and MAY occur more than once.
                 ;
                 (";" other-param)
                 ;
              )

Example: here's what it looks like in the wild 🍭

STRUCTURED-DATA;FMTTYPE=application/ld+json;
 SCHEMA="https://schema.org/SportsEvent";
 VALUE=TEXT:{\n
   "@context": "http://schema.org"\,\n
   "@type": "SportsEvent"\,\n
   "homeTeam": "Pittsburgh Pirates"\,\n
   "awayTeam": "San Francisco Giants"\n
 }\n

7. New Components ✨

7.1. Participant 💖

Okay bestie, the PARTICIPANT component is basically your cast list 🎭. It tells you about someone (or something) taking part in an event or task. You can stack it multiple times inside a VEVENT, VTODO, VJOURNAL, or VFREEBUSY calendar component 🍓.

Component name: PARTICIPANT

Purpose: Gives you info about a participant in an event or task ✨.

Conformance: You can specify this component multiple times in a VEVENT, VTODO, VJOURNAL, or VFREEBUSY calendar component.

Description: A participant is a whole vibe in a calendar component 🌸. A participant may be an attendee in a scheduling sense, and the ATTENDEE property may be specified in addition. Participants can be individuals or organizations, like a soccer team, the spectators, or the musicians 🎶.

STRUCTURED-DATA properties, if present, may point to definitions of the participant, like a vCard 📇.

The CALENDAR-ADDRESS property, if present, provides a cal-address. If an ATTENDEE property has the same value, the participant is considered schedulable 🦋. The PARTICIPANT component can also hold extra metadata related to the attendee 💜.

Format Definition: This component is defined by the following notation:

participantc = "BEGIN" ":" "PARTICIPANT" CRLF
               partprop *locationc *resourcec
               "END" ":" "PARTICIPANT" CRLF

partprop     = *(
               ;
               ; The following are REQUIRED
               ; but MUST NOT occur more than once.
               ;
               participanttype / uid /
               ;
               ; The following are OPTIONAL
               ; but MUST NOT occur more than once.
               ;
               calendaraddress / created / description / dtstamp /
               geo / last-mod / priority / seq /
               status / summary / url /
               ;
               ; The following are OPTIONAL
               ; and MAY occur more than once.
               ;
               attach / categories / comment
               contact / location / rstatus / related /
               resources / strucloc / strucres /
               styleddescription / sdataprop / iana-prop
               ;
               )

Note: When the PRIORITY property is supplied, it sets the ordering of PARTICIPANT components that share the same value for the PARTICIPANT-TYPE property 🏆.

Privacy Issues: When a LOCATION property is supplied, it tells you where a participant is at a given time or times 📍. That could be an unacceptable privacy risk for some participants 🙈.

User agents MUST NOT broadcast this information without the express permission of the participants whose location would be exposed. For further comments, see Section 10.

Example: Here's the component in action. It has a STRUCTURED-DATA property that points to a vCard with info about the event participant 🎻.

BEGIN:PARTICIPANT
UID: em9lQGZvb2GFtcGxlLmNvbQ
PARTICIPANT-TYPE:PERFORMER
STRUCTURED-DATA;VALUE=URI:
 http://dir.example.com/vcard/aviolinist.vcf
END:PARTICIPANT

Example: Here's one for the primary contact 📞.

BEGIN:PARTICIPANT
UID: em9lQGZvb2GFtcGxlLmNvbQ
STRUCTURED-DATA;VALUE=URI;
 http://dir.example.com/vcard/contacts/contact1.vcf
PARTICIPANT-TYPE:CONTACT
DESCRIPTION:A contact
END:PARTICIPANT

Example: And this one is a participant with both contact info and a location 🗺️.

BEGIN:PARTICIPANT
UID: em9lQGZvb2GFtcGxlLmNdrt
STRUCTURED-DATA;VALUE=URI;
 http://dir.example.com/vcard/contacts/my-card.vcf
PARTICIPANT-TYPE:SPEAKER
DESCRIPTION:A participant
BEGIN:VLOCATION
UID:123456-abcdef-98765432
NAME:My home location
STRUCTURED-DATA;VALUE=URI:
 http://dir.example.com/addresses/my-home.vcf
END:VLOCATION
END:PARTICIPANT

7.1.1. Schedulable Participant 📅

A PARTICIPANT component may stand for someone or something that needs to be scheduled, as defined for ATTENDEE in [RFC5545] and [RFC5546]. A PARTICIPANT component may also stand for someone or something that is NOT to receive scheduling messages 🙅‍♀️.

For backwards compatibility with existing clients and servers when they're used to schedule events and tasks, the ATTENDEE property MUST be used to specify the scheduling parameters, as defined for that property 🔁.

For other, future uses, the CALENDAR-ADDRESS property MUST be used to specify those parameters 🔮.

A PARTICIPANT component is defined to be schedulable if:

  • it contains a CALENDAR-ADDRESS property, and
  • that property value is the same as the value for an ATTENDEE property.

If both of these conditions apply, the participant defined by the value of the URL property will take part in scheduling operations, as defined in [RFC5546] 💅.

A really useful move for scheduling is storing SEQUENCE and DTSTAMP properties tied to replies from each ATTENDEE property 🧠. A LOCATION property inside the PARTICIPANT component can help you pick better meeting times when people are in different time zones 🌍✨.

7.2. Location 📍

Component name: VLOCATION

Purpose: Gives you rich info about where an event is happening, using the structured data property or, optionally, a plain-text typed value 🏠.

Conformance: You can specify this component multiple times in a VEVENT, VTODO, VJOURNAL, VFREEBUSY, or PARTICIPANT calendar component.

Description: An event can have a bunch of locations, and this component gives you the deets on each one 🗂️.

When it's used in a component, the value of this property tells you about the event venue or related services, like parking, dining, stations, and so on 🅿️🍽️.

STRUCTURED-DATA properties, if present, may point to representations of the location, like a vCard 📇.

Format Definition: This component is defined by the following notation:

locationc    = "BEGIN" ":" "VLOCATION" CRLF
               locprop
               "END" ":" "VLOCATION" CRLF

locprop      = *(
               ;
               ; The following are REQUIRED
               ; but MUST NOT occur more than once.
               ;
               uid /
               ;
               ; The following are OPTIONAL
               ; but MUST NOT occur more than once.
               ;
               description / geo / loctype / name
               ;
               ; The following are OPTIONAL
               ; and MAY occur more than once.
               ;
               sdataprop / iana-prop
            )

The NAME property is defined in [RFC7986] 🏷️.

Example: Here's one that points to a venue 🏛️.

BEGIN:VLOCATION
UID:123456-abcdef-98765432
NAME:The venue
STRUCTURED-DATA;VALUE=URI:
 http://dir.example.com/venues/big-hall.vcf
END:VLOCATION

7.3. Resource 🧰

Component name: VRESOURCE

Purpose: Gives you a typed reference to external info about a resource, or, optionally, a plain-text typed value 🔗. Basically, a resource is anything a calendar entity might need or use, and it might have a directory entry 📖.

Conformance: You can specify this component multiple times in a VEVENT, VTODO, VJOURNAL, VFREEBUSY, or PARTICIPANT calendar component.

Description: When it's used in a component, this component gives you info about the resources used for the event, like rooms, projectors, and conferencing capabilities 🎥.

The RESOURCE-TYPE value registry is where resource types can be registered 📝.

STRUCTURED-DATA properties, if present, may point to representations of the resource, like a vCard 📇.

Format Definition: This component is defined by the following notation:

resourcec    = "BEGIN" ":" "VRESOURCE" CRLF
               resprop
               "END" ":" "VRESOURCE" CRLF

resprop      = *(
               ;
               ; The following are REQUIRED
               ; but MUST NOT occur more than once.
               ;
               uid /
               ;
               ; The following are OPTIONAL
               ; but MUST NOT occur more than once.
               ;
               description / geo / name / restype /
               ;
               ; The following are OPTIONAL
               ; and MAY occur more than once.
               ;
               sdataprop / iana-prop
             )

The NAME property is defined in [RFC7986] 🏷️.

Example: Here's one that refers to a projector 📽️.

BEGIN:VRESOURCE
UID:456789-abcdef-98765432
NAME:The projector
RESOURCE-TYPE:projector
STRUCTURED-DATA;VALUE=URI:http://dir.example.com/projectors/3d.vcf
END:VRESOURCE

8. Extended Examples 🎬

The following are some examples of how the properties defined in this specification get used. They also include additional properties defined in [RFC7986], which includes IMAGE 🖼️.

8.1. Example 1

Here's a VEVENT describing a concert 🎹. It has location info for the venue itself, plus references to parking and restaurants 🍝.

BEGIN:VEVENT
CREATED:20200215T145739Z
DESCRIPTION: Piano Sonata No 3\n
 Piano Sonata No 30
DTSTAMP:20200215T145739Z
DTSTART;TZID=America/New_York:20200315T150000Z
DTEND;TZID=America/New_York:20200315T163000Z
LAST-MODIFIED:20200216T145739Z
SUMMARY:Beethoven Piano Sonatas
UID:123456
IMAGE;VALUE=URI;DISPLAY=BADGE;FMTTYPE=image/png:h
 ttp://example.com/images/concert.png
BEGIN:PARTICIPANT
PARTICIPANT-TYPE:SPONSOR
UID:dG9tQGZvb2Jhci5xlLmNvbQ
STRUCTURED-DATA;VALUE=URI:http://example.com/sponsor.vcf
END:PARTICIPANT
BEGIN:PARTICIPANT
PARTICIPANT-TYPE:PERFORMER:
UID:em9lQGZvb2GFtcGxlLmNvbQ
STRUCTURED-DATA;VALUE=URI:http://www.example.com/people/johndoe.vcf
END:PARTICIPANT
BEGIN:VLOCATION
UID:123456-abcdef-98765432
NAME:The venue
STRUCTURED-DATA;VALUE=URI:http://dir.example.com/venues/big-hall.vcf
END:VLOCATION
BEGIN:VLOCATION
UID:123456-abcdef-87654321
NAME:Parking for the venue
STRUCTURED-DATA;VALUE=URI:http://dir.example.com/venues/parking.vcf
END:VLOCATION
END:VEVENT

8.2. Example 2

Here's a VEVENT describing a meeting 🤝, where one of the attendees is a remote participant 💻.

BEGIN:VEVENT
CREATED:20200215T145739Z
DTSTAMP:20200215T145739Z
DTSTART;TZID=America/New_York:20200315T150000Z
DTEND;TZID=America/New_York:20200315T163000Z
LAST-MODIFIED:20200216T145739Z
SUMMARY:Conference planning
UID:123456
ORGANIZER:mailto:a@example.com
ATTENDEE;PARTSTAT=ACCEPTED;CN=A:mailto:a@example.com
ATTENDEE;RSVP=TRUE;CN=B:mailto:b@example.com
BEGIN:PARTICIPANT
PARTICIPANT-TYPE:ACTIVE:
UID:v39lQGZvb2GFtcGxlLmNvbQ
STRUCTURED-DATA;VALUE=URI:http://www.example.com/people/b.vcf
LOCATION:At home
END:PARTICIPANT
END:VEVENT

9. Security Considerations 🔐

This specification extends [RFC5545] and makes further use of possibly linked data 🔗. Calendar data isn't the only thing that works like this, but it's still worth reminding implementors about some of the dangers and safeguards 🚨.

9.1. URIs ✨

okay bestie, the URI security stuff is all covered in [RFC3986], so go read that if you're nosy 🤓. But the big takeaway is that clients SHOULD NOT follow URIs and fetch content automatically 🙅‍♀️. They should only do it when the user explicitly asks 💅

fetching remote stuff is genuinely risky ngl 😬. connections must only be allowed on well-known ports, using allowed protocols (generally just HTTP/HTTPS on their default ports) 🔒. the URL must be resolved externally and must not be allowed to reach internal resources 🚫. and connecting to an external source reveals IP information, which usually means location info too 📍. implementations should be careful about all of this.

also, a maliciously constructed iCalendar object can contain a ridiculous number of URIs 💀. when you've got published calendars with tons of subscribers, those objects can get passed around super widely 📣. so implementations should be careful about limiting automatic fetching of linked resources, so it doesn't turn into an amplification vector for a denial-of-service attack 🌪️. not on my watch!

9.2. Malicious Content

okay this one is a lot 😭. for the "STRUCTURED-DATA" property, agents need to know that a client could attack the underlying storage by sending extremely large values 📦. they could also attack processing time by uploading a recurring event with a huge number of overrides, and then repeatedly adding, updating, and deleting structured data 🔁. chaotic evil energy 💀.

so agents should set reasonable limits on storage size and number of instances, and actually apply those constraints 🛑. calendar protocols should make sure there's a way to report when those limits get exceeded 📢.

malicious content could also get into the calendar server through the "STRUCTURED-DATA" property and then spread to lots of end users via scheduling 🦠. so servers SHOULD check this property for malicious or inappropriate content 🔍. and if they detect that kind of content, servers SHOULD remove the property 🗑️. no bad vibes allowed ✨.

9.3. HTML Content

when you're processing HTML content, applications need to be aware of the many security and privacy issues described in the IANA Considerations section of [W3C.REC-html51-20171003] 🌐. go check that out, it's a whole thing 🫶.

10. Privacy Considerations ✨

10.1. Tracking

okay so properties with a "URI" value type can expose their users to privacy leaks 👀. any network access of the URI data can be tracked by a network observer AND by the entity hosting the remote resource 🕵️‍♀️. not it 🙅‍♀️. so clients SHOULD NOT automatically download data referenced by the URI without explicit instruction from users 💖.

to help with some of these concerns, protocols and services could provide proxy services for downloading referenced data 🧚.

10.2. Revealing Locations

the new participant component can now include location info, which tells you where participants are at a given time 📍. this information MUST NOT be distributed to other participants without those participants' express permission 🛑. and fun fact (not fun) there may be a bunch of participants who have no idea they're even included in the data 😶.

agents processing and distributing calendar data must be aware that it can tell you about a future time when a specific person may be at a particular location 😬. that could enable targeted attacks against that individual 🎯. yikes.

the same may be true of other information in the participant component 🤷‍♀️. in general, revealing only as much as is absolutely necessary should be the approach 🫧. less is more, periodt 💅.

for example, there may be some privacy considerations around the ORDER parameter, since it gives an indication of the organizer's perception of how important other participants are 👑. spicy 🌶️.

11. IANA Considerations ✨

11.1. Additional iCalendar Registrations

11.1.1. Properties

this document defines the following iCalendar properties that have been added to the "Properties" registry defined in Section 8.2.3 of [RFC5545] 📋:

      +====================+=========+=======================+
      | Property           | Status  | Reference             |
      +====================+=========+=======================+
      | CALENDAR-ADDRESS   | Current | RFC 9073, Section 6.4 |
      +--------------------+---------+-----------------------+
      | LOCATION-TYPE      | Current | RFC 9073, Section 6.1 |
      +--------------------+---------+-----------------------+
      | PARTICIPANT-TYPE   | Current | RFC 9073, Section 6.2 |
      +--------------------+---------+-----------------------+
      | RESOURCE-TYPE      | Current | RFC 9073, Section 6.3 |
      +--------------------+---------+-----------------------+
      | STRUCTURED-DATA    | Current | RFC 9073, Section 6.6 |
      +--------------------+---------+-----------------------+
      | STYLED-DESCRIPTION | Current | RFC 9073, Section 6.5 |
      +--------------------+---------+-----------------------+

           Table 1: Additions to the Properties Registry

11.1.2. Parameters

this document also defines the following iCalendar property parameters that have been added to the "Parameters" registry defined in Section 8.2.4 of [RFC5545] 🎀:

           +===========+=========+=======================+
           | Parameter | Status  | Reference             |
           +===========+=========+=======================+
           | ORDER     | Current | RFC 9073, Section 5.1 |
           +-----------+---------+-----------------------+
           | SCHEMA    | Current | RFC 9073, Section 5.2 |
           +-----------+---------+-----------------------+
           | DERIVED   | Current | RFC 9073, Section 5.3 |
           +-----------+---------+-----------------------+

            Table 2: Additions to the Parameters Registry

11.1.3. Components

and last but not least, this document defines the following iCalendar components that have been added to the "Components" registry defined in Section 8.3.1 of [RFC5545] 🧩:

          +=============+=========+=======================+
          | Component   | Status  | Reference             |
          +=============+=========+=======================+
          | PARTICIPANT | Current | RFC 9073, Section 7.1 |
          +-------------+---------+-----------------------+
          | VLOCATION   | Current | RFC 9073, Section 7.2 |
          +-------------+---------+-----------------------+
          | VRESOURCE   | Current | RFC 9073, Section 7.3 |
          +-------------+---------+-----------------------+

            Table 3: Additions to the Components Registry

11.2. Participant Types and Resource Types Registries

this section defines new registration tables for PARTICIPANT-TYPE and RESOURCE-TYPE values 🦋. these tables get updated using the same approaches laid down in Section 8.2.1 of [RFC5545] 🔄.

this document creates new IANA registries for participant and resource types 🌈. IANA will maintain these registries, and following the policies in [RFC8126], new tokens are assigned after Expert Review 📝. the Expert Reviewer will generally consult the IETF GEOPRIV Working Group mailing list, or its designated successor 📬. updates or deletions of tokens follow the same procedures ✅.

the Expert Review should be guided by a few common-sense considerations 🧠. for example, tokens should not be specific to a country, region, organization, or company. they should be well defined and widely recognized 🌍. the Expert's support of IANA includes providing IANA with the new token(s) when the update is provided only as a schema, and providing IANA with the new schema element(s) when the update is provided only as a token 💜.

to make sure tokens work widely across protocols, tokens MUST follow the character set restrictions for XML Names [W3C.REC-xml-20040204] 🫶. each registration must include the name of the token and a brief description, similar to the ones offered in this document for the initial registrations 🌸.

11.2.1. Participant Types

          +===================+=========+=======================+
          | Participant Type  | Status  | Reference             |
          +===================+=========+=======================+
          | ACTIVE            | Current | RFC 9073, Section 6.2 |
          +-------------------+---------+-----------------------+
          | INACTIVE          | Current | RFC 9073, Section 6.2 |
          +-------------------+---------+-----------------------+
          | SPONSOR           | Current | RFC 9073, Section 6.2 |
          +-------------------+---------+-----------------------+
          | CONTACT           | Current | RFC 9073, Section 6.2 |
          +-------------------+---------+-----------------------+
          | BOOKING-CONTACT   | Current | RFC 9073, Section 6.2 |
          +-------------------+---------+-----------------------+
          | EMERGENCY-CONTACT | Current | RFC 9073, Section 6.2 |
          +-------------------+---------+-----------------------+
          | PUBLICITY-CONTACT | Current | RFC 9073, Section 6.2 |
          +-------------------+---------+-----------------------+
          | PLANNER-CONTACT   | Current | RFC 9073, Section 6.2 |
          +-------------------+---------+-----------------------+
          | PERFORMER         | Current | RFC 9073, Section 6.2 |
          +-------------------+---------+-----------------------+
          | SPEAKER           | Current | RFC 9073, Section 6.2 |
          +-------------------+---------+-----------------------+

             Table 4: Initial Contents of the Participant Types
                                  Registry

11.2.2. Resource Types

       +=========================+=========+=======================+
       | Resource Type           | Status  | Reference             |
       +=========================+=========+=======================+
       | PROJECTOR               | Current | RFC 9073, Section 6.3 |
       +-------------------------+---------+-----------------------+
       | ROOM                    | Current | RFC 9073, Section 6.3 |
       +-------------------------+---------+-----------------------+
       | REMOTE-CONFERENCE-AUDIO | Current | RFC 9073, Section 6.3 |
       +-------------------------+---------+-----------------------+
       | REMOTE-CONFERENCE-VIDEO | Current | RFC 9073, Section 6.3 |
       +-------------------------+---------+-----------------------+

          Table 5: Initial Contents of the Resource Types Registry

12. Normative References 📚

okay bestie, these are the docs this spec leans on the hardest 🫶 without them, nothing here really makes sense. so here's the whole list, every single detail intact ✨

Acknowledgements 🫶

The author would like to thank Chuck Norris of eventful.com for his work, which led to the development of this RFC. 👑

The author would also like to thank the members of CalConnect: The Calendaring and Scheduling Consortium, the Event Publication technical committee, and the following individuals for contributing their ideas and support:

Cyrus Daboo, John Haug, Dan Mendell, Ken Murchison, and Scott Otis. 💖

Author's Address 🎀

Michael Douglass
Bedework
226 3rd Street
Troy, NY 12180
United States of America

Email: mdouglass@bedework.com
URI:   http://bedework.com

and that's the whole spec, bestie!! 🌈✨ you made it through all six parts 😭💅

📦 where this page comes from