Subject: My Calendar Properties proposal

From: "Doug Royer [N6AAW]" <[email-masked]>
Date: Fri, 18 Sep 1998 19:48:56 -0700 (PDT)

Below are my thoughts on Calendar Properties.

-------------------------------------------------------------------------

Calendar properties.

For the sake of this and the ACL proposal. The usage of the
word 'client' refers to any client of the server, including
administrative client.

1.0) List of properties.
Here is my list of proposed iCalendar properties. This list is simply
a list of iCalendar properties that exists in legacy code in one
format or another, that I know that exists. Or that I have been
asked to add as a calendar property.

	calendar-property =	"BEGIN" ":" "CALENDAR-PROPERTY"
				1*calendar-properties
				"END" ":" "CALENDAR-PROPERTY"

	; created is defined in iCalendar section 4.8.7.1 .
	; x-prop is defined in iCalendar section 4.8.8.1 .
	;
	calendar-properties =
				/ calendar-name
				/ *calendar-owner
				/ created
				/ calendar-language
				/ inheritance
				/ *merged-calendars
				/ timezonec
				/ *workschedule
				/ x-prop

	cal-name-value =  <any calendar name>

	user = <any authenticated user name>

	; No parameters are defined for calendar-name
	;
	calendar-name =		"CALENDAR-NAME" *( ";" param) ":" 
				cal-name-value *( "," cal-name-value) CRLF

	; No parameters are defined for calendar-owner
	;
	calendar-owner =	"CALENDAR-OWNER" *( ";" param) ":"
				user *( "," user) CRLF

	; 'language' is the value for the "LANGUAGE" parameter in
	; iCalendar section 4.2.10.
	;
	; No parameters are defined for cal-language
	;
	; Default language for the calendar.
	;
	calendar-language =	"LANGUAGE" *( ";" param) ":" language CRLF

	;
	inheritance =		"INHERITANCE" *( ";" param )
				 ":" acl-inheritance CRLF

	acl-inheritance =	"ACL" "=" ( "YES" / "NO" / "ALWAYS" )

	; 'transvalue' is as define in section 4.8..2.7 of iCalendar.
	;
	merged =		"MERGED-CALENDAR"
				*( ";" "TRANSP" "=" transvalue)
				*param ":" text *( "," text) CRLF

	;
	workschedule =		dtstart
				( dtend / duration )
				*rrule
				*exrule
				*rdate
				*exdate
2.0) Property detail

2.1) Calendar Name.

This exists so that when an entire calendar is represented on the
wire it contains the calendar name. Example: backup/restore would
need this so that the data is tagged with the name of the calendar
that goes with a user selected and seemingly random file name.

Server:		MUST implement.

Client:		MUST implement.

2.2) Calendar Owner.
This calendar property is optional because this allows for 
the calendar administration to be compartmentalized.

If "CALENDAR-OWNER" is present, then the users named have
full access to all entries in the calendar - without specific ACLs.

In order to modify the "CALENDAR-OWNER" property the authenticated user
must have the "MODIFY-ACL" or "APPEND-ACL" as "CALENDAR-OWNER" is
another form of ACL.

Server:		MUST implement.

Client:		MUST implement.

2.3) Date/Time Calendar Created.
Date/Time the calendar was created.
Property is the same as iCalendar 4.8.7.1

Server:		MUST implement.

Client:		MAY implement.

If a calendar create command is received by the server and
it does not contain a "CREATED". Then the server MUST tag the
calendar with the current date time.

2.4) Calendar language.
Default language for the calendar when errors replies or messages
are sent over the wire from the server.

The iCalendar objects can contain the "LANGUAGE" parameter (iCalendar
section 4.2.10). However if a client sends a garbage command to
the server, an error message would need to be generated. The
language of the error message would be in this language Unless
directed otherwise by the (soon to be proposed) "LANGUAGE" CAP
command.

Server:		MUST implement.

Client:		MAY implement.

If a calendar create command is received by the server and
it does not contain a "LANGUAGE". Then the server MUST tag the
calendar with a "LANGUAGE" calendar property of the servers choice.

2.5) Inheritance.
When sub-calendars are created a sub-calendar might need ACLs.
This property specifies if those initial ACLs will be set
from the parents acl or how the parent may effect the sub-calendar's ACLs.

