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-32 - Labeling — Nostr Instruction Manual</title>7<meta name="description" content="NIP-32: labeling. The L and l tags and kind 1985 label events for moderation, collections, licenses, and content classification. 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 32 - Moderation</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="32">32</div>48 <div class="titles">49 <div class="kicker">Nostr Implementation Possibility - Hex № 32</div>50 <h1>Labeling</h1>51 <p class="sub">A standard way to attach labels to events, people, relays, and topics — the raw material for moderation, collections, licenses, and classification.</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>Nostr has no central moderator. It also has no central catalog. This NIP gives any user a way to say something <em>about</em> something else. That statement is a <strong>label</strong>.</p>60 <p>The NIP defines two new indexable tags and one new event kind. The <code>L</code> tag names a label <strong>namespace</strong>. The <code>l</code> tag holds a label <strong>value</strong>. The <strong>kind 1985</strong> event attaches those labels to existing targets: events, pubkeys, relays, URLs, or topics.</p>61 <p>Labels support many use cases with one mechanism. Examples: distributed moderation, collection management, license assignment, and content classification. Clients decide which labelers to trust. The protocol only carries the labels.</p>6263 <div class="box hint">64 <span class="tag">Hint!</span>65 <p>Think of a label event as a sticky note. Anyone can write one and stick it on any event or profile. Reading clients choose whose sticky notes to display. Nobody can stick a note that others are forced to see.</p>66 </div>6768 <figure class="diagram">69 <div class="frame">70 <svg viewBox="0 0 560 210" role="img" aria-label="A kind 1985 label event points at five target types: event, pubkey, addressable event, relay or URL, and topic">71 <rect class="d-actor" x="10" y="80" width="150" height="54" rx="8"/>72 <text class="d-actor-label" x="85" y="103" text-anchor="middle">Label event</text>73 <text class="d-note" x="85" y="121" text-anchor="middle">kind 1985 + L/l tags</text>74 <rect class="d-actor" x="410" y="8" width="140" height="30" rx="6"/>75 <text class="d-actor-label" x="480" y="28" text-anchor="middle">e → event</text>76 <rect class="d-actor" x="410" y="48" width="140" height="30" rx="6"/>77 <text class="d-actor-label" x="480" y="68" text-anchor="middle">p → pubkey</text>78 <rect class="d-actor" x="410" y="88" width="140" height="30" rx="6"/>79 <text class="d-actor-label" x="480" y="108" text-anchor="middle">a → addressable</text>80 <rect class="d-actor" x="410" y="128" width="140" height="30" rx="6"/>81 <text class="d-actor-label" x="480" y="148" text-anchor="middle">r → relay / URL</text>82 <rect class="d-actor" x="410" y="168" width="140" height="30" rx="6"/>83 <text class="d-actor-label" x="480" y="188" text-anchor="middle">t → topic</text>84 <path class="d-msg d-flow" d="M162,92 C280,60 330,35 407,23"/>85 <path class="d-msg d-flow" d="M162,100 C280,85 330,70 407,63"/>86 <path class="d-msg d-flow" d="M162,107 L407,103"/>87 <path class="d-msg d-flow" d="M162,114 C280,130 330,140 407,143"/>88 <path class="d-msg d-flow" d="M162,122 C280,155 330,175 407,183"/>89 <text class="d-label" x="280" y="98" text-anchor="middle">labels</text>90 <circle r="4" fill="#f26a00">91 <animateMotion dur="2.6s" repeatCount="indefinite" path="M162,100 C280,85 330,70 407,63"/>92 </circle>93 </svg>94 </div>95 <figcaption>Fig. 32-1 — <b>One label, many target types.</b> A single kind 1985 event can point at one or more targets with <code>e</code>, <code>p</code>, <code>a</code>, <code>r</code>, or <code>t</code> tags.</figcaption>96 </figure>9798 <h2 class="bar" id="spec"><span class="num">2</span> The Label Event: Kind 1985</h2>99 <p>A label event is a regular event of <strong>kind 1985</strong> (see <a href="01.html">NIP-01</a> for storage classes). It carries three groups of data. The <code>L</code> tags declare namespaces. The <code>l</code> tags hold label values. The target tags point at the labeled objects.</p>100101 <div class="crt">102 <div class="titlebar">Wire format - label event</div>103<pre>{104 <span class="k">"kind"</span>: 1985,105 <span class="k">"tags"</span>: [106 [<span class="s">"L"</span>, <span class="c"><namespace></span>],107 [<span class="s">"l"</span>, <span class="c"><label value></span>, <span class="c"><namespace mark></span>],108 [<span class="s">"e"</span> | <span class="s">"p"</span> | <span class="s">"a"</span> | <span class="s">"r"</span> | <span class="s">"t"</span>, <span class="c"><target></span>, <span class="c"><relay hint, for e/p></span>]109 ],110 <span class="k">"content"</span>: <span class="c"><optional longer explanation></span>111 <span class="c">// other NIP-01 fields...</span>112}</pre>113 </div>114115 <div class="tscroll"><table class="ref">116 <caption>Tag reference</caption>117 <tr><th>Tag</th><th>Holds</th><th>Rule</th></tr>118 <tr><td class="btn">L</td><td>a label namespace</td><td>Any string. RECOMMENDED. Use a well-defined standard or reverse domain name notation.</td></tr>119 <tr><td class="btn">l</td><td>a label value</td><td>Any string. MUST carry a mark that matches an <code>L</code> tag in the same event, if one exists.</td></tr>120 <tr><td class="btn">e p a r t</td><td>the label target(s)</td><td>At least one target tag MUST be present in a kind 1985 event.</td></tr>121 </table></div>122123 <p>Both <code>L</code> and <code>l</code> are single-letter tags. Relays index them under the <a href="01.html">NIP-01</a> rules. Clients can query labels with the filter keys <code>{"#L": [<namespace>]}</code> and <code>{"#l": [<value>]}</code>.</p>124125 <h2 class="bar" id="namespace"><span class="num">3</span> The Namespace Tag: L</h2>126 <p>An <code>L</code> tag value can be any string. Publishers SHOULD make namespaces unambiguous. Use a well-defined namespace, such as an ISO standard. Or use reverse domain name notation, such as <code>com.example.ontology</code>.</p>127 <p><code>L</code> tags are RECOMMENDED. They let clients search by namespace instead of by one specific label. A query for <code>{"#L": ["com.example.ontology"]}</code> finds every label in that vocabulary.</p>128 <p>Two namespace values have special meaning:</p>129 <ul>130 <li><strong><code>ugc</code></strong> ("user generated content"): MAY be used when an end user typed the label content freehand.</li>131 <li><strong>Values that start with <code>#</code></strong>: the target should be associated with the label's value as a standard nostr tag. Example: <code>["L", "#t"]</code> attaches topic tags. This attaches standard tags to events, pubkeys, relays, URLs, and other objects.</li>132 </ul>133134 <h2 class="bar" id="label"><span class="num">4</span> The Label Tag: l</h2>135 <p>An <code>l</code> tag's value can be any string. The second element of the tag is the <strong>mark</strong>. The mark states which namespace the label belongs to.</p>136 <p>The mark rules are strict. Apply them in order:</p>137 <ol>138 <li>If the event has an <code>L</code> tag, each <code>l</code> tag MUST include a mark that matches one <code>L</code> tag value.</li>139 <li>If the event has no <code>L</code> tag, each <code>l</code> tag SHOULD still include a mark.</li>140 <li>If an <code>l</code> tag has no mark at all, the namespace <code>ugc</code> is implied.</li>141 </ol>142143 <figure class="diagram">144 <div class="frame">145 <svg viewBox="0 0 560 130" role="img" aria-label="The mark in an l tag must match the value of an L tag in the same event">146 <rect class="d-actor" x="20" y="20" width="240" height="36" rx="6"/>147 <text class="d-actor-label" x="140" y="43" text-anchor="middle">["L", "com.example.ontology"]</text>148 <rect class="d-actor" x="20" y="74" width="300" height="36" rx="6"/>149 <text class="d-actor-label" x="170" y="97" text-anchor="middle">["l", "VI-hum", "com.example.ontology"]</text>150 <path class="d-msg blue" d="M300,92 C400,92 420,60 268,42"/>151 <text class="d-label" x="420" y="80" text-anchor="middle">mark MUST match</text>152 <text class="d-note" x="420" y="110" text-anchor="middle">no mark → "ugc" implied</text>153 </svg>154 </div>155 <figcaption>Fig. 32-2 — <b>Namespace and mark.</b> The third element of the <code>l</code> tag points back at an <code>L</code> tag value in the same event.</figcaption>156 </figure>157158 <h2 class="bar" id="targets"><span class="num">5</span> Label Targets</h2>159 <p>A kind 1985 event MUST include one or more tags that represent the labeled object or objects. The allowed target tags are <code>e</code>, <code>p</code>, <code>a</code>, <code>r</code>, and <code>t</code>. As in <a href="01.html">NIP-01</a>, a relay hint SHOULD be included in <code>e</code> and <code>p</code> tags.</p>160 <div class="tscroll"><table class="ref">161 <caption>Target tags</caption>162 <tr><th>Tag</th><th>Target</th><th>Value</th></tr>163 <tr><td class="btn">e</td><td>an event</td><td>event id, plus a relay hint (SHOULD)</td></tr>164 <tr><td class="btn">p</td><td>a person</td><td>pubkey, plus a relay hint (SHOULD)</td></tr>165 <tr><td class="btn">a</td><td>an addressable event</td><td><code><kind>:<pubkey>:<d value></code> coordinate</td></tr>166 <tr><td class="btn">r</td><td>a relay or URL</td><td>the URL string</td></tr>167 <tr><td class="btn">t</td><td>a topic</td><td>the topic string</td></tr>168 </table></div>169 <div class="box tech">170 <span class="tag">Tech Note</span>171 <p>The source text lists five target tags but says they label "events, people, relays, or topics respectively" — only four purposes. The mapping of <code>a</code> (addressable events) and of URLs is left implicit. The table above restores the full mapping from the tags' NIP-01 meanings.</p>172 </div>173174 <h2 class="bar" id="content"><span class="num">6</span> Content and Self-Reporting</h2>175 <p><strong>Content.</strong> Labels should be short, meaningful strings. Put longer discussion in the event's <code>content</code> field. Example: the explanation of why a target was labeled a certain way.</p>176 <p><strong>Self-reporting.</strong> <code>l</code> and <code>L</code> tags MAY be added to event kinds other than 1985. For any event with a kind other than 1985, the labels refer to the event itself. The author labels their own content. See Example E below.</p>177178 <h2 class="bar" id="vocab"><span class="num">7</span> Vocabulary Guidelines</h2>179 <p><strong>Bulk labels and edits.</strong> One kind 1985 event may label many targets at once. To edit a bulk label, request deletion of the old event with <a href="09.html">NIP-09</a> and publish a replacement. The NIP deliberately does not use addressable or replaceable events here. Reason: no standard <code>d</code> tag scheme was simple enough.</p>180 <p><strong>One namespace per event.</strong> Publishers SHOULD limit a label event to a single namespace. This avoids ambiguity when querying.</p>181 <p><strong>Reuse before you invent.</strong> Before you create a vocabulary, explore existing designs for your use case. Imitate them when possible. Reverse domain name notation avoids namespace clashes. But all namespaces should be considered open for public use, not proprietary. If a namespace fits your use case, use it — even if it points to someone else's domain name.</p>182 <p><strong>Fully qualified labels.</strong> A vocabulary MAY qualify every label with its namespace, for example <code>["l", "com.example.vocabulary:my-label"]</code>. Prefer this for formal vocabularies that must not be confused with others when queried without an <code>L</code> tag. In such a vocabulary, all labels SHOULD include the namespace. Do not mix qualified and unqualified labels.</p>183 <div class="box warn">184 <span class="tag">Warning!</span>185 <p>Labels are categories, not values. A good heuristic: would the label ever be unique? Many events can share the label of a place, a topic, or a pubkey. But specific values like <code>"John Doe"</code> or <code>"3.18743"</code> are data, not labels. Handle them some other way.</p>186 </div>187 <p><strong>Known ontologies.</strong> The NIP appendix lists one non-exhaustive starting point in widespread use: the <a href="https://github.com/CLARIAH/awesome-humanities-ontologies">social ontology categories</a> collection.</p>188189 <h2 class="bar" id="examples"><span class="num">8</span> Worked Examples</h2>190 <p>The six events below restate every example from the source NIP. Placeholders in angle brackets stand for real hex values.</p>191192 <p><strong>Example A.</strong> A suggestion that multiple pubkeys be associated with the <code>permies</code> topic. The <code>#t</code> namespace attaches a standard topic tag to the two people.</p>193 <div class="crt">194 <div class="titlebar">Example A - topic label on two pubkeys</div>195<pre>{196 <span class="k">"kind"</span>: 1985,197 <span class="k">"tags"</span>: [198 [<span class="s">"L"</span>, <span class="s">"#t"</span>],199 [<span class="s">"l"</span>, <span class="s">"permies"</span>, <span class="s">"#t"</span>],200 [<span class="s">"p"</span>, <span class="c"><pubkey1></span>, <span class="c"><relay_url></span>],201 [<span class="s">"p"</span>, <span class="c"><pubkey2></span>, <span class="c"><relay_url></span>]202 ]203 <span class="c">// other fields...</span>204}</pre>205 </div>206207 <p><strong>Example B.</strong> A report that flags violence toward a human being, as defined by the ontology at <code>ontology.example.com</code>.</p>208 <div class="crt">209 <div class="titlebar">Example B - moderation report from a formal ontology</div>210<pre>{211 <span class="k">"kind"</span>: 1985,212 <span class="k">"tags"</span>: [213 [<span class="s">"L"</span>, <span class="s">"com.example.ontology"</span>],214 [<span class="s">"l"</span>, <span class="s">"VI-hum"</span>, <span class="s">"com.example.ontology"</span>],215 [<span class="s">"p"</span>, <span class="c"><pubkey1></span>, <span class="c"><relay_url></span>],216 [<span class="s">"p"</span>, <span class="c"><pubkey2></span>, <span class="c"><relay_url></span>]217 ]218 <span class="c">// other fields...</span>219}</pre>220 </div>221222 <p><strong>Example C.</strong> A moderation suggestion that approves a chat event from <a href="28.html">NIP-28</a> (a kind 40 channel).</p>223 <div class="crt">224 <div class="titlebar">Example C - chat moderation</div>225<pre>{226 <span class="k">"kind"</span>: 1985,227 <span class="k">"tags"</span>: [228 [<span class="s">"L"</span>, <span class="s">"nip28.moderation"</span>],229 [<span class="s">"l"</span>, <span class="s">"approve"</span>, <span class="s">"nip28.moderation"</span>],230 [<span class="s">"e"</span>, <span class="c"><kind40_event_id></span>, <span class="c"><relay_url></span>]231 ]232 <span class="c">// other fields...</span>233}</pre>234 </div>235236 <p><strong>Example D.</strong> Assignment of a license to an event.</p>237 <div class="crt">238 <div class="titlebar">Example D - license assignment</div>239<pre>{240 <span class="k">"kind"</span>: 1985,241 <span class="k">"tags"</span>: [242 [<span class="s">"L"</span>, <span class="s">"license"</span>],243 [<span class="s">"l"</span>, <span class="s">"MIT"</span>, <span class="s">"license"</span>],244 [<span class="s">"e"</span>, <span class="c"><event_id></span>, <span class="c"><relay_url></span>]245 ]246 <span class="c">// other fields...</span>247}</pre>248 </div>249250 <p><strong>Example E.</strong> Self-labeling. The author of this kind 1 note labels it as related to Milan, Italy, using ISO 3166-2. The labels sit on the note itself, not on a kind 1985 event.</p>251 <div class="crt">252 <div class="titlebar">Example E - self-label: location</div>253<pre>{254 <span class="k">"kind"</span>: 1,255 <span class="k">"tags"</span>: [256 [<span class="s">"L"</span>, <span class="s">"ISO-3166-2"</span>],257 [<span class="s">"l"</span>, <span class="s">"IT-MI"</span>, <span class="s">"ISO-3166-2"</span>]258 ],259 <span class="k">"content"</span>: <span class="s">"It's beautiful here in Milan!"</span>260 <span class="c">// other fields...</span>261}</pre>262 </div>263264 <p><strong>Example F.</strong> Self-labeling the note's language as English, using ISO-639-1.</p>265 <div class="crt">266 <div class="titlebar">Example F - self-label: language</div>267<pre>{268 <span class="k">"kind"</span>: 1,269 <span class="k">"tags"</span>: [270 [<span class="s">"L"</span>, <span class="s">"ISO-639-1"</span>],271 [<span class="s">"l"</span>, <span class="s">"en"</span>, <span class="s">"ISO-639-1"</span>]272 ],273 <span class="k">"content"</span>: <span class="s">"English text"</span>274 <span class="c">// other fields...</span>275}</pre>276 </div>277278 <p>Reading labels back is a normal <a href="01.html">NIP-01</a> query. The session below fetches all labels in one namespace, then all labels on one event.</p>279 <div class="crt">280 <div class="titlebar">Session transcript - querying labels</div>281<pre><span class="c">-- all labels in a namespace --</span>282<span class="send">→ ["REQ", "mods", {"kinds":[1985], "#L":["com.example.ontology"]}]</span>283<span class="recv">← ["EVENT", "mods", {"kind":1985, "tags":[["L","com.example.ontology"],284 ["l","VI-hum","com.example.ontology"], ["p","f7234bd4…"]], …}]</span>285<span class="recv">← ["EOSE", "mods"]</span>286287<span class="c">-- all labels attached to one event --</span>288<span class="send">→ ["REQ", "onevt", {"kinds":[1985], "#e":["5c83da77…"]}]</span>289<span class="recv">← ["EVENT", "onevt", {"kind":1985, "tags":[["L","license"],290 ["l","MIT","license"], ["e","5c83da77…"]], …}]</span>291<span class="recv">← ["EOSE", "onevt"]</span></pre>292 </div>293294 <h2 class="bar" id="history"><span class="num">9</span> Version History</h2>295 <p>NIP-32 grew out of Jonathan Staab's work on distributed moderation. It replaced an earlier, narrower reporting focus with a general labeling vocabulary. Notable changes, newest first:</p>296 <ul class="patchnotes">297 <li><span class="ver">2024</span><span class="when">2024-08</span>Updated the bulk-edit guidance to follow <a href="09.html">NIP-09</a>'s rename to "deletion request".</li>298 <li><span class="ver">2024</span><span class="when">2024-07</span>Added the ISO-639-1 language self-label example.</li>299 <li><span class="ver">2024</span><span class="when">2024-06</span>Strengthened the mark rules: <code>l</code> tags MUST match an <code>L</code> tag when one exists.</li>300 <li><span class="ver">2024</span><span class="when">2024-03</span>Relaxed <code>L</code> tag requirements from mandatory to RECOMMENDED; a missing mark now implies <code>ugc</code>.</li>301 <li><span class="ver">2023</span><span class="when">2023-11</span>Removed label annotations (JSON metadata on labels) to keep the spec lean; author lists dropped from all NIPs.</li>302 <li><span class="ver">2023</span><span class="when">2023-06</span>Dropped replaceable label events in favor of delete-and-republish; trimmed examples; <a href="36.html">NIP-36</a> pointed here.</li>303 <li class="minor"><span class="ver">2023</span><span class="when">2023-05</span>Added the <code>L</code> tag, self-labeling, <code>#</code>-prefixed namespaces, relay hints, and qualified-name guidance in a rapid series of revisions.</li>304 <li><span class="ver">Origin</span><span class="when">2023-05-15</span>Jonathan Staab published "Add NIP-32 for labeling things in nostr".</li>305 </ul>306307 <div class="credits">308 <h3 class="cardhead">Original Proposal - Credits</h3>309 <table>310 <tr><td>Author</td><td>Jonathan Staab</td></tr>311 <tr><td>First commit</td><td>2023-05-15 — “Add NIP-32 for labeling things in nostr”</td></tr>312 <tr><td>Status</td><td>draft - optional — implement it if your client reads or writes labels</td></tr>313 <tr><td>Source</td><td><a href="https://github.com/nostr-protocol/nips/blob/master/32.md">32.md on GitHub</a> - <a href="https://github.com/nostr-protocol/nips/commits/master/32.md">full change history</a></td></tr>314 </table>315 </div>316317 <h2 class="bar"><span class="num">10</span> See Also</h2>318 <ul>319 <li><a href="01.html">NIP-01</a> — the event format, single-letter tag indexing, and the <code>e</code>/<code>p</code>/<code>a</code> tags this NIP targets.</li>320 <li><a href="09.html">NIP-09</a> — deletion requests; the edit mechanism for bulk label events.</li>321 <li><a href="28.html">NIP-28</a> — public chat; the channel events moderated in Example C.</li>322 <li><a href="36.html">NIP-36</a> — sensitive content warnings; an early adopter that points to this labeling scheme.</li>323 <li><a href="56.html">NIP-56</a> — reporting; a narrower, fixed-vocabulary sibling for abuse reports.</li>324 </ul>325 </div>326327 <aside>328 <div class="cartridge">329 <div class="inner">330 <h3 class="cardhead">Spec Card</h3>331 <div class="lights"><span class="led on"></span><span class="led on"></span><span class="led on"></span></div>332 <dl>333 <dt>Status</dt><dd><span class="chip draft">draft</span><span class="chip">optional</span></dd>334 <dt>Defines</dt><dd>kind 1985 - L/l tags - #-prefixed namespaces - ugc</dd>335 <dt>Kind(s)</dt><dd>1985 (regular)</dd>336 <dt>Requires</dt><dd><a href="01.html">NIP-01</a></dd>337 <dt>Edits via</dt><dd><a href="09.html">NIP-09</a> deletion request</dd>338 <dt>First commit</dt><dd>2023-05-15</dd>339 <dt>Last updated</dt><dd>2026-06-13</dd>340 </dl>341 </div>342 </div>343 </aside>344 </main>345346 <nav class="navbtns">347 <a href="31.html">◀ NIP-31: Dealing with unknown event kinds</a>348 <a href="33.html">NIP-33: Parameterized Replaceable Events ▶</a>349 </nav>350351 <footer class="pagefoot">352 <a href="../index.html">Nostr Protocol Manual</a>353 <span class="pageno">NIP 32 / F4</span>354 </footer>355</div>356357<script src="../assets/webmcp.js" defer></script>358</body>359</html>