NIP-22 - Comment

22.md

@@ -0,0 +1,184 @@
+NIP-22
+======
+
+Comment
+-------
+
+`draft` `optional`
+
+A comment is a threading note always scoped to a root event or an `I`-tag.
+
+It uses `kind:1111` with plaintext `.content` (no HTML, Markdown, or other formatting).
+
+Comments MUST point to the root scope using uppercase tag names (e.g. `K`, `E`, `A` or `I`)
+and MUST point to the parent item with lowercase ones (e.g. `k`, `e`, `a` or `i`).
+
+```js
+{
+  kind: 1111,
+  content: '<comment>',
+  tags: [
+    // root scope: event addresses, event ids, or I-tags.
+    ["<A, E, I>", "<address, id or I-value>", "<relay or web page hint>", "<root event's pubkey, if an E tag>"],
+    // the root kind or type if r.
+    ["K", "<root kind>"],
+
+    // parent item: event addresses, event ids, or i-tags.
+    ["<a, e, i>", "<address, id or i-value>", "<relay or web page hint>", "<parent event's pubkey, if an e tag>"],
+    // parent item kind
+    ["k", "<parent comment kind>"]
+  ]
+  // other fields
+}
+```
+
+Tags `K` and `k` MUST be present to define the event kind of the root and the parent items.
+
+`I` and `i` tags create scopes for hashtags, geohashes, URLs, and other external identifiers.
+
+The possible values for `i` tags – and `k` tags, when related to an extenal identity – are listed on [NIP-73](73.md).
+Their uppercase versions use the same type of values but relate to the root item instead of the parent one.
+
+`q` tags MAY be used when citing events in the `.content` with [NIP-21](21.md).
+
+```json
+["q", "<event-id> or <event-address>", "<relay-url>", "<pubkey-if-a-regular-event>"]
+```
+
+`p` tags SHOULD be used when mentioning pubkeys in the `.content` with [NIP-21](21.md).
+If the parent item is an event, a `p` tag set to the parent event's author SHOULD be added.
+
+```json
+["p", "<pubkey>", "<relay-url>"]
+```
+
+## Examples
+
+A comment on a blog post looks like this:
+
+```js
+{
+  kind: 1111,
+  content: 'Great blog post!',
+  tags: [
+    // top-level comments scope to event addresses or ids
+    ["A", "30023:3c9849383bdea883b0bd16fece1ed36d37e37cdde3ce43b17ea4e9192ec11289:f9347ca7", "wss://example.relay"],
+    // the root kind
+    ["K", "30023"],
+
+    // the parent event address (same as root for top-level comments)
+    ["a", "30023:3c9849383bdea883b0bd16fece1ed36d37e37cdde3ce43b17ea4e9192ec11289:f9347ca7", "wss://example.relay"],
+    // when the parent event is replaceable or addressable, also include an `e` tag referencing its id
+    ["e", "5b4fc7fed15672fefe65d2426f67197b71ccc82aa0cc8a9e94f683eb78e07651", "wss://example.relay"],
+    // the parent event kind
+    ["k", "30023"]
+  ]
+  // other fields
+}
+```
+
+A comment on a [NIP-94](94.md) file looks like this:
+
+```js
+{
+  kind: 1111,
+  content: 'Great file!',
+  tags: [
+    // top-level comments have the same scope and reply to addresses or ids
+    ["E", "768ac8720cdeb59227cf95e98b66560ef03d8bc9a90d721779e76e68fb42f5e6", "wss://example.relay", "3721e07b079525289877c366ccab47112bdff3d1b44758ca333feb2dbbbbe5bb"],
+    // the root kind
+    ["K", "1063"],
+
+    // the parent event id (same as root for top-level comments)
+    ["e", "768ac8720cdeb59227cf95e98b66560ef03d8bc9a90d721779e76e68fb42f5e6", "wss://example.relay", "3721e07b079525289877c366ccab47112bdff3d1b44758ca333feb2dbbbbe5bb"],
+    // the parent kind
+    ["k", "1063"]
+  ]
+  // other fields
+}
+```
+
+A reply to a comment looks like this:
+
+```js
+{
+  kind: 1111,
+  content: 'This is a reply to "Great file!"',
+  tags: [
+    // nip-94 file event id
+    ["E", "768ac8720cdeb59227cf95e98b66560ef03d8bc9a90d721779e76e68fb42f5e6", "wss://example.relay", "fd913cd6fa9edb8405750cd02a8bbe16e158b8676c0e69fdc27436cc4a54cc9a"],
+    // the root kind
+    ["K", "1063"],
+
+    // the parent event
+    ["e", "5c83da77af1dec6d7289834998ad7aafbd9e2191396d75ec3cc27f5a77226f36", "wss://example.relay", "93ef2ebaaf9554661f33e79949007900bbc535d239a4c801c33a4d67d3e7f546"],
+    // the parent kind
+    ["k", "1111"]
+  ]
+  // other fields
+}
+```
+
+A comment on a website's url looks like this:
+
+```js
+{
+  kind: 1111,
+  content: 'Nice article!',
+  tags: [
+    // referencing the root url
+    ["I", "https://abc.com/articles/1"],
+    // the root "kind": for an url, the kind is its domain
+    ["K", "https://abc.com"],
+
+    // the parent reference (same as root for top-level comments)
+    ["i", "https://abc.com/articles/1"],
+    // the parent "kind": for an url, the kind is its domain
+    ["k", "https://abc.com"]
+  ]
+  // other fields
+}
+```
+
+A podcast comment example:
+
+```js
+{
+  id: "80c48d992a38f9c445b943a9c9f1010b396676013443765750431a9004bdac05",
+  pubkey: "252f10c83610ebca1a059c0bae8255eba2f95be4d1d7bcfa89d7248a82d9f111",
+  kind: 1111,
+  content: "This was a great episode!",
+  tags: [
+    // podcast episode reference
+    ["I", "podcast:item:guid:d98d189b-dc7b-45b1-8720-d4b98690f31f", "https://fountain.fm/episode/z1y9TMQRuqXl2awyrQxg"],
+    // podcast episode type
+    ["K", "podcast:item:guid"],
+
+    // same value as "I" tag above, because it is a top-level comment (not a reply to a comment)
+    ["i", "podcast:item:guid:d98d189b-dc7b-45b1-8720-d4b98690f31f", "https://fountain.fm/episode/z1y9TMQRuqXl2awyrQxg"],
+    ["k", "podcast:item:guid"]
+  ]
+  // other fields
+}
+```
+
+A reply to a podcast comment:
+
+```js
+{
+  kind: 1111,
+  content: "I'm replying to the above comment.",
+  tags: [
+    // podcast episode reference
+    ["I", "podcast:item:guid:d98d189b-dc7b-45b1-8720-d4b98690f31f", "https://fountain.fm/episode/z1y9TMQRuqXl2awyrQxg"],
+    // podcast episode type
+    ["K", "podcast:item:guid"],
+
+    // this is a reference to the above comment
+    ["e", "80c48d992a38f9c445b943a9c9f1010b396676013443765750431a9004bdac05", "wss://example.relay", "252f10c83610ebca1a059c0bae8255eba2f95be4d1d7bcfa89d7248a82d9f111"],
+    // the parent comment kind
+    ["k", "1111"]
+  ]
+  // other fields
+}
+```