.ICS File Format – Scheduling (iTIP)

Which methods apply to which component

What each does for an event: PUBLISH posts an event without inviting anyone (an Organizer is required, Attendees are forbidden); REQUEST invites, reschedules or updates; REPLY is the Attendee's answer (PARTSTAT ACCEPTED, DECLINED, TENTATIVE or DELEGATED) and also reports a failed attempt to process a request; ADD adds instances to an existing event; CANCEL cancels instances or the event; REFRESH is an Attendee asking the Organizer to resend the latest version; COUNTER is an Attendee's alternative proposal; DECLINECOUNTER is the Organizer's refusal of it. To-dos use the same roles (REQUEST assigns); journal entries have only PUBLISH, ADD and CANCEL.

How to read the rules

RFC 5546 states each method as a table of presence values: 1 exactly one must be present, 1+ at least one, 0 must not be present, 0+ any number, 0 or 1 at most one. The tables below list, for every method, only what is required or forbidden and the special rules; every other property of the component that is allowed in a calendar file is optional in the usual way (CATEGORIES, ATTACH, COMMENT, EXDATE, RDATE and RELATED-TO any number of times, the rest at most once, and DTEND and DURATION or DUE and DURATION never together). Extension properties (IANA-PROPERTY, X-PROPERTY) and components are allowed anywhere unless stated. The tables do not restrict parameters.

All messages

• VCALENDAR: PRODID 1, VERSION 1 (value 2.0), CALSCALE 0 or 1, and METHOD 1 whose value is the method.
• VTIMEZONE: must be present if any date-time refers to a time zone. Each has a TZID (1), at least one STANDARD or DAYLIGHT sub-component, and LAST-MODIFIED and TZURL (0 or 1 each). Each observance has DTSTART (local time form), TZOFFSETFROM and TZOFFSETTO (1 each), TZNAME, COMMENT and RDATE (0+) and RRULE (0 or 1); in a STANDARD component RDATE and RRULE must not both be present.
• VALARM (where allowed): ACTION 1, TRIGGER 1, DESCRIPTION, SUMMARY, ATTENDEE, ATTACH as the action needs; DURATION and REPEAT must appear together or not at all.

Events

To-dos

Optional in the to-do methods besides the usual: COMPLETED, PERCENT-COMPLETE, DUE (not with DURATION), DTSTART. STATUS values: COMPLETED, NEEDS-ACTION, IN-PROCESS, plus CANCELLED where stated.

Journal entries

Free-busy

In every free-busy message DTSTART and DTEND must be UTC date-times, and the component has exactly one VFREEBUSY (one or more for PUBLISH). VALARM, VEVENT, VTODO, VJOURNAL and VTIMEZONE are forbidden. COMMENT 0+, CONTACT 0 or 1.

Revisions, sequencing and scheduling state

• State. The state of the object is its STATUS (no default; the Organizer sets it). An Attendee's state is the PARTSTAT of its ATTENDEE property; the Organizer's first message leaves it NEEDS-ACTION and the Attendee changes it in a REPLY.
• When SEQUENCE must rise. When the Organizer changes DTSTART, DTEND, DURATION, DUE, RRULE, RDATE, EXDATE or STATUS, and for any other change that could invalidate Attendees' answers (a distant new location). It rises by the rules of PUBLISH and REQUEST, always with ADD and CANCEL, and never with REPLY, REFRESH, COUNTER, DECLINECOUNTER or a delegation REQUEST. Attendees should compare old and new versions rather than trust the number alone.
• Matching messages. The key is UID (with RECURRENCE-ID for an instance); among the same key the highest SEQUENCE replaces the others; for replies likewise; if the sequence is equal the later DTSTAMP wins. A client must therefore remember UID, RECURRENCE-ID, SEQUENCE and DTSTAMP, and an Organizer's client the sequence and stamp of each Attendee's last reply, so that late replies can be discarded.
• Roles. SENT-BY on ORGANIZER or ATTENDEE says someone acted on behalf of that user; answers still go to the Organizer.

What a REQUEST can mean (events)

• Invite: a new UID.
• Reschedule: the UID is known and SEQUENCE (or DTSTAMP) is greater than the stored one.
• Update or reconfirm: the UID is known and SEQUENCE is the same; it is also the answer to a REFRESH.
• Ask for status: ATTENDEE;RSVP=TRUE, same SEQUENCE; the Attendee replies with its current state.
• Delegate: the delegator forwards the request to the delegate (with an ATTENDEE for the delegate) and sends the Organizer a REPLY with PARTSTAT=DELEGATED and DELEGATED-TO; the delegate replies to the Organizer, optionally to the delegator too, with DELEGATED-FROM. The delegate takes part instead of, not in addition to, the delegator, who may keep getting updates by setting ROLE=NON-PARTICIPANT in the reply.
• Forward to an uninvited user: the Attendee forwards the unchanged request; the new user may REPLY to the Organizer, who decides whether to add an ATTENDEE (and should then send a REQUEST) or may send a CANCEL. A reply from an unknown user is a "party crasher".
• Change the Organizer: agreed out of band; the new Organizer sends a REQUEST with a higher SEQUENCE and the new ORGANIZER.

The same pattern applies to to-dos (the specification gives separate sections for them).

REQUEST-STATUS codes in replies

REQUEST-STATUS reports the outcome of a REPLY, COUNTER or DECLINECOUNTER; if absent, 2.0 is assumed. Within one component all codes must start with the same digit; across the components of a message, if any has a 5.x code every component must have one in that range (or none), else if any has 3.x the same rule applies; 2.x and 4.x may mix between components. extdata may carry the offending data. Others may be registered (IANA registry created by RFC 5546).