nips/32.md

NIP-32
======

Labeling
---------

`draft` `optional`

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
----

The label event MUST include one or more tags representing the object or objects being
labeled: `e`, `p`, `a`, `r`, or `t` tags. This allows for labeling of events, people, relays,
or topics respectively. As with NIP-01, a relay hint SHOULD be included when using `e` and
`p` tags.

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
--------------

A suggestion that multiple pubkeys be associated with the `permies` topic.

```json
{
  "kind": 1985,
  "tags": [
    ["L", "#t"],
    ["l", "permies", "#t"],
    ["p", <pubkey1>, <relay_url>],
    ["p", <pubkey2>, <relay_url>]
  ],
  ...
}
```

A report flagging violence toward a human being as defined by ontology.example.com.

```json
{
  "kind": 1985,
  "tags": [
    ["L", "com.example.ontology"],
    ["l", "VI-hum", "com.example.ontology"],
    ["p", <pubkey1>, <relay_url>],
    ["p", <pubkey2>, <relay_url>]
  ],
  ...
}
```

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", "ISO-3166-2"],
    ["l", "IT-MI", "ISO-3166-2"]
  ],
  "content": "It's beautiful here in Milan!",
  ...
}
```

Other Notes
-----------

When using this NIP to bulk-label many targets at once, events may be deleted and a replacement
may be published. We have opted not to use parameterizable/replaceable events for this due to the
complexity in coming up with a standard `d` tag. In order to avoid ambiguity when querying,
publishers SHOULD limit labeling events to a single namespace.

Before creating a vocabulary, explore how your use case may have already been designed and
imitate that design if possible. Reverse domain name notation is encouraged to avoid
namespace clashes, but for the sake of interoperability all namespaces should be
considered open for public use, and not proprietary. In other words, if there is a
namespace that fits your use case, use it even if it points to someone else's domain name.

Vocabularies MAY choose to fully qualify all labels within a namespace (for example,
`["l", "com.example.vocabulary:my-label"]`. This may be preferred when defining more
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.