NIP-12

Generic Tag Queries

draft optional author:scsibug author:fiatjaf

Relays may support subscriptions over arbitrary tags. NIP-01 requires relays to respond to queries for e and p tags. This NIP allows any single-letter tag present in an event to be queried.

The <filters> object described in NIP-01 is expanded to contain arbitrary keys with a # prefix. Any single-letter key in a filter beginning with # is a tag query, and MUST have a value of an array of strings. The filter condition matches if the event has a tag with the same name, and there is at least one tag value in common with the filter and event. The tag name is the letter without the #, and the tag value is the second element. Subsequent elements are ignored for the purposes of tag queries.

Example Subscription Filter

The following provides an example of a filter that matches events of kind 1 with an r tag set to either foo or bar.

{
  "kinds": [1],
  "#r": ["foo", "bar"]
}

Client Behavior

Clients SHOULD use the supported_nips field to learn if a relay supports generic tag queries. Clients MAY send generic tag queries to any relay, if they are prepared to filter out extraneous responses from relays that do not support this NIP.

Rationale

The decision to reserve only single-letter tags to be usable in queries allow applications to make use of tags for all sorts of metadata, as it is their main purpose, without worrying that they might be bloating relay indexes. That also makes relays more lightweight, of course. And if some application or user is abusing single-letter tags with the intention of bloating relays that becomes easier to detect as single-letter tags will hardly be confused with some actually meaningful metadata some application really wanted to attach to the event with no spammy intentions.

Suggested Use Cases

Motivating examples for generic tag queries are provided below. This NIP does not promote or standardize the use of any specific tag for any purpose.

• Decentralized Commenting System: clients can comment on arbitrary web pages, and easily search for other comments, by using a r (“reference”, in this case an URL) tag and value.
• Location-specific Posts: clients can use a g (“geohash”) tag to associate a post with a physical location. Clients can search for a set of geohashes of varying precisions near them to find local content.
• Hashtags: clients can use simple t (“hashtag”) tags to associate an event with an easily searchable topic name. Since Nostr events themselves are not searchable through the protocol, this provides a mechanism for user-driven search.

---

Source: nostr-protocol/nips/12.md version: 3771186 2022-07-10T15:32:55-03:00