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

1 files changed, 37 insertions, 4 deletions

diff --git a/31.md b/31.md
index 37e4130..889413d 100644
--- a/31.md
+++ b/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.