Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
76 commits
Select commit Hold shift + click to select a range
7be86fa
fix(schema): correct amenityFeature array indentation bug and example…
rajaneeshk90 Jan 14, 2026
be9df0b
fix(schema): correct example values to match enum definitions
rajaneeshk90 Jan 14, 2026
b8d7b68
docs: fix typos and formatting in schema descriptions and documentation
rajaneeshk90 Jan 14, 2026
362210d
fix(schema): standardize enum casing and tokenization to SCREAMING_SN…
rajaneeshk90 Jan 14, 2026
c9ec78a
fix(api): rename filters.type to expressionType to avoid reserved key…
rajaneeshk90 Jan 14, 2026
ae5116b
fix(schema): standardize property names from snake_case to camelCase
rajaneeshk90 Jan 14, 2026
3ffffd9
fix(schema): standardize abbreviation casing - meteredEnergyKWh to me…
rajaneeshk90 Jan 14, 2026
a0b9ee7
Merge pull request #67 from rajaneeshk90/spec-authoring
ravi-prakash-v Jan 15, 2026
cfd3b83
fix(schema): align class names with folder names - add Ev prefix to d…
rajaneeshk90 Jan 16, 2026
cf4367a
fix(naming): standardize snake_case to camelCase in profile.json and …
rajaneeshk90 Jan 16, 2026
2adda64
fix(enums): standardize all enum values to SCREAMING_SNAKE_CASE
rajaneeshk90 Jan 16, 2026
e029061
Merge pull request #68 from rajaneeshk90/spec-authoring
ravi-prakash-v Jan 16, 2026
8438563
Add schema design framework for Beckn Protocol 2.0
ravi-prakash-v Jan 20, 2026
81da0f3
Add script to forge GitHub organization layout
ravi-prakash-v Jan 23, 2026
2404b8d
Add script to forge network organization structure
ravi-prakash-v Jan 23, 2026
0e9c710
Delete scripts/forge-the-network.sh
ravi-prakash-v Jan 23, 2026
9a2c379
Add usage instructions to README.md
ravi-prakash-v Jan 23, 2026
6797ce6
Change default NETWORK_SLUG to 'acmenet'
ravi-prakash-v Jan 23, 2026
5dce6ab
Update script usage from 'acme' to 'acmenet'
ravi-prakash-v Jan 23, 2026
556dfa2
Create style_guide.md
ravi-prakash-v Jan 23, 2026
f0eb2d8
Create Attribution Guidelines for NFOs
ravi-prakash-v Jan 23, 2026
e2ab8ef
Revise attribution guidelines and document structure
ravi-prakash-v Jan 27, 2026
6d5d43e
Updated heading sizes
Jan 27, 2026
f5b97a2
Updated heading sizes
Jan 27, 2026
e7ea008
Add contributing guidelines for domain-specific schemas
ravi-prakash-v Jan 27, 2026
065ed88
Added governance model. Reorganized some folders
Jan 28, 2026
a6df164
Added symlinks
Jan 28, 2026
a261328
Merge branch 'core-2.0.0-rc2-issues-ravi' of github.com:beckn/protoco…
Jan 28, 2026
64dd72b
Update README to reflect new release candidate version
ravi-prakash-v Jan 28, 2026
91b38f2
Added Governance docs
Jan 28, 2026
c747215
Added scaffolding script section. Numbered the headings
Jan 28, 2026
77854b0
Updated governance and attribution files
Jan 28, 2026
2399c39
Added references to scripts and NFO org structure
Jan 28, 2026
73eacee
Added v2-rc2 api folder to avoid downstream breaking changes
Jan 29, 2026
cbcfd90
Updated governance files - added DRAFT suffix until final review
Jan 29, 2026
d97a093
Temporarily re-added EV Charging Schema Packs to avoid breaking downs…
Jan 29, 2026
2b6a6ea
Deleted old RFC Template
Jan 29, 2026
e780839
Added network scaffolding scripts (experimental)
Jan 29, 2026
0e0671d
Re-added PaymentSettlement v1 schema and added new v2-rc2 schema to a…
Jan 29, 2026
b769d27
Added new core schema for rc2 release
Jan 29, 2026
a436de0
(Temporarily) Restored last folder structure to avoid downstream brea…
Jan 29, 2026
9556577
Updated metadata for the API spec
Jan 29, 2026
164b43c
Updated /discover endpoint description, response body schema, simplified
Jan 29, 2026
25b74d7
Reorganized API doc, added external refs, added detailed descriptions…
Feb 2, 2026
be190f7
Moved examples to external file
Feb 2, 2026
4345820
Added examples for publish and on_publish
Feb 2, 2026
f4a2c98
Added symlink to beckn.yaml inside v2 to preserve backward compatibility
Feb 2, 2026
7604aab
Fixed some URLs in v2.1/beckn.yaml
Feb 2, 2026
bdc3ad1
Added essential scripts
Feb 2, 2026
c5cc8f3
Restored v2 to original state
Feb 2, 2026
47dc7ca
Restored PaymentSettlement to old schema to preserve backward compati…
Feb 2, 2026
41728d9
Added governance folder
Feb 2, 2026
c5a7b62
Removed owl mappings from context.jsonld
Feb 2, 2026
87092db
Reverted owl mappings from context.jsonld to peserve backward compati…
Feb 2, 2026
e041ff9
Added some new schemas, added some schema.org mappings
Feb 2, 2026
d1a1d2e
Added some new schema used in beckn.yaml
Feb 2, 2026
5fb1525
Changed intro text, added a TODO - TO refine README
Feb 2, 2026
085f46c
Removed old folder nomenclature
Feb 2, 2026
729ea13
Merge pull request #76 from beckn/core-2.0.0-rc2-issues-ravi
ravi-prakash-v Feb 2, 2026
8c5ccda
Updated beckn.yaml
Feb 4, 2026
6a0d924
Moved governance model out of the governance folder
Feb 4, 2026
2a314c9
Added organized docs folder
Feb 4, 2026
68263f9
Removed governance directory
Feb 4, 2026
bd804dd
Merge pull request #82 from beckn/core-2.0.0-rc2-issues-ravi
ravi-prakash-v Feb 4, 2026
1a484f1
Reordered properties of the schemas in attributes.yaml
Feb 4, 2026
f016e97
Removed hyphenated enums in AcceptedPaymentMethods
Feb 4, 2026
8d85e0f
Deleted governance folder
Feb 4, 2026
572abe7
Linked examples to schema via and built a script for the same
Feb 5, 2026
2393ac4
Create migration-notics.svg for schema updates
ravi-prakash-v Feb 5, 2026
84b05fc
Delete schema/EvChargingOffer/v1/migration-notics.svg
ravi-prakash-v Feb 5, 2026
0dde8ac
Added a migration notice header svg
Feb 5, 2026
29a6e27
Merge branch 'core-2.1-rc1' of github.com:beckn/protocol-specificatio…
Feb 5, 2026
9b2c983
Added migration notices to all schema
Feb 5, 2026
e2f4901
Added Caution Block
Feb 5, 2026
7d2e94b
Updated attributes.yaml with a few more schema
Feb 6, 2026
4f5567b
Merge pull request #85 from beckn/core-2.1-rc1
ravi-prakash-v Feb 6, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1 +1,2 @@
.DS_Store
.cursor/*
3 changes: 0 additions & 3 deletions CONTRIBUTING.md

This file was deleted.

359 changes: 359 additions & 0 deletions GOVERNANCE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,359 @@
# Beckn Protocol Governance Model (2.x)

**Status:** Draft
**Applies to:** Beckn Protocol (Core), Domain Specifications, and Open Networks built using Beckn

---

## 0. Notice

This document is part of the **Governance Model of the Beckn Protocol** and is the **highest-precedence governance artifact** for specification evolution and interpretation.

All other documents (e.g., attribution guidelines, contribution guidelines, style guide, domain charters, network publishing guides, implementation guides) are **derived artifacts**.

When any derived artifact conflicts with this document, **this document prevails**.

## 1. Purpose and non-goals

### 1.1 Purpose

Establish a governance framework that is:

- **Lightweight:** minimal roles and minimal ceremony.
- **Airtight:** unambiguous precedence, decision rules, compatibility rules, and dispute handling.
- **Composable:** explicitly supports the reality of **Core → Domain → Network** evolution without breaking interoperability.

### 1.2 Non-goals

This governance model does not aim to:

- create membership structures, gatekeeping, or bureaucracy;
- force every network to move at the pace of core/domain;

## 2. The Beckn credo (constitutional intent)

Beckn is an open protocol designed to create an interoperable value exchange layer on the internet across diverse actors and ecosystems—globally, across domains, and across regions—while preserving agency, choice, and competition.

Governance exists to protect:
- interoperability,
- user and participant safety (security, privacy, consent),
- predictable evolution,
- and the long-term coherence of the protocol.

## 3. Constitutional principles

These principles are the primary basis for approving changes, resolving ambiguity, and interpreting disputes.

### 3.1 Interoperability-first

Any change that reduces interoperability is presumed harmful unless a compelling, globally-relevant justification and migration path exists.

### 3.2 Abstraction over specificity

Core remains domain-agnostic. Domain and network specificity belongs in the appropriate layer.

### 3.3 Optimal ignorance

If a feature is not required to achieve interoperability, it should not be standardized in the core. Prefer extension mechanisms and profiles when feasible.

### 3.4 Security by design

Changes must not introduce avoidable security vulnerabilities, ambiguity around trust, or unsafe defaults.

### 3.5 Privacy and consent by default

Changes must not weaken privacy expectations or expand data collection without explicit, scoped rationale and safeguards.

### 3.6 Scalability neutrality

The protocol should remain viable across scales—from small deployments to large ecosystems—without requiring centralized control.

### 3.7 Reusability before novelty

Prefer general patterns that can be reused across domains and regions over one-off solutions.

### 3.8 Unification over forced standardization

Aim to unify patterns and meaning while allowing diversity through profiles and extensions, instead of imposing rigid, premature uniformity.

### 3.9 Dependency over duplication (2.x emphasis)

Prefer **upstream dependencies** (versioned references, overlays, profiles) over copying, forking, and rebranding upstream content. This reduces drift and preserves interoperability.

### 3.10 Automation-first governance (2.x emphasis)

If a rule can be validated, it should be enforced through tooling/CI rather than social process.

## 4. Scope and layering (Core → Domain → Network)

### 4.1 Core

The global, domain-agnostic protocol contract: verbs, baseline schemas, semantics, normative behaviors, and conformance rules.

### 4.2 Domain

Domain specializations: domain vocabulary bindings, domain IGs, domain-level conformance guidance, and recommended workflows.

### 4.3 Network

Network-specific constraints and additions: regional policy requirements, identifiers, compliance constraints, stricter validation rules, and network-specific implementation guidance.

**Key constraint:** Network rules MUST NOT silently alter core semantics. Networks may constrain (be stricter than) the domain/core, but must not contradict core conformance.

## 5. Artifact hierarchy and precedence

### 5.1 Normative vs informative

- **Normative** text uses MUST/SHOULD/MAY and defines conformance.
- **Informative** text includes examples, diagrams, tutorials, and explanatory material unless explicitly declared normative.

### 5.2 Precedence order (highest → lowest)

1. **Governance Model (this document)**
2. **Core Specification (normative sections)**
3. **Domain Charters and Domain Specifications (normative sections)**
4. **Network Profiles and Network Conformance Rules (normative within that network)**
5. **Implementation Guides, examples, tutorials (informative unless declared normative)**

### 5.3 Conflict handling

If two artifacts conflict:
1) follow precedence order;
2) if still ambiguous, apply **constitutional principles**;
3) final interpretation authority lies with the **Core Working Group** (Section 6).

## 6. Roles (minimal and accountable)

### 6.1 Core Working Group (CWG)

**Mandate:** protect constitutional principles and decide final interpretations.

**Responsibilities:**
- approve governance amendments;
- appoint and remove Editors;
- arbitrate disputes escalated beyond Editors;
- ratify major releases (as defined in Section 9);
- publish binding interpretations when ambiguity arises.

**Size:** 5 stewards (default), adjustable only by governance amendment.

**Term:** 2 years, rolling/staggered when possible.

**Transparency:** all decisions must be documented publicly with rationale, except sensitive disclosures (Section 11).

### 6.2 Editors

**Mandate:** maintain coherence and quality of the specification.

**Responsibilities:**
- merge changes that meet requirements;
- ensure changelogs, migration notes, and conformance impact are included;
- enforce process gates and CI requirements;
- maintain release readiness and documentation hygiene.

### 6.3 Release Captain (per release)

Time-bounded role responsible for:
- coordinating release checklist completion;
- publishing release artifacts;
- ensuring validation and migration material is complete.

### 6.4 Domain Stewards (per domain)

Domains follow this governance model, adapted through a **Domain Charter** that must remain consistent with this document.

---

## 7. Selection, rotation, and removal (lightweight but real)

### 7.1 CWG selection (default mechanism)

- A public call for nominations is opened.
- Nominations must include:
- statement of intent,
- relevant experience,
- disclosure of conflicts of interest (employment, advisory roles, major commercial dependencies).
- The CWG selects candidates via rough consensus; if contested, a 2/3 CWG vote applies.
- A time-boxed public objection window is provided before finalizing appointments.

### 7.2 Removal

A steward/editor may be removed for:
- sustained inactivity,
- repeated bypassing of governance gates,
- serious misconduct (as defined by the project’s Code of Conduct),
- undisclosed conflicts of interest that materially affect trust.

Removal requires:
- documented rationale,
- an opportunity to respond,
- CWG vote (2/3).

---

## 8. Decision-making

### 8.1 Default: rough consensus + recorded objections

A decision passes when:
- objections are addressed, or
- objections are recorded with rationale and the decision proceeds with documented tradeoffs.

### 8.2 Fallback: time-boxed vote

If consensus stalls:
- Editors or CWG may call a vote with a defined deadline.
- Vote outcomes and rationale must be documented in the issue/PR.

### 8.3 Interpretation authority

When ambiguity exists in the spec:
- Editors attempt resolution using principles;
- unresolved disputes escalate to CWG;
- CWG interpretations are binding until superseded by a release.

---

## 9. Specification change lifecycle (simple, enforceable)

### 9.1 Stages

1. **Proposal** (issue/RFC with use case + motivation)
2. **Draft** (PR with working text/schema + examples)
3. **Candidate** (passes validation + includes migration notes if needed)
4. **Release** (tagged and published)
5. **Deprecated** (sunset clock starts)
6. **Removed** (major versions only)

### 9.2 Minimum requirements for normative changes

Any normative change MUST include:
- clear statement of **conformance impact**;
- **compatibility classification** (patch/minor/major);
- updated or new machine-verifiable examples when applicable;
- security/privacy implications (even if “no impact”, explicitly stated).

### 9.3 Optional maturity labels (for clarity, not ceremony)

Governance tooling MAY use labels such as:
- `proposal`, `draft`, `candidate`, `released`, `deprecated`, `removed`.

---

## 10. Versioning, compatibility, and deprecation

### 10.1 Semantic versioning (SemVer)

- **PATCH**: clarifications, fixes, non-breaking tightening with explicit rationale.
- **MINOR**: backward-compatible additions.
- **MAJOR**: breaking changes, removals, or semantic shifts.

### 10.2 Deprecation policy (airtight rule)

Deprecations MUST specify:
- replacement guidance;
- migration plan (or “no migration possible” with rationale);
- earliest version where removal may occur (MAJOR only).

---

## 11. Core–Domain–Network interaction rules (2.x foundation)

### 11.1 Networks publish profiles, overlays, and extensions—not forks

Networks SHOULD publish:
- **Network Profile**: the subset/constraints of core+domain they adopt, plus stricter validations.
- **Overlays/Addenda**: network-specific guidance layered atop domain IGs.
- **Extensions**: network-specific fields using approved extension containers or namespaces.
- **Pinned dependencies**: exact upstream versions used (core + domain).

### 11.2 Upstreaming classification (fast, explicit)

Changes discovered in networks/domains should be categorized as:
- **Core-candidate** (domain-agnostic, broadly reusable),
- **Domain-candidate** (sector-wide),
- **Network-only** (regional/policy/operational constraints).

### 11.3 Constraint rule

Networks may be **stricter** than domain/core, but must not:
- contradict core semantics,
- redefine core meanings incompatibly,
- claim core conformance while violating core requirements.

---

## 12. Attribution, licensing, and redistribution (constitutional framing)

Attribution and licensing are governance concerns because they affect trust, reuse, and interoperability.

Minimum expectations for derived works:
- preserve upstream license notices;
- include a `NOTICE` artifact listing upstream dependencies and versions;
- ensure documentation sites and compiled outputs visibly credit upstream sources.

(Operational details live in derived “Attribution Guidelines”, which must not conflict with this model.)

---

## 13. Transparency and confidentiality

The process should be transparent by default.

Exceptions:
- sensitive customer/partner information,
- security vulnerabilities prior to coordinated disclosure,
- legal or privacy-sensitive content.

If discussion happens privately, the final decision MUST be published with an anonymized rationale.

---

## 14. Enforcement (automation-first)

To keep governance lightweight and real:

- Normative PRs MUST pass automated validation (schemas, examples, conformance rules) where applicable.
- Editors MUST refuse merges that omit required change metadata.
- Repeated bypassing of gates triggers escalation to CWG.

---

## 15. Amendments to this governance model

Because this document is constitutional:

- Amendments require:
- written proposal,
- documented rationale tied to principles,
- a time-boxed public review window,
- CWG approval (2/3 minimum).
- Amendment history MUST be maintained in a changelog section or linked artifact.

---

## 16. Derived governance artifacts (registry)

The following documents are derived from (and subordinate to) this model:

- Attribution Guidelines
- Contribution Guidelines
- Style Guide
- Release Guide / Checklist
- Domain Charter Template
- Network Profile Publishing Guide
- Code of Conduct (if adopted)

Each derived document MUST include the Notice statement defined in Section 0.

---

## 17. Key changes from Governance 1.x (summary)

- Governance is now explicitly **constitutional**: precedence and interpretation are formal.
- The **Core → Domain → Network** layering is first-class and rules are explicit.
- Roles are compressed into a minimal set (CWG, Editors, Release Captain, Domain Stewards).
- Change lifecycle is tied to **enforceable gates** (validation + migration + conformance impact).
- Dependency-over-duplication is elevated as a governance principle to reduce drift and preserve interoperability.
- Deprecation and removal rules are formalized (sunset clocks; removal via major versions only).
- Automation-first enforcement is emphasized to reduce human bureaucracy.
10 changes: 6 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,20 @@
# Beckn Protocol v2.0.0 (Release Candidate)
This repository contains the release candidate of the latest major version release of Beckn Protocol - v2.0.0, defining a JSON-LD and schema.org-aligned core schema, updated APIs, and reference flows for the next generation of Beckn networks. It introduces a catalog-first Catalog Discovery Service (CDS) (replacing the Beckn Gateway for discovery), a DeDi-compliant Network Registry, and a modular “core + schema packs” model to enable strong design-time and run-time composability and global semantic interoperability.
# Beckn Protocol Version 2
This repository contains the the latest major version release of Beckn Protocol - Version 2, defining a JSON-LD and schema.org-aligned core schema, updated APIs, and reference flows for the next generation of Beckn networks. It introduces a catalog-first Catalog Discovery Service (CDS) (replacing the Beckn Gateway for discovery), a DeDi-compliant Network Registry, and a modular “core + schema packs” model to enable strong design-time and run-time composability and global semantic interoperability.

TODO: Add version history table

## 1. High-level goals of v2

Beckn v2 reorganizes the protocol around:
- **Global semantic interoperability** via JSON-LD and deep alignment with schema.org and other globally interoperable linked data schemas.
- Design-time composability: modular core + pluggable domain-specific “schema”.
- **Run-time composability**: independent but interoperable actors (BAP, BPP, CDS, Registry, Agents) that can be recombined without changing the core.
- **Run-time composability**: independent but interoperable actors (BAP, BPP, CDS, Registry) that can be recombined without changing the core.
- **Registry and discovery modernization**:
- BG → CDS: Beckn Gateway is replaced by a Catalog Discovery Service (CDS).
- Legacy Registry → DeDi-compliant Registry: Network Registry becomes compliant with the Decentralized Directory (DeDi) protocol. 


## 2. Schema changes: from v1.x to v2
## 2. Schema changes: from v1 to v2

### 2.1 From OpenAPI/JSON Schema to JSON-LD + schema.org

Expand Down
4 changes: 4 additions & 0 deletions api/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Beckn Protocol 2.0 API Specification

> Note: All release candidate versions of the protocol can be found under specific folders named `v2-rc*` to avoid any downstream impact. However, these folders are only temporary and will be removed upon release of a minor version of the specification. The long term support (LTS) version of the API specs can be found in the beckn.yaml file in this folder.

Loading