Status warning: The current NIP-31 specification marks itself unrecommended as “unnecessarily bloated,” and its status line reads draft, unrecommended and optional. Relays already hold events that use this convention, so this page explains how clients read them. It does not recommend NIP-31 for new protocols.

NIP-31 defines a top-level alt tag. The tag holds a short plaintext summary for custom event kinds that are not meant to be read as ordinary text notes.

How It Works

The author of a custom-kind event adds an alt tag with a label a person can read. Clients built around kind 1 do not have to subscribe to every kind they do not recognize. Their users can still come across such an event when a note references it, and the label gives some context even though the client does not implement that kind.

Tag fragment, not a complete event:

["alt", "<short plaintext summary>"]

A readable label only covers display. It cannot cast a vote, act on a wallet request or perform any other native action of the kind. For richer interaction, the spec points to NIP-89: Recommended Application Handlers.

Implementations

In noStrudel’s unknown-event card at commit 7c68acf, the first alt tag is trimmed and becomes the main label, with an optional Using <client> line. A missing or blank value yields Unknown event (kind ...), and up to three lines of content appear on their own. The same component resolves the client tag through NIP-89 handler templates. It shows an Open button when a shareable address exists and Open in <client> when a valid handler link resolves. The explanation and the app dispatch are separate controls.

Amethyst’s UnknownEventDigest.kt at commit 553f761 prefers content it classifies as prose and falls back to alt. Its parser trims values and takes the first nonblank alt. As a result, an event whose first alt is blank can get a different label here than in noStrudel. Both descriptions reflect the source code at those commits. Neither confirms how a released version behaves.

Limits

  • alt is a tag, so the event ID and signature defined in NIP-01 cover it. A valid signature shows that the author published the label. It does not show that the label is accurate, so a summary can mislead.
  • Tags are public. An alt on an event with encrypted content exposes its summary and can reveal what the content hides.
  • Both properties above come from the NIP-01 event envelope. NIP-31’s own text does not state them as requirements.
  • A top-level alt tag is different from the image-description alt field inside imeta, and renderers parse them separately.

Primary sources:

Mentioned in:

See also: