ORDER

To define ordering for the associated property.

This parameter is defined by the following notation:

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

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.

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.

SCHEMA

To specify the schema used for the content of a “STRUCTURED-DATA” property value.

This parameter is defined by the following notation:

schemaparam    = "SCHEMA" "=" DQUOTE uri DQUOTE

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.

DERIVED

To specify that the value of the associated property is derived from some other property value or values.

This parameter is defined by the following notation:

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

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 and a value created from the rtf value.

LOCATION-TYPE

To specify the type(s) of a location.

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

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.

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 IETF RFC 4589, Section 3. New location types SHOULD be registered in the manner laid down in section 5 of that specification.

PARTICIPANT-TYPE

To specify the type of participant.

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

Non-standard parameters can be specified on this property.

This property MUST be specified once within a PARTICIPANT component.

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.

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)

A participant taking an active role — for example a team member.

A participant taking an inactive role — for example an audience member.

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

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

Contact information for reservations or payment

Contact in case of emergency

Contact for publicity

Contact for the event planner or organizer

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 at an event

RESOURCE-TYPE

To specify the type of resource.

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

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)

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

A room for the event/meeting.

Projection equipment.

Audio remote conferencing facilities.

Video remote conferencing facilities.

CALENDAR-ADDRESS

To specify the calendar address for a participant.

CAL-ADDRESS

IANA-registered, or non-standard property parameters can be specified on this property.

This property MAY be specified once within a PARTICIPANT component.

This property provides a calendar user address for the participant. If there is an ATTENDEE property with the same value then the participant is schedulable.

This property is defined by the following notation:

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

caladdressparam   = *(";" other-param)

STYLED-DESCRIPTION

This property provides for one or more rich-text descriptions to replace that provided by the DESCRIPTION property.

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.

IANA-registered, non-standard, id, alternate text representation, format type, derived and language property parameters can be specified on this property.

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 be either absent or have the parameter DERIVED=TRUE.

This property supports rich-text descriptions, for example HTML. Event publishers typically wish to provide more and better formatted information about the event.

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. In the PARTICIPANT component it provides 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.

This property is defined by the following notation:

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

The following is an example of this property. It points to an html description.

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

STRUCTURED-DATA

This property specifies ancillary data associated with the calendar component.

There is no default value type for this property. The value type can be set to TEXT, BINARY or URI

IANA-registered, non-standard, 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.

This property can be specified multiple times in an iCalendar object. Typically it would be used in “VEVENT”, “VTODO” or “VJOURNAL” calendar components.

The existing properties in iCalendar cover key elements of events and tasks such as start time, end time, location, summary, etc. However, different types of events often have other specific “fields” that it is 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 non-calendaring 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 with a link to the resource. Thus a new property to support inclusion of schema data is warranted.

This property is defined by the following notation:

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)
                ;
             )

The following is an example of this property:

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

PARTICIPANT

This component provides information about a participant in an event or task.

This component can be specified multiple times in a “VEVENT”, “VTODO”, “VJOURNAL” or “VFREEBUSY” calendar component.

This component provides information about a participant 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, for example a soccer team, the spectators or the musicians.

STRUCTURED-DATA properties if present may refer to definitions of the participant — such as a vCard.

The CALENDAR-ADDRESS property if present will provide a cal-address. If an ATTENDEE property has the same value the participant is considered schedulable. The PARTICIPANT component can be used to contain additional meta-data related to the attendee.

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
               ;
               )

When the PRIORITY is supplied it defines the ordering of PARTICIPANT components with the same value for the PARTICIPANT-TYPE property.

When a LOCATION is supplied it provides information about the location of a participant at a given time or times. This may represent 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.

The following is an example of this component. It contains a STRUCTURED-DATA property which points to a vCard providing information about the event participant.

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

The following is an example 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

The following is an example for a participant with contact and 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

VLOCATION

This component provides rich information about the location of an event using the structured data property or optionally a plain text typed value.

This component can be specified multiple times in a “VEVENT”, “VTODO”, “VJOURNAL”, “VFREEBUSY” or “PARTICIPANT” calendar component.

There may be a number of locations associated with an event. This component provides detailed information about a location.

When used in a component the value of this property provides information about the event venue or of related services such as parking, dining, stations etc.

STRUCTURED-DATA properties if present may refer to representations of the location — such as a vCard.

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 following is an example of this component. It 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

VRESOURCE

This component provides a typed reference to external information about a resource or optionally a plain text typed value. Typically a resource is anything that might be required or used by a calendar entity and possibly has a directory entry.

This component can be specified multiple times in a “VEVENT”, “VTODO”, “VJOURNAL”, “VFREEBUSY” or “PARTICIPANT” calendar component.

When used in a component this component provides information about resources used for the event such as rooms, projectors, conferencing capabilities.

The RESOURCE-TYPE value registry provides a place in which resource types may be registered.

STRUCTURED-DATA properties if present may refer to representations of the resource — such as a vCard.

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 following is an example of this component. It 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