12<html lang="en">3<head>4<meta charset="utf-8">5<meta name="viewport" content="width=device-width, initial-scale=1">6<title>NIP-27 - Text Note References — Nostr Instruction Manual</title>7<meta name="description" content="NIP-27: inline references to profiles and events inside note text. nostr: URIs, optional q and p tags, and reader-side rendering. Complete manual page.">8<link rel="preload" href="../assets/fonts/michroma-400-latin.woff2" as="font" type="font/woff2" crossorigin>9<link rel="preload" href="../assets/fonts/exo2-var-latin.woff2" as="font" type="font/woff2" crossorigin>10<link rel="preload" href="../assets/fonts/sairacondensed-600-latin.woff2" as="font" type="font/woff2" crossorigin>11<link rel="preload" href="../assets/fonts/sairacondensed-700-latin.woff2" as="font" type="font/woff2" crossorigin>12<link rel="preload" href="../assets/fonts/sairacondensed-500-latin.woff2" as="font" type="font/woff2" crossorigin>13<link rel="preload" href="../assets/fonts/sharetechmono-400-latin.woff2" as="font" type="font/woff2" crossorigin>14<link rel="preload" href="../assets/fonts/exo2-400i-latin.woff2" as="font" type="font/woff2" crossorigin>15<link rel="icon" href="../assets/favicon.svg" type="image/svg+xml">16<link rel="stylesheet" href="../assets/manual.css">17</head>18<body>1920<svg width="0" height="0" style="position:absolute">21 <defs>22 <marker id="arr" markerWidth="9" markerHeight="9" refX="7" refY="4.5" orient="auto">23 <path d="M1,1 L8,4.5 L1,8 Z" fill="#f26a00"/>24 </marker>25 <marker id="arrb" markerWidth="9" markerHeight="9" refX="7" refY="4.5" orient="auto">26 <path d="M1,1 L8,4.5 L1,8 Z" fill="#2e5f9e"/>27 </marker>28 </defs>29</svg>3031<div class="page">32 <span class="staple s1"></span><span class="staple s2"></span>3334 <header class="band">35 <a class="logo" href="../index.html">NOSTR<b>▸</b>PROTOCOL MANUAL</a>36 <span class="booklet-note">Chapter 27 - Social</span>37 </header>38 <nav class="tabs">39 <a href="../index.html">Contents</a>40 <a href="#overview" class="on">Overview</a>41 <a href="#spec">Spec</a>42 <a href="#examples">Examples</a>43 <a href="#history">History</a>44 </nav>4546 <div class="chapter">47 <div class="nipno" data-n="27">27</div>48 <div class="titles">49 <div class="kicker">Nostr Implementation Possibility - Hex № 27</div>50 <h1>Text Note References</h1>51 <p class="sub">How a client embeds mentions of profiles and events inside note text, and how a reader client turns them back into links.</p>52 </div>53 </div>5455 <main class="spread">56 <div class="main">5758 <h2 class="bar" id="overview"><span class="num">1</span> Overview</h2>59 <p>Users mention other users and other posts all the time. A mention must survive as plain text, yet render as a rich link. This NIP standardizes how clients treat inline references to other events and profiles inside the <code>content</code> field.</p>60 <p>The rule applies to any event whose <code>content</code> holds readable text. The main cases are <code>kind:1</code> text notes (<a href="10.html">NIP-10</a>) and <code>kind:30023</code> long-form articles (<a href="23.html">NIP-23</a>).</p>61 <p>The convention is simple. The writing client puts a <a href="21.html">NIP-21</a> <code>nostr:</code> URI in the middle of the text, such as <code>nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg</code>. The reading client finds the URI, decodes it, and renders whatever it wants: a name, a link, a preview, or nothing.</p>6263 <div class="box hint">64 <span class="tag">Hint!</span>65 <p>This NIP defines no new kind, tag, or message. It is a convention for the <code>content</code> string. The codes themselves come from <a href="19.html">NIP-19</a>; the <code>nostr:</code> prefix comes from <a href="21.html">NIP-21</a>.</p>66 </div>6768 <h2 class="bar" id="spec"><span class="num">2</span> Writing Mentions</h2>69 <p>When a client creates an event, it should encode each mention of a profile or an event as a <a href="21.html">NIP-21</a> code. Place the code inline, in the middle of the <code>content</code>, where the mention belongs.</p>7071 <div class="tscroll"><table class="ref">72 <caption>Inline reference codes (from <a href="19.html">NIP-19</a> / <a href="21.html">NIP-21</a>)</caption>73 <tr><th>Code</th><th>Refers to</th><th>Carries</th></tr>74 <tr><td class="btn">nostr:npub1…</td><td>a profile</td><td>public key only</td></tr>75 <tr><td class="btn">nostr:nprofile1…</td><td>a profile</td><td>public key + optional relay hints</td></tr>76 <tr><td class="btn">nostr:nevent1…</td><td>an event</td><td>event id + optional relay hints and author</td></tr>77 <tr><td class="btn">nostr:naddr1…</td><td>an addressable event</td><td>kind, pubkey, <code>d</code> value + relay hints</td></tr>78 </table></div>7980 <figure class="diagram">81 <div class="frame">82 <svg viewBox="0 0 560 120" role="img" aria-label="Typed text passes through autocomplete and encoding, then is published with an inline nostr URI and an optional tag">83 <rect class="d-actor" x="10" y="35" width="115" height="50" rx="8"/>84 <text class="d-actor-label" x="67" y="57" text-anchor="middle">Compose</text>85 <text class="d-note" x="67" y="74" text-anchor="middle">"hello @mat"</text>86 <rect class="d-actor" x="160" y="35" width="115" height="50" rx="8"/>87 <text class="d-actor-label" x="217" y="57" text-anchor="middle">Autocomplete</text>88 <text class="d-note" x="217" y="74" text-anchor="middle">pick a profile</text>89 <rect class="d-actor" x="310" y="35" width="115" height="50" rx="8"/>90 <text class="d-actor-label" x="367" y="57" text-anchor="middle">Encode</text>91 <text class="d-note" x="367" y="74" text-anchor="middle">nostr:nprofile1…</text>92 <rect class="d-actor" x="460" y="35" width="90" height="50" rx="8"/>93 <text class="d-actor-label" x="505" y="57" text-anchor="middle">Publish</text>94 <text class="d-note" x="505" y="74" text-anchor="middle">+ p / q tag</text>95 <path class="d-msg d-flow" d="M127,60 L157,60"/>96 <path class="d-msg d-flow" d="M277,60 L307,60"/>97 <path class="d-msg d-flow" d="M427,60 L457,60"/>98 <circle r="4" fill="#f26a00">99 <animateMotion dur="2.6s" repeatCount="indefinite" path="M127,60 L457,60"/>100 </circle>101 </svg>102 </div>103 <figcaption>Fig. 27-1 — <b>Writer pipeline.</b> The mention becomes an inline <code>nostr:</code> URI in <code>content</code>, plus optional tags.</figcaption>104 </figure>105106 <h2 class="bar" id="tags"><span class="num">3</span> Optional Reference Tags</h2>107 <p>Tags for the referenced things are optional. For each event reference, the client may add a <a href="18.html">NIP-18</a> quote tag:</p>108109 <div class="crt">110 <div class="titlebar">Quote tag - from NIP-18</div>111<pre>[<span class="s">"q"</span>, <span class="c"><event-id or event-address></span>, <span class="c"><relay-url></span>, <span class="c"><pubkey-if-a-regular-event></span>]</pre>112 </div>113114 <p>Add the tag when you want the mentioned profile to receive a notification. Add it also when you want the referenced event to count your mention as a reply. Omit it otherwise.</p>115 <p>The same choice exists for profile mentions. A client can add a <code>["p", …]</code> tag for a mentioned pubkey, as in the example in §5. A user who wants to mention someone <em>without</em> notifying them can tell the client to skip the <code>p</code> tag. The inline link still works.</p>116 <p>Likewise for events: a user can reference a note without joining its reply thread. The client then omits the corresponding <code>["e", …]</code> tag for that <code>nostr:nevent1…</code> URI. Clients may expose these choices to users, or stay opinionated and decide alone.</p>117118 <div class="box tech">119 <span class="tag">Tech Note</span>120 <p>Two rough edges in the source text. First: it says to add <code>q</code> tags "whenever they want the profile being mentioned to be notified", but a <code>q</code> tag carries an event reference; the spec's own example notifies a profile with a <code>p</code> tag. Second: a 2025 change replaced mention markers with <code>q</code> tags, yet the considerations section still tells clients to omit an <code>["e", …]</code> tag for an unwanted event reference. Read <code>q</code>, <code>e</code>, and <code>p</code> here as "the matching reference tag".</p>121 </div>122123 <h2 class="bar" id="reading"><span class="num">4</span> Reading Mentions</h2>124 <p>A reader client receives an event with <code>nostr:…</code> URIs in its <code>content</code>. It may first display the raw text as it is. Then it parses the text and augments each reference with any context it wants. Typical steps:</p>125 <ol>126 <li>Find each <code>nostr:</code> URI in the <code>content</code>.</li>127 <li>Decode the <a href="19.html">NIP-19</a> code. Extract the public key or event id, and any relay hints.</li>128 <li>Fetch the profile or event from a local database or from relays.</li>129 <li>Replace the URI with a display form: a highlighted <code>@name</code>, a link, or a preview box.</li>130 </ol>131 <p>When a client turns a mention into a link, it picks the target itself. The link can be an internal page of the client, a <a href="21.html">NIP-21</a> <code>nostr:</code> link, or a direct link to a web client that handles the reference.</p>132133 <figure class="diagram">134 <div class="frame">135 <svg viewBox="0 0 560 130" role="img" aria-label="Reader client parses content, decodes the nostr URI, fetches the profile, and renders a mention link">136 <rect class="d-actor" x="10" y="40" width="98" height="50" rx="8"/>137 <text class="d-actor-label" x="59" y="62" text-anchor="middle">Content</text>138 <text class="d-note" x="59" y="79" text-anchor="middle">raw text</text>139 <rect class="d-actor" x="148" y="40" width="98" height="50" rx="8"/>140 <text class="d-actor-label" x="197" y="62" text-anchor="middle">Parse</text>141 <text class="d-note" x="197" y="79" text-anchor="middle">find nostr: URIs</text>142 <rect class="d-actor" x="286" y="40" width="98" height="50" rx="8"/>143 <text class="d-actor-label" x="335" y="62" text-anchor="middle">Decode</text>144 <text class="d-note" x="335" y="79" text-anchor="middle">key + hints</text>145 <rect class="d-actor" x="424" y="40" width="60" height="50" rx="8"/>146 <text class="d-actor-label" x="454" y="62" text-anchor="middle">Fetch</text>147 <text class="d-note" x="454" y="79" text-anchor="middle">db / relays</text>148 <rect class="d-actor" x="498" y="40" width="52" height="50" rx="8"/>149 <text class="d-actor-label" x="524" y="62" text-anchor="middle">Show</text>150 <text class="d-note" x="524" y="79" text-anchor="middle">@mattn</text>151 <path class="d-msg blue d-flow" d="M110,65 L145,65"/>152 <path class="d-msg blue d-flow" d="M248,65 L283,65"/>153 <path class="d-msg blue d-flow" d="M386,65 L421,65"/>154 <circle r="4" fill="#2e5f9e">155 <animateMotion dur="2.6s" repeatCount="indefinite" path="M110,65 L421,65"/>156 </circle>157 </svg>158 </div>159 <figcaption>Fig. 27-2 — <b>Reader pipeline.</b> The client decodes the inline URI and swaps it for a friendly link.</figcaption>160 </figure>161162 <h2 class="bar" id="examples"><span class="num">5</span> Worked Example: a Profile Mention</h2>163 <p>Bob writes a note in a client with search-and-autocomplete for users. The character <code>@</code> triggers it. Bob types <code>"hello @mat"</code>. The client offers mattn's profile, with a picture and a name. Bob presses enter. He now sees <code>"hello @mattn"</code>, and <code>@mattn</code> is highlighted as a mention. Internally, the event looks like this:</p>164165 <div class="crt">166 <div class="titlebar">Published event - kind 1 with an inline profile mention</div>167<pre>{168 <span class="k">"content"</span>: <span class="s">"hello nostr:nprofile1qqszclxx9f5haga8sfjjrulaxncvkfekj097t6f3pu65f86rvg49ehqj6f9dh"</span>,169 <span class="k">"created_at"</span>: 1679790774,170 <span class="k">"id"</span>: <span class="s">"f39e9b451a73d62abc5016cffdd294b1a904e2f34536a208874fe5e22bbd47cf"</span>,171 <span class="k">"kind"</span>: 1,172 <span class="k">"pubkey"</span>: <span class="s">"79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798"</span>,173 <span class="k">"sig"</span>: <span class="s">"f8c8bab1b90cc3d2ae1ad999e6af8af449ad8bb4edf64807386493163e29162b5852a796a8f474d6b1001cddbaac0de4392838574f5366f03cc94cf5dfb43f4d"</span>,174 <span class="k">"tags"</span>: [175 [176 <span class="s">"p"</span>,177 <span class="s">"2c7cc62a697ea3a7826521f3fd34f0cb273693cbe5e9310f35449f43622a5cdc"</span>178 ]179 ]180}</pre>181 </div>182183 <p>The mention could also be a <code>nostr:npub1…</code> URI instead. That form carries the public key alone, with no relay hints.</p>184 <p>Bob publishes the event. Carol's client receives it. It first displays the <code>content</code> as raw text. Later it parses the text and finds the <code>nostr:</code> URI. It decodes the URI, extracts the public key and any relay hints, and fetches the profile from its database or from relays. Then it replaces the full URI with the name <code>@mattn</code>, linked to its internal page view for that profile.</p>185186 <h2 class="bar" id="notes"><span class="num">6</span> Implementation Notes</h2>187 <p>The spec calls these "verbose and probably unnecessary considerations". They give clients room to differ:</p>188 <ul>189 <li>No client must implement the flow above. A client without autocomplete can let users paste raw <a href="19.html">NIP-19</a> codes into the text. It then prefixes each code with <code>nostr:</code> before it publishes the event.</li>190 <li>Event references work the same way. A user pastes a <code>nevent1…</code> code; the client turns it into a <code>nostr:nevent1…</code> URI. A reader client may then show the referenced note in a preview box — or show nothing at all.</li>191 <li>A client can pick other display procedures. A <code>kind:1</code>-only client that meets a <a href="23.html"><code>kind:30023</code></a> <code>nostr:naddr1…</code> reference can render it as a link to some hardcoded web app that displays such events.</li>192 <li>Clients may let the user include or skip tags per mention. Mention <code>mattn</code> without a <code>["p", …]</code> tag and no notification fires, but the link still augments.</li>193 <li>Reference a note without the matching <code>["e", …]</code> tag and the reference stays out of that note's reply thread. Clients may expose these advanced choices, or stay opinionated.</li>194 </ul>195196 <div class="box warn">197 <span class="tag">Warning!</span>198 <p>Always ship the full <code>nostr:</code> URI in <code>content</code>, never a bare <code>@name</code>. Names are not unique and readers cannot resolve them. The URI is the mention; the pretty name is only a rendering.</p>199 </div>200201 <h2 class="bar" id="history"><span class="num">7</span> Version History</h2>202 <p>The number 27 has lived two lives. Its first occupant was an unrelated "Multicasting" draft in 2022. The current spec arrived in 2023. Notable changes, newest first:</p>203 <ul class="patchnotes">204 <li><span class="ver">2026</span><span class="when">2026-03</span>Removed the references to <code>note1</code> codes. Event mentions now point to <code>nevent</code> and <code>naddr</code> forms, which carry relay hints.</li>205 <li><span class="ver">2025</span><span class="when">2025-02</span>Replaced the old "mention" markers with <a href="18.html">NIP-18</a> <code>q</code> tags for event references.</li>206 <li class="minor"><span class="ver">2023-24</span><span class="when">2023-2024</span>Link and typo fixes: NIP-21 links added, broken profile link repaired via njump, NIP author lists removed repo-wide.</li>207 <li><span class="ver">2023</span><span class="when">2023-03-25</span>fiatjaf refactored the spec for simplicity and added the worked example plus the considerations list.</li>208 <li><span class="ver">2023</span><span class="when">2023-03-21</span>arthurfranca rewrote number 27 as "Text Note References", an alternative to putting mention markers in tags.</li>209 <li><span class="ver">Origin</span><span class="when">2022-08-16</span>Ricardo Arturo Cabral Mejía proposed "NIP-27 Multicasting" under this number. It was removed the same day; the number was later reused.</li>210 </ul>211212 <div class="credits">213 <h3 class="cardhead">Original Proposal - Credits</h3>214 <table>215 <tr><td>Author</td><td>arthurfranca (current spec, 2023); the number was first used by Ricardo Arturo Cabral Mejía</td></tr>216 <tr><td>First commit</td><td>2022-08-16 — “NIP-27 Multicasting” (removed the same day; the current spec dates from 2023-03-21)</td></tr>217 <tr><td>Status</td><td>draft - optional — a content convention, safe to adopt incrementally</td></tr>218 <tr><td>Source</td><td><a href="https://github.com/nostr-protocol/nips/blob/master/27.md">27.md on GitHub</a> - <a href="https://github.com/nostr-protocol/nips/commits/master/27.md">full change history</a></td></tr>219 </table>220 </div>221222 <h2 class="bar"><span class="num">8</span> See Also</h2>223 <ul>224 <li><a href="01.html">NIP-01</a> — the base event format and the <code>e</code>/<code>p</code> tags referenced here.</li>225 <li><a href="19.html">NIP-19</a> — the bech32 codes (<code>npub</code>, <code>nprofile</code>, <code>nevent</code>, <code>naddr</code>) that mentions embed.</li>226 <li><a href="21.html">NIP-21</a> — the <code>nostr:</code> URI scheme that wraps those codes.</li>227 <li><a href="18.html">NIP-18</a> — reposts and the <code>q</code> quote tag used for event references.</li>228 <li><a href="10.html">NIP-10</a> — <code>kind:1</code> notes and reply threading, where mention tags matter most.</li>229 <li><a href="23.html">NIP-23</a> — <code>kind:30023</code> long-form content, the other main home for inline references.</li>230 </ul>231 </div>232233 <aside>234 <div class="cartridge">235 <div class="inner">236 <h3 class="cardhead">Spec Card</h3>237 <div class="lights"><span class="led on"></span><span class="led on"></span><span class="led on"></span></div>238 <dl>239 <dt>Status</dt><dd><span class="chip draft">draft</span><span class="chip optional">optional</span></dd>240 <dt>Defines</dt><dd>inline <code>nostr:</code> mention convention for <code>content</code></dd>241 <dt>Kinds</dt><dd>none new — applies to kind 1, kind 30023, any readable text</dd>242 <dt>Requires</dt><dd><a href="01.html">NIP-01</a> - <a href="19.html">NIP-19</a> - <a href="21.html">NIP-21</a></dd>243 <dt>Optional</dt><dd><a href="18.html">NIP-18</a> <code>q</code> tags</dd>244 <dt>First commit</dt><dd>2022-08-16</dd>245 <dt>Last updated</dt><dd>2026-03-20</dd>246 </dl>247 </div>248 </div>249 </aside>250 </main>251252 <nav class="navbtns">253 <a href="26.html">◀ NIP-26: Delegated Event Signing</a>254 <a href="28.html">NIP-28: Public Chat ▶</a>255 </nav>256257 <footer class="pagefoot">258 <a href="../index.html">Nostr Protocol Manual</a>259 <span class="pageno">NIP 27 / F4</span>260 </footer>261</div>262263<script src="../assets/webmcp.js" defer></script>264</body>265</html>