Mac OS X Reference Library Apple Developer
Search

iCal Calendars

Schema Name

com.apple.Calendars

Declared in

/System/Library/SyncServices/Schemas/Calendars.syncschema

Data Classes

com.apple.Calendars

Availability

Available in Mac OS X v10.4 and later.

The Calendars schema defines all the entities and properties used to represent a calendar in iCal—entities used to create a calendar object containing multiple event and tasks with associated alarms. Other entities are used to describe details of an event or task such as the frequency, organizer, and attendees of an event.

Figure 1 illustrates some of the entities, attributes, and relationships contained in the Calendars schema.

Important: In this schema, if the time value of a calendar date attribute is not specified, iCal will default it to 12:00 GMT/UTC.

Figure 1  Calendars schema

Calendars schema

Syncing notes: How applications interpret a Boolean property missing from a pushed record is application dependent. If you omit a Boolean property from a pushed record, iCal assumes you intend to set the value to NO.

Attendee

Entity name

com.apple.calendars.Attendee

Data class

com.apple.Calendars

Availability

Available in Mac OS X v10.4 and later.

Someone who attends an event or participates in a task. Below are the attributes and relationships of an Attendee record.

Attribute

Type

Description

common name

string

This attendee’s display name.

Available in Mac OS X v10.4 and later.

delegatedfrom

array

An array of strings representing email addresses of those people who delegated participation in an event or task to this attendee.

Available in Mac OS X v10.4 and later.

delegatedto

array

An array of strings representing the email addresses of people whom an attendee has delegated to participation in an event or task. For example, a manager may delegate participation in an event to his/her staff.

Available in Mac OS X v10.4 and later.

directory entry

url

This attendee’s directory entry in an LDAP database. The entry is a URL conforming to RFC 2255. See The LDAP URL Format for details.

Available in Mac OS X v10.4 and later.

email

string

This attendee’s email address.

Available in Mac OS X v10.4 and later.

role

string

The role of this attendee. Possible values are chair, requiredparticipant, optionalparticipant, and nonparticipant. iCal defaults this value to requiredparticipant.

Available in Mac OS X v10.4 and later.

rsvp

boolean

Set to YES if a response from this attendee is required, NO otherwise. iCal defaults this value to NO.

Available in Mac OS X v10.4 and later.

status

string

A string that indicates the participation status of this attendee. Possible values are needsaction, accepted, declined, tentative, delegated, completed, and inprocess.

Available in Mac OS X v10.4 and later.

user type

string

The type of attendee. Possible values are individual, group, resource, room, and unknown. iCal defaults this value to individual.

Available in Mac OS X v10.4 and later.

Relationship

Targets

Description

owner

Event, Task

The event or task associated with this attendee.

Available in Mac OS X v10.4 and later.

AudioAlarm

Entity name

com.apple.calendars.AudioAlarm

Data class

com.apple.Calendars

Availability

Available in Mac OS X v10.4 and later.

An alarm that alerts the user of a pending event or task by playing an audio file. Below are the attributes and relationships of an AudioAlarm record.

Attribute

Type

Description

description

string

Long description of this alarm.

Available in Mac OS X v10.4 and later.

repeat count

number

The number of times this alarm will repeat.

Available in Mac OS X v10.4 and later.

repeat interval

number

The delay, in seconds, between alarm repeats.

Available in Mac OS X v10.4 and later.

sound

string

The name of a system sound that plays when this alarm triggers.

Available in Mac OS X v10.5 and later.

summary

string

Short description of this alarm.

Available in Mac OS X v10.4 and later.

triggerdate

calendar date

The date/time this alarm will trigger. This is an absolute value. If you set triggerdate, do not set triggerduration.

Available in Mac OS X v10.4 and later.

triggerduration

number

The delay, in seconds, between this alarm and the reference date of owner. The reference date for an event is start date, and for a task is due date. If negative, triggers before the reference date, otherwise after the reference date. If you set triggerduration, do not set triggerdate.

Available in Mac OS X v10.4 and later.

Relationship

Targets

