calendar-plugin/requirements/ics.md

ICS Export Requirements

Purpose

Define requirements for generating iCalendar (.ics) output from plugin calendar data.

Standards and RFC

ICS output must comply with the iCalendar specification:

• RFC 5545: Internet Calendaring and Scheduling Core Object Specification (iCalendar)

Where additional iCalendar properties are used beyond RFC 5545 core, they must be documented and standards-compatible.

Timezone Assumption

Unless explicitly overridden by a future requirement, all plugin dates and times are assumed to be in the Europe/London timezone.

Scope

This document covers:

• ICS feed/file generation
• Mapping from plugin event data to iCalendar properties
• Recurrence representation
• Validation and interoperability expectations

Output Requirements

• Content type must be text/calendar.
• Character encoding must be UTF-8.
• Calendar payload must include required VCALENDAR envelope properties.
• Output must be consumable by common calendar clients (Apple, Google, Outlook-class clients).

VCALENDAR Requirements

The ICS output must include, at minimum:

• BEGIN:VCALENDAR
• VERSION:2.0
• PRODID identifying the plugin/system
• CALSCALE:GREGORIAN (recommended default)
• VTIMEZONE definition for Europe/London
• END:VCALENDAR

VEVENT Mapping

Each plugin calendar entry maps to at least one VEVENT.

Field mapping requirements:

• Plugin title -> SUMMARY
• Plugin description -> DESCRIPTION
• Plugin location -> LOCATION
• Plugin start date/time -> DTSTART
• Plugin end date/time -> DTEND
• Plugin category -> CATEGORIES
• Stable unique event identifier -> UID
• Last update timestamp -> DTSTAMP

Additional mapping guidance:

• All-day events use date-based DTSTART/DTEND semantics per RFC 5545.
• Timed events must use DTSTART;TZID=Europe/London and DTEND;TZID=Europe/London.
• DTEND must represent a valid end boundary and not precede DTSTART.

Recurrence Mapping

Recurring entries should be represented with RRULE where possible.

Mapping expectations:

• Daily/weekly/monthly/yearly repeat -> corresponding FREQ values.
• Custom interval (every n) -> INTERVAL=n.
• Range modes:
  • No end date -> RRULE without UNTIL or COUNT.
  • Create <n> appointments -> RRULE with COUNT=n.
  • Repeat until <date> -> RRULE with UNTIL=<date/time>.

If specific recurrence shapes cannot be represented in a single RRULE, plugin may emit standards-compliant expanded VEVENT instances as fallback, documented in implementation notes.

Timezone Requirements

• ICS generation must use a deterministic timezone strategy documented in settings/docs.
• Current project baseline timezone is Europe/London unless explicitly overridden by a future requirement.
• For the baseline configuration, ICS output must include a VTIMEZONE block describing Europe/London.
• For the baseline configuration, timed DTSTART and DTEND values must use TZID=Europe/London.
• If a future configurable timezone mode is introduced, output must remain standards-compliant and subscriber-coherent.

Data Quality and Escaping

• Text values must be escaped/formatted according to iCalendar rules (e.g., commas, semicolons, line folding).
• Invalid or incomplete records must not produce malformed ICS output.
• Generation errors should fail safely with observable error handling.

Security and Privacy

• Export must include only events intended for public/user-facing distribution.
• Internal/admin-only metadata must not leak into ICS properties.

Verification Requirements

Acceptance should verify:

• Output validates as RFC 5545-compatible ICS.
• Field mappings are correct for single and recurring events.
• All-day and timed events render correctly in major clients.
• Recurrence limits (COUNT/UNTIL) behave as configured.