calendar-plugin/requirements/caldav_endpoints.md

CalDAV Endpoint Requirements

Purpose

Define exact CalDAV URI structure, required methods/reports/properties, and expected status behavior for interoperability.

Scope

This document covers:

• CalDAV URI layout
• Method support by resource type
• Required WebDAV/CalDAV properties and reports
• Required status-code behavior

Normative Boundaries

• This document is authoritative for CalDAV URI structure and method/property/report support.
• Event/recurrence data semantics are defined in requirements/caldav.md and requirements/recurrence_exceptions.md.
• Authentication/authorization and error behavior norms are defined in:
  • requirements/authentication.md
  • requirements/authorization.md
  • requirements/error_model.md

Endpoint Layout

Base CalDAV root:

• /caldav/
• If url_slug is configured in setup, canonical CalDAV root is /<url_slug>/caldav/.

Resource hierarchy:

• Principal collection: /caldav/principals/
• User principal: /caldav/principals/{user_id}/
• Calendar home set: /caldav/calendars/
• Shared public calendar collection: /caldav/calendars/public/
• Event object resource: /caldav/calendars/public/{object_id}.ics

URI rules:

• {user_id} is stable and URL-safe.
• {object_id} is stable for object lifetime.
• All authenticated principals discover the same shared calendar home set and public collection.
• Object rename/move behavior is unsupported in first pass unless explicitly implemented.

Methods by Resource Type

/caldav/

• OPTIONS
• PROPFIND (Depth 0/1)

Principal resources

• PROPFIND
• REPORT where applicable for principal discovery support

Calendar collection resources

• OPTIONS
• PROPFIND
• REPORT (calendar-query, calendar-multiget, sync-collection)

Event object resources

• GET
• PUT
• DELETE
• PROPFIND (Depth 0)

Required DAV/CalDAV Properties

Calendar collection and principal responses must support, at minimum, these properties (where applicable):

• resourcetype
• displayname
• current-user-principal
• principal-URL
• calendar-home-set
• supported-calendar-component-set
• getctag (or equivalent documented change tag)
• getetag for object resources
• sync-token for collections supporting sync

REPORT Support

• calendar-query with time-range filtering
• calendar-multiget by href set
• sync-collection for incremental changes since sync token

If a report is unsupported for a resource, server returns standards-appropriate error status with DAV error body.

Status Behavior

• 200 successful read/report/property retrieval
• 201 object created by PUT
• 204 successful delete/update with no body where applicable
• 207 multi-status for PROPFIND/REPORT responses
• 401 unauthenticated
• 403 authenticated but forbidden
• 404 resource not found
• 405 method not allowed on resource
• 409 parent/resource state conflict
• 412 precondition failed (etag/if-match semantics)
• 415 unsupported media type

Content Handling

• Event objects use text/calendar payloads with RFC 5545-compatible VCALENDAR.
• Authenticated CalDAV object responses (GET, REPORT, calendar-multiget) return full event details for both public and private events.
• Unsupported component types should be rejected unless explicitly mapped.
• Server should normalize line endings/content as required by iCalendar compatibility.

Concurrency

• Object resources must emit ETag.
• If-Match and If-None-Match must be honored on PUT.
• Lost-update prevention is required on concurrent writes.

Recurrence Exception Behavior

• Deleting one recurrence occurrence must be represented as an exception for the existing series.
• The resulting data must remain one logical series (same UID), without splitting into separate series resources unless explicitly required by standards-compatible override semantics.

Verification Requirements

Acceptance should verify:

• URI layout and discovery flows are stable.
• Required methods return expected statuses.
• REPORT responses include correct event sets.
• Conditional write and etag behavior prevents stale overwrite.