Description

owner

Event, Task

The event or task associated with this alarm.

Available in Mac OS X v10.4 and later.

Calendar

Entity name

com.apple.calendars.Calendar

Data class

com.apple.Calendars

Availability

Available in Mac OS X v10.4 and later.

Represents a group of events and tasks which can have a number of alarms. For example, events associated with work can be grouped together on one calendar and manipulated separately from other events. Below are the attributes and relationships of a Calendar record.

Attribute

Type

Description

color

color

The color used to display this calendar and its events.

Available in Mac OS X v10.5 and later.

notes

string

A description of this calendar.

Available in Mac OS X v10.4 and later.

read only

boolean

A flag that indicates whether or not this calendar is read only. Set to YES if read-only, NO otherwise.

Available in Mac OS X v10.4 and later.

subscription_url

url

The URL for a subscription calendar.

Available in Mac OS X v10.5 and later.

title

string

The name of this calendar.

Available in Mac OS X v10.4 and later.

url

url

A link to a webpage about this calendar.

Available in Mac OS X v10.4 and later.

Relationship

Targets

Description

events

Event

Events belonging to this calendar.

Available in Mac OS X v10.4 and later.

tasks

Task

Tasks belonging to this calendar.

Available in Mac OS X v10.4 and later.

CalendarOrder

Entity name

com.apple.calendars.CalendarOrder

Data class

com.apple.Calendars

Availability

Available in Mac OS X v10.4 and later.

Represents an ordered collection of calendars. There can be only one CalendarOrder record. This record is used by iCal and is intended to be read-only to all other clients. Below are the attributes and relationships of a CalendarOrder record.

Attribute

Type

Description

identity

string

A string used to identify this record. Must be set to com.apple.calendars.CalendarOrder.

Available in Mac OS X v10.4 and later.

Relationship

Targets

Description

calendars

Calendar

All of the calendars in this collection.

Available in Mac OS X v10.4 and later.

CalDAVAccount

Entity name

com.apple.calendars.CalDAVAccount

Data class

com.apple.Calendars

Availability

Available in Mac OS X v10.5 and later.

Represents a CalDAV account used to subscribe to its calendars. For example, if you add a CalDAVAccount record, iCal attempts to subscribe to it and if successful, display its calendars. There may be multiple CalDAVAccount records.

Attribute

Type

Description

displayName

string

A human-readable name for this account that iCal uses to represent this account and its group of calendars.

Available in Mac OS X v10.5 and later.

login

string

Login name for this account.

Available in Mac OS X v10.5 and later.

fullName

string

Full name of the user for this account.

Available in Mac OS X v10.5 and later.

principalURL

string

The URL for subscribing to this CalDAV account.

Available in Mac OS X v10.5 and later.

useKerberos

boolean

A flag that indicates whether or not to use Kerberos to authenticate this account. Set to YES if Kerberos should be used, NO otherwise.

Available in Mac OS X v10.5 and later.

refreshInterval

number

How often in seconds to refresh this account and its calendars in iCal.

Available in Mac OS X v10.5 and later.

order

number

The order of this account’s group of calendars in the iCal display of calendars and groups..

Available in Mac OS X v10.5 and later.

isAutoDiscovery

boolean

A flag indicating whether or not the principal URI was automatically discovered by iCal. Set to YES if it was automatically discovered, NO otherwise. iCal sets this value when it subscribes to this account.

Available in Mac OS X v10.5 and later.

DisplayAlarm

Entity name

com.apple.calendars.DisplayAlarm

Data class

com.apple.Calendars

Availability

Available in Mac OS X v10.4 and later.

An alarm that alerts the user of a pending event or task by displaying something. Below are the attributes and relationships of a DisplayAlarm record.

Attribute

Type

Description

description

string

A description of this alarm.

Available in Mac OS X v10.4 and later.

repeat count

number

The number of times this alarm will repeat.

Available in Mac OS X v10.4 and later.

repeat interval

number

The delay, in seconds, between alarm repeats.

Available in Mac OS X v10.4 and later.

