nips/12.md
2022-05-01 07:48:57 -03:00

39 lines
2.1 KiB
Markdown

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.