nostr/nips/12.md

NIP-12

Generic Tag Queries

draft optional author:scsibug

Relays may support subscriptions over arbitrary tags. NIP-01 requires relays to respond to queries for e and p tags. This NIP allows any 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 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 first element of a tag array with the initial # removed, 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 a foo tag set to either bar or baz.

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

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.

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 url tag and value.
• Location-specific Posts: clients can use a 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 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.