nips/52.md

NIP-52

Calendar Events

draft optional

This specification defines calendar events representing an occurrence at a specific moment or between moments. These calendar events are parameterized replaceable and deletable per NIP-09.

Unlike the term calendar event specific to this NIP, the term event is used broadly in all the NIPs to describe any Nostr event. The distinction is being made here to discern between the two terms.

Calendar Events

There are two types of calendar events represented by different kinds: date-based and time-based calendar events. Calendar events are not required to be part of a calendar.

Date-Based Calendar Event

This kind of calendar event starts on a date and ends before a different date in the future. Its use is appropriate for all-day or multi-day events where time and time zone hold no significance. e.g., anniversary, public holidays, vacation days.

Format

The format uses a parameterized replaceable event kind 31922.

The .content of these events should be a detailed description of the calendar event. It is required but can be an empty string.

The list of tags are as follows:

• d (required) universally unique identifier (UUID). Generated by the client creating the calendar event.
• title (required) title of the calendar event
• start (required) inclusive start date in ISO 8601 format (YYYY-MM-DD). Must be less than end, if it exists.
• end (optional) exclusive end date in ISO 8601 format (YYYY-MM-DD). If omitted, the calendar event ends on the same date as start.
• address (optional) address of the calendar event following ISO 19160:2015 and splitting the elements in the array; the country is specified in ISO 3166
• place (optional) name of the place of the calendar event. e.g. university, building, business, public space
• g (optional) geohash to associate calendar event with a searchable physical location
• languages (optional) list of IETF language tags indicating the major languages used in the event
• p (optional, repeated) 32-bytes hex pubkey of a participant, optional recommended relay URL, and participant's role in the meeting
• t (optional, repeated) hashtag to categorize calendar event
• r (optional, repeated) references / links to web pages, documents, video calls, recorded videos, etc.

The following tags are deprecated:

• name name of the calendar event. Use only if title is not available.

{
  "id": <32-bytes lowercase hex-encoded SHA-256 of the the serialized event data>,
  "pubkey": <32-bytes lowercase hex-encoded public key of the event creator>,
  "created_at": <Unix timestamp in seconds>,
  "kind": 31922,
  "content": "<description of calendar event>",
  "tags": [
    ["d", "<UUID>"],

    ["title", "<title of calendar event>"],

    // Dates
    ["start", "<YYYY-MM-DD>"],
    ["end", "<YYYY-MM-DD>"],

    // Location
    ["address", "<street name and number>", "<city or locality>", "<postal or zip code>", "<country>"],
    ["place", "<place>"],
    ["g", "<geohash>"],
    ["url", "<nostr:naddr1xxx or a http(s)://xxx>"],

    // Participants
    ["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>", "<role>"],
    ["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>", "<role>"],

    // Languages
    ["languages", "<lang>", "<lang>"]

    // Hashtags
    ["t", "<tag>"],
    ["t", "<tag>"],

    // Reference links
    ["r", "<url>"],
    ["r", "<url>"]
  ]
}

Time-Based Calendar Event

This kind of calendar event spans between a start time and end time.

Format

The format uses a parameterized replaceable event kind 31923.

The .content of these events should be a detailed description of the calendar event. It is required but can be an empty string.

The list of tags are as follows:

• d (required) universally unique identifier (UUID). Generated by the client creating the calendar event.
• type (required) type of the event, list of [onsite, online]
• title (required) title of the calendar event
• start (required) inclusive start Unix timestamp in seconds. Must be less than end, if it exists.
• end (optional) exclusive end Unix timestamp in seconds. If omitted, the calendar event ends instantaneously.
• start_tzid (optional) time zone of the start timestamp, as defined by the IANA Time Zone Database. e.g., America/Costa_Rica
• end_tzid (optional) time zone of the end timestamp, as defined by the IANA Time Zone Database. e.g., America/Costa_Rica. If omitted and start_tzid is provided, the time zone of the end timestamp is the same as the start timestamp.
• address (recommended if type is onsite) address of the calendar event following ISO 19160:2015 and splitting the elements in the array; the country is specified in ISO 3166
• place (recommended if type is onsite) name of the place of the calendar event. e.g. university, building, business, public space
• g (optional) geohash to associate calendar event with a searchable physical location
• url (recommended if type is online) the url where the user can access the calendar event; it can be a nostr:naddr1xxx (preferably a NIP-53 event) or an http(s)://xxx endpoint
• languages (optional) list of IETF language tags indicating the major languages used in the event
• p (optional, repeated) 32-bytes hex pubkey of a participant, optional recommended relay URL, and participant's role in the meeting
• t (optional, repeated) hashtag to categorize calendar event
• r (optional, repeated) references / links to web pages, documents, video calls, recorded videos, etc.

The following tags are deprecated:

• name name of the calendar event. Use only if title is not available.

