nip31: template-based "alt" tags for known kinds.

01.md

@@ -78,8 +78,8 @@ This NIP defines 3 standard tags that can be used across all event kinds with th
 - The `e` tag, used to refer to an event: `["e", <32-bytes lowercase hex of the id of another event>, <recommended relay URL, optional>, <32-bytes lowercase hex of the author's pubkey, optional>]`
 - The `p` tag, used to refer to another user: `["p", <32-bytes lowercase hex of a pubkey>, <recommended relay URL, optional>]`
 - The `a` tag, used to refer to an addressable or replaceable event
-    - for an addressable event: `["a", <kind integer>:<32-bytes lowercase hex of a pubkey>:<d tag value>, <recommended relay URL, optional>]`
-    - for a normal replaceable event: `["a", <kind integer>:<32-bytes lowercase hex of a pubkey>:, <recommended relay URL, optional>]`
+    - for an addressable event: `["a", "<kind integer>:<32-bytes lowercase hex of a pubkey>:<d tag value>", <recommended relay URL, optional>]`
+    - for a normal replaceable event: `["a", "<kind integer>:<32-bytes lowercase hex of a pubkey>:", <recommended relay URL, optional>]` (note: include the trailing colon)
 
 As a convention, all single-letter (only english alphabet letters: a-z, A-Z) key tags are expected to be indexed by relays, such that it is possible, for example, to query or subscribe to events that reference the event `"5c83da77af1dec6d7289834998ad7aafbd9e2191396d75ec3cc27f5a77226f36"` by using the `{"#e": ["5c83da77af1dec6d7289834998ad7aafbd9e2191396d75ec3cc27f5a77226f36"]}` filter. Only the first value in any given tag is indexed.
 

31.md

@@ -6,10 +6,43 @@ Dealing with unknown event kinds
 
 `draft` `optional`
 
-When creating a new custom event kind that is part of a custom protocol and isn't meant to be read as text (like `kind:1`), clients should use an `alt` tag to write a short human-readable plaintext summary of what that event is about.
+When faced with an event of an unknown or unsupported kind, clients still have to display _something_ to the user.
 
-The intent is that social clients, used to display only `kind:1` notes, can still show something in case a custom event pops up in their timelines. The content of the `alt` tag should provide enough context for a user that doesn't know anything about this event kind to understand what it is.
+Besides indicating that the event kind is not supported and suggesting other clients to handle it (possibly using [NIP-89](89.md)) clients may try these two alternatives:
 
-These clients that only know `kind:1` are not expected to ask relays for events of different kinds, but users could still reference these weird events on their notes, and without proper context these could be nonsensical notes. Having the fallback text makes that situation much better -- even if only for making the user aware that they should try to view that custom event elsewhere.
+1. Display text generated from a hardcoded or dynamic template;
+2. Display the value of the event's `alt` tag;
 
-`kind:1`-centric clients can make interacting with these event kinds more functional by supporting [NIP-89](89.md).
+(Of course if both are unavailable then the client has to decide on something else, like displaying a generic error message or the raw JSON contents or something else.)
+
+### Templates
+
+Templates can be either hardcoded by application developers or downloaded at runtime (or downloaded at compile-time) from a trusted provider or from a library, anything.
+
+They consist of a [Mustache](https://mustache.github.io/)-compatible template (with no loops or partials) that takes the following parameters:
+
+- `kind`
+- `created_at`
+- `pubkey`
+- `content`
+- `tags`
+
+In which each of these values corresponds to the attribute of the event with the same name, except for `tags`, which is treated as an object with key-value access given by the first two items of each tag (and in the case of multiple tags with the same key only one, presumably the first, should be used).
+
+**For example,**
+  - a reasonable template for a `kind:1111` event (comment) would be: `{{content}}`
+  - a reasonable template for a `kind:14` event (direct message) would be: `encrypted message to {{tags.p}}`
+  - a reasonable template for a `kind:7` event (reaction) would be: `{{pubkey}} reacts to {{tags.e}} by {{tags.p}}{{#content}} with {{.}}{{/content}}`
+  - a reasonable template for a `kind:30617` event (repository announcement) would be: `git repository {{tags.name}}{{#tags.web}}hosted at {{.}}{{/tags.web}} by {{pubkey}}`
+  - a reasonable template for a `kind:10002` event (relay list) would be: `canonical relays list for {{pubkey}}`
+  - a reasonable template for a `kind:31922` event (calendar) would be: `{{tags.title}} happening at {{tags.start}}`
+
+To be easily exchangeable and reusable, trusted providers that want to do it SHOULD serve these templates through HTTP at `https://<domain-name>/.well-known/nip31/<kind-number>`, returning just the raw text.
+
+Clients MAY format `{{pubkey}}` into a clickable `nostr:npub1...` link, or print `created_at` as a human-friendly date instead of as a timestamp, or anything like that.
+
+### `alt` tags
+
+When creating a new custom event kind that is part of a custom protocol and isn't meant to be read as text, clients SHOULD write an `alt` tag to include a short human-readable plaintext summary of what that event is about.
+
+This is recommended for a while, until clients and providers have been given enough time to update their templates, then clients should stop doing it.