triggerdate

calendar date

The date/time this alarm will trigger. This is an absolute value.

Available in Mac OS X v10.4 and later.

triggerduration

number

The delay, in seconds, between this alarm and the reference date of owner. The reference date for an event is start date, and for a task is due date. If negative, triggers before the reference date, otherwise after the reference date.

Available in Mac OS X v10.4 and later.

Relationship

Targets

Description

owner

Event, Task

The event or task associated with this alarm.

Available in Mac OS X v10.4 and later.

Event

Entity name

com.apple.calendars.Event

Data class

com.apple.Calendars

Availability

Available in Mac OS X v10.4 and later.

Represents a scheduled event or activity that can be displayed on a calendar. Below are the attributes and relationships of an Event record.

Attribute

Type

Description

all day

boolean

A flag that indicates whether or not this event occurs all day. Set to YES if this event occurs all day, NO otherwise.

Available in Mac OS X v10.4 and later.

classification

string

The classification of this event. Possible values are public, private, and confidential. iCal defaults this value to public.

Available in Mac OS X v10.4 and later.

description

string

A description of this event.

Available in Mac OS X v10.4 and later.

end date

calendar date

The end date and time of this event.

Available in Mac OS X v10.4 and later.

exception dates

array

An array of calendar dates that are exceptions to the recurrence of this event—dates where this event will not occur.

Available in Mac OS X v10.4 and later.

floatingGMTDate

calendar date

The date of the floating event in GMT time.

Available in Mac OS X v10.5 and later.

floatingOffset

number

The difference between the fixed date and GMT date of a floating event.

Available in Mac OS X v10.5 and later.

location

string

The location where this event will take place.

Available in Mac OS X v10.4 and later.

original date

calendar date

The original date of a detached event. When you create a recurrent event, a list of occurrences of the event are created. If you change a property of an occurrence of the event, it becomes detached and this attribute is used to record the original occurrence date.

Available in Mac OS X v10.4 and later.

priority

number

A number from 0 to 9 used to indicate the priority of this event, where 0 indicates no priority, 1 indicates maximum priority, and 9 indicates minimum priority. For example, iCal uses 1 for high, 5 for medium and 9 for low priority (mostly used for tasks, not events).

Available in Mac OS X v10.4 and later.

start date

calendar date

The start date and time of this event.

Available in Mac OS X v10.4 and later.

status

string

A string that indicates the status of this event. Possible values are tentative, confirmed, cancelled, or none. iCal defaults this value to none.

Available in Mac OS X v10.4 and later.

summary

string

A short description of this event.

Available in Mac OS X v10.4 and later.

url

url

A link to a webpage about this event.

Available in Mac OS X v10.4 and later.

Relationship

Targets

Description

attendees

Attendee

People who are invited to attend this event.

Available in Mac OS X v10.4 and later.

audio alarms

AudioAlarm

Audio alarms associated with this event.

Available in Mac OS X v10.4 and later.

calendar

Calendar

The calendar this event belongs to.

Available in Mac OS X v10.4 and later.

detached events

Event

Events that were detached from this (recurrent) event. Only detached events have a main event relationship set to its parent event. Used only if events were detached from this parent event.

Available in Mac OS X v10.4 and later.

display alarms

DisplayAlarm

Display alarms associated with this event.

Available in Mac OS X v10.4 and later.

mail alarms

MailAlarm

Mail alarms associated with this event.

Available in Mac OS X v10.4 and later.

main event

Event

The parent event of this event. Used only if this is a detached event.

Available in Mac OS X v10.4 and later.

organizer

Organizer

Person or organization that sponsored this event.

Available in Mac OS X v10.4 and later.

recurrences

Recurrence

Recurrence that contains frequency details about this event.

Available in Mac OS X v10.4 and later.

MailAlarm

Entity name

com.apple.calendars.MailAlarm

Data class

com.apple.Calendars

Availability

Available in Mac OS X v10.4 and later.

An alarm that alerts the user of a pending event or task by sending email. Below are the attributes and relationships of a MailAlarm record.

