NIP-31: Dealing with unknown event kinds
Custom events needed a humane fallback
NIP-31 begins from a real problem in an expanding protocol. Nostr lets developers create many event kinds. A timeline client that mainly understands kind 1 notes may still encounter references to a music event, game event, marketplace object, calendar item, community artifact or another custom kind. Without a fallback, the user sees an opaque object with no clue what it is.
The proposal asks custom non-text events to include an alt tag with a short plaintext summary. That summary is not meant to fully render the object. It gives enough context for a normal social client to say, in effect, 'this is a thing from another app, here is what it is about.'
The file is now marked unrecommended as unnecessarily bloated. That warning matters. NIP-31 is best read as an early attempt to keep custom event kinds from becoming unreadable litter in feeds, not as a mandate to overload every custom event with a polished fallback narrative.
The alt tag as minimum context
The alt tag carries a human-readable summary for a custom event kind that is not itself normal readable text. The value gives a user enough context to understand why the event appeared and whether a different client may be needed.
NIP-31 is careful about the client model. A kind 1-centric client is not expected to query relays for arbitrary event kinds. But a user can quote, reference or encounter those objects in ordinary notes. In that case, fallback text is better than a blank box or a raw JSON dump.
The standard points toward NIP-89 for richer handling. NIP-89 defines application-handler recommendations so a client can discover which app can open a given event kind. In that pair, NIP-31 is the label on the unknown object; NIP-89 is the door to a specialized app.
A tiny fallback became a warning about protocol sprawl
Fiatjaf added NIP-31 in May 2023 as a way to deal with custom unknown events. In June 2023, Pablo Fernandez updated it to use the alt tag, making the fallback mechanism explicit. Author metadata was removed in November 2023, and Mohammed Alotaibi fixed NIP references in early 2025.
The decisive change came with the 2026 warning pass that marked NIP-31 unrecommended. The warning text says 'unnecessarily bloated,' which is blunt but useful. The ecosystem still needs fallback context, but not every custom object needs another layer of mandated explanatory structure.
The better reading is that NIP-31 captured a real UX problem before Nostr had a mature app-discovery story. NIP-89 now carries more of the product answer: show the fallback, then offer an application handler that actually understands the event.
Fallback text is a UX courtesy, not a renderer
Nostrbook's tag registry lists alt as a human-readable summary for custom event kinds. The Rust Nostr standardized tag source includes broad tag handling where alt appears in the wider tag universe. NIP-89's own user flow explicitly mentions displaying an unknown kind through its NIP-31 alt tag before looking up a handler.
A careful client treats alt as fallback text. It does not trust it as a full semantic description, because any author can write misleading fallback text. It also does not replace specialized rendering when a proper handler exists.
A careful event author keeps the summary short and plain. A fallback such as 'A calendar event for the Zurich meetup' helps. A paragraph of marketing copy does not. The tag is there to prevent confusion, not to smuggle a second post into metadata.
Fallback copy can become false confidence
The main risk is treating the alt tag as trustworthy meaning. It is author-supplied text. A malicious event can describe itself innocently. Clients still need event-kind handling, signature checks and app-specific validation.
The second risk is clutter. If every event type carries verbose fallback copy, timelines become noisier and storage grows for little user gain. NIP-31's unrecommended status is a signal to keep the problem in mind while favoring simpler, more precise app-discovery patterns.
Read NIP-31 in the wild
NIP-31 tells clients how to handle unknown event kinds. This is one of the quiet standards that keeps experimentation from breaking the interface: an app can see that something exists without pretending to understand it.
That matters because Nostr evolves by adding event kinds. A graceful unknown-event view protects users from blank screens while protecting the protocol from clients that throw away everything unfamiliar.
What changes when you actually use it
For you, NIP-31: Dealing with Unknown Events is felt when an app either behaves predictably or suddenly loses context. The visible symptom may be a missing reply, a broken link, a strange reaction count, an empty result or a relay error that looks like the whole network failed. The official terms kind 1, unrecommended, draft, kind:1, alt are where that visible behavior begins, so the source is not background material; it is the place where the product promise gets its limits.
What changes for builders and operators
For builders, NIP-31: Dealing with Unknown Events is compatibility discipline. Implement kind 1, unrecommended, draft, kind:1, alt against more than one relay and more than one library, then test malformed, missing and duplicated data. Core standards fail most painfully when the happy path looks fine and the second client exposes the shortcut.
What the official file makes concrete
Inspect kind 1, unrecommended, draft, kind:1, alt because these are the pieces most likely to surface as product behavior. Read it beside NIP-89 before treating it as isolated.
NIP-31: Dealing with Unknown Events is a shared contract between independent software. The smallest field can become user-visible when two clients disagree about it.
Where it breaks
The failure mode in NIP-31: Dealing with Unknown Events is often indirect. Nobody complains about kind 1, unrecommended, draft, kind:1, alt; they complain that the feed is wrong, the reply vanished or the relay behaved strangely. Use the official file to diagnose the hidden cause instead of patching only the visual symptom.
Where this appears outside the markdown
In the ecosystem, NIP-31: Dealing with Unknown Events is not something most people choose directly. It is the invisible grammar behind clients, relays, crawlers, search tools and archives. When a product team treats kind 1, unrecommended, draft, kind:1, alt as implementation detail only, the mistake eventually reaches the surface as missing history, bad threading or state that cannot be reconstructed after a client switch.
The nearby-standard trap
The nearby-standard trap in NIP-31: Dealing with Unknown Events is assuming the base layer solves the higher-level feature. This NIP may define the common grammar, but publishing, wallets, moderation, media or groups still need their own constraints. Read NIP-89 to see where the base contract ends and the product-specific promise begins.
Language that keeps the feature honest
Good product copy for NIP-31: Dealing with Unknown Events does not say "the protocol handles it" and move on. It explains the visible consequence: what was sent, what was accepted, what was rejected, what is still loading and what another relay or client may show differently.
What this page does not promise
NIP-31: Dealing with Unknown Events does not promise a finished social product. It gives software a shared grammar. Feed design, moderation, ranking, notifications, storage duration and recovery remain separate product decisions. That distinction matters because a client can be technically compatible and still give you a weak experience if it hides relay errors, drops context or treats optional fields as if every app understood them.
Read it as a field test
Start NIP-31: Dealing with Unknown Events with the visible product symptom, then trace it back to kind 1, unrecommended, draft, kind:1, alt. That order keeps the article grounded: you see why the field exists, which relay or client behavior depends on it, and where adjacent standards change the story. A core NIP is strong only when it explains both the normal path and the awkward edge case.
Where the standard earns trust
The source links give you places to test the interpretation in public: nips.nostr.com NIP-31 mirror, nostr-nips.com NIP-31 mirror, NIP-89 application handlers, nips.nostr.com NIP-89. Use those links to move from the spec to live libraries, mirrors, pull requests, guides or products.
Official NIP-31 source is the anchor for exact wording, and NIP-31 commit history shows how that wording moved over time. The strongest secondary clues here are nips.nostr.com NIP-31 mirror, nostr-nips.com NIP-31 mirror, NIP-89 application handlers. Treat this evidence chain as part of the article, not as footnotes. A NIP page becomes useful when you can move from claim to source to working behavior without guessing.
Keep the chain visible for NIP-31: Dealing with Unknown Events: first the human promise, then kind 1, unrecommended, draft, kind:1, alt, then the implementation record, then the real-world failure case. That order keeps NIP-31 useful without turning it into marketing copy or protocol trivia.
Three questions to carry forward
- Can two independent clients read the same
kind 1,unrecommended,draft,kind:1without a hidden compatibility rule? - Does the UI explain relay rejection, missing context or state replacement without blaming the whole network?
- Which adjacent standard, especially NIP-89, changes the behavior once the base event leaves the happy path?
What to verify before you rely on it
- Find
kind 1,unrecommended,draft,kind:1,altin the official file and check where the UI exposes the same concept. - Read NIP-89 as context before treating NIP-31 as a complete product story.
- Open at least one implementation, mirror, pull request or library source from the source links before trusting that the idea is mature.
- Test the unhappy path: missing relays, stale metadata, invalid signatures, blocked events, expired state, revoked permissions or unavailable media.
- Write the user-facing copy in plain language. If a standard changes authority, privacy, money, moderation or recovery, say that before the click.
Direct sources
Use these sources for NIP-31: Dealing with Unknown Events in that order: Official NIP-31 source for the current wording; NIP-31 commit history for the change record; nips.nostr.com NIP-31 mirror, nostr-nips.com NIP-31 mirror, NIP-89 application handlers for public context. The article gives you the consequence in plain language, but the source trail is where exact fields, status notes, unresolved debates and implementation proof stay checkable.
