DISCOVR — find catalogs

Welcome to the documentation for NFH fabric DISCOVR — the Discovery Service (DS) of the NFH fabric ecosystem.

Realises the NFH fabric Discovery Edge service.

Welcome to the documentation for NFH fabric DISCOVR — the Discovery Service (DS) of the NFH fabric ecosystem. It is a high-performance, real-time discovery engine that enables consumers to find resources across all published catalogues in NFH fabric-enabled networks.

This guide is intended for Consumer Node (CN) developers, consumer application builders, network facilitators, and anyone building search experiences on top of NFH fabric catalogues.

High-level catalog data flow

What is NFH fabric DISCOVR?

NFH fabric DISCOVR is the query-time search and discovery layer for NFH fabric ecosystems. It runs on the consumer node side of the network — it exists to serve consumer applications' search requests, not to publish or manage provider catalogues.

A Provider Node self-hosts and self-signs its own catalogue on infrastructure it controls (see Catalog Publishing and Discovery); DISCOVR (DS) is purpose-built for real-time search — it crawls, independently verifies, and indexes catalogue data straight from every provider's own storage, and exposes it through fast, flexible query APIs that power consumer-facing search experiences.

DISCOVR runs its own crawler: it resolves each provider's Registry record, fetches and verifies that provider's signed catalogue index and files directly, indexes what it has verified, and serves discovery requests from Consumer Nodes (CNs) and consumer applications with sub-second response times. A provider's catalogue starts flowing into DISCOVR as soon as its Registry record points at a crawlable index — see How DISCOVR Stays Updated below.

Why Do You Need NFH fabric DISCOVR?

Without a dedicated discovery layer, consumer applications face:

• Querying raw catalogue data directly — slow, unstructured, and unscalable
• Building custom search indexes per application — duplicated effort, inconsistent results
• No support for natural language, spatial, or attribute-based search across providers
• No unified view of resources across multiple catalogues and networks

NFH fabric DISCOVR solves this by offering:

• One search endpoint across all catalogues published to the network
• Multiple search modes — natural language, keyword, spatial (location-based), and JSONPath attribute filtering
• Real-time indexing — catalogue changes a provider publishes are indexed and searchable within seconds
• Provider-agnostic results — consumers see resources from all providers, with offers from multiple retailers in one response

Key Capabilities

For Consumer Nodes (CNs)

• Natural language search — ask questions like "strong Assam tea for morning chai" or "premium coffee under 500 rupees"
• Keyword search — find resources by name, description, brand, or any indexed attribute
• Spatial search — find resources available near a location using GeoJSON coordinates and distance radius
• Attribute filtering — query resources and offers using JSONPath expressions for fine-grained filtering (e.g., "flat discount offers under ₹100")
• Combined queries — mix text search with spatial constraints in a single request
• Schema-aware results — responses include full resource attributes, ratings, offers, and provider details

For Discovery Service (DS) Builders

• Crawler-fed indexing — DISCOVR runs its own crawler against every provider's self-hosted, self-signed catalogue index — no push, no subscription, no central relay in the path
• Full-text and spatial search — supports keyword matching, natural language understanding, and geospatial proximity queries
• Quality-assured results — every catalogue is signature- and digest-verified before indexing, then deduplicated and pruned before being served to consumers

For Network Facilitators

• Network-wide search — query across all providers and catalogues in a network
• Schema type filtering — discover resources by domain type (e.g., GroceryItem, ChargingService, HealthcareProvider)
• Offer comparison — see multiple retailer offers for the same resource in one response
• Real-time availability — search results reflect the latest published catalogue state

High-Level Architecture

Provider Node                                DISCOVR
(self-hosted, self-signed catalogue)         (crawler + search engine)
      |                                            |
      |   Registry record: catalog_index_urls      |
      |<--------------------------------------------  resolve
      |                                            |
      |   GET catalogue index + files              |
      |<--------------------------------------------  crawl, on its own schedule
      |   signed index + catalogue files           |
      |-------------------------------------------->  verify signatures + digests
      |                                            |  Index for search
      |                                            |  Store for spatial queries
      |                                            |
      |                                            |
Consumer Node (CN)                                 |
      |                                            |
      |  POST /discover                            |
      |  (text / spatial / JSONPath)                |
      |------------------------------------------->|
      |                                            |  Query search + spatial indexes
      |  POST /on_discover (callback)               |
      |  (matching resources + offers)              |
      |<-------------------------------------------|

Example Use Case

