nips/31.md

NIP-31

Dealing with unknown event kinds

draft optional

When faced with an event of an unknown or unsupported kind, clients still have to display something to the user.

Besides indicating that the event kind is not supported and suggesting other clients to handle it (possibly using NIP-89) clients may try these two alternatives:

1. Display text generated from a hardcoded or dynamic template;
2. Display the value of the event's alt tag;

(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-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.