simplify nip-52 (#1922)

1 files changed, 45 insertions, 74 deletions

diff --git a/52.md b/52.md
index f701ca6..898e011 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
-
-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.
+These tags are common to both types of calendar events:
 
-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": <Unix timestamp in seconds>,
+  "created_at": <unix timestamp in seconds>,
   "kind": 31922,
   "content": "<description of calendar event>",
   "tags": [
@@ -50,25 +59,17 @@ The following tags are deprecated:
 
     ["title", "<title of calendar event>"],
 
-    // 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": [