Core 2.0.0 rc2 alt by ravi-prakash-v · Pull Request #92 · beckn/protocol-specifications-v2

ravi-prakash-v · 2026-02-24T07:11:23Z

Request for Comments (Core-2.0.0 LTS Release)

This RFC is published as a Pull Request to finalize the architecture of the Beckn Protocol v2 specification.

Status : Under Review

Context

This is the reference specification for Beckn Protocol v2.0.0 (LTS) — a re-arch of the Beckn protocol layer as per our last Friday discussion. The key idea as suggested by @pramodkvarma to keep the core protocol envelope as small and stable, like HTTP, while enabling a rich, composable ecosystem on top via JSON-LD, schema.org alignment, and pluggable domain schema packs.

The branch contains the following changes:

An updated README.md : This is to be reviewed
The OpenAPI spec api/v2.0.0/beckn.yaml : This is to be reviewed
The repo also has a docs/ folder. The docs are staged as a progressive reading journey (stages 1–7), and most docs are normative RFCs. You can read this at your leisure, but the key review request is for the api/v2.0.0/beckn.yaml file. Not in the scope of this review, but comments are always appreciated
A new Governance model: This too is NOT in scope of the review
After this release, the old folder structure will been moved to https://github.com/beckn/protocol-specifications-v2/tree/core-2.0.0-rc1-eos for implementers still using the old version

Key architectural changes to be reviewed:

Standard endpoint pattern: Single /beckn/{endpoint} supporting GET (Body Mode + Query Mode for QR/deep-links/IoT) and POST, which can allow as many endpoints as possible to be created without evolving the core repo.
All transaction first-class schema like Intent, Catalog, Order, Support, etc have been moved out into a new repository: https://github.com/beckn/core_schema/tree/draft (Check out main branch of this repo to understand the design philosophy)

Issues Addressed

Addressed issue Proposal: Strengthening Non Repudiation and Causality in Beckn Transactions #69 raised by @abhimail regarding non-repudiation model by adding new schemas - CounterSignature, InReplyTo, LineageEntry
Addressed Error object not present in on_* requests #45 raised by @nirmalnr regarding error codes in callback responses

Note: Expect more issue to be added here

Note : There was an earlier plan to keep transaction schemas — Catalog, Contract, Intent, Fulfillment,etc. I've preserved that approach on this branch if anyone wants to compare. But after working for a while through the design, I moved them out. The reasoning: if even abstract domain schemas live here, there is a risk of another domain-agnostic schema getting added or renamed or aliased, especially when new modules like IGM, RSF, etc get added. That approach couples protocol stability to domain evolution.

By keeping this repo to the transport envelope only, the protocol itself becomes analogous to HTTP: a small, stable contract that rarely changes, while an entire ecosystem evolves freely on top of it. The transaction schemas now live in the draft branch of this repo : https://github.com/beckn/core_schema/tree/draft , and domain-specific schema packs live in their own vertical repositories.

Looking forward to your comments on this RFC.

… enum casing

…AKE_CASE with underscores

…word ambiguity

…teredEnergyKWH

…omain schemas

…api/beckn.yaml

Beckn Protocol Specification 2.0 - Schema & Naming Standardization

This document outlines a schema design framework for creating domain-specific bindings for the Beckn Protocol 2.0. It addresses the need for interoperability and validation in domain implementations.

This script initializes a GitHub organization layout by creating multiple repositories and setting up their folder structures, including optional submodules for upstream repositories.

This script initializes a network of repositories for an Open Network GitHub organization, setting up folder structures, creating git repositories, and adding submodules.

Added a draft for Attribution Guidelines for NFOs, outlining the structure and principles for GitHub organizations to ensure proper attribution and organization of network-specific content.

Updated the document to enhance clarity and structure, including sections on implementation, feedback, and attribution guidelines.

This document outlines the structure and guidelines for adding domain-specific schemas, including folder structure, file descriptions, conventions, and when to create or extend schema bundles.

…l-specifications-v2 into core-2.0.0-rc2-issues-ravi

Rename all N_ prefixes to reflect pedagogical order: Stage 1 (1-3) — Prerequisites: Introduction, Keyword Definitions, RFC Template Stage 2 (4-6) — Big Picture: Network Architecture, Versioning, Schema Distribution Stage 3 (7-11) — Core Mechanics: Communication, API Envelope, Auth, Signing, Errors Stage 4 (12-16)— Infrastructure: Registry, DeDi, Discovery, CPS, CDS Stage 5 (17-19)— Advanced: Non-Repudiation, Full Comm Flows, GET Query Mode Stage 6 (20-23)— Extension/Policy: JSON-LD, Schema Packs, Network Profiles, Payments Stage 7 (24-25)— Conformance: Testing guide, Certification RFC Also: fix all internal cross-links to match new filenames; rewrite docs/README.md as a staged learning guide with goal descriptions per stage and a Quick Reference by Role table.

