1 Overview
The source repository marks this NIP unrecommended with the warning: unnecessarily bloated. The alt tag adds a copy of the event's meaning to every custom event. Do not add it to new event kinds. For real interoperability with unknown kinds, use the handler discovery flow in NIP-89 instead.
Nostr lets any NIP claim a new event kind. A custom protocol can publish events that carry structured data, not prose. A social client that only understands kind:1 text notes cannot render such an event. This NIP defines a fallback for that case.
The fallback is the alt tag: a short human-readable plaintext summary of what the event is about. A social client that meets an unknown kind reads the alt tag. It shows the summary instead of a blank or nonsensical note.
Clients that only know kind:1 are not expected to ask relays for events of other kinds. But users can still reference these custom events in their notes. Without context, such a reference renders as nonsense. The fallback text improves that situation. At minimum, it tells the user to view the custom event in another client.
2 The alt Tag
When a client creates an event of a new custom kind, and that kind is part of a custom protocol, and its content is not meant to be read as text (unlike kind:1), the client should add an alt tag. The tag has one value: the summary string.
"tags": [ ["alt", <short human-readable plaintext summary>], ... protocol-specific tags ... ]
| Tag | Value | Rule |
|---|---|---|
| alt | plaintext string | A short human-readable summary of what the event is about. Add it to custom event kinds whose content is not readable text. This is a should, not a must. |
The summary must give enough context on its own. Write it for a user who knows nothing about the event kind. After reading it, the user should understand what the event is, even if the client cannot render it.
Two gaps in the source text. First, it defines no behavior for a custom event that lacks an alt tag; each client must invent its own fallback. Second, the deprecation warning names no replacement; NIP-89 is only referenced as an optional improvement, not as a successor. Also note: alt is not a single-letter tag, so relays do not index it under the NIP-01 rules. You cannot query it with a filter.
3 Client Behavior
Rendering follows one decision. If the client understands the kind, it renders the event natively. If it does not, it shows the alt summary as plain text. The client does not need to parse the content of an unknown kind.
alt tag and show the summary as plain text.kind:1-centric clients can go one step further than plain fallback text. With NIP-89, a client can discover which application handles an unknown kind and link the user straight to it.
4 Worked Example
A music application publishes an audio track as a custom kind:31337 event. The content holds protocol data that only music clients parse. The alt tag carries the fallback summary.
{
"id": "7fa31c22e0…",
"pubkey": "9d0c44eb17…",
"created_at": 1749980000,
"kind": 31337,
"tags": [
["d", "track-sunrise"],
["alt", "An audio track: 'Sunrise'. Open this event in a music client to play it."]
],
"content": "{\"url\":\"https://cdn.example.com/sunrise.mp3\",\"bpm\":121}",
"sig": "c04d19e2a5…"
}
A user references this event in a kind:1 note. A social client fetches the event and does not recognize kind:31337. It ignores the content and renders the alt summary:
-- timeline view --
@dj_anon: check out my new track! nostr:nevent1qqs0…
┌──────────────────────────────────────────────────┐
│ An audio track: 'Sunrise'. Open this event in a │
│ music client to play it. │
└──────────────────────────────────────────────────┘
Do not put protocol data in the alt tag, and do not put the fallback text in content. The summary is for humans only. Clients that understand the kind never read it.
5 Version History
NIP-31 had a short, quiet life. It changed its mechanism once, then sat unchanged until it was marked unrecommended. Notable changes, newest first:
- 20262026-05Deprecated. fiatjaf marked the NIP
unrecommendedwith the warning "unnecessarily bloated". - 2023-252023-2025Housekeeping: author names removed from all NIP documents; cross-reference links fixed (#1740).
- 20232023-06pablof7z reworked the mechanism: the fallback summary moved into a dedicated
alttag. - Origin2023-05fiatjaf published the first draft as "dealing with custom unknown events".
Original Proposal - Credits
| Author | fiatjaf |
| First commit | 2023-05-05 — “nip-31: dealing with custom unknown events.” |
| Status | draft - unrecommended - optional — deprecated, do not implement in new kinds |
| Source | 31.md on GitHub - full change history |