[PRD]: Business-first discovery for the Data Marketplace

Problem Statement

Non-technical and business users struggle to discover the right data products in Ontos. The Data Marketplace feels too technical: product names and descriptions read like engineering artifacts, search on the marketplace does not match the quality of global search elsewhere in the app, and the first screen surfaces governance controls (scopes, exact-match domain logic, dense badges) before outcomes and trust. That mismatch raises support burden, slows self-serve adoption, and undermines the value of well-governed products, contracts, and domains.

Solution

Deliver a layered discovery experience on the Data Marketplace:

1. One search brain — Marketplace search uses the same ranked, permission-aware search pipeline as the rest of the app, restricted (and clearly labeled) to marketplace-relevant hits, especially published data products.
2. Business-oriented presentation — First-party nullable columns on the data product (or equivalent persisted API model) for shopper-facing title, short consumer summary, and optional discovery keywords, indexed for search with higher weight than internal technical names.
3. Curated storefront rails — Stewards maintain rows in a dedicated persistence model (DB table): title, description, visibility rules, and membership (ordered product IDs and/or query rules). A steward UI supports create/edit/reorder without developer involvement.
4. Progressive disclosure — Cards and filters default to simple language and one primary trust signal; technical metadata (publication scope, certification detail, exact domain match) moves behind Advanced or the existing product info flow.
5. Differentiators (later phases in same PRD) — Explainable recommendations (e.g. same domain, shared business concepts via semantic links) and optional assist for how to phrase a search, without replacing the primary ranked list.

Users should feel: “I can describe what I need, see what’s official, and subscribe without talking to engineering first.”

User Stories

1. As a business analyst, I want the marketplace search box to find products when I use everyday words, so that I do not need to know internal product codenames.
2. As a business analyst, I want search results to be ranked and consistent with search elsewhere in the app, so that I trust the product is relevant.
3. As a business analyst, I want zero useful results to show suggestions (e.g. broaden query, browse by domain, browse by concept), so that I am not stuck on a dead end.
4. As a business analyst, I want product cards to show a short plain-language title separate from the technical ODPS name, so that I can scan the grid quickly.
5. As a business analyst, I want a one-line “what this is for” blurb on the card, so that I understand value before opening details.
6. As a business analyst, I want one clear trust signal (e.g. certified / official) on the card, so that I know what is safe to use without reading five badges.
7. As a business analyst, I want owner/steward shown as a human-friendly name when available, so that I know whom to contact.
8. As a business analyst, I want technical details (scope, status strings, secondary certification) available after I show interest, so that the first screen is not overwhelming.
9. As a domain steward, I want to define curated rails (e.g. “Featured for Retail Q1”, “Starter kit for finance reporting”), so that I can guide my organization to the right products.
10. As a domain steward, I want to add, remove, and reorder products in a rail, so that the storefront stays current without code changes.
11. As a domain steward, I want rails to support visibility rules (e.g. org-wide vs domain-scoped), so that I do not accidentally promote restricted content broadly.
12. As a domain steward, I want audit or history of who changed rails and when (if the platform supports it), so that governance reviews are possible.
13. As a data product owner, I want guided fields when publishing to the marketplace for consumer title and summary, so that my product is discoverable by non-technical users.
14. As a data product owner, I want validation or soft warnings when the technical name is jargon-heavy but consumer fields are empty, so that I am nudged toward good practice.
15. As a data product owner, I want discovery keywords to improve findability without polluting the official product name, so that search matches real user language.
16. As a governance lead, I want marketplace copy and rails changes to respect existing RBAC and publication rules, so that we do not bypass access control.
17. As a consumer, I want clicking a product from search to land in the appropriate consumer context (subscribe-oriented flow), so that I am not dropped into a producer-only screen by mistake.
18. As a consumer, I want domain browsing to default to an inclusive interpretation (e.g. include related sub-domains) with advanced precision optional, so that I do not miss relevant products due to strict hierarchy.
19. As a consumer, I want an “Advanced filters” area for exact domain match and similar controls, so that power users still have precision without scaring novices.
20. As a consumer, I want curated rails above the full catalog, so that I can start from “what my org recommends” instead of an undifferentiated grid.
21. As a consumer, I want rails to show why a section exists (short subtitle), so that I understand the intent of each row.
22. As a consumer, I want empty rails to hide cleanly or show a steward-configured message, so that the UI does not look broken.
23. As an admin, I want to restrict who can edit marketplace rails, so that only authorized stewards change the storefront.
24. As an admin, I want rails and marketplace fields to be documented in operator docs, so that rollout is repeatable across environments.
25. As a platform engineer, I want search indexing to include new marketplace fields with sensible boost defaults, so that relevance improves without per-tenant tuning.
26. As a platform engineer, I want a clear API contract for marketplace search vs global search, so that clients do not fork logic.
27. As a business user, I want to filter or pivot by business concept (where semantic links exist), so that I can discover products aligned to vocabulary I already use.
28. As a business user, I want “Related products” with a one-line explanation (e.g. same domain, shared concept), so that recommendations feel transparent, not magical.
29. As a business user, I want an optional “Help me phrase this search” entry point, so that I can get query suggestions without the AI inventing catalog entries.
30. As a accessibility-minded user, I want search, rails, and cards to work with keyboard and screen readers, so that the marketplace is inclusive.
31. As a mobile or narrow-layout user, I want the marketplace to remain usable when rails and filters collapse sensibly, so that I can discover on a laptop or tablet.
32. As a subscriber, I want the experience to reflect what I already follow where appropriate (e.g. “Because you subscribed to X”), so that repeat discovery is faster—subject to privacy policy.
33. As a new employee, I want a guided empty state on first visit (e.g. suggested rails and example searches), so that I learn how to use the marketplace quickly.
34. As a auditor, I want marketplace-visible products to still respect publication_scope and permissions, so that discovery never leaks unauthorized metadata.
35. As a support engineer, I want telemetry on searches, zero-result queries, and rail clicks (privacy-preserving), so that we can iterate on copy and curation.
36. As a demo builder, I want sample data to showcase consumer titles and summaries, so that demos match the intended business story.