Attribute

Type

Description

description

string

Long description of this alarm.

Available in Mac OS X v10.4 and later.

recipients

array

An array of strings representing email addresses that will receive notification of this alarm.

Available in Mac OS X v10.4 and later.

repeat count

number

The number of times this alarm will repeat.

Available in Mac OS X v10.4 and later.

repeat interval

number

The delay, in seconds, between alarm repeats.

Available in Mac OS X v10.4 and later.

summary

string

Short description of this alarm.

Available in Mac OS X v10.4 and later.

triggerdate

calendar date

The date/time this alarm will trigger. This is an absolute value.

Available in Mac OS X v10.4 and later.

triggerduration

number

The delay, in seconds, between this alarm and the reference date of owner. The reference date for an event is start date, and for a task is due date. If negative, triggers before the reference date, otherwise after the reference date.

Available in Mac OS X v10.4 and later.

Relationship

Targets

Description

owner

Event, Task

The event or task associated with this alarm.

Available in Mac OS X v10.4 and later.

Organizer

Entity name

com.apple.calendars.Organizer

Data class

com.apple.Calendars

Availability

Available in Mac OS X v10.4 and later.

Person or organization who sponsors or creates an event or task. Below are the attributes and relationships of an Organizer record.

Attribute

Type

Description

common name

string

This organizer’s display name.

Available in Mac OS X v10.4 and later.

directory entry

url

This organizer’s directory entry in an LDAP database. The entry is a URL conforming to RFC 2255. See The LDAP URL Format for details.

Available in Mac OS X v10.4 and later.

email

string

This organizer’s email address.

Available in Mac OS X v10.4 and later.

Relationship

Targets

Description

owner

Event, Task

The event or task sponsored by this organizer.

Available in Mac OS X v10.4 and later.

Recurrence

Entity name

com.apple.calendars.Recurrence

Data class

com.apple.Calendars

Availability

Available in Mac OS X v10.4 and later.

Represents the details of the frequency of which an event or task may occur. Below are the attributes and relationships of a Recurrence record.

Attribute

Type

Description

bydaydays

array

An array of strings representing the days of the week on which this recurrence occurs. Possible string values are sunday, monday, tuesday, wednesday, thursday, friday, and saturday. If you set bydaydays, you must also set bydayfreq. For example, if bydaydays is monday and bydayfreq contains 0, then the recurrence is every Monday.

Available in Mac OS X v10.4 and later.

bydayfreq

array

An array of integer numbers used in combination with bydaydays to specify which week within a month or year this recurrence occurs. For example, if frequency is monthly, bydaydays is monday and bydayfreq contains 2, then the recurrence will occur the second Monday of every month.

Available in Mac OS X v10.4 and later.

bymonth

array

An array of numbers, with integer values ranging from 1 to 12, that indicate the months within a year that this recurrence occurs.

Available in Mac OS X v10.4 and later.

bymonthday

array

An array of numbers, with integer values ranging from 1 to 31 or -31 to -1, that indicate the days within a month that this recurrence occurs. Negative values indicate the number of days from the last day of the month.

Available in Mac OS X v10.4 and later.

bysetpos

array

An array of integer numbers used to specify specific days within an expanded set of occurrences. The numbers specify the index of an expanded sequence of occurrences starting with 1. For example, if frequency is daily, the event or task starts on a Monday, and bysetpos is (1, 8), then the recurrence will occur on the first and second Mondays only. If bysetpos is (2, 8) the event or task will occur on the first Tuesday in the sequence and the second Monday.

Available in Mac OS X v10.4 and later.

byweeknumber

array

An array of numbers, with integer values ranging from 1 to 53 or -53 to -1, that indicate the weeks within a year that this recurrence occurs. Negative values indicate the number of weeks from the last week of the year.

Available in Mac OS X v10.4 and later.

byyearday

array

An array of numbers, with integer values ranging from 1 to 366 or -366 to -1, that indicate the days within a year that this recurrence occurs. Negative values indicate the number of days from the last day of the year.

