NIP-27: Text Note References
Readable text needed links that survive across clients
NIP-27 is about a deceptively simple problem: when a note or article mentions another profile or event, where does that reference live? Old approaches put special positional tags beside the content and asked clients to replace markers. That was brittle, hard to read and easy to leak into places where mentions did not belong.
The newer answer is inline nostr: references. The content itself can include a NIP-21 link such as nostr:nprofile..., nostr:nevent... or nostr:naddr.... A client parses the content, decodes the NIP-19 entity and renders a useful mention, preview or link.
That preserves the text. If a client does not support rich previews, the reference is still visible as a link-like object. If it does support previews, it can fetch the profile, event or article and render something friendlier. The reference is no longer hidden in tag indexes alone.
Inline references first, tags only when they mean something
When creating readable text events, clients include references inside .content using NIP-21 codes. A user can type or paste a NIP-19 value, and the client can turn it into a nostr: link. On display, another client can replace that raw link with a username, profile card, note preview or internal route.
Tags remain useful, but they are no longer automatic decoration. A p tag can notify a mentioned profile. A q tag can register a quote or cited event without making it a reply. A client can choose not to add such tags when the reference is deliberately quiet or when the author wants an inline link without notification.
This separation is the core idea. Content carries the readable reference. Tags carry indexing, notification and relationship meaning. That keeps references flexible across kind 1 notes, kind 30023 articles and other text-bearing event kinds.
NIP-27 replaced an older multicasting idea and cleaned up mentions
NIP-27 did not always mean text references. In August 2022, Ricardo Cabral added and then removed an older NIP-27 about multicasting. The modern text-reference work arrived in March 2023 through Arthur Franca, with several follow-up commits clarifying why e tags were discouraged as the primary inline reference mechanism.
Fiatjaf then refactored the NIP for simplicity while keeping the verbose example that shows how a user typing @mattn can produce a nostr:nprofile... link in the event content. Martin Dutra added NIP-21 links, and later commits removed old note1 references.
In February 2025, Vitor Pamplona updated the NIP to use q tags instead of older mention markers. That aligns NIP-27 with NIP-18's quote-reference behavior and reduces the chance that a cited event gets treated as a reply by accident.
Parsing references is where writing and reading clients meet
nostr-tools exposes a NIP-27 parser that yields text blocks, references, URLs, relay URLs, images, videos, audio, emoji and hashtags. go-nostr has a nip27 package with reference positions and pointers. 0xChat's Dart library lists NIP-27 support. These implementations show the same design pressure: rich rendering starts with parsing plain content safely.
Rust Nostr's support table is useful for contrast because it lists NIP-27 as not implemented while many adjacent NIPs are supported. That is a reminder that NIP-27 is largely a client-content parsing convention rather than a relay feature. Some SDKs keep it outside the core event model.
A strong client avoids naive search-and-replace. NIP-04's warning about not processing encrypted DMs like public text notes applies as a general caution: mention parsing belongs only where readable public content is actually meant to be augmented. Parsing every string as a social mention surface can leak metadata or create unwanted notifications.
Mentions can notify, cite or merely point - those are different acts
The biggest risk is collapsing different meanings. A reference can be a quote, a reply, a mention, a citation, a footnote or just a navigational link. If clients add tags automatically for every inline reference, they can notify people who were not meant to be notified or make cited events appear as replies.
The second risk is unsafe parsing. Content can contain malformed bech32, long strings, misleading text around links or references to events a client cannot fetch. A good NIP-27 renderer degrades gracefully: show the original text, parse known references, verify fetched events and avoid inventing meaning when the tags do not say it.
Read NIP-27 in the wild
NIP-27 explains references inside text notes. It helps clients turn embedded Nostr identifiers into links while keeping the connection to the underlying key, event or addressable object.
The user-facing benefit is continuity: a post can point to another profile, note or article without losing the cryptographic reference. The failure mode is visual lying, where the text suggests one object and the encoded reference points to another.
What changes when you actually use it
For you, NIP-27: Text Note References 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, kind 30023, draft, .content, nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg, nostr:npub1... 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-27: Text Note References is compatibility discipline. Implement kind 1, kind 30023, draft, .content, nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg, nostr:npub1... 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
The official file is organized around Example of a profile mention process, Verbose and probably unnecessary considerations. Inspect kind 1, kind 30023, draft, .content, nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg, nostr:npub1..., nevent1..., nostr:nevent1... because these are the pieces most likely to surface as product behavior. Read it beside NIP-21, NIP-18, NIP-19 before treating it as isolated.
NIP-27: Text Note References 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-27: Text Note References is often indirect. Nobody complains about kind 1, kind 30023, draft, .content, nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg, nostr:npub1...; 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-27: Text Note References 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, kind 30023, draft, .content, nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg, nostr:npub1... 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-27: Text Note References 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-21, NIP-18, NIP-19 to see where the base contract ends and the product-specific promise begins.
Language that keeps the feature honest
Good product copy for NIP-27: Text Note References 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-27: Text Note References 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-27: Text Note References with the visible product symptom, then trace it back to kind 1, kind 30023, draft, .content, nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg, nostr:npub1.... 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-27 mirror, NIP-21 nostr URI scheme, NIP-19 bech32 entities, NIP-18 quote tags. Use those links to move from the spec to live libraries, mirrors, pull requests, guides or products.
Official NIP-27 source is the anchor for exact wording, and NIP-27 commit history shows how that wording moved over time. The strongest secondary clues here are nips.nostr.com NIP-27 mirror, NIP-21 nostr URI scheme, NIP-19 bech32 entities. 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-27: Text Note References: first the human promise, then kind 1, kind 30023, draft, .content, nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg, nostr:npub1..., then the implementation record, then the real-world failure case. That order keeps NIP-27 useful without turning it into marketing copy or protocol trivia.
Three questions to carry forward
- Can two independent clients read the same
kind 1,kind 30023,draft,.contentwithout 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-21, NIP-18, NIP-19, changes the behavior once the base event leaves the happy path?
What to verify before you rely on it
- Find
kind 1,kind 30023,draft,.content,nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvgin the official file and check where the UI exposes the same concept. - Read NIP-21, NIP-18, NIP-19 as context before treating NIP-27 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-27: Text Note References in that order: Official NIP-27 source for the current wording; NIP-27 commit history for the change record; nips.nostr.com NIP-27 mirror, NIP-21 nostr URI scheme, NIP-19 bech32 entities 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.
