]> iCalDAV Project

https://github.com/iCalDAV/ical-dependency-graph

art calext iCalendar CalDAV property dependencies merge safety VEVENT RFC 5545 RFC 5545 defines inter-property interaction rules for iCalendar components in prose scattered across multiple RFC sections. No published, standalone representation of these rules exists in a form suitable for machine consumption. This document specifies a formal dependency graph for VEVENT components with 27 properties and 20 edges spanning six edge types. It classifies properties into five merge safety categories that determine whether concurrent edits can be combined without user intervention. The specification is published as YAML and JSON artifacts for cross-language consumption.

Introduction CalDAV treats calendar resources as opaque blobs. Clients PUT entire iCalendar objects; servers use ETags for conflict detection. When two clients modify the same event, the only options are whole-event replacement or manual resolution. Property-level merge is not part of the protocol. The barrier to property-level merge is not algorithmic. Three-way merge for structured data is well understood. The barrier is that property dependencies are implicit: changing DTSTART can invalidate RRULE expansion, EXDATE membership, and VALARM trigger offsets, but this is expressed only in prose across separate RFC sections. Without a formal model of which properties depend on which, a merge engine cannot determine whether two concurrent edits are safe to combine. This document extracts these implicit dependencies into a formal graph for VEVENT components and classifies each property by merge safety.

Scope This specification covers VEVENT properties only. VTODO and VJOURNAL have different dependency structures (e.g., the Tasks draft removes the VTODO DURATION-to-DTSTART requirement). Extension to other component types is future work. The graph includes all VEVENT properties with non-trivial inter-property dependencies, plus commonly-edited safe properties. Section 3.6.1 defines additional VEVENT properties with no inter-property dependencies that are omitted for brevity: ATTACH, COMMENT, CONTACT, RELATED-TO, and RESOURCES. All are safe with set cardinality and union merge semantics. Single-property cardinality constraints (e.g., DTSTART is REQUIRED) and value-level constraints (e.g., DTEND datetime MUST be greater than or equal to DTSTART datetime) are not modeled. This graph captures structural and type-level dependencies only.

Merge Unit CalDAV resources can contain multiple VEVENTs sharing a UID: one master and zero or more exception VEVENTs (each identified by RECURRENCE-ID). This graph models properties within a single VEVENT, but three edges cross VEVENT boundaries. A merge engine consuming this graph MUST operate on the full UID group (all VEVENTs sharing a UID), not individual VEVENTs in isolation. Edges marked "cross_vevent" in the machine-readable artifact require this UID-group scope.

Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. The following terms are used throughout this document:

Edge:

A directed relationship between two properties in the dependency graph. Each edge has a type and a strength.

Merge safety:

A classification of whether a property can be independently merged when two clients concurrently edit the same event.

UID group:

The set of all VEVENTs sharing the same UID value within a calendar resource. Consists of one master VEVENT and zero or more exception VEVENTs identified by RECURRENCE-ID.

Significant change:

A change to a property classified as "dependent" or "scheduling" in the merge safety classification. Significant changes require SEQUENCE to be incremented per Section 2.1.4.

Edge Type Definitions The graph uses six edge types with the following semantics:

depends_on:

The source property's interpretation requires the target property's value. Changing the target makes the source's cached result stale, but the source's stored value remains syntactically valid. Example: RRULE depends_on DTSTART ( Section 3.8.5.3) because recurrence expansion uses DTSTART's day-of-week, month, etc. for BY* rules.

derived_from:

The source property's value was computed from the target at creation time. The target can change afterward without requiring the source to update. Example: RECURRENCE-ID derived_from DTSTART.

requires:

The source property requires the target to be present. The source without the target is a protocol violation. Example: ATTENDEE requires ORGANIZER ( Section 3.8.4.1).

mutually_exclusive_with:

The source and target MUST NOT both be present on the same VEVENT. This relationship is symmetric. Example: DTEND mutually_exclusive_with DURATION ( Section 3.6.1).

type_consistency:

The source and target must use the same value type (DATE or DATE-TIME). This relationship is symmetric. Example: EXDATE type_consistency DTSTART ( Section 3.8.5.1).

computes_with:

The source and target are used together in computation. Neither needs updating when the other changes. Example: DTSTART computes_with DURATION to produce the implied end time.

Edge Strength Each edge carries a strength indicating the RFC conformance level of the constraint it represents:

must:

An RFC MUST or MUST NOT requirement. Violation is a protocol error.

should:

An RFC SHOULD or SHOULD NOT recommendation. Violation is suboptimal but conformant.

advisory:

Not a conformance requirement. Useful for generating warnings (e.g., an EXDATE for a date not in the recurrence set is a no-op, not a violation).

informational:

Annotation only. Documents a computational relationship with no conformance or warning implication. Used for computes_with and derived_from edges.

Property Dependencies The following table lists the 20 inter-property edges. All edges derive from . Additional RFCs (, , , ) contribute property definitions and scheduling semantics used in the merge safety classification (), but no edges in this table originate from those documents. Symmetric edges (type_consistency, mutually_exclusive_with) are listed on both participating properties, yielding 20 entries for 16 unique relationships. Inter-Property Dependency Edges for VEVENT

