Crate jmap_jscalendar_types

Expand description

JSCalendar (RFC 8984) typed sub-types for the jmap-* crate family.

Normative reference: RFC 8984 (JSCalendar).

These are sub-object types that have no JMAP identity of their own. They are embedded within CalendarEvent (from jmap-calendars-types), Task (from jmap-tasks-types), and other JMAP objects.

§Crate family position

jmap-types (RFC 8620 wire primitives)
    └── jmap-jscalendar-types  ← this crate (RFC 8984 typed sub-types)
            ├── jmap-calendars-types (consumes via path-dep + re-export)
            └── jmap-tasks-types     (consumes via path-dep + re-export)

§Design: newtype wrappers for scalar temporal values

RFC 8984 §1.4.5 defines LocalDateTime as a string without a timezone offset (e.g. "2024-06-15T09:00:00"). RFC 8984 §1.4.6 defines Duration as an ISO 8601-subset string (e.g. "PT1H"). RFC 8984 §1.4.7 defines SignedDuration as an optional-sign prefix on Duration.

These are modelled as newtype wrappers around String to document intent at the type level without pulling in a heavy parser dependency. Validation of internal format is left to the backend.

§Spec-driven divergences (deliberate, do not “fix”)

Three design choices in this crate look like inconsistency at a glance but are deliberate spec-compliance decisions; preserve them against future “consistency” or “simplification” PRs.

Bare String at_type (not Option<String>). Diverges from the sibling jmap-jscontact-types which uses Option<String>. Spec authority: RFC 8984 marks every @type discriminator as (mandatory) with zero defaultType annotations; RFC 9553 §1.3.4 introduces defaultType and permits omitting @type in implied-type positions. Workspace canonical-templates rule explicitly permits “differences mandated by the relevant RFC or draft”. See PLAN.md and bd:JMAP-sgrr.3.
AlertTrigger::Unknown(serde_json::Value). Holds an opaque Value rather than a typed struct or a String. Spec authority: RFC 8984 §4.5.2 “Implementations MUST NOT trigger for trigger types they do not understand but MUST preserve them.” A typed Unknown(String) would discard the inner fields; a typed Unknown { at_type, fields } would force a schema on what is explicitly unschema’d. The manual Deserialize impl is required because serde does not support #[serde(tag = "@type", other)] with non-unit tuple variants. See AlertTrigger rustdoc.
serde_json::{Map, Value} in the public API surface. The workspace extras-preservation policy mandates a pub extra: serde_json::Map<String, serde_json::Value> field on every wire-format struct, and AlertTrigger::Unknown carries a raw Value. This locks the crate’s major version to serde_json’s, which is the explicit trade-off: round-trip fidelity for vendor / site / private fields outweighs the coupling cost. See PLAN.md “Extras-preservation policy” and workspace AGENTS.md.

§Test-oracle discipline

Test fixtures are constructed from serde_json::json!({...}) literals whose shape comes directly from RFC 8984 example text. Per workspace test-integrity rules, the oracle MUST be the spec example, NOT the code under test. Do NOT replace fixture construction with “build a typed struct, serialize, deserialize, compare” — that pattern uses the code under test as its own oracle.

Structs§

AbsoluteTrigger: A trigger time given as an absolute UTC date-time (RFC 8984 §4.5.2).
Alert: An alert to be shown or emailed before or after an event (RFC 8984 §4.5.2).
Duration: An ISO 8601 duration string (RFC 8984 §1.4.6).
Id: Opaque non-empty server-assigned identifier (RFC 8620 §1.2).
Link: An attachment, image, or URL associated with an event (RFC 8984 §1.4.11).
LocalDateTime: A date-time string without a timezone offset (RFC 8984 §1.4.5).
Location: A physical or virtual location associated with an event (RFC 8984 §4.2.5).
NDay: The nthOfPeriod field of an NDay entry (RFC 8984 §4.3.3).
OffsetTrigger: A trigger time given as an offset from the event start or end (RFC 8984 §4.5.2).
Participant: A participant in an event (RFC 8984 §4.4.6).
PatchObject: A JMAP PatchObject (RFC 8620 §5.3) — a String → JSON map describing the changes to apply to a record during */set update.
RecurrenceRule: A recurrence rule as defined in RFC 8984 §4.3.3.
Relation: A relationship between this object and another, identified by UID (RFC 8984 §1.4.10).
SignedDuration: A signed ISO 8601 duration string (RFC 8984 §1.4.7).
TimeZone: A time-zone definition embedded in CalendarEvent.timeZones or Task.timeZones (RFC 8984 §4.7.2).
TimeZoneRule: A STANDARD or DAYLIGHT sub-component of a TimeZone (RFC 8984 §4.7.2).
TypeTagMismatch: Mismatch between an object’s at_type wire string and the RFC 8984-mandated discriminator literal for its Rust type.
UTCDate: RFC 3339 UTC timestamp string (RFC 8620 §1.4).
UTCOffset: A UTC offset string (RFC 5545 / RFC 8984 §4.7.2 — the TZOFFSETFROM / TZOFFSETTO format).
VirtualLocation: An online meeting or virtual location (RFC 8984 §4.2.6).

Enums§

AlertTrigger: Alert trigger — either offset-based, absolute, or an unknown future type (RFC 8984 §4.5.2).
LinkSourceError: Error returned by Link::validate_source when the source invariant (RFC 8984 §1.4.11 + JMAP Calendars draft §5.3) is violated.
ParticipantRolesError: Error returned by Participant::validate_roles when the RFC 8984 §4.4.6 non-empty-roles invariant is violated.
RecurrenceOverridesError: Error returned by TimeZoneRule::validate_recurrence_overrides_empty when the RFC 8984 §4.7.2 “PatchObject value MUST be the empty patch” constraint is violated.

Traits§

TypeDiscriminator: Wire-format type-tag discriminator for JSCalendar sub-objects (RFC 8984).