Implementation Decisions

• Marketplace copy: Persist nullable columns (or equivalent single-table columns on the existing data product persistence model) for at least: consumer-facing title, consumer summary, discovery keywords (format TBD: comma-separated or normalized join table if keywords need analytics). These are optional; fallback remains ODPS name and structured description fields for backward compatibility.
• Search: Marketplace UI calls a server-side search path that reuses the existing SearchManager ranking and authorization behavior, then intersects with marketplace-eligible products (published / allowed scope). Avoid maintaining a second ad-hoc ranking algorithm in the frontend.
• Navigation consistency: Search hits for data products resolve to the consumer-appropriate product route or a route that defaults to subscribe/discover actions for marketplace users (exact path is a product decision; behavior is the requirement).
• Curated rails: New relational model for rails: identity, title, subtitle, sort order, visibility scope, tenant/org scoping as needed, membership (ordered list of product IDs and/or rule-based query stored as structured JSON with validated schema), audit columns. Steward UI for CRUD and reorder; optional approval workflow is out of scope unless already standard in the app.
• Deep module: Introduce a small MarketplaceDiscoveryService (name illustrative) that encapsulates: “search published products,” “resolve rails for current user,” “hydrate cards from product IDs,” and “explainable recs v0”—one place for orchestration so routes and UI stay thin.
• Indexing: Extend search index building for data products to include consumer title, summary, and keywords with weights defined in centralized search configuration (not hard-coded in multiple controllers).
• Progressive disclosure: UX rule—card shows at most one primary trust indicator by default; additional governance chips behind expand or info dialog.
• Domain graph: Retained as a secondary discovery mode; not the primary investment for v1 beyond copy and placement cleanup.
• LLM assist: Optional, non-authoritative; never the sole source of catalog truth; scoped to query suggestion or facet hints if implemented.

Testing Decisions

• Good tests assert observable behavior: correct filtering of unpublished products from marketplace search; permission-denied products never appear; rails respect visibility; reordering rails changes API list order; consumer title appears on card when set, with fallback when null.
• Modules under test: Marketplace discovery service (unit), search integration with published filter (unit or integration), API routes for rails CRUD (integration), frontend behavior via Playwright for: search debounce, empty state, advanced filters collapsed by default.
• Prior art: Follow existing patterns for search route tests, data product API tests, and Playwright critical user journeys already used in the repo for search and home flows.

Out of Scope

• Replacing the entire domain graph with a new visualization engine.
• Full enterprise recommendation system (ML ranking, collaborative filtering at scale) beyond simple, explainable v0 rules.
• Auto-generating consumer summaries with LLM as the default (optional assist only, if at all).
• Multi-language marketplace copy beyond what the existing i18n framework already provides for chrome strings (unless explicitly added later).
• External marketplace syndication (e.g. public internet listings).

Further Notes

• Migration path: Ship DB columns with safe defaults; backfill optional script or steward prompt for high-value products first.
• Link alignment: Ensure search link targets and marketplace navigation agree on consumer vs producer experience for the same product where roles differ.

Start by reading the existing search route tests, data product API tests, SearchManager, and Playwright critical user journeys for search and home flows. The work is done when marketplace discovery reuses authorized search, filters unpublished products, supports visible ordered rails, and shows consumer-field fallbacks with the specified API and UI behavior.