Source	Target	Type	Str.	Ref
RRULE	DTSTART	depends_on	must	S3.8.5.3
EXDATE	DTSTART	type_cons.	must	S3.8.5.1
EXDATE	RRULE	depends_on	adv.	S3.8.5.1
RDATE	DTSTART	type_cons.	must	S3.8.5.2
VALARM	DTSTART	depends_on	must	S3.8.6.3
VALARM	DTEND	depends_on	must	S3.8.6.3
VALARM	DURATION	depends_on	must	S3.8.6.3
REC-ID	DTSTART	derived_from	info.	S3.8.4.4
REC-ID	RRULE	depends_on	must	S3.8.4.4
REC-ID	RDATE	depends_on	must	S3.8.4.4
ATTENDEE	ORGANIZER	requires	must	S3.8.4.1
DTEND	DURATION	mut_excl.	must	S3.6.1
DTSTART	DURATION	computes_w.	info.	S3.8.2.5
DURATION	DTSTART	depends_on	must	S3.8.2.5
DTSTART	DTEND	type_cons.	must	S3.6.1
DTSTART	EXDATE	type_cons.	must	S3.8.5.1
DTSTART	RDATE	type_cons.	must	S3.8.5.2
DTSTART	UNTIL	type_cons.	must	S3.3.10
DTEND	DTSTART	type_cons.	must	S3.6.1
DURATION	DTEND	mut_excl.	must	S3.6.1

Abbreviations: REC-ID = RECURRENCE-ID; type_cons. = type_consistency; mut_excl. = mutually_exclusive_with; computes_w. = computes_with; adv. = advisory; info. = informational. All references are to sections. VALARM is a sub-component nested inside VEVENT, not a VEVENT property. Its edges are modeled at the VEVENT level for merge safety purposes. A complete VALARM merge requires set-level comparison of sub-components, not scalar property diffing. The VALARM depends_on edges are conditional on each alarm's TRIGGER RELATED parameter: RELATED=START (the default) depends on DTSTART; RELATED=END depends on DTEND or, when DTEND is absent, on DURATION. A merge engine that unconditionally flags all VALARMs when DTEND changes will produce false positive conflicts for RELATED=START alarms. The DURATION depends_on DTSTART edge ( Section 3.8.2.5) captures a non-obvious format constraint: if DTSTART uses the DATE value type (all-day event), DURATION MUST use dur-day or dur-week format (e.g., P1D, P2W), not time granularity (e.g., PT1H). Changing DTSTART from DATE-TIME to DATE requires validating the DURATION format.

Cross-VEVENT Edges RECURRENCE-ID lives on an exception VEVENT; its targets (RRULE, RDATE, DTSTART) live on the master VEVENT. These edges are marked "cross_vevent: true" in the machine-readable artifact. A merge engine MUST resolve these edges across the full set of VEVENTs sharing a UID.

RRULE Internal Constraints COUNT and UNTIL are mutually exclusive within an RRULE value ( Section 3.3.10). This is captured as an internal constraint rather than an inter-property edge, because both are parameters of the RRULE value, not separate VEVENT properties.

Merge Safety Classification Given two concurrent edits to the same event (local and remote), can a property be independently merged? This section classifies all 27 VEVENT properties into five categories.

Safe Properties: SUMMARY, DESCRIPTION, LOCATION, URL, GEO, PRIORITY, CATEGORIES, COLOR (), CLASS, TRANSP, STATUS. No cross-property dependencies. Independent merge is always valid. If local changes SUMMARY and remote changes LOCATION, both edits can be kept without conflict. STATUS is structurally safe but semantically hazardous. Auto-merging STATUS:CANCELLED with a concurrent SUMMARY edit produces a cancelled event with a new title. A merge engine SHOULD surface STATUS:CANCELLED as a manual-resolution candidate.

Dependent Properties: DTSTART, DTEND, DURATION, RRULE, EXDATE, RDATE, VALARM. Can be merged if graph validation passes. For example, if local changes DTSTART and remote adds an EXDATE, the merge engine MUST verify that the EXDATE value type still matches the new DTSTART type.

Scheduling Properties: ATTENDEE, ORGANIZER, REQUEST-STATUS. When CalDAV Scheduling is active, modifying these properties triggers scheduling messages per . They MUST NOT be auto-merged. On servers without (e.g., Radicale, Baikal), ATTENDEE is dependent (requires ORGANIZER) and ORGANIZER is also dependent (removing ORGANIZER while ATTENDEEs are present violates the "requires" edge regardless of scheduling support). REQUEST-STATUS falls back to safe. The machine-readable artifact captures this via a "scheduling_fallback" field.

Immutable Properties: UID, CREATED, RECURRENCE-ID. Set once within a VEVENT instance. MUST NOT be changed after initial creation. UID identifies the event ( Section 3.8.4.7). CREATED records creation time ( Section 3.8.7.1). RECURRENCE-ID identifies which occurrence of a recurrence series was modified ( Section 3.8.4.4).

