beckn / beckn/protocol-specifications-v2

NFH-014: Follow-up on Provider/network-topology semantics (post-PR #193)

Open
#194 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
No language data
Stars
15
Forks
13
PR merge metrics
No merged PRs in 30d

Description

# NFH-014: Follow-up on Provider/network-topology semantics (post-PR #193)

## Context
PR #193 merged NFH-014 (Decentralized Catalog Publishing and Discovery). During review, ut-utkarsh raised four related gaps that were acknowledged as valid but out of scope for that PR, and flagged for a follow-up iteration. This ticket tracks that follow-up.

## Intent
Formalize the "Provider" entity and its network-topology implications in NFH-014, and use that clarity to tighten the trust, cutover, and availability-signal rules that depend on it. These four items are interdependent — defining Provider affects how DS trust scoping, cutover semantics, and unavailability signals should be framed — so they're tracked as one coherent design pass rather than four separate tickets.

## Scope

### 1. Formally define "Provider" as an entity distinct from PN
- NFH-014 currently uses "Provider" in a way that implies a distinct role from a Provider Node (PN), without defining it.
- Decide: is Provider its own node type, or is it onboarded to a Platform (the actual network node), with PN being the technical/wire-level entity?
- Reconcile with existing PN taxonomy in NFH-003 (The Beckn Protocol Stack).
- Update the sequence diagram in `Catalog_Publishing_and_Discovery.md` (~line 145) to separate network-node-level semantics from catalog (functional/business) update semantics.
- Ref: `docs/Catalog_Publishing_and_Discovery.md:137, 145`

### 2. Define catalog trust semantics for network-scoped Discovery Services
- No current mechanism specifies which catalogs a network-scoped DS should trust when building its index.
- Determine whether trust is driven by catalog-level meta-annotations, Registry/Fabric policy, or another mechanism — and document it explicitly.
- Ref: `docs/Catalog_Publishing_and_Discovery.md:25`

### 3. Generalize the cutover / grace-period rule
- Grace-period semantics are currently framed around baseline-file changes only.
- Rework so the same rule applies uniformly whether the transition is a baseline-to-baseline swap or an incremental change-file application.
- Ref: `docs/Catalog_Publishing_and_Discovery.md:91`

### 4. Distinguish functional vs. non-functional unavailability signals
- "No longer offered" (functional) and "host unreachable" (non-functional/transient) are currently described only via examples, with no explicit signal for a DS to distinguish the two.
- Introduce an explicit field/signal for this distinction and reframe existing examples as illustrations of the general rule.
- Ref: `docs/Catalog_Publishing_and_Discovery.md:101`

## Out of scope (tracked separately / already deferred, no action here)
- ETag/conditional-fetch necessity for small index files
- Dedup / reference-counting design for cross-catalog Resource/Offer IDs
- Whether ID domain-prefixing should become protocol-enforced
- Minor copy edit ("between two versions of the specific catalog") and DS-operator-type clarification in NFH-003 — low priority, can be folded in opportunistically if this ticket's PR touches those sections, but not a blocking requirement.

## Acceptance Criteria
- [ ] NFH-014 (and NFH-003 where needed) contains a formal definition of "Provider" and its relationship to PN/Platform
- [ ] Sequence diagram updated to reflect the Provider/PN distinction
- [ ] Trust-scoping rule for network-scoped DS is explicitly documented
- [ ] Cutover/grace-period rule is generalized to cover both baseline swaps and incremental changes
- [ ] A functional vs. non-functional unavailability signal is defined and existing examples reframed under it
- [ ] Changes reviewed by ut-utkarsh (original commenter) before merge

## References
- PR #193: https://github.com/beckn/protocol-specifications-v2/pull/193
- Related: NFH-003 (The Beckn Protocol Stack), NFH-010 (Protocol Flows/Schema Change ordering constraint)

Contributor guide

Open the contributing guide

Research direction

Start by reading docs/Catalog_Publishing_and_Discovery.md at lines 25, 91, 101, 137, and 145, then compare the related Provider Node taxonomy in NFH-003 and the context from PR #193. The work is done when the Provider/PN relationship, network-scoped DS trust rule, generalized grace period, and functional versus non-functional availability signal are documented, with the sequence diagram updated and review from ut-utkarsh.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.