{
  "id": <32-bytes lowercase hex-encoded SHA-256 of the the serialized event data>,
  "pubkey": <32-bytes lowercase hex-encoded public key of the event creator>,
  "created_at": <Unix timestamp in seconds>,
  "kind": 31923,
  "content": "<description of calendar event>",
  "tags": [
    ["d", "<UUID>"],

    ["type", "<onsite>", "<online>"],

    ["title", "<title of calendar event>"],

    // Timestamps
    ["start", "<Unix timestamp in seconds>"],
    ["end", "<Unix timestamp in seconds>"],

    ["start_tzid", "<IANA Time Zone Database identifier>"],
    ["end_tzid", "<IANA Time Zone Database identifier>"],

    // Location
    ["address", "<street name and number>", "<city or locality>", "<postal or zip code>", "<country>"],
    ["place", "<place>"],
    ["g", "<geohash>"],
    ["url", "<nostr:naddr1xxx or a http(s)://xxx>"],

    // Languages
    ["languages", "<lang>", "<lang>"]

    // Participants
    ["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>", "<role>"],
    ["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>", "<role>"],

    // Hashtags
    ["t", "<tag>"],
    ["t", "<tag>"],

    // Reference links
    ["r", "<url>"],
    ["r", "<url>"]
  ]
}

Calendar

A calendar is a collection of calendar events, represented as a custom replaceable list event using kind 31924. A user can have multiple calendars. One may create a calendar to segment calendar events for specific purposes. e.g., personal, work, travel, meetups, and conferences.

Format

The .content of these events should be a detailed description of the calendar. It is required but can be an empty string.

The format uses a custom replaceable list of kind 31924 with a list of tags as described below:

• d (required) universally unique identifier. Generated by the client creating the calendar.
• title (required) calendar title
• a (repeated) reference tag to kind 31922 or 31923 calendar event being responded to

{
  "id": <32-bytes lowercase hex-encoded SHA-256 of the the serialized event data>,
  "pubkey": <32-bytes lowercase hex-encoded public key of the event creator>,
  "created_at": <Unix timestamp in seconds>,
  "kind": 31924,
  "content": "<description of calendar>",
  "tags": [
    ["d", "<UUID>"],
    ["title", "<calendar title>"],
    ["a", "<31922 or 31923>:<calendar event author pubkey>:<d-identifier of calendar event>", "<optional relay url>"],
    ["a", "<31922 or 31923>:<calendar event author pubkey>:<d-identifier of calendar event>", "<optional relay url>"]
  ]
}

Calendar Event RSVP

A calendar event RSVP is a response to a calendar event to indicate a user's attendance intention.

If a calendar event tags a pubkey, that can be interpreted as the calendar event creator inviting that user to attend. Clients MAY choose to prompt the user to RSVP for the calendar event.

Any user may RSVP, even if they were not tagged on the calendar event. Clients MAY choose to prompt the calendar event creator to invite the user who RSVP'd. Clients also MAY choose to ignore these RSVPs.

This NIP is intentionally not defining who is authorized to attend a calendar event if the user who RSVP'd has not been tagged. It is up to the calendar event creator to determine the semantics.

This NIP is also intentionally not defining what happens if a calendar event changes after an RSVP is submitted.

Format

The format uses a parameterized replaceable event kind 31925.

The .content of these events is optional and should be a free-form note that adds more context to this calendar event response.

The list of tags are as follows:

• a (required) reference tag to kind 31922 or 31923 calendar event being responded to.
• d (required) universally unique identifier. Generated by the client creating the calendar event RSVP.
• status (required) accepted, declined, or tentative. Determines attendance status to the referenced calendar event.
• fb (optional) free or busy. Determines if the user would be free or busy for the duration of the calendar event. This tag must be omitted or ignored if the status label is set to declined.

{
  "id": <32-bytes lowercase hex-encoded SHA-256 of the the serialized event data>,
  "pubkey": <32-bytes lowercase hex-encoded public key of the event creator>,
  "created_at": <Unix timestamp in seconds>,
  "kind": 31925,
  "content": "<note>",
  "tags": [
    ["a", "<31922 or 31923>:<calendar event author pubkey>:<d-identifier of calendar event>", "<optional relay url>"],
    ["d", "<UUID>"],
    ["status", "<accepted/declined/tentative>"],
    ["fb", "<free/busy>"],
  ]
}

Unsolved Limitations

• No private events

Intentionally Unsupported Scenarios

Recurring Calendar Events

Recurring calendar events come with a lot of complexity, making it difficult for software and humans to deal with. This complexity includes time zone differences between invitees, daylight savings, leap years, multiple calendar systems, one-off changes in schedule or other metadata, etc.

This NIP intentionally omits support for recurring calendar events and pushes that complexity up to clients to manually implement if they desire. i.e., individual calendar events with duplicated metadata represent recurring calendar events.