# 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.