Available in Mac OS X v10.4 and later.

count

number

The number of occurrences generated by this recurrence.

Available in Mac OS X v10.4 and later.

frequency

string

The frequency of this recurrence specified by a constant. Possible values are daily, weekly, monthly, or yearly.

Available in Mac OS X v10.4 and later.

interval

number

A positive integer indicating how often the specified frequency repeats. For example, if frequency is daily, then an interval value of 2 indicates a recurrence every two days.

Available in Mac OS X v10.4 and later.

until

calendar date

The end date of this recurrence.

Available in Mac OS X v10.4 and later.

weekstartday

string

A string that indicates the start day of the week. Possible values are sunday, monday, tuesday, wednesday, thursday, friday, and saturday.

Available in Mac OS X v10.4 and later.

Relationship

Targets

Description

owner

Event, Task

The event or task in which this recurrence appears.

Available in Mac OS X v10.4 and later.

Task

Entity name

com.apple.calendars.Task

Data class

com.apple.Calendars

Availability

Available in Mac OS X v10.4 and later.

Something that you need to do or accomplish. Below are the attributes and relationships of a Task record.

Attribute

Type

Description

classification

string

A string that indicates the classification of this task. Possible values are public, private, or confidential. iCal defaults this value to public.

Available in Mac OS X v10.4 and later.

completion date

calendar date

The completion date/time of this task.

Available in Mac OS X v10.4 and later.

description

string

A long description of this task.

Available in Mac OS X v10.4 and later.

due date

calendar date

Due date/time of this task. If the date is specified but not the time, iCal defaults the time to 12:00 GMT/UTC.

Available in Mac OS X v10.4 and later.

due date is date only

boolean

A flag that is set to YES if due date is a date-only value, and NO if it has a date and time.

Available in Mac OS X v10.4 and later.

exception dates

array

An array of calendar dates that are exceptions to the recurrence of this event—dates when this event will not occur.

Available in Mac OS X v10.4 and later.

original date

calendar date

The original date of a detached task. When you create a recurrent task, a list of occurrences of the task is created. If you change a property of an occurrence task, it becomes detached and this attribute is used to record the original occurrence date.

Available in Mac OS X v10.4 and later.

priority

number

A number from 0 to 9 used to indicate the priority of this task, where 0 indicates no priority, 1 indicates maximum priority, and 9 indicates minimum priority. For example, iCal uses 1 for high, 5 for medium and 9 for low priority.

Available in Mac OS X v10.4 and later.

start date

calendar date

The start date of this task (must be a date-only value).

Available in Mac OS X v10.4 and later.

status

string

A string that indicates the status of this task. Possible values are cancelled, needsaction, completed, inprocess or none. iCal defaults this value to none.

Available in Mac OS X v10.4 and later.

summary

string

A short description of this task.

Available in Mac OS X v10.4 and later.

url

url

A link to a webpage about this task.

Available in Mac OS X v10.4 and later.

Relationship

Targets

Description

attendees

Attendee

People who will participate in this task.

Available in Mac OS X v10.4 and later.

audio alarms

AudioAlarm

The audio alarms associated with this task.

Available in Mac OS X v10.4 and later.

calendar

Calendar

The calendar this task belongs to.

Available in Mac OS X v10.4 and later.

detached tasks

Task

Tasks that are detached from this task. Not used if this is not a recurrent task.

Available in Mac OS X v10.4 and later.

display alarms

DisplayAlarm

The display alarms associated with this task.

Available in Mac OS X v10.4 and later.

mail alarms

MailAlarm

The mail alarms associated with this task.

Available in Mac OS X v10.4 and later.

main task

Task

The parent task of this task. Not used if this is not a detached task.

Available in Mac OS X v10.4 and later.

organizer

Organizer

The person or organization that initiated this task.

Available in Mac OS X v10.4 and later.

recurrences

Recurrence

The recurrence that contains frequency details about this task.

Available in Mac OS X v10.4 and later.



Last updated: 2009-07-07

Did this document help you? Yes It's good, but... Not helpful...