Struct CalendarEvent 

#[non_exhaustive]
pub struct CalendarEvent {

    pub id: Option<Id>,
    pub base_event_id: Option<Id>,
    pub calendar_ids: Option<BTreeMap<Id, bool>>,
    pub is_draft: Option<bool>,
    pub is_origin: Option<bool>,
    pub utc_start: Option<UTCDate>,
    pub utc_end: Option<UTCDate>,
    pub use_default_alerts: Option<bool>,
    pub may_invite_self: Option<bool>,
    pub may_invite_others: Option<bool>,
    pub hide_attendees: Option<bool>,
    pub blob_id: Option<Id>,
    pub icalendar: Option<Value>,
    pub at_type: Option<String>,
    pub version: Option<String>,
    pub uid: Option<String>,
    pub related_to: Option<Value>,
    pub prod_id: Option<String>,
    pub created: Option<UTCDate>,
    pub updated: Option<UTCDate>,
    pub sequence: Option<u64>,
    pub title: Option<String>,
    pub description: Option<String>,
    pub description_content_type: Option<String>,
    pub show_without_time: Option<bool>,
    pub locations: Option<Value>,
    pub virtual_locations: Option<Value>,
    pub links: Option<Value>,
    pub locale: Option<String>,
    pub keywords: Option<BTreeMap<String, bool>>,
    pub categories: Option<BTreeMap<String, bool>>,
    pub color: Option<String>,
    pub recurrence_id: Option<String>,
    pub recurrence_id_time_zone: Option<String>,
    pub recurrence_rules: Option<Value>,
    pub excluded_recurrence_rules: Option<Value>,
    pub recurrence_overrides: Option<BTreeMap<String, PatchObject>>,
    pub excluded: Option<bool>,
    pub priority: Option<u8>,
    pub free_busy_status: Option<String>,
    pub privacy: Option<String>,
    pub reply_to: Option<BTreeMap<String, String>>,
    pub sent_by: Option<String>,
    pub organizer_calendar_address: Option<String>,
    pub participants: Option<Value>,
    pub request_status: Option<String>,
    pub alerts: Option<Value>,
    pub localizations: Option<BTreeMap<String, PatchObject>>,
    pub time_zone: Option<String>,
    pub time_zones: Option<Value>,
    pub start: Option<String>,
    pub duration: Option<String>,
    pub status: Option<String>,
    pub metadata: Option<Map<String, Value>>,
    pub private_metadata: Option<Map<String, Value>>,
    pub extra: Map<String, Value>,
}

A JMAP CalendarEvent object (draft-ietf-jmap-calendars-33 §5; RFC 8984 §5.1).

CalendarEvent is a JSCalendar Event with additional JMAP-specific properties. Every field is Option<T> because RFC 8620 §5.1 allows partial responses (clients may request only specific fields via the properties argument). A field absent from the server response MUST NOT fail deserialization.

Complex sub-objects

JSCalendar sub-objects with their own rich structure (locations, participants, alerts, recurrenceRules, etc.) are represented as Option<serde_json::Value>. This avoids an exhaustive typed representation while preserving full round-trip fidelity. Consumers that need to manipulate these fields should parse the Value using the concrete types re-exported at this crate’s root (e.g. crate::Location, crate::Participant, crate::Alert) — defined in the jmap-jscalendar-types crate.

PatchObject envelopes

recurrenceOverrides and localizations are typed as Option<BTreeMap<String, jmap_types::PatchObject>>: the outer envelope is JMAP-level (RFC 8620 §5.3 PatchObject) while the inner leaves stay serde_json::Value to preserve per-leaf JSCalendar flexibility. Wire format is byte-identical to the prior opaque Option<Value> shape via #[serde(transparent)] on PatchObject.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

id: Option<Id>

Server-assigned immutable identifier.

base_event_id: Option<Id>

Id of the base recurring event when id is a synthetic expanded instance id. null for non-synthetic events.

calendar_ids: Option<BTreeMap<Id, bool>>

Set of Calendar ids this event belongs to (values always true).

is_draft: Option<bool>

If true, this is a draft; the server will not send scheduling messages. Always serialized; absent deserializes, and None serializes, as the spec default false.

is_origin: Option<bool>

Server-set; true if this account is the authoritative source.

utc_start: Option<UTCDate>

Computed UTC start time (not returned by default; must be requested).

Uses the UTCDate newtype to make the wire-format constraint (RFC 8620 §1.4: 20-character UTCDateTime string) explicit at the type level. JSON wire format is unchanged because UTCDate is a transparent newtype around String.

utc_end: Option<UTCDate>

Computed UTC end time (not returned by default; must be requested).

See utc_start for the typing rationale.