If the "ACL" value is "NO" then the sub-calendar may have
no ACLs or only the ACLs that are passed down in the create calendar
command or those that are added after the calendar create command.

If the "ACL" value is "YES" then during the calendar create command
the server MUST initialize the parents ACL list to match that of the
parent calendar. And at a later time ACLs may be added, deleted,
or modified in the sub-calendar independent of the parent calendar.

If the "ACL" value is "ALWAYS" then during the create the server MUST
initialize the parents ACL list to match that of the parent calendar.
Then as long as "ACL" is set to "ALWAYS" the sub-calendars ACLs MUST be
the same as the parents.

2.6) Time Zone
The default time zone for an iCalendar object. The iCalendar specification
defines that a component may specify a time in local time. If the
client and server are not in the same time zone this is a way for
the client to determine what 'local' means to the server.

Server:		MUST implement.

Client:		MAY implement.
		Note: If not implemented by the client and a new entry
		is sent to a server without a TZID (which is optional).
		The appointment might not be inserted at the date or
		time as intended by the end user.

		I assumed that the reason that TZID was optional in
		iCalendar was because some wanted a client to exist
		without	time zone knowledge. The word 'local' does not
		mean much of anything across time zones.

This calendar property can also be used by clients to determine
a default time zone for themselves.

2.7) Work Schedule.
Work schedule both aids "VFREEBUSY" and enforces some access control over
the calendar. 

For "VFREEBUSY" it simplifies the task of masking out "OPAQUE" time
that will never contain any components.

For access control it keeps someone from inserting an appointment
into a calendar outside of the valid operational time of the calendar.

Example:
		'Third-Shift' calendar may be set to 15:00pm-24:00.

		DTSTART;TZID=US/Pacific:01011990T150000
		DURATION:PT8H
		RRULE:FREQ=DAILY

		With these calendar properties no client would
		be able to append an entry into the third shift
		calendar outside of working hours for the 3rd shift.

For *all* if the WORK-SCHEDULE calendar properties:

Server:		MAY implement, MUST not reject if in "CAL-PROPERTY".
		MUST store values even if not enforced.

Client:		MAY implement. If not implemented, MUST NOT
		issue any command that will remove or modify
		Work Schedule calendar properties in the server.

2.7.1) Date/Time Start time of operational time for calendar.

This is part of work schedule and is used to describe the 
start date/time of valid operational time for the calendar.

Same as "DTSTART" in iCalendar section 4.8.2.4 except it MUST be
in the time zone described in 'timezonec' as defined by the target
calendars time zone property.

2.7.1) Date Time End or Duration of the operational time for the calendar.

This is part of work schedule and is used to describe the 
end date/time of valid operational time for the calendar.

Same as "DTEND" in iCalendar section 4.8.2.2  except it MUST be
in the time zone described in 'timezonec' as defined by the target
calendars time zone property.

And "DURATION" is defined in iCalendar section 4.3.6 .

2.7.1) Work Schedule; RRULE, RDATE, EXRULE, EXDATE
This is part of work schedule and is used to describe the 
recurrence rule for the valid operational time for the calendar.

2.8) Merged Calendars.

Merged views to allow shared common appointments.

A company might have 'companyHoliday' calendar, a 'department' calendar,
and a 'group' calendar. This is a method to merge those calendars
into both the "VFREEBUSY" and to optionally have the appointments
show up as if they were in the target calendar.

Merged calendar entries are read only regardless if the merged calendar
ACL allows modification or appends. Any attempt to modify an entry from
an merged calendar will result in a reply from the server equivalent to
not having ACL access to modify the entry.

merged-calendar =	"MERGED-CALENDAR" *( ";" mergeparam ) ":"
				calendar-name *("," calendar-name) CRLF

margeparam =		  *( ";" param) / *( ";" "TRANSP" "=" transvalue)

The default for "TRANSP" is "TRANSPARENT". That is any entry
that the authenticated user would have read access if directly
connected to calendar-name, would show up as if they were part of
the target current calendar selected. Additionally the transparency
of the items in the merged calendar would roll up into the current
calendar for free busy searches.

