Defines externally visible behavior when search returns no matches, including recovery suggestions, query reformulation affordances, and bounded fallbacks without inventing results or leaking unauthorized catalog breadth.
Package status: AI-assisted reference package. Static package validation has passed; implementation scenarios remain not run and human domain review is required before stable adoption.
Decision
A zero-result search is a first-class outcome, not an empty template. The product must tell the user that nothing matched the current query and filters, offer bounded recovery actions such as spelling correction, filter removal, or category broadening, and optionally show popular or curated items that remain within the viewer authorization scope. The system must never fabricate result rows to avoid an empty state, never suggest terms or items from catalogs the viewer cannot access, and must record zero-result events for relevance tuning without leaking raw query text into untrusted analytics sinks.
Scope
- Search UI and API behavior when the authorized result set is empty.
- Recovery suggestions, filter echo, and optional popular-item fallback.
- Analytics events for zero-result monitoring.
- Accessibility announcements for empty states.
Outside this block
- Ranking and hybrid retrieval quality (see related search blocks).
- Facet count computation and filter grammar (see faceted search block).
- Indexing pipeline correctness for missing documents.
Contract
- Zero-result responses include an explicit empty marker, the submitted query echo, and a machine-readable list of active filters when filters were applied.
- Recovery suggestions are computed only from documents and facets the current principal may view; cross-tenant or hidden-catalog signals are excluded even if index statistics exist globally.
- Popular or curated fallback items, when enabled, are drawn from the same authorization scope as primary search results and are labeled as suggestions, not matches for the query.
- The system never inserts synthetic result records to populate the results list; hints and fallback panels are structurally separate from ranked hits.
- Zero-result analytics emit a stable query hash and filter signature; raw query text is omitted from third-party analytics exports unless the profile explicitly allows it for trusted internal pipelines.
- Empty states announce accessibly to assistive technology without trapping keyboard focus away from logical next actions such as editing the query or clearing filters.
Implementation guidance
- Separate recovery computation from primary retrieval so a slow suggestion path does not block the empty response.
- Cap suggestion count and compute budget to keep zero-result pages responsive under load.
- Use the same authorization predicate for fallback items as for search hits, not a weaker cached path.
Failure handling and safeguards
- When recovery computation times out, return the empty state without suggestions rather than partial misleading hints.
- If spelling correction would expose a term the user cannot access, omit the correction entirely.
- Rate-limit expensive zero-result recovery for automated clients to prevent catalog probing.
Verification and operations
- Track zero-result rate by segment, suggestion click-through, and fallback impression rate.
- Test with principals of differing entitlements to prove no unauthorized suggestion appears.
- Verify analytics payloads exclude raw queries in third-party-bound exports for the default profile.
The executable-looking examples in this package are fixtures and acceptance contracts. Run static validation on the package structure and metadata, then implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map authorization scopes, analytics sinks, and UI copy to its product.
- NN/g guidance on no-results pages informs UX expectations but does not mandate a specific component library.