A consumer opens a grocery shopping app and searches for "instant coffee near me". The Consumer Node (CN) sends a discover request to NFH fabric DISCOVR combining natural language text search with a spatial constraint (5 km radius around the consumer's location).

DISCOVR queries its search index for resources matching "instant coffee" and its spatial index for resources with availability locations within 5 km. The response includes multiple matching products from different providers — each with competing offers showing different prices, discounts, and delivery estimates.

The consumer compares offers and proceeds to order from the provider with the best price and fastest delivery.

Design Principles

• Real-time query engine: Optimized for sub-second search — not for catalogue storage or signing (that's the publisher's role — see Catalog Publishing and Discovery)
• Crawler-fed: Discovers and pulls catalogue updates directly from each provider's own storage on its own schedule — no polling of a central service, no manual sync
• Verify-before-index: Every catalogue index and file is checked against its publisher's Registry-registered signature and digest before anything is indexed
• Multi-modal search: Supports text, natural language, spatial, and structured attribute queries — individually or combined
• Provider-agnostic: Returns resources from all providers in a network, with competing offers side by side
• Schema-aware: Understands NFH fabric resource and offer schemas — filters, groups, and prunes results based on schema context

API Reference

DISCOVR exposes one consumer-facing HTTP endpoint for running queries. Catalog data reaches DISCOVR's index via its own crawler, which pulls directly from each provider's self-hosted storage and indexes it via an internal /catalog/push API (see Catalog indexing and How DISCOVR Stays Updated below).

Discovery APIs (Consumer Node-facing)

API	Method	Description
/discover	POST	Asynchronous — acknowledges with ACK, delivers results via POST /on_discover callback to bapUri

Catalog indexing

DISCOVR implements the /catalog/push endpoint that the crawler calls to deliver catalog updates matching an active subscription — the push leg of How DISCOVR Stays Updated. DISCOVR validates the push and responds synchronously with an NFH fabric ACK (accepted — indexed asynchronously and searchable via /discover shortly after) or NACK.

What DISCOVR receives. Each entry in message.catalogs[] is a resolved catalog, not the raw fragment a Provider Node published. For resources that extend a master (masterResourceId), the crawler merges the master into the overlay (master-wins) before pushing, so DISCOVR receives self-contained, indexable resources. DISCOVR does not re-resolve against masters — it indexes exactly what is pushed.

This endpoint's authentication, request/response shape, and status codes are not part of the Beckn protocol — /catalog/push here is an internal API between the Edge Discovery Service and its crawler, not a wire-level Beckn action. Nothing mandates using this same interface between the two: an implementation is free to wire its crawler to its own indexing layer however it chooses (a different internal API, an in-process call, or any other mechanism) — this section documents the shape this reference implementation happens to use.

Search Modes

Mode	Description	Example
Text / Natural Language	Keyword or conversational query	"strong Assam tea for morning chai"
Spatial	Find resources near a location	Within 5 km of a GPS coordinate
Attribute Filter	Fine-grained filtering on resource or offer attributes	Flat discount offers under ₹100
Combined	Mix any of the above in a single request	Coffee search within 5 km radius

For detailed request/response formats and examples, see Usage and Examples.

How DISCOVR Stays Updated

Reference Discovery service ships with a crawler, which helps the service to keep its indexes current with the decentralised catalogs.

1. DISCOVR's crawler resolves each provider's Registry manifest and Subscriber record, filtered to the networkIds and/or schemaTypes it cares about, and finds the catalog index url
2. It fetches the provider's catalogue index over HTTPS and verifies the index's signature against the provider's Registry-registered key
3. It compares the index's entryVersion against its own stored cursor for that catalogue — an unchanged entry is skipped without any further fetch
4. For a changed entry, it fetches only the baseline or change files the cutover rule calls for, verifies each file's signature and digest, and applies upserts/removals into its own index
5. The updated data is immediately searchable via POST /discover

There is no separate bulk "initial sync" call — a brand-new crawl and a routine re-crawl are the same operation; a crawler simply starts from no cursor the first time, so it fetches a provider's full baseline rather than an incremental change file. See Catalog Publishing and Discovery → Hosting & Discovery for the full crawl sequence and verification rules a provider can expect DISCOVR to apply.

The NFH fabric capability: Discovery

DISCOVR realises the NFH fabric Discovery capability — network-wide search across every catalogue on NFH fabric: offerings, providers, credentials, and capabilities.

What it gives you

• Network-wide search — one query, every catalogue.
• Structured filters — by category, geography, provider type, credential, price.
• Agent-native queries — discovery exposed as MCP tools for autonomous agents.
• Federated indexes — operators can run sector- or geography-specific indexes that compose into the global surface.

Where it sits — a service NFH runs (the indexed discovery surface that consumes Cataloguing), the protocol NFH defines (query and response schemas), and reference software NFH publishes (discovery clients and agent integrations).

Standards alignment: MCP for agent-native discovery · open query APIs.