If "TRANSP" is "OPAQUE", then the "FREEBUSY" time for calendar-name
would be in addition to the target calendars "FREEBUSY". However
the entries in calendar-name would not be visible.

If calendar "Doug Royer" were the target calendar and it had:

	MERGED-CALENDAR: dougr,dougr/social,companyHolidays

Then all appointments in calendars 'dougr', 'dougr/social',
and 'companyHolidays' would be readable as if they were in
calendar 'Doug Royer'.

All appends to "Doug Royer" still go to "Doug Royer" and not
the merged calendars.

Any entry that was from a merged calendar would NOT be modifiable.
It is NOT possible to append to a merged calendar without directly
accessing the merged calendar.

And if calendar "Doug Royer" also had:

	MERGED-CALENDAR;TRANSP=OPAQUE: dougr/private

Then the "FREEBUSY" time from calendar 'dougr/private' would
roll up into calendar "Doug Royer". None of the entries in
calendar 'dougr/private' would be visible.

Server:		MAY implement, MUST not reject "MERGED-CALENDAR".
		MUST store values even if not enforced.

Client:		MAY implement. If not implemented, MUST NOT
		issue any command that will remove or modify
		"MERGED-CALENDAR" calendar properties in the server.

3.0) Example

	BEGIN:CAL-PROPERTY
	CALENDAR-NAME:Teams Base Ball [email-masked]
	CALENDAR-OWNER:doug,frank
	CREATED:19980101T000000Z
	LANGUAGE:EN-us
	INHERITANCE:ACL=YES
	MERGED-CALENDAR:Traning [email-masked]
	DTSTART;TZID=US/Pacific:19980801T170000
	DTSTART;TZID=US/Pacific:19980801T200000
	RRULE:FREQ=DAILY;UNTIL=19991230T235959Z;BYDAY=WED,THR
	BEGIN:VTIMEZONE
	TZID:US/Pacific
	LAST-MODIFIED:19870101T000000Z
	BEGIN:STANDARD
	DTSTART:19971026T020000
	RDATE:19971026T020000
	TZOFFSETFROM:-0700
	TZOFFSETTO:-0800
	TZNAME:PST
	END:STANDARD
	BEGIN:DAYLIGHT
	DTSTART:19971026T020000
	RDATE:19970406T020000
	TZOFFSETFROM:-0800
	TZOFFSETTO:-0700
	TZNAME:PDT
	END:DAYLIGHT
	END:VTIMEZONE
	END:CAL-PROPERTY

3.1) CALENDAR-NAME

	CALENDAR-NAME:Teams Base Ball Schedule

The calendar name is 'Teams Base Ball Schedule'

3.2) CALENDAR-OWNER

	CALENDAR-OWNER:doug,frank

Users 'doug' and 'frank' have unlimited access to the calendar.

3.3) CREATED

	CREATED:19980101T000000Z

The calendar was created at Jan 1st, 1998 at midnight Zulu.

3.4) LANGUAGE

	LANGUAGE:EN-us

Lacking any other (yet to be defined) command, the server
will respond in the U.S. English language.

3.5) INHERITANCE:ACL=YES

	INHERITANCE:ACL=YES

If any sub-calendars are created they will inherit any
ACL list from this calendar. After they are created, the
sub-calendars ACL list may be modified.

3.6) MERGED-CALENDAR

	MERGED-CALENDAR:Traning [email-masked]

Overlay the 'Traning [email-masked]' calendar on top, entries
that are visible by directly connecting to 'Training [email-masked]'
show up as part of this calendar view. Free busy time also
rolls up into this calendar.

3.7) Work schedule

	DTSTART;TZID=US/Pacific:19980801T170000
	DTSTART;TZID=US/Pacific:19980801T200000
	RRULE:FREQ=DAILY;UNTIL=19991230T235959Z;BYDAY=WE,TH

This calendar can only be inserted into between the hours of:

	5pm-8pm US/Pacific time
	and only on Wednesdays and Thursdays.

3.8) Time Zone

A standard "VTIMEZONE".

-Doug
-------------------------------------------------------------------
[email-masked]		http://www.royer.com/dougr.html
801 W. El Camino #131		Work:   (650)786-7599
Mountain View, CA 94040		Ham Radio: N6AAW, Aviation: PP-ASEL

