nips/50.md

NIP-50

Keywords Filter

draft optional author:brugeman author:mikedilger

Abstract

Many Nostr use cases require some form of search by content field. The meaning and format of content differs with event kind and use case. Thus, this NIP only establishes a general framework for search over content, and specifies the details for kind 0 and kind 1 events.

keywords filter field

A new keywords field is introduced for REQ messages from clients:

{
  "kinds": <an array of kind numbers>
  "keywords": <an array of strings>
}

A filter with keywords field MUST also include kinds field. This NIP specifies the behavior for kinds 0 and 1, if none of these kinds are provided along with keywords, relay SHOULD ignore the filter, and MAY send a NOTICE to inform the client. Future NIPs will specify behavior for other event kinds.

A filter matches if one of the provided keywords matches. Each keyword string may contain several conditions - words, all the words must match for a keyword to match. The meaning of words depends on event kind.

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

Clients SHOULD query several relays supporting this NIP and specific kind to compensate for potentially different implementation details between relays (like string sanitization, etc).

Clients SHOULD verify that events returned by a relay match the specified keywords in the way that suits the client's use case, and MAY stop querying relays that have low precision.

Keyword search for kind 0 and kind 1

For kind 0 and kind 1, each keyword is a lowercase string consisting of words separated by spaces (in most languages), punctuation/control characters are ignored.

For kind 1, an event must include all words in it's content field for it to match the keyword.

For kind 0, an event must include all mentioned words in the json object stored at the content field. Recommended json fields for matching are about, display_name, name, nip05, lud06 and lud18.

A keyword may contain a word starting with prefix option: (like option:no_spam), such words specify additional constraints for event matching, and are reserved for the future extensions. Relay SHOULD ignore option: words that it does not support.

Relay MAY support these options for kind 0 and kind 1 events:

• option:no_spam - only include events deemed 'high-quality' by whatever internal metric the relay adopts