Back to Journal
#24 • Jul 28, 2025 • notes

Calendar Systems and CalDAV Protocol

Understanding how calendar applications work, from iCalendar to CalDAV servers

What Calendars Actually Are

  • Time-based data structures solving: time representation, recurring events, timezones, sharing, synchronization
  • Event Object Structure: UID, title, start/end time, location, description, recurrence rules, attendees, timezone, timestamps, status
  • Think of it as: Specialized database for time-based records + UI that presents data visually

The Standards Stack (Bottom → Top)

  1. HTTP/1.1 (RFC 2616) - Base protocol
  2. WebDAV (RFC 4918) - HTTP extensions for file manipulation
  3. CalDAV (RFC 4791) - Calendar extensions to WebDAV
  4. CalDAV Scheduling (RFC 6638) - Meeting invites/responses
  5. iCalendar (RFC 5545) - Calendar data format (.ics files)

Who Controls: IETF sets standards, CalConnect provides guidance, Apple/Google/Microsoft implement

How Calendar Systems Work

Data Format: iCalendar (.ics)

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Company//App//EN
BEGIN:VEVENT
UID:unique-id@domain.com
DTSTART:20240315T143000Z
DTEND:20240315T153000Z
SUMMARY:Meeting Title
END:VEVENT
END:VCALENDAR

CalDAV: The Calendar Protocol

  • What it is: HTTP server with specific endpoints + XML responses
  • Core HTTP Methods: GET, PUT, DELETE, OPTIONS, PROPFIND, PROPPATCH, MKCALENDAR, REPORT
  • URL Structure: /principals/ (users), /calendars/user/collection/ (calendar collections), /event.ics (individual events)
  • Key Insight: Just a regular HTTP server with calendar-specific endpoint patterns

The Three Security Layers

  1. Transport Security: HTTPS/TLS (prevents eavesdropping)
  2. Authentication: Who are you? (OAuth, Basic Auth, API keys)
  3. Authorization: What can you do? (permissions, scopes)

Google Calendar Auth (Modern Standard)

  • Requirement: OAuth 2.0 only (basic auth disabled March 2025)
  • Flow: App registration → User authorization → Token exchange → Bearer token in requests
  • CalDAV URL: https://apidata.googleusercontent.com/caldav/v2/{calendar-id}/events

Traditional CalDAV Auth

  • Basic Auth: Username/password over HTTPS
  • Digest Auth: Hashed password challenge/response
  • Custom Tokens: API keys, session cookies

Implementation Approaches

Calendar Integration Options

Option A: ICS File Generation (Simplest)

  • Cron script generates static .ics file
  • All consumers read from same ICS URL
  • 0-15 minute update delay
  • No server complexity

Option B: API Server + ICS Export (Balanced)

  • Real-time updates via API
  • Still serves ICS for compatibility
  • Instant updates, easy to extend
  • Requires server hosting

Option C: Full CalDAV Server (Most Flexible)

  • Standards-compliant two-way sync
  • Works with any CalDAV client
  • Most complex to implement
  • Best for multi-client scenarios

Real-World Calendar Ecosystem

How Apps Actually Connect

  • Google Calendar: OAuth 2.0 required, CalDAV interface available
  • Apple Calendar: CalDAV native, supports OAuth + Basic auth
  • Outlook: EWS/Graph API preferred, limited CalDAV support
  • Third-party apps: Usually CalDAV with OAuth or app passwords

Remember

  • CalDAV server = regular HTTP server with calendar-specific endpoints
  • Authentication = OAuth for external, API keys for internal
  • ICS files = universal calendar language that everything speaks
  • Real-time vs batch = main architectural decision point