From 553c1c77c004329206a3ba851f3a68367d9edc9a Mon Sep 17 00:00:00 2001 From: fiatjaf_ Date: Wed, 14 May 2025 09:27:59 -0300 Subject: [PATCH] simplify nip-52 (#1922) --- 51.md | 1 + 52.md | 119 ++++++++++++++++++++++------------------------------------ 2 files changed, 46 insertions(+), 74 deletions(-) diff --git a/51.md b/51.md index bac1a928..5313cea9 100644 --- a/51.md +++ b/51.md @@ -60,6 +60,7 @@ Aside from their main identifier, the `"d"` tag, sets can optionally have a `"ti | Emoji sets | 30030 | categorized emoji groups | `"emoji"` (see [NIP-30](30.md)) | | Release artifact sets | 30063 | group of artifacts of a software release | `"e"` (kind:1063 [file metadata](94.md) events), `"a"` (software application event) | | App curation sets | 30267 | references to multiple software applications | `"a"` (software application event) | +| Calendar | 31924 | a set of events categorized in any way | `"a"` (calendar event event) | | Starter packs | 39089 | a named set of profiles to be shared around with the goal of being followed together | `"p"` (pubkeys) | | Media starter packs | 39092 | same as above, but specific to multimedia (photos, short video) clients | `"p"` (pubkeys) | diff --git a/52.md b/52.md index f701ca6f..898e011e 100644 --- a/52.md +++ b/52.md @@ -12,23 +12,14 @@ Unlike the term `calendar event` specific to this NIP, the term `event` is used ## 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](#calendar). +There are two types of calendar events represented by different kinds: _date-based_ and _time-based_ calendar events. -### Date-Based Calendar Event +These tags are common to both types of calendar events: -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 an _addressable event_ of `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) a short unique string identifier. 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`. +* `summary` (optional) brief description of the calendar event +* `image` (optional) url of an image to use for the event * `location` (optional, repeated) location of the calendar event. e.g. address, GPS coordinates, meeting room name, link to video call * `g` (optional) [geohash](https://en.wikipedia.org/wiki/Geohash) to associate calendar event with a searchable physical location * `p` (optional, repeated) 32-bytes hex pubkey of a participant, optional recommended relay URL, and participant's role in the meeting @@ -36,13 +27,31 @@ The list of tags are as follows: * `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. -```jsonc +Calendar events are _not_ required to be part of a [calendar](#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. + +It's an _addressable event_ of `kind:31922`. + +The `.content` of these events SHOULD be a description of the calendar event. + +Aside from the common tags, this also takes the following tags: + +* `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`. + +Example: + +```yaml { "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": , + "created_at": , "kind": 31922, "content": "", "tags": [ @@ -50,25 +59,17 @@ The following tags are deprecated: ["title", ""], - // Dates + // dates ["start", "<YYYY-MM-DD>"], ["end", "<YYYY-MM-DD>"], - // Location + // location ["location", "<location>"], ["g", "<geohash>"], - // Participants + // 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>"] ] } ``` @@ -77,36 +78,22 @@ The following tags are deprecated: This kind of calendar event spans between a start time and end time. -#### Format +It's an _addressable event_ of `kind:31923`. -The format uses an _addressable event_ kind `31923`. +The `.content` of these events should be a description of the calendar event. It is required but can be an empty string. -The `.content` of these events should be a detailed description of the calendar event. It is required but can be an empty string. +Aside from the common tags, this also takes the following tags: -The list of tags are as follows: -* `d` (required) a short unique string identifier. Generated by the client creating the calendar event. -* `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. -* `summary` (optional) brief description of the calendar event -* `image` (optional) url of an image to use for the event -* `location` (optional, repeated) location of the calendar event. e.g. address, GPS coordinates, meeting room name, link to video call -* `g` (optional) [geohash](https://en.wikipedia.org/wiki/Geohash) to associate calendar event with a searchable physical location -* `p` (optional, repeated) 32-bytes hex pubkey of a participant, optional recommended relay URL, and participant's role in the meeting -* `l` (optional, repeated) label to categorize calendar event. e.g. `audiospace` to denote a scheduled event from a live audio space implementation such as cornychat.com -* `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. - -```jsonc +```yaml { "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>, + "created_at": <unix timestamp in seconds>, "kind": 31923, "content": "<description of calendar event>", "tags": [ @@ -116,54 +103,39 @@ The following tags are deprecated: ["summary", "<brief description of the calendar event>"], ["image", "<string with image URI>"], - // Timestamps - ["start", "<Unix timestamp in seconds>"], - ["end", "<Unix timestamp in seconds>"], + // 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 + // location ["location", "<location>"], ["g", "<geohash>"], - // Participants + // 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>"], - - // Labels (example using com.cornychat namespace denoting the event as an audiospace) - ["L", "com.cornychat"], - ["l", "audiospace", "com.cornychat"], - - // 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 +A calendar is a collection of calendar events, represented as a custom _addressable 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. 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 -```json +```yaml { "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>, + "created_at": <unix timestamp in seconds>, "kind": 31924, "content": "<description of calendar>", "tags": [ @@ -191,13 +163,12 @@ The RSVP MUST have an `a` tag of the event coordinates to the calendar event, an The RSVP MAY tag the author of the calendar event it is in response to using a `p` tag so that clients can easily query all RSVPs that pertain to the author. -### Format - -The format uses an _addressable event_ kind `31925`. +The RSVP is an _addressable event_ of `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: +The list of tags is as follows: + * `a` (required) coordinates to a kind `31922` or `31923` calendar event being responded to. * `e` (optional) event id of a kind `31922` or `31923` calendar event being responded to. * `d` (required) universally unique identifier. Generated by the client creating the calendar event RSVP. @@ -205,11 +176,11 @@ The list of tags are as follows: * `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`. * `p` (optional) pubkey of the author of the calendar event being responded to. -```json +```yaml { "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>, + "created_at": <unix timestamp in seconds>, "kind": 31925, "content": "<note>", "tags": [