NIP-12: Generic Tag Queries
Relays needed more than author and kind filters
NIP-12 looks almost empty today because its substance moved into NIP-01. That does not make it unimportant. Generic tag queries are one of the quiet mechanics that let Nostr feel searchable, threaded and connected instead of being a firehose of signed objects.
A Nostr event can carry tags: event references, pubkey references, addressable coordinates, hashtags, labels and many application-specific signals. Without a shared query rule, relays could store those tags but clients would have no portable way to ask for events that mention a person, point at an event, use a topic tag or reference an addressable object.
NIP-12 was the original place for that rule. It later became basic enough to belong in NIP-01: all single-letter tag names are expected to be indexed by relays, and clients can query them through filter keys such as #e, #p, #a or #t. That one convention powers replies, quotes, mentions, hashtags, lists, comments, zaps and a lot of product glue.
A small query rule with large consequences
The current NIP-01 text says all single-letter English alphabet tag keys are expected to be indexed by relays. The client can send a filter containing a property like #e with one or more values. The relay returns events where an e tag has a matching first value. The same idea works for any single-letter tag that a NIP or app uses.
Only the first value in a tag is indexed. That matters because many tags carry extra fields: relay hints, markers, pubkeys, labels or other metadata. The indexed key is the first real target value. A tag such as ["e", "event-id", "relay-url", "reply"] is searchable by the event ID, not by the relay hint or marker.
The single-letter limit is a relay economics choice. If every arbitrary tag name had to be indexed by every relay, the storage and query burden would grow fast. NIP-12 drew a line: give the network a predictable general query primitive, but keep indexing bounded enough for relay authors to implement.
A small NIP that disappeared into the foundation
The visible file history starts with fiatjaf migrating the NIPs in May 2022. In July 2022, the text was changed so only single-letter tags were indexed. In July 2023, jiftechnify clarified case sensitivity around tag names, a reminder that tiny differences in filters can create large interoperability bugs.
In August 2023, PR #703 merged NIP-12, NIP-16, NIP-20 and NIP-33 material into NIP-01. The reason is easy to see from your perspective: generic tag queries are not an optional product feature. They are part of how the base client-relay language works.
The archived file now says only 'Moved to NIP-01.' This page exists so people understand what moved. If someone is debugging why #t hashtag search works on one relay but not another, or why a reply lookup uses #e, they are reading the afterlife of NIP-12.
Where people feel NIP-12 without seeing it
A normal user does not think about generic tag queries. They click a hashtag, open replies to a note, view zaps on an event, follow quote posts or fetch comments under an article. Behind those flows, clients send tag filters and relays need indexes that can answer them.
The implementation burden lives mostly with relays and client libraries. Relays have to index the first value of single-letter tags. Clients have to build filters correctly and know which tags belong to which product behavior. Libraries such as rust-nostr, go-nostr and nostr-tools inherit this as part of the base event and filter model rather than a separate feature module.
The mistake to avoid is treating tag queries like full-text search. NIP-12 is structured lookup, not search relevance. It asks for exact tag values. Search by words, ranking or fuzzy matching belongs elsewhere, especially NIP-50.
Indexing is a promise relays can quietly fail
The risk is invisible disagreement. A relay can store an event and still fail to index the tag a client relies on. The user experiences that as missing replies, incomplete hashtag pages or broken references, even though the event exists.
Another risk is overloading tags. Because single-letter tags are powerful, NIP authors can be tempted to squeeze too much meaning into small keys. The more meanings a tag carries, the more careful clients have to be about kind-specific interpretation.
Read NIP-12 in the wild
NIP-12 is archived because its core idea moved into NIP-01: relays can index generic tag queries. That sounds technical, but it is why clients can ask for events by tags instead of downloading the world and filtering locally.
Read it as protocol history. Tag queries became too fundamental to live as a side note, and that move explains why event tags are not decorative metadata. They are part of how the network is searched.
What changes when you actually use it
For you, NIP-12: Generic Tag Queries is felt when an app either behaves predictably or suddenly loses context. The visible symptom may be a missing reply, a broken link, a strange reaction count, an empty result or a relay error that looks like the whole network failed. The official terms the event kind, tags, content field, relay behavior and signature path are where that visible behavior begins, so the source is not background material; it is the place where the product promise gets its limits.
What changes for builders and operators
For builders, NIP-12: Generic Tag Queries is compatibility discipline. Implement the event kind, tags, content field, relay behavior and signature path against more than one relay and more than one library, then test malformed, missing and duplicated data. Core standards fail most painfully when the happy path looks fine and the second client exposes the shortcut.
What the official file makes concrete
Read it beside NIP-01 before treating it as isolated.
NIP-12: Generic Tag Queries is a shared contract between independent software. The smallest field can become user-visible when two clients disagree about it.
Where it breaks
The failure mode in NIP-12: Generic Tag Queries is often indirect. Nobody complains about the event kind, tags, content field, relay behavior and signature path; they complain that the feed is wrong, the reply vanished or the relay behaved strangely. Use the official file to diagnose the hidden cause instead of patching only the visual symptom.
Where this appears outside the markdown
In the ecosystem, NIP-12: Generic Tag Queries is not something most people choose directly. It is the invisible grammar behind clients, relays, crawlers, search tools and archives. When a product team treats the event kind, tags, content field, relay behavior and signature path as implementation detail only, the mistake eventually reaches the surface as missing history, bad threading or state that cannot be reconstructed after a client switch.
The nearby-standard trap
The nearby-standard trap in NIP-12: Generic Tag Queries is assuming the base layer solves the higher-level feature. This NIP may define the common grammar, but publishing, wallets, moderation, media or groups still need their own constraints. Read NIP-01 to see where the base contract ends and the product-specific promise begins.
Language that keeps the feature honest
Good product copy for NIP-12: Generic Tag Queries does not say "the protocol handles it" and move on. It explains the visible consequence: what was sent, what was accepted, what was rejected, what is still loading and what another relay or client may show differently.
What this page does not promise
NIP-12: Generic Tag Queries does not promise a finished social product. It gives software a shared grammar. Feed design, moderation, ranking, notifications, storage duration and recovery remain separate product decisions. That distinction matters because a client can be technically compatible and still give you a weak experience if it hides relay errors, drops context or treats optional fields as if every app understood them.
Read it as a field test
Start NIP-12: Generic Tag Queries with the visible product symptom, then trace it back to the event kind, tags, content field, relay behavior and signature path. That order keeps the article grounded: you see why the field exists, which relay or client behavior depends on it, and where adjacent standards change the story. A core NIP is strong only when it explains both the normal path and the awkward edge case.
Where the standard earns trust
The source links give you places to test the interpretation in public: NIP-01 tag query text, Issue #278: NIP-12 question, Nostr-nips mirror: NIP-12, Nostrbook tags overview. Use those links to move from the spec to live libraries, mirrors, pull requests, guides or products.
Official NIP-12 source is the anchor for exact wording, and NIP-12 commit history shows how that wording moved over time. The strongest secondary clues here are NIP-01 tag query text, Issue #278: NIP-12 question, Nostr-nips mirror: NIP-12. Treat this evidence chain as part of the article, not as footnotes. A NIP page becomes useful when you can move from claim to source to working behavior without guessing.
Keep the chain visible for NIP-12: Generic Tag Queries: first the human promise, then the event kind, tags, content field, relay behavior and signature path, then the implementation record, then the real-world failure case. That order keeps NIP-12 useful without turning it into marketing copy or protocol trivia.
Three questions to carry forward
- Can two independent clients read the same the main event fields without a hidden compatibility rule?
- Does the UI explain relay rejection, missing context or state replacement without blaming the whole network?
- Which adjacent standard, especially NIP-01, changes the behavior once the base event leaves the happy path?
What to verify before you rely on it
- Find the main event shape in the official file and check how the UI exposes it.
- Read NIP-01 as context before treating NIP-12 as a complete product story.
- Open at least one implementation, mirror, pull request or library source from the source links before trusting that the idea is mature.
- Test the unhappy path: missing relays, stale metadata, invalid signatures, blocked events, expired state, revoked permissions or unavailable media.
- Write the user-facing copy in plain language. If a standard changes authority, privacy, money, moderation or recovery, say that before the click.
Direct sources
Use these sources for NIP-12: Generic Tag Queries in that order: Official NIP-12 source for the current wording; NIP-12 commit history for the change record; NIP-01 tag query text, Issue #278: NIP-12 question, Nostr-nips mirror: NIP-12 for public context. The article gives you the consequence in plain language, but the source trail is where exact fields, status notes, unresolved debates and implementation proof stay checkable.
