Beckn Schema and Protocol Architecture Consolidation — Work in Progress

[ravi-prakash-v]

What this is

This thread documents an active, in-progress consolidation of the Beckn Protocol schema and API architecture. The work spans beckn/core_schema, beckn/protocol-specifications-v2, and beckn-one/schema.beckn.io. It started as a schema review (Issue #1 in core_schema, raised by @anandp504) and has grown into a comprehensive architectural redesign.

Work proceeds on feature branches and draft RFCs. No approval is needed to start — if design changes are required after discussion, we adjust on the branch. Please raise questions or concerns here or in the relevant issues.

---

Why this matters

The Beckn network is going to grow substantially. We already have BAP, BPP, Registry, and Catalog Discovery/Publishing Services. Coming soon: Issue and Grievance Management Service, Reconciliation and Settlement Service, Reputation Management Service, Credentialing Service, Observability and Insight Engine, Transaction Ledger, and potentially AI Agents. Each new actor needs to speak Beckn. The current architecture does not make that easy — the protocol spec is entangled with action definitions, schemas are scattered across repos, and the schema registry doesn't support federation.

We are fixing this now, while the v2 spec is still being consolidated, not after.

---

Design philosophy (the short version)

Four guiding philosophies:

1. Minimalism — each component does exactly one thing
2. Future-readiness — design for actors and use cases that don't exist yet
3. Pragmatism — must be implementable today, not just theoretically sound
4. Optimal ignorance — each layer knows only what it must

Two derived principles:

1. Protocol stability — beckn.yaml has a very long half-life (like HTTP). New actors and endpoints don't require commits to protocol-specifications-v2.
2. Independent evolution — new actors, actions, and domains are added to schemas (formerly core_schema) without touching the protocol spec.

Full document: docs/design-philosophy.md | Tracking issue: #93

---

The target architecture

Tier 1: protocol-specifications-v2  (transport — frozen)
  beckn.yaml — HTTP endpoint, auth, ACK/NACK, signatures
  References Tier 2 via $ref at exactly two points:
    - path param → https://schema.beckn.io/BecknEndpoint/v2.0
    - request body → https://schema.beckn.io/BecknAction/v2.0

Tier 2: schemas (formerly core_schema)  (schema registry — evolves freely)
  BecknEndpoint, Context, Message, BecknAction
  All data model schemas (Catalog, Item, Provider, Fulfillment, ...)
  All action schemas (DiscoverAction, SelectAction, ...)
  Domain schemas (/mobility/*, /logistics/*, /deg/*, ...)

schema.beckn.io is a namespace router — domain owners can keep schemas in their own repos and register a namespace prefix. schema-admin.beckn.io is a staging/validation pipeline before publish.

Implementers need exactly three imports:

1. beckn.yaml
2. context.jsonld
3. vocab.jsonld

Everything else resolves automatically via $ref.

---

What is broken right now

• RequestAction and CallbackAction in core_schema have oneOf nested inside properties — structurally invalid JSON Schema, they don't validate anything
• Context is duplicated between core_schema and beckn.yaml with divergent content
• BecknEndpoint only exists inline in beckn.yaml — can't be referenced from schemas
• Action schemas (DiscoverAction, SelectAction, etc.) are in core_schema but not referenced by beckn.yaml — orphaned
• core_schema/Context references https://schema.beckn.io/Action/v2.0 which does not exist

---

What is already fixed (Issues #2–#7 in core_schema)

Issue	Fix	PR
#2	beckn: namespace URI corrected	#12
#3	$ref URIs standardised to versioned canonical form	(schema-fixes)
#4	Bare type:object replaced with allOf $ref	#14
#5	Provider @context URL and FulfillmentStage @type bugs fixed	#17
#6	additionalProperties: false added to 25 schemas	#15
#7	schema: prefix removed from property keys; @type defaults fixed	#18

---

Phased execution plan

Phase 0 — Design record ✅ Done

• docs/design-philosophy.md published to protocol-specifications-v2 (branch docs/design-philosophy-rfc)
• RFC Issue RFC: Beckn Architecture Design Philosophy and Principles #93 created

Phase 1 — Stakeholder communication ✅ In progress (this thread)

Phase 2 — All issues filed (next)
Issues will be created in core_schema, protocol-specifications-v2, and beckn-one/schema.beckn.io covering: BecknAction implementation, schema-admin pipeline, folder structure investigation, federated registry manifest, domain migration (opt-in), repo rename, deprecation of RequestAction/CallbackAction, compatibility testing, example generation framework.

Phase 3 — Issue #8 code
Create BecknEndpoint, Message, fix Context, create BecknAction. PR → schema-fixes in core_schema.

Phase 4 — Slim down beckn.yaml
Remove inline Context/BecknEndpoint/Message. Wire two $ref touch points. PR → main in protocol-specifications-v2.

Phase 5 — Validation and testing
Schema compatibility checks, vocabulary compatibility, use case stress testing (retail, mobility, logistics, energy), design principles adherence audit.

Phase 6 — Structural migration (gated on Phase 5)
Folder rename (schema/ → data/), namespace routing manifest, schema-admin pipeline, optional domain schema migrations, repo rename (core_schema → schemas).

Phase 7 — Example generation framework
Retail use case examples for all 10 action pairs. Discovery/catalog examples against the active runtime service. Disclaimer: if API design changes post-discussion, examples are regenerated (framework, not manual).

---

Who is affected and how

Stakeholder	Affected by
@anandp504	Issue #1 resolution, schema review items #2–#7 done, #8 in progress; beckn.yaml changes in Phase 4
@pramodkvarma	DEG schemas stay in beckn/DEG; federated registry design ensures they're served via schema.beckn.io namespace routing; schema-admin pipeline for external schema ingestion
@abhimail @ameetdesh @nirmay @bachia	beckn.yaml update (Phase 4), repo rename (Phase 6), example generation (Phase 7), use case stress testing (Phase 5)
All domain implementers	Three-import principle simplifies onboarding; schema.beckn.io namespace routing makes domain schemas discoverable

---

Complex interdependencies to be aware of

Phase 0 → Phase 1 → Phase 2
  Phase 2 branches into:
    Phase 3 (Issue #8) → Phase 4 (beckn.yaml) → Phase 5 (testing) → Phase 6 (migration)
    Phase 7 (examples) — parallel, but regenerate after Phase 4 settles

Blocking dependencies:
  schema.beckn.io folder structure issue → blocks schema/ → data/ rename (Phase 6)
  schema-admin pipeline → blocks external repos going live in namespace (Phase 6)
  Phase 3 must complete before Phase 4 can reference BecknAction
  Phase 5 must pass before Phase 6 (domain migration is irreversible)

---

Questions and concerns welcome here. @abhimail @ameetdesh @nirmay @bachia @anandp504 @pramodkvarma