- Move beckn.yaml from api/v2.0.1/ to api/v2.0.0/ (v2.0.1 was never officially released) - Remove api/v2.0.1/ and api/v2/ folders - Remove api/README.md (no longer needed) - Update root README.md: - v2.0.0 promoted to LTS with full feature description - Remove v2.0.1 row from version history (was draft only) - Update core-2.0.0-eos branch refs to core-2.0.0-rc1-eos - Update all api/v2.0.1/beckn.yaml paths to api/v2.0.0/beckn.yaml - Update repository structure block

nirmay · 2026-02-24T07:40:56Z

docs/BECKN-010-QR-Codes.md

Why is the QR Codes spec removed? this is already being used by networks? @ravi-prakash-v

My mistake, Will add it back.

Btw, as mentioned, docs are not part of this PR. I have not fully reviewed them myself. Consider them as drafts for now.

Will raise a separate PR to review docs as well. Kindly bear with me.

this is not a doc, but a spec that we needed to add.

nirmay · 2026-02-24T07:42:38Z

docs/11_Error_Codes.md

there is completely new v2 ERROR_CODES file that we should be adding here instead.

@abhimail @ravi-prakash-v

Could you please share the error codes file here?

@abhimail pls share the location of latest error-codes spec.

#51 (comment)

abhimail · 2026-02-24T09:19:18Z

@ravi-prakash-v This is a mega PR (67 files, 138 commits!) - will need quiet some time to just get our heads around it. Could you please break it into multiple related chunks as we discussed last time? Very difficult to review otherwise, and my concern is that we may end up not doing justice to it.

- Copy api/ folder from fix/beckn-yaml-schema-refs: - Updated api/v2.0.0/beckn.yaml (schema fixes) - New api/v2.0.0/components/io/core.yaml - New api/v2.0.0/components/schema/core.yaml - Remove api/beckn.yaml (root-level copy was redundant; canonical spec lives at api/v2.0.0/beckn.yaml) - Copy docs/design-philosophy.md from docs/design-philosophy-rfc branch

…chemas Deleted 56 domain-level schemas (Context, Catalog, Intent, Fulfillment, Provider, Item, Offer, Person, Organization, Address, Location, Descriptor, Tracking, etc.) that are now authoritative at schema.beckn.io. Retained 8 transport-layer schemas that are not hosted at schema.beckn.io and are directly referenced from components.responses / components.parameters: Ack, AckNoCallback, NackBadRequest, NackUnauthorized, ServerError, Signature, CounterSignature, Error File reduced: 3148 → 817 lines (-2331 lines, -56 schemas) All endpoint requestBody refs already point to canonical IRIs at schema.beckn.io (done in previous commit 4a67b43). All remaining internal $ref pointers are intact and resolvable. New script: scripts/prune_beckn_yaml.py — computes transitive schema closure from responses+parameters and deletes everything unreachable.

…m source files rebuild_beckn_yaml.py is now a proper code generator, not a patcher. It reads two source files and produces beckn.yaml entirely from scratch: Source 1: api/v2.0.0/components/io/core.yaml Abstract IO spec with generic /beckn/{becknEndpoint} path (GET + POST) Source 2: api/v2.0.0/components/schema/core.yaml Transport-layer schemas: Ack, AckNoCallback, AsyncError, CounterSignature, Error, InReplyTo, NackBadRequest, NackUnauthorized, ServerError, Signature Generated beckn.yaml: - 20 concrete per-action paths (/beckn/discover … /beckn/on_support) - Each requestBody.$ref points to https://schema.beckn.io/{Action}Action/v2.0 - components.schemas: 10 transport-layer schemas from schema/core.yaml - 933 lines (was 817 hand-edited lines) - Zero dangling internal $ref pointers Usage: cd protocol-specifications-v2 && python3 scripts/rebuild_beckn_yaml.py

…t schemas from schema/core.yaml Fixes issue #109 — two OpenAPI 3.1 structural bugs: Bug 1: Removed invalid 'in: path' becknEndpoint parameter from the POST handler. POST endpoints generate concrete paths (/beckn/discover, /beckn/select, etc.) with no {becknEndpoint} path variable, so 'in: path' was invalid OpenAPI 3.1. The GET handler correctly keeps this parameter (its path is /beckn/{becknEndpoint}). Bug 2: Replaced invalid '$ref' at components map-key level with inlined definitions. OpenAPI 3.1 does not allow '$ref' to replace an entire components/schemas or components/parameters map. All transport-layer schemas, parameters, and responses from api/v2.0.0/components/schema/core.yaml are now inlined directly in core.yaml. schema/core.yaml is preserved as a standalone reference document. Regenerated api/v2.0.0/beckn.yaml (833 lines, 20 endpoints, 10 transport schemas). Branch: core-2.0.0-rc2-alt