---

From: "Frank Dawson" <[email-masked]>
Date: Mon, 28 Sep 1998 10:00:21 -0400

Doug:

Some comments on your contribution.

- - Frank Dawson

>1.0) List of properties.

<frd>snipped text</frd>

> / inheritance

<frd>Since this relates only to the ACL definitions, this property should be
moved from the "calendar properties" to the "acl properties". Calendar
properties apply to many different calendar components. This property
applies to the ACL component alone.</frd>

> cal-name-value =  <any calendar name>

<frd>snipped text</frd>

> ; No parameters are defined for cal-language

<frd>What value type is "user"? If it is text, then you will need to support
the same parameters as a text value.</frd>

<frd>snipped text.</frd>

>the client to determine what 'local' means to the server.

<frd>The server is just a calendar repository for the client. Since clients
can be mobile, your use of the term "'local'" is ambiguous. In addition,
iCalendar provides for 3 time formats. The local+TZID does not necessitate
the specification of this property. If a local+TZID formatted time is
specified in an iCalendar object, the time zone associated with the TZID
must either be specified also or point to a registered time zone definition.
In the case of a UTC formatted time, this property is not necessary. Lastly,
for a local time formatted value, the semantic is not that you are to use
the local server time, but rather the current local time within the client.
In this third case, you also do not need this property. Unless you have a
concrete scenario for it's use, this calendar property should be
removed.</frd>

<frd>snipped text.</frd>

> mean much of anything across time zones.

<frd>Quite the contrary. A local formatted time value, without a TZID
specified, means that the client is to use it's own local time when
determining the DTSTART or DTEND/DUE for the calendar component.</frd>

<frd>snipped text.</frd>

>that will never contain any components.

<frd>I think we have some confusion here. This property dates back to the
ISO/ITU Distributed Office Application work on the Engagement Scheduling and
Recording Application (ESRA). It was also borrowed for use in the XAPIA and
X/Open Calendaring and Scheduling API (CSA). A work schedule defines the
possibly repeating periods for which the calendar user *typically* schedules
appointments. This does *not* mean that events can not be scheduled during
these periods. Rather, that when you request busy time information, this
interval should be masked as "busy and not schedulable". This is far
different than ""OPAQUE" time that will never contain any components". In
reality, a calenedar owner (or a calendar user with the same access right as
the owner) can schedule calendar components during non-work scheduled
periods. If this were not the case, then we couldn't use a single calendar
for both personal, as well as work components.</frd>

<frd>snipped text.</frd>

> DTSTART;TZID=US/Pacific:01011990T150000

<frd>Don't let the labor office know about this 7-day aweek work schedule
;-) Maybe you meant some set of days of the week, other than all 7? It would
make a more realistic example, anyway.</frd>

<frd>snipped text.</frd>

> MUST store values even if not enforced.

<frd>You don't really mean this do you? A server must store even the
non-standard properties?</frd>

<frd>snipped text.</frd>

<frd>This seems best addressed as a client function, not a server function.
If the client needs to display a logical view with calendar data from more
than one calendar, then they will access more than one calendar.</frd>

<frd>snipped text.</frd>

>The calendar name is 'Teams Base Ball Schedule'

<frd> Where are the text value parameter for this property? You need to be
able to specify LANGUAGE and other text parameters.</frd>

>Users 'doug' and 'frank' have unlimited access to the calendar.

<frd>This seems to be saying that the property takes on a "calendar user"
value. This has an architectural problem associated with it. You have just
introduced two mechanisms to define access rights; the ACL calendar
component and the CAL-OWNER property. This will lead to possible data/access
rights inconsistencies. This property can only take on the semantics of a
display name. It can only have a text value. Hence, it needs the common
parameters for text values. If you want to know who is the owner of a
calendar, then check the ACL for the calendar user(s) that have "OWNER"
access rights.</frd>

<frd>snipped text.</frd>

>will respond in the U.S. English language.

<frd>Assume that any valid iCalendar value for LANGUAGE parameter can also
be specified here? Needs to say so.</frd>

>sub-calendars ACL list may be modified.

<frd> Per my previous observation. This should not be a calendar property,
but rather a property within the ACL calendar component.</frd>