Always-Update Properties: SEQUENCE, DTSTAMP, LAST-MODIFIED. Automatically set on any edit. DTSTAMP and LAST-MODIFIED are set to the current UTC time. SEQUENCE has a non-trivial merge rule. If only one side changed significant properties, the merge engine SHOULD preserve that side's SEQUENCE. If both sides changed significant properties, the merge engine SHOULD use max(local, remote) + 1. If neither changed significant properties, the merge engine SHOULD use max(local, remote). A blind max + 1 on every merge causes the escalation loop documented in existing CalDAV client implementations.

Set-Valued Properties Properties with cardinality "set" (EXDATE, RDATE, CATEGORIES, ATTENDEE, VALARM) hold multiple values. The merge safety classification determines whether a property can be independently merged with edits to other properties but does not specify how to merge concurrent edits to the same multi-valued property. The machine-readable artifact includes a "merge_op" field for set properties: "union" (EXDATE, RDATE, CATEGORIES) for additive merge, or "conflict" (ATTENDEE, VALARM) for set-level comparison requiring manual resolution. EXDATE union requires checking for corresponding exception VEVENTs on the same date before applying. Adding an EXDATE for a date that has an exception VEVENT produces conflicting signals (the occurrence is both excluded and replaced).

Machine-Readable Artifact The dependency graph is published as structurally equivalent YAML and JSON files at <https://github.com/iCalDAV/ical-dependency-graph>. The YAML includes inline commentary; the JSON uses fields prefixed with underscore ("_note", "_schema") for annotations. Underscore-prefixed fields are non-normative.

Schema Fields Each property object contains:

cardinality:

"scalar" (single value) or "set" (multiple values).

merge_safety:

One of: "safe", "dependent", "scheduling", "immutable", "always_update".

Edge lists:

Zero or more of: "depends_on", "derived_from", "requires", "mutually_exclusive_with", "type_consistency", "computes_with". Each entry is an object with "target" (property name) and "strength" (must/should/advisory/ informational).

merge_op:

(Set properties only.) "union" or "conflict".

scheduling_fallback:

(Scheduling properties only.) The merge safety category to use on servers without .

merge_rule:

(SEQUENCE only.) Three conditions: "one_side_changed" (PRESERVE), "both_sides_changed" (MAX_PLUS_ONE), "neither_changed" (MAX).

cross_vevent:

(Optional, boolean.) True when the edge crosses VEVENT boundaries within a UID group.

Versioning The "version" field uses semantic versioning:

• Patch (1.0.x): Corrects an incorrect edge. No new properties or edge types.
• Minor (1.x.0): Adds new properties, edge types, or schema fields. Existing edges unchanged.
• Major (x.0.0): Changes existing edge semantics or restructures the schema.

Implementation Evidence 25 bugs were identified across 17 distinct open-source projects spanning 8 programming languages (JavaScript, Python, C, Java, PHP, Kotlin, C#, Vala) where the root cause is a violated property dependency. The bugs fall into three categories:

• Expansion/interpretation (13 bugs): The dependency rule was not correctly implemented in RRULE expansion, EXDATE filtering, or property interpretation.
• Validation/serialization (10 bugs): Invalid property combinations were accepted or produced.
• Merge/sync (2 bugs): Concurrent edits or sync operations produced invalid state due to missing property-level awareness.

The EXDATE-type-must-match-DTSTART rule ( Section 3.8.5.1) alone accounts for 7 separate bugs across independent implementations. The RRULE-DTSTART interaction has bugs dating back to 2013. 13 of 25 bugs involve these same two rules across independent implementations. Additionally, 7 major calendar libraries across 6 languages have documented cross-property validation gaps: ical4j (Java), ical.js (JavaScript), libical (C), Python icalendar (Python), sabre/vobject (PHP), rrule.js (JavaScript), and ical4android (Kotlin). The full bug catalog with links to individual issues is available in the companion preprint and at the repository listed in .

Security Considerations This document formalizes existing constraints from and related specifications. It does not introduce new protocol elements or modify existing ones. Implementations that consume the dependency graph for automated merge operations SHOULD validate the graph artifact's integrity before use (e.g., by verifying a checksum or fetching from a trusted source). A modified graph could cause a merge engine to incorrectly classify unsafe merges as safe, producing invalid iCalendar objects. The scheduling properties (ATTENDEE, ORGANIZER, REQUEST-STATUS) have side effects beyond the local event when CalDAV Scheduling is active. A merge engine MUST NOT auto-merge scheduling properties without the user's explicit consent, as this could result in unintended scheduling messages being sent to other participants.

IANA Considerations This document has no IANA actions.

References Normative References Informative References

Acknowledgements The dependency rules formalized in this document were validated against 295+ tests across three codebases and six CalDAV servers (iCloud, Nextcloud, Radicale, Baikal, Stalwart, Zoho). The bug catalog was compiled from public GitHub issues across 17 open-source calendar projects.