Event Standard

Calendar events: appointments, all-day entries, recurring series and the calendars that hold them. Designed to round-trip with iCalendar (RFC 5545), so events can be imported from and exported to Android, desktop and web calendars. Dates follow the date rules, people are contacts, places are locations.

Appointment

A timed event. $start/$end are local wall-clock times in $timezone.

{
	$type: 'event',
	$version: 1,
	$kind: 'appointment',
	$id: '7f3c2a1e-5b8d-4c1a-9e2f-0a6b3d4c5e6f',
	$title: 'Dentist',
	$description: 'Bring the insurance card',
	$start: '2026-10-02T18:00:00',
	$end: '2026-10-02T19:00:00',
	$timezone: 'Europe/Vienna',
	$location: {
		$type: 'location',
		$kind: 'point',
		$name: 'Dr. Huber',
		$lat: 48.20012,
		$lng: 16.36921,
		$address: { $street: 'Mariahilfer Straße 12', $city: 'Vienna', $postal: '1070', $country: 'AT' }
	},
	$status: 'confirmed',
	$visibility: 'private',
	$reminders: [
		{ $before: 'PT1H' },
		{ $days_before: 1, $time: '20:00' }
	],
	$created: '2026-09-25T09:12:00Z',
	$updated: '2026-09-25T09:12:00Z'
}

Recurring Appointment with Attendees

{
	$type: 'event',
	$version: 1,
	$kind: 'appointment',
	$id: 'standup-3b9d',
	$title: 'Team Standup',
	$start: '2026-10-05T09:30:00',
	$duration: 'PT15M',
	$timezone: 'Europe/Vienna',
	$location: 'Room 4',
	$url: 'https://meet.example.com/standup',
	$organizer: { $type: 'contact', $name: 'John', $email: '[email protected]' },
	$attendees: [
		{ $type: 'contact', $name: 'Jane', $email: '[email protected]', $role: 'required', $response: 'accepted' },
		{ $type: 'contact', $name: 'Tom', $email: '[email protected]', $role: 'optional', $response: 'pending' }
	],
	$recurrence: {
		$rule: 'FREQ=WEEKLY;BYDAY=MO,WE,FR;UNTIL=20261231T225959Z',
		$exclude: ['2026-10-26T09:30:00']
	},
	$overrides: [
		{ $recurrence_id: '2026-10-14T09:30:00', $start: '2026-10-14T11:00:00', $location: 'Room 1' },
		{ $recurrence_id: '2026-11-02T09:30:00', $status: 'cancelled' }
	],
	$busy: true
}

All-Day Event

Dates without time. A yearly birthday with the default reminders replaced by custom ones:

{
	$type: 'event',
	$version: 1,
	$kind: 'allday',
	$id: 'bday-jane',
	$title: 'Jane\'s Birthday',
	$start: '2026-11-03',
	$recurrence: 'FREQ=YEARLY',
	$reminders: [
		{ $days_before: 1, $time: '20:00' },
		{ $days_before: 0, $time: '08:00' }
	],
	$busy: false
}

// multi-day: $end is exclusive -- this is 20 to 24 December
{ $type: 'event', $version: 1, $kind: 'allday', $title: 'Vacation', $start: '2026-12-20', $end: '2026-12-25' }

Calendar

A named collection of events. Carries the defaults its events inherit.

{
	$type: 'event',
	$version: 1,
	$kind: 'calendar',
	$id: 'cal-private',
	$name: 'Private',
	$color: '#3b82f6',
	$timezone: 'Europe/Vienna',
	$visibility: 'private',
	$owner: { $type: 'contact', $name: 'John', $platforms: [{ $url: 'https://ident.worldapi.org', $identifier: 'john' }] },
	$reminders: [
		{ $before: 'PT1H' },
		{ $days_before: 1, $time: '20:00' }
	],
	$events: [ ... ]
}

Object Kinds

Standard Properties

* Required depends on $kind: events need $title and $start, calendars need $name.

Time Rules

• $start without offset + $timezone -- wall-clock time in that zone (recommended). The event stays at 18:00 local across DST changes.
• $start without offset and no $timezone -- floating: same clock time wherever the viewer is. $timezone falls back to the calendar's.
• $start ending in Z -- an absolute instant. Use for events whose start and end are in different zones (flights).
• allday uses dates only and never shifts with timezones.
• $end is exclusive (as in iCal). Missing $end and $duration: appointment = zero length, allday = one day.

Recurrence

$recurrence uses iCalendar RRULE syntax verbatim (RFC 5545 §3.3.10), evaluated in the event's $timezone. The short form is the rule string alone.

$overrides entries hold $recurrence_id (the original $start of the instance) plus only the properties that differ. $status: 'cancelled' in an override equals an $exclude. To change "this and all following", end the series with UNTIL and start a new event.

Reminders

Each reminder uses exactly one of $before, $days_before+$time, or $at. For all-day events, $before counts back from 00:00 of the start date. For recurring events, reminders apply to every instance. Resolution order: the event's $reminders, then the calendar's $reminders, then the app settings. A list that is present replaces the defaults. It does not merge with them.

Attendees

Attendees are contact objects with two extra properties:

Privacy

$visibility controls what others see when a calendar is shared: private = nothing, busy = only the time slot, public = everything. Single private fields (notes, internal IDs) use the _ prefix, e.g. _notes, _android_id, and are never exported to shared or public views.

Mapping to iCalendar (RFC 5545)

Exports only reach inherited default reminders if they are resolved and written as explicit VALARMs. On import, a TRIGGER becomes $before. Android stores reminders as minutes before the start. A $days_before+$time reminder has to be converted to minutes for each event, and it can be off by an hour across a DST change.