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](89.md)) 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](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.