@type

…mpliance validator - examples/retail/: 146 JSON example files covering all 13 Beckn retail action endpoints (discover, on_discover, select, on_select, init, on_init, confirm, on_confirm, status, on_status, cancel, on_cancel, support, on_support) - 10 consumer personas per endpoint (Arjun, Priya, Rahul, Sunita, Vikram, Deepa, Kiran, Anjali, Ravi, Meena), Dominos India / Zomato BPP scenario - on_discover includes full catalog: 25 items, 41 offers with RetailCoreOffer attributes (cancellation/return/replacement policies, serviceability timing, FSSAI declarations, payment methods) - All examples schema-compliant with live https://schema.beckn.io/ schemas: Item/@type=Item, Offer/@type=Offer, Location/@type=Location, TimePeriod uses startDate/endDate, AcceptedPaymentMethod is string array - scripts/validate_examples.py: schema compliance validator that fetches schemas live from schema.beckn.io and validates all typed objects, reporting PASS / VALIDATION_FAILURE / URL_RESOLUTION_FAILURE

- EXAMPLES_DIR: examples/retail/ → examples/ (examples were copied without the retail/ subdirectory, so all 146 JSON files are directly under examples/) - REPORT_PATH: plans/ → docs/ (protocol-specs repo uses docs/, not plans/)

Restructure so examples live under examples/retail/ (not directly under examples/) to allow future domains (mobility/, healthcare/, etc.) to coexist. Also restore EXAMPLES_DIR = examples/retail/ in validator.

…mapping - api/v2.0.0/components/io/core.yaml: path /beckn/{becknEndpoint} → /{becknEndpoint} (endpoint values already include the beckn/ prefix in BecknEndpoint const values) - scripts/rebuild_beckn_yaml.py: update ACTIONS list to use full beckn/-prefixed endpoint values matching the BecknEndpoint schema const values

…enario-based names - discover/: stripped consumer.id (email), consumer.name, consumer.location.address from all 10 examples; kept only consumer.location.geo for spatial BPP routing - select/, on_select/: stripped consumer displayName, telephone, email; anonymized consumer id to session token; removed personal delivery address from fulfillment.stages[end]; kept store address in stages[start] - All 130 example files renamed from person-name-based (arjun, priya, rahul...) to scenario-based names (single_item_delivery, two_items_delivery, large_order_delivery, etc.) - init, on_init, confirm, on_confirm, cancel, on_cancel, status, support, on_support: renamed only (user context is correct in these endpoints per Beckn protocol) Per Beckn protocol: discover and select are user-agnostic (BAP may call independently of UI workflow for catalog caching/reorganization). User context (billing, payment, delivery address, phone, email) begins only at init.

…pecify pickup location) In a Dominos-style delivery scenario, the BAP does not know which store will fulfill the order. The BPP selects the fulfilling store based on the consumer's delivery area. The stages (including start/pickup location) are determined and returned by the BPP in on_select. The BAP's select should only specify: items/offers, fulfillment mode (DELIVERY), and participant (consumer session ID as recipient).

…ery/ hierarchy Reorganizes examples/ into a use-case taxonomy: examples/retail/food-and-beverages/IN/pizza-delivery/{discover,on_discover,select,...}/ This structure supports multiple retail verticals (food-and-beverages, electronics, apparel, etc.) and geographies (IN, US, EU, etc.) under examples/retail/. The pizza-delivery scenario represents a Domino's-style delivery use case in India.

…er/v2.0 fields - Add eligibleRegion (3 Bangalore delivery zones as GeoJSON Polygon) to all 41 offers - Add addOnItems (dips + sides) to all pizza offers; sides to wings offers - Add offerAttributes.timeRange (11:00–23:30 daily) to all offers - Add offerAttributes.holidays (Republic Day, Independence Day, Gandhi Jayanti, Christmas) to all offers - All 41 enriched offers validated against Offer/v2.0 schema (PASS) - Script: scripts/regenerate_on_discover.py

rajaneeshk90 and others added 30 commits January 14, 2026 20:44

fix(schema): correct amenityFeature array indentation bug and example…

7be86fa

… enum casing

fix(schema): correct example values to match enum definitions

be9df0b

docs: fix typos and formatting in schema descriptions and documentation

b8d7b68