use_default_alerts: Option<bool>

If true, use per-calendar default alerts instead of alerts (default false). Always serialized; absent deserializes, and None serializes, as the spec default false.

may_invite_self: Option<bool>

If true, anyone may add themselves to the event as a participant (draft §5.1.1).

may_invite_others: Option<bool>

If true, any current participant may add new participants (draft §5.1.2).

hide_attendees: Option<bool>

If true, only users with full permission to modify the event see the complete set of participants; others see only the owners and themselves (draft §5.1.3, §5.7).

blob_id: Option<Id>

JMAP Blob id for the iCalendar representation of this event.

icalendar: Option<Value>

iCalendar data that converted to this event, as an ICalComponent object (draft-ietf-calext-jscalendar-icalendar-28 §5.1.1).

Only returned when explicitly requested via properties:["iCalendar"] (draft-ietf-jmap-calendars-33 §5.7: a null properties returns all properties except iCalendar). Kept as a serde_json::Value per the workspace Sloppy-Value policy: it carries jCal arrays (RFC 7265).

Wire name is "iCalendar"; a manual rename keeps it explicit rather than relying on rename_all of a i_calendar field name.

at_type: Option<String>

JSCalendar object type; always "Event" when present. Included for round-trip fidelity; omitted on create.

version: Option<String>

JSCalendar version this event conforms to, e.g. "2.0" (draft-ietf-calext-jscalendarbis-22 §3.1.2). The server sets it when a create omits it (draft-ietf-jmap-calendars-33 §5.9).

uid: Option<String>

Globally unique identifier for this event.

related_to: Option<Value>

Map of related event UIDs → Relation objects.

prod_id: Option<String>

Product identifier (who created the event data).

created: Option<UTCDate>

UTC date-time when this event was created.

updated: Option<UTCDate>

UTC date-time of last modification (mandatory in full responses).

sequence: Option<u64>

iCalendar sequence number (default 0).

title: Option<String>

Human-readable summary/title.

description: Option<String>

Longer-form description.

description_content_type: Option<String>

Content type of description (default "text/plain").

show_without_time: Option<bool>

If true, this is an all-day event (default false).

locations: Option<Value>

Map of location id → Location object.

virtual_locations: Option<Value>

Map of virtual location id → VirtualLocation object.

links: Option<Value>

Map of link id → Link object (attachments, images, etc.).

locale: Option<String>

BCP 47 language tag for this event’s locale.

keywords: Option<BTreeMap<String, bool>>

Map of keyword strings → true (RFC 8984 §4.2.10).

categories: Option<BTreeMap<String, bool>>

Map of category URI strings → true (RFC 8984 §4.2.11).

color: Option<String>

CSS color name or #rrggbb for this event.

recurrence_id: Option<String>

LocalDateTime string identifying which recurrence instance this object overrides.

recurrence_id_time_zone: Option<String>

Time zone for recurrence_id (required when recurrence_id is set).

This crate does not check the value against the IANA Time Zone Database; validating the zone name is the backend’s job.

recurrence_rules: Option<Value>

Array of RecurrenceRule objects.

excluded_recurrence_rules: Option<Value>

Array of RecurrenceRule objects to exclude from the series.

recurrence_overrides: Option<BTreeMap<String, PatchObject>>

Map of LocalDateTime string → PatchObject for per-occurrence overrides (RFC 8984 §4.3.2).

Outer envelope is typed at the JMAP level: keys are LocalDateTime strings and values are JMAP PatchObject (RFC 8620 §5.3) wire objects. The inner PatchObject leaves remain serde_json::Value so per-occurrence overrides retain full JSCalendar shape flexibility (Sloppy-Value at the leaf, typed at the envelope). Wire format is byte-identical via #[serde(transparent)].

Maintainer note: do NOT “simplify” this shape. Two refactors commonly surface; both are wrong:

1. Revert to Option<serde_json::Value>. Loses the type-level signal that the outer envelope follows JMAP PatchObject (RFC 8620 §5.3) semantics. JMAP and JSCalendar are co-evolving specs with separate ownership of the envelope vs leaf semantics, and the type-level split mirrors that.
2. Type the inner leaves with full JSCalendar field-by-field structs. Would require an exhaustive JSCalendar leaf type that must track both specs and break partial deserialize. The workspace Sloppy-Value policy (workspace AGENTS.md) is designed exactly to avoid this trap.

Wire-format byte-identity is pinned by calendar_event_recurrence_overrides_wire_format_is_object_map in tests/types_test.rs. Design defense: bd:JMAP-1rwf.6. See also localizations below — same shape, same rationale.

excluded: Option<bool>

If true, this occurrence is excluded from the series.

