hcalendar-singular-properties

hCalendar singular properties

This is an explanation of the list of singular properties in hCalendar.

This page is a stub and should not be considered "complete" documentation until all properties in hCalendar/iCalendar have been analylzed and documented.

The analysis here is derived from thoroughly reading and analyzing both section "4.6.1 Event Component" and the specific property definitions in the iCalendar RFC 2445 spec, along with reasoning using physics, and reasonableness.

This summary is provided because that thorough reading and analysis (will take / takes) a long time, and while repeatable, is not something that is worth encumbering other developers with. See the Reasoning section for more.

Editor/Author

Tantek Çelik

vevent properties

class

Per section 4.6.1 - MUST NOT occur more than once.

created

Per section 4.6.1 - MUST NOT occur more than once.

description

Per section 4.6.1 - MUST NOT occur more than once.

dtend

Section 4.6.1 says "either 'dtend' or 'duration' may appear in a 'eventprop', but 'dtend' and 'duration' MUST NOT occur in the same 'eventprop'" which implies that there should be at most one of either, but not both.

dtstart

Per section 4.6.1 - MUST NOT occur more than once.

duration

Section 4.6.1 says "either 'dtend' or 'duration' may appear in a 'eventprop', but 'dtend' and 'duration' MUST NOT occur in the same 'eventprop'" which implies that there should be at most one of either, but not both.

geo

Per section 4.6.1 - MUST NOT occur more than once.

last-mod

Per section 4.6.1 - MUST NOT occur more than once.

location

Per section 4.6.1 - MUST NOT occur more than once.

organizer

Per section 4.6.1 - MUST NOT occur more than once.

priority

Per section 4.6.1 - MUST NOT occur more than once.

dtstamp

Per section 4.6.1 - MUST NOT occur more than once.

recurid

Per section 4.6.1 - MUST NOT occur more than once.

seq

Per section 4.6.1 - MUST NOT occur more than once.

status

Per section 4.6.1 - MUST NOT occur more than once.

Also implied in property definition. From rfc-2445:

"4.8.1.11 ... Purpose: This property defines the overall status or confirmation for the calendar component."

(emphasis added).

It also makes sense for an event to have at most one STATUS.

summary

Per section 4.6.1 - MUST NOT occur more than once.

However, note that section 4.8.1.12 Summary says: "Purpose: This property defines a short summary or subject for the calendar component." (emphasis added).

It could make sense for an event to have multiple SUMMARY value, perhaps of different lengths, so user interfaces that allocate different amounts of space for events (either in a short listing or lengthier listing) can display whichever SUMMARY fits.

However, in practice there has been no demand for multiple summaries, and thus it is better to keep the SUMMARY property singular consistent with the iCalendar spec unless there is a sufficient reason given to do otherwise.

transp

Per section 4.6.1 - MUST NOT occur more than once.

uid

Per section 4.6.1 - MUST NOT occur more than once.

The "uid" property is a globally unique identifier corresponding to the event associated with the hCalendar vevent. It doesn't make sense for an hCalendar vevent to have more than one "uid".

not singular FAQ

It's also useful to document which properties we have determined are not singular and why, to reduce the need to re-analyze them.

url

Not that section 4.6.1 lists "url" in the sentence listing properties that "MUST NOT occur more than once."

This appears to be a bug in the iCalendar specification:

• vCard allows for multiple URLs, why not iCalendar?
• it is very useful for an event to link to multiple URLs that represent it (perhaps one local to the event listing site, and perhaps additional links to equivalents on other sites).
  • real world: Upcoming.org does this for example.

Thus hCalendar permits more than one "url" per "vevent".

hCalendar to iCalendar processors may:

• Output any iCalendar VEVENT URL: property line per hCalendar vevent url property and let iCalendar implementations handle them as they can. OR
• Take only one url property (as chosen below) and use it to output at most one iCalendar VEVENT URL: property line
  • First, if there is a url property that is also the value of the uid property, then use it.
  • Otherwise use the first url property found in the hCalendar vevent.

reasoning

Reasoning and methodology.

Tantek Çelik has analyzed both the explicit conformance requirements (in particular 4.6.1 Event Component) and the language of the iCalendar specification, and (is doing / did) logical analysis on the semantics of each property to determine its singular vs. plural status. Such derived/implied conformance criteria have value from such specs, as they typically do capture the intent of the authors of the spec. The goal is to minimize the introduction of new rules/assumptions as much as possible (per the principles). Relying upon only the iCalendar specification and logical reasoning seemed the best way to do so. The only exception(s) that have/has been made are in the case where it is very practical to do so (e.g. URL), and in such cases a conversion is provided for hCalendar to iCalendar processors.

related pages

• hCalendar singular properties
• hCalendar - specification
• hCalendar intro - plain English introduction
• hCalendar authoring - learn how to add hCalendar markup to your existing events.
• hCalendar creator (hCalendar creator feedback) - create your own hCalendar events.
• hCalendar cheatsheet - hCalendar properties
• hCalendar examples in the wild - an on-going list of websites which use hCalendars.
• hCalendar implementations - websites or tools which either generate or parse hCalendars
• hCalendar FAQ - If you have any questions about hCalendar, check here.
• hCalendar parsing - normative details of how to parse hCalendar.
• hCalendar profile - the XMDP profile for hCalendar
• hCalendar singular properties - an explanation of the list of singular properties in hCalendar.
• hCalendar tests - a wiki page with actual embedded hCalendar events to try parsing.
• hCalendar "to do" - jobs to do
• hCalendar advocacy - encourage others to use hCalendar.
• iCalendar implementations

This specification is a work in progress. As additional aspects are discussed, understood, and written, they will be added. These thoughts, issues, and questions are kept in separate pages.

• hCalendar Brainstorming - brainstorms and other explorations relating to hCalendar
• hCalendar issues - issues with the specification