fix(schema): standardize enum casing and tokenization to SCREAMING_SN…

362210d

…AKE_CASE with underscores

fix(api): rename filters.type to expressionType to avoid reserved key…

c9ec78a

…word ambiguity

fix(schema): standardize property names from snake_case to camelCase

ae5116b

fix(schema): standardize abbreviation casing - meteredEnergyKWh to me…

3ffffd9

…teredEnergyKWH

Merge pull request #67 from rajaneeshk90/spec-authoring

a0b9ee7

fix(schema): align class names with folder names - add Ev prefix to d…

cfd3b83

…omain schemas

fix(naming): standardize snake_case to camelCase in profile.json and …

cf4367a

…api/beckn.yaml

fix(enums): standardize all enum values to SCREAMING_SNAKE_CASE

2adda64

Merge pull request #68 from rajaneeshk90/spec-authoring

e029061

Beckn Protocol Specification 2.0 - Schema & Naming Standardization

Add schema design framework for Beckn Protocol 2.0

8438563

This document outlines a schema design framework for creating domain-specific bindings for the Beckn Protocol 2.0. It addresses the need for interoperability and validation in domain implementations.

Add script to forge GitHub organization layout

81da0f3

This script initializes a GitHub organization layout by creating multiple repositories and setting up their folder structures, including optional submodules for upstream repositories.

Add script to forge network organization structure

2404b8d

This script initializes a network of repositories for an Open Network GitHub organization, setting up folder structures, creating git repositories, and adding submodules.

Delete scripts/forge-the-network.sh

0e9c710

Add usage instructions to README.md

9a2c379

Change default NETWORK_SLUG to 'acmenet'

6797ce6

Update script usage from 'acme' to 'acmenet'

5dce6ab

Create style_guide.md

556dfa2

Create Attribution Guidelines for NFOs

f0eb2d8

Added a draft for Attribution Guidelines for NFOs, outlining the structure and principles for GitHub organizations to ensure proper attribution and organization of network-specific content.

Revise attribution guidelines and document structure

e2ab8ef

Updated the document to enhance clarity and structure, including sections on implementation, feedback, and attribution guidelines.

Updated heading sizes

6d5d43e

Updated heading sizes

f5b97a2

Add contributing guidelines for domain-specific schemas

e7ea008

This document outlines the structure and guidelines for adding domain-specific schemas, including folder structure, file descriptions, conventions, and when to create or extend schema bundles.

Added governance model. Reorganized some folders

065ed88

Added symlinks

a6df164

Merge branch 'core-2.0.0-rc2-issues-ravi' of github.com:beckn/protoco…

a261328

…l-specifications-v2 into core-2.0.0-rc2-issues-ravi

Update README to reflect new release candidate version

64dd72b

Added Governance docs

91b38f2

Ravi Prakash added 2 commits February 23, 2026 17:48

ravi-prakash-v requested review from abhimail, anandp504 and pramodkvarma February 24, 2026 07:11

ravi-prakash-v self-assigned this Feb 24, 2026

ravi-prakash-v added enhancement New feature or request pre-release release v2 design-discussion labels Feb 24, 2026

ravi-prakash-v requested review from nirmalnr and nirmay and removed request for pramodkvarma February 24, 2026 07:14

nirmay reviewed Feb 24, 2026

View reviewed changes

Ravi Prakash added 13 commits March 6, 2026 05:32

refactor: move examples into examples/retail/ subdirectory

4116376

Restructure so examples live under examples/retail/ (not directly under examples/) to allow future domains (mobility/, healthcare/, etc.) to coexist. Also restore EXAMPLES_DIR = examples/retail/ in validator.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Core 2.0.0 rc2 alt#92

Core 2.0.0 rc2 alt#92
ravi-prakash-v wants to merge 141 commits intomainfrom
core-2.0.0-rc2-alt

ravi-prakash-v commented Feb 24, 2026 •

edited

Loading

Uh oh!

nirmay Feb 24, 2026

Uh oh!

ravi-prakash-v Feb 24, 2026

Uh oh!

ravi-prakash-v Feb 24, 2026

Uh oh!

nirmay Feb 24, 2026

Uh oh!

nirmay Feb 24, 2026

Uh oh!

ravi-prakash-v Feb 24, 2026

Uh oh!

nirmay Feb 24, 2026

Uh oh!

abhimail Feb 24, 2026

Uh oh!

abhimail commented Feb 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

ravi-prakash-v commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Request for Comments (Core-2.0.0 LTS Release)

Context

Key architectural changes to be reviewed:

Issues Addressed

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

abhimail commented Feb 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ravi-prakash-v commented Feb 24, 2026 •

edited

Loading