priority: Option<u8>

Priority of this event (0–9; 0 = undefined).

free_busy_status: Option<String>

Free/busy status: "free" or "busy" (default "busy").

privacy: Option<String>

Privacy: "public", "private", or "secret" (default "public").

reply_to: Option<BTreeMap<String, String>>

Map of scheduling method → reply-to URI (RFC 8984 §4.4.4).

sent_by: Option<String>

Addr-spec of the person who sent this event data.

organizer_calendar_address: Option<String>

The organizer’s calendarAddress (wire: organizerCalendarAddress).

participants: Option<Value>

Map of participant id → Participant object.

request_status: Option<String>

iTIP request status string.

alerts: Option<Value>

Map of alert id → Alert object.

localizations: Option<BTreeMap<String, PatchObject>>

Map of language tag → PatchObject for per-language overrides (RFC 8984 §4.6).

Outer envelope is typed at the JMAP level: keys are BCP 47 language tags and values are JMAP PatchObject (RFC 8620 §5.3) wire objects. The inner PatchObject leaves remain serde_json::Value so per- language overrides retain full JSCalendar shape flexibility (Sloppy- Value at the leaf, typed at the envelope). Wire format is byte- identical via #[serde(transparent)].

Maintainer note: do NOT “simplify” this shape — see the same note on Self::recurrence_overrides above for the full rationale. The two fields share the hybrid Sloppy-Value-at-the-leaf, typed-at-the-envelope pattern (JMAP §5.3 envelope ownership vs. JSCalendar §4.6 leaf ownership). Design defense: bd:JMAP-1rwf.6.

time_zone: Option<String>

IANA time zone id for the event’s start/end times.

This crate does not check the value against the IANA Time Zone Database; validating the zone name is the backend’s job.

time_zones: Option<Value>

Custom time zone definitions; opaque passthrough (RFC 8984 §4.7.2).

start: Option<String>

Start date-time as a LocalDateTime string.

duration: Option<String>

Duration as an ISO 8601 duration string (e.g. "PT1H").

status: Option<String>

Event status: "confirmed", "cancelled", or "tentative".

metadata: Option<Map<String, Value>>

Shared metadata, keyed by namespace identifier (draft-ietf-jmap-metadata-04 §2). Each value is a JSON object (§2.1). None when absent, which -04 §2 treats as {}; in an update a null value “is equivalent to {}” (-04 §3.2) and also decodes as None.

private_metadata: Option<Map<String, Value>>

The authenticated user’s own metadata, keyed by namespace identifier (draft-ietf-jmap-metadata-04 §2). Same shape and None handling as metadata.

extra: Map<String, Value>

Catch-all for vendor / site / private extension fields not covered by the typed fields above. Preserves unknown fields across deserialize/serialize round-trip per workspace extras-preservation policy (see workspace AGENTS.md).

Trait Implementations

impl Clone for CalendarEvent

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CalendarEvent

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for CalendarEvent

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl GetObject for CalendarEvent

impl JmapObject for CalendarEvent

const TYPE_NAME: &'static str = "CalendarEvent"

The JMAP type name string (e.g. "Email", "Mailbox", "Chat").

type Property = CalendarEventProperty

The property selector enum for this type (server-side only, no serde).

impl PartialEq for CalendarEvent

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl QueryObject for CalendarEvent

type Filter = Filter<CalendarEventFilterCondition>

The filter condition type.

type Comparator = CalendarEventComparator

The comparator type for sort operations.

impl Serialize for CalendarEvent

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl SetObject for CalendarEvent

draft-ietf-jmap-calendars-33 §5 (lines 1133, 1138, 1151): id and baseEventId are “(immutable; server-set)”, isOrigin is “(server-set)”. No other property, JMAP or JSCalendar, carries either attribute.

draft-ietf-jmap-metadata-04 §3.2: clients write metadata and privateMetadata through Foo/set.

const SERVER_SET: &'static [&'static str]

Wire names of the properties the spec marks “server-set”: “Only the server can set the value for this property. The client MUST NOT send this property when creating a new object of this type.” (RFC 8620 §1.1). A property the type’s /set method text never accepts from a client, on create or update, is server-set too.

const CLIENT_SETTABLE: &'static [&'static str]

Wire names of every property that is not SERVER_SET: the ones a client may set through /set.

const IMMUTABLE: &'static [&'static str]

The CLIENT_SETTABLE properties the spec marks “immutable”: “The value MUST NOT change after the object is created.” (RFC 8620 §1.1). A property the /set method text accepts on create but not on update is immutable too.

type Patch = PatchObject

The patch type for update operations.

impl StructuralPartialEq for CalendarEvent