Clarify NIP 32

32.md

@@ -6,7 +6,30 @@ Labeling
 
 `draft` `optional` `author:staab` `author:gruruya` `author:s3x-jay`
 
-A label is a `kind 1985` event that is used to label other entities. This supports a number of use cases, including distributed moderation, collection management, license assignment, and content classification.
+A label is a `kind 1985` event that is used to label other entities. This supports a number of use cases,
+including distributed moderation, collection management, license assignment, and content classification.
+
+This NIP introduces two new tags:
+
+- `L` denotes a label namespace
+- `l` denotes a label
+
+Label Namespace Tag
+----
+
+An `L` tag can be any string, but publishers SHOULD ensure they are unambiguous by using a well-defined namespace
+(such as an ISO standard) or reverse domain name notation.
+
+`L` tags are REQUIRED in order to support searching by namespace rather than by a specific tag. The special `ugc`
+("user generated content") namespace MAY be used when the label content is provided by an end user.
+
+`L` tags starting with `#` indicate that the label target should be associated with the label's value.
+This is a way of attaching standard nostr tags to events, pubkeys, relays, urls, etc.
+
+Label Tag
+----
+
+An `l` tag's value can be any string. `l` tags MUST include a `mark` matching an `L` tag value in the same event.
 
 Label Target
 ----
@@ -16,37 +39,18 @@ labeled: `e`, `p`, `a`, `r`, or `t` tags. This allows for labeling of events, pe
 or topics respectively. As with NIP-01, a relay hint SHOULD be included when using `e` and
 `p` tags.
 
-Label Tag
-----
-
-This NIP introduces a new tag `l` which denotes a label, and a new `L` tag which denotes a label namespace.
-A label MUST include a mark matching an `L` tag. `L` tags refer to a tag type within nostr, or a nomenclature
-external to nostr defined either formally or by convention. Any string can be a namespace, but publishers SHOULD
-ensure they are unambiguous by using a well-defined namespace (such as an ISO standard) or reverse domain name notation.
-
-Namespaces starting with `#` indicate that the label target should be associated with the label's value.
-This is a way of attaching standard nostr tags to events, pubkeys, relays, urls, etc.
-
-Some examples:
-
-- `["l", "footstr", "#t"]` - the publisher thinks the given entity should have the `footstr` topic applied.
-- `["l", "<pubkey>", "#p"]` - the publisher thinks the given entity is related to `<pubkey>`
-- `["l", "IT-MI", "ISO-3166-2"]` - Milano, Italy using ISO 3166-2.
-- `["l", "VI-hum", "com.example.ontology"]` - Violence toward a human being as defined by ontology.example.com.
-
-`L` tags containing the label namespaces MUST be included in order to support searching by
-namespace rather than by a specific tag. The special `ugc` ("user generated content") namespace
-MAY be used when the label content is provided by an end user.
-
-`l` and `L` tags MAY be added to other event kinds to support self-reporting. For events
-with a kind other than 1985, labels refer to the event itself.
-
 Content
 -------
 
 Labels should be short, meaningful strings. Longer discussions, such as for a review, or an
 explanation of why something was labeled the way it was, should go in the event's `content` field.
 
+Self-Reporting
+-------
+
+`l` and `L` tags MAY be added to other event kinds to support self-reporting. For events
+with a kind other than 1985, labels refer to the event itself.
+
 Example events
 --------------
 
@@ -60,39 +64,61 @@ A suggestion that multiple pubkeys be associated with the `permies` topic.
     ["l", "permies", "#t"],
     ["p", <pubkey1>, <relay_url>],
     ["p", <pubkey2>, <relay_url>]
-  ],
+  ]
-  "content": "",
-  ...
 }
 ```
 
-A review of a relay.
+A report flagging violence toward a human being as defined by ontology.example.com.
 
 ```json
 {
   "kind": 1985,
   "tags": [
     ["L", "com.example.ontology"],
-    ["l", "relay/review", "com.example.ontology"],
+    ["l", "VI-hum", "com.example.ontology"],
-    ["r", <relay_url>],
+    ["p", <pubkey1>, <relay_url>],
-    ["rating", "0.1"]
+    ["p", <pubkey2>, <relay_url>]
-  ],
+  ]
-  "content": "This relay is full of mean people.",
-  ...
 }
 ```
 
-Publishers can self-label by adding `l` tags to their own non-1985 events.
+A moderation suggestion for a chat event.
+
+```json
+{
+  "kind": 1985,
+  "tags": [
+    ["L", "nip28.moderation"],
+    ["l", "approve", "nip28.moderation"],
+    ["e", <kind40_event_id>, <relay_url>]
+  ],
+}
+```
+
+Assignment of a license to an event.
+
+```json
+{
+  "kind": 1985,
+  "tags": [
+    ["L", "license"],
+    ["l", "MIT", "license"],
+    ["e", <event_id>, <relay_url>]
+  ],
+}
+```
+
+Publishers can self-label by adding `l` tags to their own non-1985 events. In this case, the kind 1 event's author
+is labeling their note as being related to Milan, Italy using ISO 3166-2.
 
 ```json
 {
   "kind": 1,
   "tags": [
-    ["L", "com.example.ontology"],
+    ["L", "ISO-3166-2"],
-    ["l", "IL-frd", "com.example.ontology"]
+    ["l", "IT-MI", "ISO-3166-2"]
   ],
-  "content": "Send me 100 sats and I'll send you 200 back",
+  "content": "It's beautiful here in Milan!",
-  ...
 }
 ```
 
@@ -115,3 +141,8 @@ Vocabularies MAY choose to fully qualify all labels within a namespace (for exam
 formal vocabularies that should not be confused with another namespace when querying
 without an `L` tag. For these vocabularies, all labels SHOULD include the namespace
 (rather than mixing qualified and unqualified labels).
+
+A good heuristic for whether a use case fits this NIP is whether labels would ever be unique.
+For example, many events might be labeled with a particular place, topic, or pubkey, but labels
+with specific values like "John Doe" or "3.18743" are not labels, they are values, and should
+be handled in some other way.