diff --git a/api/registry/README.md b/api/registry/README.md
index 0e6977c5..d45347b1 100644
--- a/api/registry/README.md
+++ b/api/registry/README.md
@@ -41,7 +41,7 @@ openapi: 3.0.0
info:
title: Beckn Protocol Core
description: Beckn Core API specification
- version: "1.0.0"
+ version: "1.2.0"
security:
- SubscriberAuth: []
diff --git a/api/transaction/build/transaction.yaml b/api/transaction/build/transaction.yaml
index 11472c94..26e578b2 100644
--- a/api/transaction/build/transaction.yaml
+++ b/api/transaction/build/transaction.yaml
@@ -738,10 +738,6 @@ components:
$ref: '#/components/schemas/Descriptor'
price:
$ref: '#/components/schemas/Price'
- quantity:
- description: The Selling quantity of the Item
- allOf:
- - $ref: '#/components/schemas/ItemQuantity'
Address:
description: Describes a postal address.
type: string
@@ -824,6 +820,7 @@ components:
format: date-time
cancelled_by:
type: string
+ description: 'Represents the entity which initiated a cancellation'
enum:
- CONSUMER
- PROVIDER
@@ -886,6 +883,7 @@ components:
type: string
format: date-time
ttl:
+ description: Represents the time for which the catalog will be valid.
$ref: '#/components/schemas/Duration'
Category:
description: A label under which a collection of items can be grouped.
@@ -929,8 +927,10 @@ components:
type: object
properties:
phone:
+ description: Phone number of an entity.
type: string
email:
+ description: Email address of an entity.
type: string
jcard:
type: object
@@ -1004,9 +1004,11 @@ components:
type: object
properties:
id:
+ description: A unique identifier for the credential
type: string
type:
type: string
+ description: 'Type of the credential, i.e. token, SAML, ssh keys etc.'
default: VerifiableCredential
url:
description: URL of the credential
@@ -1069,8 +1071,6 @@ components:
url:
type: string
format: uri
- label:
- type: string
mime_type:
description: 'Describes the contents of the uri field. If the value is text/html, it is recommended for the BAP to render the contents inside a webview. This generally does not render a good user experience on the BAP, hence the payment page developers are recommended to develop their payment pages in a mobile-friendly manner.'
type: string
@@ -1122,7 +1122,7 @@ components:
type: object
properties:
url:
- description: 'The URL from where the form can be fetched. The content fetched from the url must be processed as per the mime_type specified in this object. Once fetched, the rendering platform can choosed to render the form as-is as an embeddable element; or process it further to blend with the theme of the application. In case the interface is non-visual, the the render can process the form data and reproduce it as per the standard specified in the form.'
+ description: 'The URL from where the form can be fetched. The content fetched from the url must be processed as per the mime type specified in this object. Once fetched, the rendering platform can choosed to render the form as-is as an embeddable element; or process it further to blend with the theme of the application. In case the interface is non-visual, the the render can process the form data and reproduce it as per the standard specified in the form.'
type: string
format: uri
data:
@@ -1139,8 +1139,10 @@ components:
- application/html
resubmit:
type: boolean
+ description: 'Set to true if the resubmission of a form is required. It could be due to a validation error, or session timeout etc. Otherwise, it is set to false.'
submission_id:
type: string
+ description: A unique identifier associated with a submission of a form.
format: uuid
auth:
type: object
@@ -1149,6 +1151,7 @@ components:
$ref: '#/components/schemas/Descriptor'
value:
type: string
+ description: 'The token that will be used for the authentication. It could be JWT (JSON Web Token), OAuth etc.'
Fulfillment:
description: Describes how a an order will be rendered/fulfilled to the end-customer
type: object
@@ -1171,7 +1174,7 @@ components:
allOf:
- $ref: '#/components/schemas/FulfillmentState'
documents:
- description: The Documents associated to the fullfilment
+ description: 'The Documents associated with the fullfilment object. For example in the case of online courses, it could represent a certificate of completion of a course.'
type: array
items:
$ref: '#/components/schemas/Document'
@@ -1524,7 +1527,7 @@ components:
description: This object contains a url to a media file.
type: object
properties:
- mimetype:
+ mime_type:
description: 'indicates the nature and format of the document, file, or assortment of bytes. MIME types are defined and standardized in IETF''s RFC 6838'
type: string
url:
@@ -1818,20 +1821,31 @@ components:
properties:
currency:
type: string
+ description: 'Medium of exchange i.e. INR, USD etc.'
value:
type: string
+ description: 'Monetary cost of an item, a decimal represented as string'
estimated_value:
type: string
+ description: 'Monetary cost of an item, a decimal represented as string'
computed_value:
type: string
+ description: 'Monetary cost of an item, a decimal represented as string'
listed_value:
type: string
+ description: 'Monetary cost of an item, a decimal represented as string'
offered_value:
type: string
+ description: 'Monetary cost of an item, a decimal represented as string'
minimum_value:
type: string
+ description: 'Monetary cost of an item, a decimal represented as string'
maximum_value:
type: string
+ description: 'Monetary cost of an item, a decimal represented as string'
+ unit:
+ type: string
+ description: 'A custom unit of payment, i.e. carbon credit, bitcoin, etc.'
Provider:
description: Describes the catalog of a business.
type: object
diff --git a/docs/BECKN-000-Terminology.md b/docs/BECKN-000-Terminology.md
new file mode 100644
index 00000000..862cade6
--- /dev/null
+++ b/docs/BECKN-000-Terminology.md
@@ -0,0 +1,98 @@
+# BECKN-000: Terminology
+
+## License:
+This document is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/).
+
+
+
+## Category:
+Terminology
+
+## Published on:
+Sept 9th, 2025
+
+## Last Updated on:
+Sept 16th, 2025
+
+## History:
+Click on this [link](https://github.com/beckn/protocol-specifications/commits/core-1.2-release/docs/BECKN-000-Terminology.md) to view the history of changes to this document
+
+## Issues:
+To view issues related to this document, click on this [link](https://github.com/beckn/protocol-specifications/issues?q=is%3Aissue+label%3ABECKN-000)
+
+## Discussions:
+To view discussions related to this document, click on this [link](https://github.com/beckn/protocol-specifications/discussions?discussions_q=label%3ABECKN-000)
+
+## Authors:
+1. [Ravi Prakash](https://github.com/ravi-prakash-v)
+
+## Reviewers:
+1. [Sujith Nair](https://github.com/sjthnrk)
+2. [Pramod Varma](https://github.com/pramodkvarma)
+3. [Venkatraman Mahadevan](https://github.com/venkatramanm)
+
+# Abstract
+
+This document provides a comprehensive glossary of terms and definitions used across the Beckn Protocol specifications. It serves as a reference for network participants, implementers, and stakeholders to ensure consistent understanding of key concepts and terminology.
+
+# Scope
+
+This document defines the standard terminology used across all Beckn Protocol specifications and related documents. It is intended for:
+
+1. Network participants implementing Beckn Protocol
+2. Developers building on Beckn-enabled networks
+3. Policy makers and governance bodies
+4. Technical writers and documentation maintainers
+
+## Prerequisites
+
+Readers of this document should have:
+
+1. Basic understanding of distributed systems and API protocols
+2. Familiarity with commerce and transaction terminology
+3. Knowledge of the Beckn Protocol architecture
+
+# Introduction
+
+The Beckn Protocol ecosystem involves multiple stakeholders, technical concepts, and domain-specific terminology. This document establishes a common vocabulary to ensure clear communication and consistent implementation across all Beckn-enabled networks.
+
+# Terminology
+
+1. **Network :** In the context of beckn protocol, a network refers to an open commerce network formed by the instantiation of beckn protocol specification with a standard network policy
+2. **Network Participant:** Any platform that has implemented beckn protocol specification and is part of an open commerce network
+3. **Schema:** These are JSON Schema objects with properties as defined in the core specification
+4. **Action:** These are specific events that occur during the lifecycle of a typical commerce transaction
+5. **Network Policy**: These are specific rules that apply to the implementers of a network while developing the protocol API middleware
+6. **BAP (Beckn Application Platform)**: A platform that enables buyers to discover and transact with sellers on a Beckn-enabled network
+7. **BPP (Beckn Provider Platform)**: A platform that enables sellers to list their services and fulfill orders on a Beckn-enabled network
+8. **BG (Beckn Gateway)**: A network infrastructure component used for provider discovery; it routes discovery requests from BAPs to relevant BPPs and enforces basic routing and validation policies
+9. **Registry**: A centralized directory service that maintains information about network participants, their capabilities, and network policies
+
+# Examples
+
+## Common Usage Examples
+
+- **Network**: "The mobility network in Bangalore uses Beckn Protocol with specific policies for ride-sharing and public transport"
+- **Network Participant**: "Uber and Ola are both network participants in the mobility network"
+- **Schema**: "The Order schema defines the structure for transaction data"
+- **Action**: "The search action initiates the discovery of available services"
+- **Network Policy**: "The network policy requires all transactions to include location data"
+- **BAP**: "The Swiggy app acts as a BAP, allowing users to discover and order food from restaurants"
+- **BPP**: "Restaurant partners use a BPP platform to list their menus and manage orders"
+- **BG**: "The beckn gateway is used for provider discovery and routes search requests from BAPs to relevant BPPs in the food delivery network"
+- **Registry**: "The registry maintains a directory of all food delivery BPPs and their service capabilities"
+
+# Recommendations
+
+- Use terminology consistently across all documentation and implementations
+- Refer to this document when introducing new terms or concepts
+- Update this document when new terminology is introduced in the protocol
+- Cross-reference related terms to maintain clarity
+
+# Acknowledgements
+
+The authors would like to thank the following people for their support and contributions to this document.
+
+* Pramod Varma (Beckn Foundation)
+* Sujith Nair (Beckn Foundation)
+* Venkataramanan Mahadevan (Humbhionline)
diff --git a/docs/BECKN-001-Layering-Network-Policy-Draft-01.md b/docs/BECKN-001-Layering-Network-Policy.md
similarity index 70%
rename from docs/BECKN-001-Layering-Network-Policy-Draft-01.md
rename to docs/BECKN-001-Layering-Network-Policy.md
index ed7a8b2b..6553b184 100644
--- a/docs/BECKN-001-Layering-Network-Policy-Draft-01.md
+++ b/docs/BECKN-001-Layering-Network-Policy.md
@@ -1,104 +1,96 @@
# BECKN-001:Layering Network Policy on the Specification
+## License:
+This document is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/).
+
+
+
## Category:
Network Policy
+
+## Published on:
December 10, 2021
## Last Updated on:
-July 2nd, 2024
+Sept 16th, 2025
-## License:
-This document is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/).
+## History:
+Click on this [link](https://github.com/beckn/protocol-specifications/commits/core-1.2-release/docs/BECKN-001-Layering-Network-Policy.md) to view the history of changes to this document
-
+## Issues:
+To view issues related to this document, click on this [link](https://github.com/beckn/protocol-specifications/issues?q=is%3Aissue+label%3ABECKN-001)
+
+## Discussions:
+To view discussions related to this document, click on this [link](https://github.com/beckn/protocol-specifications/discussions?discussions_q=label%3ABECKN-001)
## Authors:
-1. Ravi Prakash : ravi@becknprotocol.io
+1. [Ravi Prakash](https://github.com/ravi-prakash-v)
## Reviewers:
-1. Sujith Nair : sujith@becknprotocol.io
-2. Pramod Varma : pramod@ekstep.org
-3. Venkatraman Mahadevan : venkatramanm@gmail.com
+1. [Sujith Nair](https://github.com/sjthnrk)
+2. [Pramod Varma](https://github.com/pramodkvarma)
+3. [Venkatraman Mahadevan](https://github.com/venkatramanm)
+
+# Abstract
-replace email with github ids.
+Beckn Protocol is an abstracted but **highly configurable** specification. A network is an **instantiation** of the core protocol specification. However, to instantiate a network, additional policies must be layered via machine-readable configuration files. These configurations vary from network to network depending upon the use cases supported by them. These configurations allow sector-specific policies to be applied on a network _without_ changing the underlying core specification. This document defines a methodology to publish these network-specific policies as machine-readable documents that can be read by network participants to create API validation middleware.
# Scope
-This document contains design principles and methodologies that should be used to configure beckn protocol specification for various sector-specific networks. This document is intended for the following audience.
-1. Anyone who is using beckn protocol specifications to design open commerce networks for a specific set of use cases
+This document contains design principles and methodologies that should be used to configure beckn protocol specification for various sector-specific networks. This document is intended for the following audience:
+
+1. Anyone who is using beckn protocol specifications to design open commerce networks for a specific set of use cases
-# Prerequisites
+## Prerequisites
Readers of this document must:
1. Have knowledge of the core protocol specification
2. Have knowledge of the Architecture of Open Commerce Networks instantiated using beckn protocol.
-3. Have knowledge of Open API 3.0 Specification
-
-# Abstract
+3. Have knowledge of Open API 3.1 Specification
-Beckn Protocol is an abstracted but **highly configurable** specification. A network is an **instantiation** of the core protocol specification. However, to instantiate a network, additional policies must be layered via machine-readable configuration files. These configurations vary from network to network depending upon the use cases supported by them. These configurations allow sector-specific policies to be applied on a network _without_ changing the underlying core specification. This document defines a methodology to publish these network-specific policies as machine-readable documents that can be read by network participants to create API validation middleware.
-
-# Context
+# Introduction
-Beckn protocol is a set of specifications that enables any two platforms to perform commercial transactions by implementing an API with standard action calls and schema. These specifications are by-design generic and therefore, sector agnostic. However, to establish a smart contract between a BAP and a BPP, additional domain-specific information must sometimes be transmitted between the platforms. For example, a logistics network might have different allowed values for the types of fulfillments it supports like “HOME-DELIVERY” and “STORE-PICKUP” as opposed to an education network where the allowed values may be “TELE-CONSULTATION” or “PHYSICAL-CONSULTATION''. These values are not standardized in the core schema but rather exist as _policies_ framed by the architects of a beckn-enabled open commerce network.
+Beckn protocol is a set of specifications that enables any two platforms to perform commercial transactions by implementing an API with standard action calls and schema. These specifications are by-design generic and therefore, sector agnostic. However, to establish a smart contract between a BAP and a BPP, additional domain-specific information must sometimes be transmitted between the platforms. For example, a logistics network might have different allowed values for the types of fulfillments it supports like "HOME-DELIVERY" and "STORE-PICKUP" as opposed to an education network where the allowed values may be "TELE-CONSULTATION" or "PHYSICAL-CONSULTATION''. These values are not standardized in the core schema but rather exist as _policies_ framed by the architects of a beckn-enabled open commerce network.
Similarly, a network might put a limit on the number of matched items that can be returned in a single catalog object. To maintain interoperability but also allow its configurability, beckn protocol specification governance restricts modification of the core schema and actions. However, to allow its adaptability, instead of forcing all specification users to adhere to the core specification and, beckn protocol governance allows creation of network-specific policies. These policies allow sector-agnostic rules and validation criteria to be published along with the specification based on recommendations and comments received from various ecosystem contributors and network participants implementing the protocol. These rules and policies must be layered on the core specification and published as a separate document that can be accessed by the network participants in a machine readable manner.
-
-# Terminology ( should go to separate RFC - BECKN-012-Terminology.md )
-
-1. **Network :** In the context of beckn protocol, a network refers to an open commerce network formed by the instantiation of beckn protocol specification with a standard network policy
-2. **Network Participant:** Any platform that has implemented beckn protocol specification and is part of an open commerce network
-3. **Schema:** These are JSON Schema objects with properties as defined in
-4. **Action:** These are specific events that occur during the lifecycle of a typical commerce transaction
-5. **Network Policy**: These are specific rules that apply to the implementers of a network while developing the protocol API middleware
-
-
# Problem
Given the Non-Derivative nature of the core specification, how can networks allow configurability of the core specification without disrupting global interoperability?
+## Forces
-# Forces
-
-Beckn protocol governance allows highly specific configurations to the core specification via network policies. These policies must be designed not to modify the underlying schema itself but rather govern the values these schema properties are allowed to take like,
-
-
+Beckn protocol governance allows highly specific configurations to the core specification via network policies. These policies must be designed not to modify the underlying schema itself but rather govern the values these schema properties are allowed to take like:
1. Adding enumerations to core schema properties
2. Adding additional qualifiers like min / max and defaults
3. Adding sector-specific and region-specific standards to using regex patterns
+## Expected Outcomes after reading this document
-# Expected Outcomes after reading this document
-
-After reading this document, the reader should be able to
-
-
+After reading this document, the reader should be able to:
1. Understand how policies can be layered on the core specification
2. Understand how a machine-readable network-specific protocol can be published
3. Understand how such policies can be made available as an infrastructure on a network for dynamic network policy transmission and enforcement
-
-# Network Policy as Code
+# Solution
A network policy is a set of rules that must be published by the architects of beckn-enabled open commerce networks as a machine-readable specification to allow its participants to create protocol validation middleware in their implementations. This specification should **inherit** all the attributes of the core specification along with some additional constraints on the usage of the specification during network transactions.
+# Implementation Details
-## Inheritance and Polymorphism in Open API 3.0
-
-The core specification currently exists in the form of an Open API Specification 3.0 document with some reserved modifications. To layer policy on the specification, beckn protocol governance allows layering of policies by way of configuration. This configuration is done on the core Open API document by using the inheritance and polymorphism feature of Open API Specification 3.0. Inheritance and polymorphism are terms used in Object Oriented Design and are applicable to beckn protocol specifications as well. To learn more about Inheritance and Polymorphism as a generic concept, click here.
+## Inheritance and Polymorphism in Open API 3.1
-## Applying Network-Specific Policies using Open API 3.0
+The core specification currently exists in the form of an Open API Specification 3.1 document with some reserved modifications. To layer policy on the specification, beckn protocol governance allows layering of policies by way of configuration. This configuration is done on the core Open API document by using the inheritance and polymorphism feature of Open API Specification 3.1. Inheritance and polymorphism are terms used in Object Oriented Design and are applicable to beckn protocol specifications as well. To learn more about Inheritance and Polymorphism as a generic concept, click here.
+## Applying Network-Specific Policies using Open API 3.1
### Adding enumerations, defaults and min / max values
It is possible to add **enumerations**, **defaults**, **min/max** values to any schema. For example, a network may allow only **search** and **confirm** actions. Hence the `context.action` attribute will contain an enumeration of only `search / on_search` and `confirm / on_confirm` API calls as shown below.
-
```
ContextPolicy1:
description: Describes the context policy of a message on this network
@@ -129,10 +121,8 @@ ContextPolicy1:
maximum: P1M
```
-
Another example is related to the **Rating** schema
-
```
Rating:
description: Describes the rating of a person or an object.
@@ -149,10 +139,8 @@ Rating:
type: number
```
-
If a network policy requires rating to range between 1 and 10, it must create a Rating Policy schema that inherits the properties of the Core **Rating** Schema as shown below
-
```
RatingPolicy1:
description: Describes the context policy of a message on this network
@@ -166,12 +154,9 @@ RatingPolicy1:
maximum: 10
```
-
-
### Adding alternative schemas
-Sometimes it is possible to have requests and responses that can be described by several alternative schemas. In OpenAPI 3.0, to describe such a model, we can use the oneOf or anyOf keywords. For example, while transmitting payment terms from BPP to the BAP via the **on_init** action, multiple payment endpoints can be sent in the _params_ property of the **Payment** schema as shown below.
-
+Sometimes it is possible to have requests and responses that can be described by several alternative schemas. In OpenAPI 3.1, to describe such a model, we can use the oneOf or anyOf keywords. For example, while transmitting payment terms from BPP to the BAP via the **on_init** action, multiple payment endpoints can be sent in the _params_ property of the **Payment** schema as shown below.
```
PaymentParams:
@@ -224,12 +209,9 @@ PaymentGatewayParams:
type: string
```
-
-
### Adding required fields
-It is also possible to add **required** properties to any attribute. For example, in the domain of mobility, the origin location’s gps coordinate must be a required field.
-
+It is also possible to add **required** properties to any attribute. For example, in the domain of mobility, the origin location's gps coordinate must be a required field.
```
FulfillmentPolicy1:
@@ -303,16 +285,12 @@ FulfillmentPolicy1:
$ref: '#/components/schemas/Rateable'
tags:
$ref: '#/components/schemas/Tags'
-
```
-
-
### Adding standards and formats
A network in India might choose to use the NIC 2004, Industry Classification Codes to identify the Industry Sector of a network via the **Context.domain** attribute as shown below
-
```
Domain:
description: Describes the industry domain of an object in the country of India.
@@ -320,12 +298,9 @@ Domain:
pattern: "^nic2004:(52110|52114)"
```
+The above pattern indicates that the network allows only Retail and Delivery transactions
-
- The above pattern indicates that the network allows only Retail and Delivery transactions
-
-Adding domain-specific, region-specific, technology-specific attributes or schema to the **Tags** object to accommodate extensions that might get abstracted and merged into core specifications in future releases. For example, a retail network should publish a list of allowed tags for various schemas used by a network.
-
+Adding domain-specific, region-specific, technology-specific attributes or schema to the **Tags** object to accommodate extensions that might get abstracted and merged into core specifications in future releases. For example, a retail network should publish a list of allowed tags for various schemas used by a network.
```
Tags:
@@ -334,16 +309,14 @@ Tags:
type: string
```
-
All these extensions must be published as part of a separate document called **Network Implementation Policy**
-It is recommended that this document be published along with the API specification of that network using the **externalDocs** attribute as defined by Open API Specification 3.0
+It is recommended that this document be published along with the API specification of that network using the **externalDocs** attribute as defined by Open API Specification 3.1
More Examples:
The specifications allow a network to define a master list of Rating Categories that can be used by NPs. So when creating the API specification of a network, the **rating_categories ** API must define all the allowed rating categories as enums as shown below.
-
```
Rating:
description: Describes the rating of an object.
@@ -373,3 +346,56 @@ Rating:
$ref: '#/components/schemas/FeedbackUrl/properties/params/properties/feedback_id'
required: false
```
+
+# Examples
+
+## Network Policy Implementation Example
+
+A concrete example of network policy implementation can be found in the [DEG2.0 Layer2 Services specification](https://github.com/beckn/missions/blob/main/DEG2.0/layer2/ev-charging/charging_1.1.0.yaml). This YAML file demonstrates how network-specific policies are layered on the core Beckn protocol specification for the DEG2.0 network.
+
+This example shows:
+- How to define service-specific policies
+- Implementation of network-specific constraints
+- Real-world application of the layering methodology described in this document
+
+# Recommendations
+
+- Policy design
+ - Keep the core schema immutable; express all network constraints as overlays (enums, min/max, patterns, required) via composition (allOf/oneOf/anyOf)
+ - Prefer additive, non-breaking constraints; avoid narrowing fields that are widely used across domains unless mandated by governance
+ - Separate “what” (policy rules) from “how” (implementation specifics); encode rules so any NP can enforce them consistently
+
+- Schema layering (OpenAPI 3.1)
+ - Use allOf to inherit from core components; never copy-paste core schemas
+ - Constrain only the necessary properties; avoid redefining unchanged fields
+ - Use oneOf/anyOf for alternative policy shapes; add clear descriptions for consumers
+ - Keep policy component names and $ref paths stable and human-readable
+
+- Versioning and compatibility
+ - Version policies independently of the core (e.g., policy_version vs core_version)
+ - Declare explicit compatibility matrices (policy_version ↔ core_version)
+ - Use semantic versioning for policy bundles; increment MINOR for additive rules, MAJOR for breaking changes
+ - Publish deprecation windows and migration notes for each change
+
+- Publication and discoverability
+ - Publish machine-readable policies alongside the network API using OpenAPI 3.1 externalDocs
+ - Provide a canonical policy manifest (index) with links, versions, signatures, and checksums
+ - Maintain a changelog with human-readable summaries and diffs of rule changes
+
+- Validation and conformance
+ - Provide JSON Schema/OpenAPI-first policy artifacts that NPs can plug into their validation middleware
+ - Offer a conformance test suite (positive/negative cases) and golden test vectors
+ - Automate policy gating in CI for NPs (schema validation, example replay, signature checks)
+
+- Security and integrity
+ - Sign policy artifacts (manifest + individual files); publish public verification keys
+ - Include checksums for each artifact; verify at download time and at runtime before load
+ - Pin policy versions in production; roll out updates via controlled staged deployments
+
+# Acknowledgements
+
+The authors would like to thank the following people for their support and contributions to this document.
+
+* Pramod Varma (Beckn Foundation)
+* Sujith Nair (Beckn Foundation)
+* Venkataramanan Mahadevan (Humbhionline)
diff --git a/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md b/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md
index 2c6984cd..4aa33368 100644
--- a/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md
+++ b/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md
@@ -1,69 +1,98 @@
-# Payments on Beckn-Enabled Networks
+# BECKN-002:Payments on Beckn-Enabled Networks
+## License:
+This document is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/).
-## ID:
-BECKN-RFC-002
-
-## Draft ID
-Draft-01
-
-## Title:
-Payments on Beckn-Enabled Networks
+
## Category:
-Payments
-
-## Status:
-Protocol Draft
+Payment
## Published on:
December 10, 2021
-## Expires on:
-April 05, 2022 or Date of publication of next draft which ever is earlier
+## Last Updated on:
+Sept 16th, 2025
-## License:
-CC-BY-ND
+## History:
+Click on this [link](https://github.com/beckn/protocol-specifications/commits/core-1.2-release/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md) to view the history of changes to this document
+
+## Issues:
+To view issues related to this document, click on this [link](https://github.com/beckn/protocol-specifications/issues?q=is%3Aissue+label%3ABECKN-002)
+
+## Discussions:
+To view discussions related to this document, click on this [link](https://github.com/beckn/protocol-specifications/discussions?discussions_q=label%3ABECKN-002)
## Authors:
-1. Ravi Prakash : ravi@becknfoundation.org
+1. [Ravi Prakash](https://github.com/ravi-prakash-v)
## Reviewers:
-1. Sujith Nair : sujith@becknfoundation.org
-2. Pramod Varma : pramod@ekstep.org
+1. [Sujith Nair](https://github.com/sjthnrk)
+2. [Pramod Varma](https://github.com/pramodkvarma)
+3. [Venkatraman Mahadevan](https://github.com/venkatramanm)
+
+# Abstract
+
+In beckn-enabled networks, payments settle outside the protocol.
+This document defines the Payment Contract Agreement (exchange of terms and proof of payment between BAP and BPP) and provides implementation guidance for interoperable use across regional payment systems.
+# Scope
+
+This document is intended for the following audience:
+
+1. Anyone implementing beckn-enabled applications that require payment functionality
+2. Network facilitators designing payment policies for beckn-enabled networks
+3. Payment service providers integrating with beckn protocol
+4. Developers building payment middleware for beckn applications
+
+## Prerequisites
+
+Readers of this document must:
+
+1. Have knowledge of the core beckn protocol specification
+2. Have understanding of payment systems and digital payment methods
+3. Have knowledge of Open API 3.0 Specification
# Introduction
-In beckn-enabled networks, payments are expected to be settled outside the network. Meaning, the implementers of beckn-enabled applications are expected to use existing payment infrastructures in their region(s) of operation to collect, process and settle payments. Since payments is a highly regulated industry across the world, different geo-political regions may choose different standards and modalities to enable digital payments. Therefore, it is left to the implementer to templatize such region-specific payment modalities and dynamically enable them on the respective user applications of both the payer and payee, based on their respective geo-political locations.
+In beckn-enabled networks, payments are expected to be settled outside the network. Meaning, the implementers of beckn-enabled applications are expected to use existing payment infrastructures in their region(s) of operation to collect, process and settle payments. Since payments is a highly regulated industry across the world, different geo-political regions may choose different standards and modalities to enable digital payments. Therefore, it is left to the implementer to templatize such region-specific payment modalities and dynamically enable them on the respective user applications of both the payer and payee, based on their respective geo-political locations.
-*it is left to the implementer to templatize such region-specific payment modalities and dynamically enable them on the respective user applications of both the payer and payee, based on their respective geo-political locations...*
-==
+# Problem
-# Payment Infrastructure on a Beckn-enabled Network
+How to enable payment transactions in beckn-enabled networks while maintaining compliance with regional payment regulations and ensuring interoperability across different payment systems?
+
+# Solution
+
+On the protocol layer, only the terms of payment and the proof of payment are exchanged between the BAP and the BPP. Together, the exchange of terms; and the agreement of those terms between the payer and the payee are together known as a **Payment Contract Agreement**.
+
+It is important to note that beckn protocol only supports the Payment Contract Agreement. The actual act of payment and settlements like charging a card, source bank account debit and destination account remittance are performed asynchronously by integrating with the already established payment infrastructure available in the region of operation like banking APIs, payment gateway / aggregator services, payment processors, open payment protocols etc.
+
+# Implementation Details
+
+## Payment Infrastructure on a Beckn-enabled Network
-# Payment Contract Agreement
+## Payment Contract Agreement
On the protocol layer, only the terms of payment and the proof of payment are exchanged between the BAP and the BPP. Together, the exchange of terms; and the agreement of those terms between the payer and the payee are together known as a **Payment Contract Agreement**.
It is important to note that beckn protocol only supports the Payment Contract Agreement. The actual act of payment and settlements like charging a card, source bank account debit and destination account remittance are performed asynchronously by integrating with the already established payment infrastructure available in the region of operation like banking APIs, payment gateway / aggregator services, payment processors, open payment protocols etc.
-# Payment Contract Roles
+## Payment Contract Roles
There are two roles that participate in a payment contract agreement on beckn protocol. They are
- Payer (belongs to BAP): The entity that pays for an order.
- Payee (belongs to BPP): The entity that receives payment for the order
-# Payment Terms
+## Payment Terms
The money transfer from a Payer to a Payee may go via different channels and modes. For example, a customer may use his credit card to pay the BAP say, at time T=0. The BAP may pay the BPP on T=1 as part of a bulk settlement. The BPP may pay the provider on T=2. And finally the provider may settle the money to the store owner or agent at T=3. At each stage, the intermediary may charge a small transaction fee to process that payment. In beckn protocol, only the settlement terms between the BAP and the BPP are considered. All other payment terms are outside the scope of beckn protocol and are strictly within the scope of the business partnership agreement between the respective parties.
-## BAP Terms
+### BAP Terms
During a transaction, a BAP can inform the BPP its terms and conditions about collecting the payment.
- If it is going to collect the money first
-## BPP Payment Terms
+### BPP Payment Terms
The BPP must send its terms to the BAP . These terms contain the following information:
- The amount that needs to be paid in a specific currency
- The payment endpoint in url format. The supported url schemes are
@@ -73,11 +102,11 @@ The BPP must send its terms to the BAP . These terms contain the following infor
- When the payment must be settled with the Payee
- Status of the payment
-# Payment Contract Sequence
+## Payment Contract Sequence
-# Payment Scenarios on beckn-enabled Networks
+## Payment Scenarios on beckn-enabled Networks
An end-to-end payment flow between a BAP and a BPP comprises of the following activities
@@ -86,21 +115,21 @@ An end-to-end payment flow between a BAP and a BPP comprises of the following ac
From the buyer to the seller, money may flow through different payment intermediaries. Each intermediary may collect a small transaction fee for processing the transaction. Some common flows are shown below
-## Flow 1: BAP Collects Payment from Buyer
+### Flow 1: BAP Collects Payment from Buyer
1. BAP informs BPP that it will be collecting the payment first and then settling it with BPP via beckn protocol APIs
-2. BPP agrees to BAP’s terms and allows BAP to collect the payment from the buyer via beckn protocol APIs
-3. The BAP shows a payment interface to the buyer and the buyer makes the payment. The money gets deposited into the BAP’s bank account. This is NOT done via any beckn protocol APIs
-4. BAP pays BPP : The BAP transfers the amount to the BPP’s bank account
+2. BPP agrees to BAP's terms and allows BAP to collect the payment from the buyer via beckn protocol APIs
+3. The BAP shows a payment interface to the buyer and the buyer makes the payment. The money gets deposited into the BAP's bank account. This is NOT done via any beckn protocol APIs
+4. BAP pays BPP : The BAP transfers the amount to the BPP's bank account
5. BPP pays the Seller
-## Flow 2: BPP collects payment from Buyer
+### Flow 2: BPP collects payment from Buyer
1. BAP informs BPP that it will NOT be collecting the payment and the BPP should provide the payee details for collection
-2. BPP agrees to BAP’s terms and provides the payee details. These details can include a link to the BPP’s payment interface; bank account details or a virtual payment address (in case of UPI)
-3. BPP renders the payment interface or other payment details on the BAP’s UI
+2. BPP agrees to BAP's terms and provides the payee details. These details can include a link to the BPP's payment interface; bank account details or a virtual payment address (in case of UPI)
+3. BPP renders the payment interface or other payment details on the BAP's UI
4. The BAP user makes the payment directly to the BPP
5. BAP queries the BPP for the status of the transaction by providing the proof of payment via beckn protocol APIs
6. BPP periodically checks for transaction success from its Payment Service Provider
@@ -108,25 +137,27 @@ From the buyer to the seller, money may flow through different payment intermedi
-# Invoking the Payment Flow on the BAP app
+## Invoking the Payment Flow on the BAP app
-Whenever a BAP user wants to checkout an order, the BAP should call the init action on the BPP’s API. The init message contains the final draft of the order that contains the items selected, billing and fulfillment details, or any other information the BPP might need to checkout the order. By calling this action, the BAP should expect the BPP to send the terms of payment along with any additional information needed to make the payment.
+Whenever a BAP user wants to checkout an order, the BAP should call the init action on the BPP's API. The init message contains the final draft of the order that contains the items selected, billing and fulfillment details, or any other information the BPP might need to checkout the order. By calling this action, the BAP should expect the BPP to send the terms of payment along with any additional information needed to make the payment.
-Once the BPP receives the init message, it should send the acknowledgement that it has received the message. The BPP should then send the terms of payment by calling the on_init action on the BAP’s API. Upon receipt of the on_init API call, The BAP must invoke the payment flow on its app to collect the payment from the buyer and asynchronously settle the money with the BPP according to those terms.
+Once the BPP receives the init message, it should send the acknowledgement that it has received the message. The BPP should then send the terms of payment by calling the on_init action on the BAP's API. Upon receipt of the on_init API call, The BAP must invoke the payment flow on its app to collect the payment from the buyer and asynchronously settle the money with the BPP according to those terms.
-# Payment Object
+## Payment Object
| Property | Description |
|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| url | Payment endpoint URL as defined in “BAP Terms” |
+| url | Payment endpoint URL as defined in "BAP Terms" |
| tl_method | Method to call the API URL. supported values are 1. HTTP/GET 2. HTTP/POST 3. PAYTO 4. UPI |
| params | Parameters associated with that URL like 1. amount 2. currency Any other parameters required to authorize the payment like 1. ifsc 2. account 3. vpa (In case of UPI) |
| type | Stage at which the payment should happen. Supported values are: 1. ON-ORDER, 2. PRE-FULFILLMENT, 3. ON-FULFILLMENT, 4. POST-FULFILLMENT |
-| time | If the type is “POST_FULFILLMENT”, this field contains the time related information at which the payment must be made |
+| time | If the type is "POST_FULFILLMENT", this field contains the time related information at which the payment must be made |
-# Runtime Payment Object Examples
+# Examples
-## Example 1
+## Runtime Payment Object Examples
+
+### Example 1
Payment Collection by a BAP and settled at the end of the month to a bank account before 30th of November 2021
```
@@ -149,7 +180,7 @@ Payment Collection by a BAP and settled at the end of the month to a bank accoun
}
```
-## Example 2
+### Example 2
Immediate payment on order placement to a UPI Endpoint
```
@@ -165,7 +196,7 @@ Immediate payment on order placement to a UPI Endpoint
}
```
-## Example 3
+### Example 3
Transfer to a Payment Gateway Endpoint
```
@@ -181,7 +212,7 @@ Transfer to a Payment Gateway Endpoint
}
```
-## Example 4
+### Example 4
Payment Collection by a BAP and settled at the end of the month using UPI before 15th of February 2022
```
@@ -203,7 +234,39 @@ Payment Collection by a BAP and settled at the end of the month using UPI before
}
```
+# Recommendations
+
+- Security and compliance
+ - Follow applicable payment regulations (e.g., PCI DSS) when handling any payment artifacts outside beckn scope
+ - Do not transmit sensitive payment credentials in beckn payloads; share only payment endpoints and proofs
+ - Digitally sign all requests and callbacks; verify signatures and BLAKE-512 digests before processing
+
+- Payment object usage
+ - Use URI schemes consistently: https:// for gateways; payto:// per RFC 8905; upi:// for UPI
+ - Keep params minimal: amount, currency, and required authorization hints only; never include secrets
+ - Set type to the exact stage (ON-ORDER, PRE-FULFILLMENT, ON-FULFILLMENT, POST-FULFILLMENT) and honor it in flows
+
+- Idempotency and retries
+ - Make confirm, status, and settlement notifications idempotent using stable keys (transaction_id, message_id)
+ - Use bounded exponential backoff for retries; avoid duplicate charges by reconciling proofs
+
+- Settlement and reconciliation
+ - Persist proofs-of-payment and map them to orders for auditability
+ - Reconcile periodically with PSPs/gateways and surface mismatches via status and error codes
+ - Emit precise currency and amount formatting (ISO 4217; two-decimal unless regulated otherwise)
+
+- Error handling
+ - Use standardized error codes from BECKN-005; prefer specific 4xx/5xx mappings where applicable
+ - For non-actionable errors, return ack.status = NACK immediately and include reason codes
+- Refunds and adjustments
+ - Define network policy for refunds/chargebacks; communicate via status and/or dedicated flows
+ - Record adjustment references to maintain end-to-end audit trails
+# Acknowledgements
+The authors would like to thank the following people for their support and contributions to this document.
+* Pramod Varma (Beckn Foundation)
+* Sujith Nair (Beckn Foundation)
+* Venkataramanan Mahadevan (Humbhionline)
diff --git a/docs/BECKN-003-Beckn-Protocol-Communication-Draft-01.md b/docs/BECKN-003-Beckn-Protocol-Communication-Draft-01.md
deleted file mode 100644
index 23a08ea7..00000000
--- a/docs/BECKN-003-Beckn-Protocol-Communication-Draft-01.md
+++ /dev/null
@@ -1,87 +0,0 @@
-# Beckn Protocol Communication
-
-## ID
-BECKN-RFC-003
-
-## Draft ID
-Draft-01
-
-## Title
-Beckn Protocol Communication
-
-## Category
-Communication
-
-## Status
-Protocol Draft
-
-## Published on
-December 10, 2021
-
-## Expires on
-December 10, 2021 or Date of publication of next draft which ever is earlier
-
-## License
-CC-BY-ND
-
-## Authors
-1. Ravi Prakash : ravi@becknfoundation.org
-
-## Reviewers
-1. Sujith Nair : sujith@becknfoundation.org
-2. Pramod Varma : pramod@ekstep.org
-
-# Abstract
-Communication on beckn enabled networks is server-to-server. Server-to-server means that communication between any two systems on a beckn network does not involve the client application. The client is free to render the data in whatever form chosen by the product. Secondly, all communication is asynchronous. Asynchronous API calls do not block (or wait) for the API call to return from the receiver server in the same session. Instead, an immediate acknowledgment is sent to the sender server in the same session and the actual response from the receiver server is in the form of a callback API call to the sender server. The above two features provide a remarkable advantage as all sorts of innovations are possible in the application layer due to the experience layer being unbundled from the session and presentation layer of the application.
-
-# Introduction
-A beckn enabled network has multiple entities communicating with each other via standard protocol APIs. The following types of communication are possible.
-
-1. BAP and BG
-2. BAP and BPP
-3. BG and BPP
-4. BAP and Registry
-5. BPP and Registry
-6. BG and Registry
-
-All API calls between any two entities on the beckn network are asynchronous. Meaning, an API call from a BAP server (sender) to a BPP server (receiver) does not expect an informational response from a BPP in the same session. The immediate response in the same session is merely an acknowledgement or ACK which basically means, “_Hey, I have received your request and it looks okay during validation of the input. Let me call you back when I have the details you need_”. The actual response is sent later in the form of a standard callback API which the sender is required to implement.
-
-# Communication Protocol Between 2 Entities
-
-The sequence diagram of a typical beckn protocol API is shown in Figure 1. For example, let’s say X is the sender and Y is the receiver, and the API being called is **search.**
-
-In most cases, the sender will call the API first and the receiver will respond immediately with an ACK and close the session. After an arbitrary period of time (which is dependent on the processing of the message), the receiver will respond with an API callback to the sender. The name of the callback API is the name of the sender API with an “on_” prefix. For example, if the request API is called “**search**” then the associated callback API will be “**on_search**”.
-
-
-
-Figure 1
-
-
-# Communication Protocol for Search Via Beckn Gateway
-
-Most communication in a beckn enabled network involves two entities. But sometimes, an intermediate entity like a Beckn Gateway (BG) is involved. In those cases, the flow of communication should be as follows.
-
-If the address of the BPP is not specified in the context of the API call, then the BAP should call the BG and the BG may multicast this API to multiple BPPs.
-The BPPs synchronously respond with ACKs. The BPPs then asynchronously call the **on_search** API which is sent back to the BAP.
-
-
-
-Figure 2:
-
-
-# Communication Protocol for Search Via Beckn Gateway with Registry Lookup
-
-Sometimes the BG may query a Registry via the **lookup** API to get the BPP addresses and then multicast the message to the BPPs. See Figure 3.
-
-
-Figure 3:Search with Registry Lookup
-
-
-# Communication Protocol during status updates
-
-During the status and on_status calls, the BAP first initiates the transaction by calling **status**. The BAP responds with an **on_status **API call to the BPP just like any other beckn API. However, in the case of the **status** API call, the BPP can asynchronously send multiple **on_status** calls to the BAP after the first call. The BAP does not have to poll the BPP to get an on_status callback. See Figure 4.
-
-
-
-Figure 4
-
diff --git a/docs/BECKN-003-Beckn-Protocol-Communication.md b/docs/BECKN-003-Beckn-Protocol-Communication.md
new file mode 100644
index 00000000..cdff3984
--- /dev/null
+++ b/docs/BECKN-003-Beckn-Protocol-Communication.md
@@ -0,0 +1,134 @@
+# BECKN-003:Beckn Protocol Communication
+
+## License:
+This document is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/).
+
+
+
+## Category:
+Communication
+
+## Published on:
+December 10, 2021
+
+## Last Updated on:
+July 8th, 2024
+
+## History:
+Click on this [link](https://github.com/beckn/protocol-specifications/commits/core-1.2-release/docs/BECKN-003-Beckn-Protocol-Communication.md) to view the history of changes to this document
+
+## Issues:
+To view issues related to this document, click on this [link](https://github.com/beckn/protocol-specifications/issues?q=is%3Aissue+label%3ABECKN-003)
+
+## Discussions:
+To view discussions related to this document, click on this [link](https://github.com/beckn/protocol-specifications/discussions?discussions_q=label%3ABECKN-003)
+
+## Authors:
+1. [Ravi Prakash](https://github.com/ravi-prakash-v)
+
+## Reviewers:
+1. [Sujith Nair](https://github.com/sjthnrk)
+2. [Pramod Varma](https://github.com/pramodkvarma)
+3. [Venkatraman Mahadevan](https://github.com/venkatramanm)
+
+# Abstract
+
+Communication on beckn enabled networks is server-to-server. Server-to-server means that communication between any two systems on a beckn network does not involve the client application (like the website or the mobile app). The client is thus free to render the data in whatever form chosen by the product.
+
+Secondly, all communication is asynchronous. Asynchronous API calls do not block (or wait) for the response to return from the receiver server in the same session. This is done to replicate real-world behaviour of economic transactions across various domains and use cases. For example, a hotel booking confirmation request does not _always_ get a response in the same session. Sometimes the customer needs to wait for 24 hours or more to receive a confirmation. Sometimes the provider needs to send information to the consumer without them explicitly requesting it like in the case of a driver cancelling a confirmed ride before pickup. Such asynchronocity avoids the BAP continously polling the BPP until it receives a status update. Instead, an immediate acknowledgment is sent to the BAP in the same session and the actual response from the BPP is in the form of a callback API call to the BAP. The above two features provide a remarkable advantage as all sorts of innovations are possible in the application layer due to the experience layer being unbundled from the session and presentation layer of the application.
+
+# Scope
+
+This document is intended for the following audience:
+
+1. Anyone implementing beckn protocol communication systems
+2. Network facilitators designing communication policies
+3. Developers building beckn-enabled applications
+4. System architects designing distributed commerce networks
+
+## Prerequisites
+
+Readers of this document must:
+
+1. Have knowledge of the core beckn protocol specification
+2. Have understanding of HTTP APIs and asynchronous communication
+3. Have knowledge of distributed systems architecture
+
+# Introduction
+
+A beckn enabled network has multiple entities communicating with each other via standard protocol APIs. The following types of communication are possible.
+
+1. BAP and BG
+2. BAP and BPP
+3. BG and BPP
+4. BAP and Registry
+5. BPP and Registry
+6. BG and Registry
+
+All API calls between any two entities on the beckn network are asynchronous. Meaning, an API call from a BAP server (sender) to a BPP server (receiver) does not expect an informational response from a BPP in the same session. The immediate response in the same session is merely an acknowledgement or ACK which basically means, "_Hey, I have received your request and it looks okay during validation of the input. Let me call you back when I have the details you need_". The actual response is sent later in the form of a standard callback API which the sender is required to implement.
+
+# Problem
+
+How to enable reliable, scalable, and interoperable communication between distributed entities in beckn-enabled networks while maintaining real-world transaction behavior patterns?
+
+# Solution
+
+The beckn protocol implements a server-to-server asynchronous communication model that decouples the presentation layer from the business logic layer, enabling flexible and scalable distributed commerce networks.
+
+# Implementation Details
+
+## Communication Protocol Between 2 Entities
+
+The sequence diagram of a typical beckn protocol API is shown in Figure 1. For example, let's say X is the sender and Y is the receiver, and the API being called is **search.**
+
+In most cases, the sender will call the API first and the receiver will respond immediately with an ACK and close the session. After an arbitrary period of time (which is dependent on the processing of the message), the receiver will respond with an API callback to the sender. The name of the callback API is the name of the sender API with an "on_" prefix. For example, if the request API is called "**search**" then the associated callback API will be "**on_search**".
+
+
+
+Figure 1
+
+
+## Communication Protocol for Search Via Beckn Gateway
+
+Most communication in a beckn enabled network involves two entities. But sometimes, an intermediate entity like a Beckn Gateway (BG) is involved. In those cases, the flow of communication should be as follows.
+
+If the address of the BPP is not specified in the context of the API call, then the BAP should call the BG and the BG may multicast this API to multiple BPPs.
+The BPPs synchronously respond with ACKs. The BPPs then asynchronously call the **on_search** API which is sent back to the BAP.
+
+
+
+Figure 2:
+
+
+## Communication Protocol for Search Via Beckn Gateway with Registry Lookup
+
+Sometimes the BG may query a Registry via the **lookup** API to get the BPP addresses and then multicast the message to the BPPs. See Figure 3.
+
+
+Figure 3:Search with Registry Lookup
+
+
+## Communication Protocol during status updates
+
+During the status and on_status calls, the BAP first initiates the transaction by calling **status**. The BAP responds with an **on_status **API call to the BPP just like any other beckn API. However, in the case of the **status** API call, the BPP can asynchronously send multiple **on_status** calls to the BAP after the first call. The BAP does not have to poll the BPP to get an on_status callback. See Figure 4.
+
+
+
+Figure 4
+
+
+# Examples
+
+[Examples section to be added with concrete communication scenarios]
+
+# Recommendations
+
+[Recommendations section to be added with best practices for communication implementation]
+
+# Acknowledgements
+
+The authors would like to thank the following people for their support and contributions to this document.
+
+* Pramod Varma (Beckn Foundation)
+* Sujith Nair (Beckn Foundation)
+* Venkataramanan Mahadevan (Humbhionline)
diff --git a/docs/BECKN-004-Policy-Administration-On-Beckn-Enabled-Networks.md b/docs/BECKN-004-Policy-Administration-On-Beckn-Enabled-Networks.md
index a21f436b..f52cc0ca 100644
--- a/docs/BECKN-004-Policy-Administration-On-Beckn-Enabled-Networks.md
+++ b/docs/BECKN-004-Policy-Administration-On-Beckn-Enabled-Networks.md
@@ -1,37 +1,56 @@
-# Policy Administration on Beckn-Enabled Networks
+# BECKN-004:Policy Administration on Beckn-Enabled Networks
-## ID:
-BECKN-RFC-004
-
-## Draft ID
-Draft-01
+## License:
+This document is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/).
-## Title:
-Policy Administration on Beckn-Enabled Networks
+
## Category:
Policy
-## Status:
-Protocol Draft
-
## Published on:
December 10, 2021
-## Expires on:
-December 10, 2022 or Date of publication of next draft which ever is earlier
+## Last Updated on:
+July 8th, 2024
-## License:
-CC-BY-ND
+## History:
+Click on this [link](https://github.com/beckn/protocol-specifications/commits/core-1.2-release/docs/BECKN-004-Policy-Administration-On-Beckn-Enabled-Networks.md) to view the history of changes to this document
+
+## Issues:
+To view issues related to this document, click on this [link](https://github.com/beckn/protocol-specifications/issues?q=is%3Aissue+label%3ABECKN-004)
+
+## Discussions:
+To view discussions related to this document, click on this [link](https://github.com/beckn/protocol-specifications/discussions?discussions_q=label%3ABECKN-004)
## Authors:
-1. Ravi Prakash : ravi@becknfoundation.org
-2. Sujith Nair : sujith@becknfoundation.org
+1. [Ravi Prakash](https://github.com/ravi-prakash-v)
## Reviewers:
-1. Sujith Nair : sujith@becknfoundation.org
-2. Pramod Varma : pramod@ekstep.org
+1. [Sujith Nair](https://github.com/sjthnrk)
+2. [Pramod Varma](https://github.com/pramodkvarma)
+3. [Venkatraman Mahadevan](https://github.com/venkatramanm)
+
+# Abstract
+
+Beckn protocol allows the creation of **Open Commerce Networks**. The primary actors on such networks are BAP, BPP, BG and Registry. Each actor implements an API that enables products and services to be discovered, ordered and fulfilled via a standard API. These API calls correspond to different interactions that happen between a buyer and a seller. This document defines the methodology to publish, implement and enforce Network Policy on an Open Commerce Network.
+
+# Scope
+
+This document is intended for the following audience:
+
+1. Network facilitators designing policy administration systems
+2. Anyone implementing beckn-enabled networks with policy requirements
+3. Policy administrators and compliance officers
+4. Developers building policy enforcement middleware
+
+## Prerequisites
+
+Readers of this document must:
+1. Have knowledge of the core beckn protocol specification
+2. Have understanding of policy administration systems
+3. Have knowledge of Open API 3.0 Specification
# Introduction
@@ -45,30 +64,52 @@ Each network has a logical boundary. This boundary is created by the governance
This document contains the methodology to publish, implement and enforce the Network Policy on an Open Commerce Network. The process of publication, implementation and enforcement of network policy is known as **Network Policy Administration**.
-# Network Policy Use Cases
+# Problem
+
+How do we set up a digital infrastructure that achieve the following outcomes:
+1. Create, view, update and delete network policies for various use cases described above
+2. Create, view, update and delete subscriber policies policies of a subscriber
+3. Agree or disagree to a network policy
+4. View network participants that have agreed / disagreed to specific network policies
+5. Dynamically apply network policies as a middleware on protocol implementations
+6. Audit network participants for compliance with a network policy
+
+# Solution
+
+This section describes the specification to create a digital infrastructure to achieve the above outcomes. It contains:
+1. Implementation Process
+2. Data Model
+3. Policy APIs
+4. Policy Agreement and Adoption Protocol
+5. Reference Architecture
+6. Sample Workflow
+
+# Implementation Details
+
+## Network Policy Use Cases
To get a better understanding of what a network policy outlines, let us take a look at some policy use cases that a network creator might enforce on the participants.
-## Supported Industry Sectors Adaptations
+### Supported Industry Sectors Adaptations
-While the protocol itself is sector agnostic, a network may support only a specific set of industry sectors like “Mobility”, “Retail”, or “Logistics”. These sectors may contain sub-sectors like, say, “On-demand Cab Services”, “Bike Rental”, “Metro services” under the Mobility Sector. Such sectors could be specified by allowing only certain sector codes to be transmitted in the messages.
+While the protocol itself is sector agnostic, a network may support only a specific set of industry sectors like "Mobility", "Retail", or "Logistics". These sectors may contain sub-sectors like, say, "On-demand Cab Services", "Bike Rental", "Metro services" under the Mobility Sector. Such sectors could be specified by allowing only certain sector codes to be transmitted in the messages.
-## Supported Fulfillment Modes
+### Supported Fulfillment Modes
A network may support various fulfillment flows for various sectors. For example, a retail network may support "STORE-PICKUP" and "HOME-DELIVERY". In the sector of education, a network may support "VIRTUAL-CLASS" and "PHYSICAL-CLASS". These modes may vary with the Industry Sector Adaptations of a network.
-## Catalog Restrictions
+### Catalog Restrictions
A network may place restrictions on a catalog. For example, a network may restrict certain kinds of goods like *illegal items* or *non-essential* items to be listed or searched for.
-## Policy Coverage
+### Policy Coverage
A policy may apply to different geo-political regions on the map. It may also apply only during certain time slots. Such spatial and temporal on the policy is called **Policy Coverage**
-## Geo-Spatial Coverage
+### Geo-Spatial Coverage
The network may place geo-spatial constraints on various activities performed on a network. For example, a network may allow certain businesses to operate only within a specific city. This rule may also include exclusion and inclusion zones within a city like containment zones, restricted areas etc. Such restrictions could be implemented by rejecting search requests to exclusion zones.
-## Temporal Coverage
+### Temporal Coverage
The network may place temporal (time-based) constraints on various activities performed on a network. For example, a network may allow certain businesses to operate only within certain hours of the day, or only on certain days of the week. Sometimes, the network may allow specific platforms to operate for a fixed duration (like a month) as part of a pilot launch.
-# Policy Categories
+## Policy Categories
Policies can be of various categories as shown below
1. Implementation
@@ -79,188 +120,168 @@ Policies can be of various categories as shown below
6. Data Transmission
7. Communication
-# Problem Definition
-
-How do we set up a digital infrastructure that achieve the following outcomes:
-1. Create, view, update and delete network policies for various use cases described above
-2. Create, view, update and delete subscriber policies policies of a subscriber
-3. Agree or disagree to a network policy
-4. View network participants that have agreed / disagreed to specific network policies
-5. Dynamically apply network policies as a middleware on protocol implementations
-6. Audit network participants for compliance with a network policy
+## Network Policy Design Principles
-# Solution Approach
-
-This section describes the specification to create a digital infrastructure to achieve the above outcomes. It contains
-1. Implementation Process
-2. Data Model
-3. Policy APIs
-4. Policy Agreement and Adoption Protocol
-5. Reference Architecture
-6. Sample Workflow
-
-# Network Policy Design Principles
-
-## Ensuring Interoperabililty
+### Ensuring Interoperabililty
The guiding design principle of any network policy is to ensure interoperability at all costs. This can be achieved by publishing sector-specific codes, standards, benchmarks, data exchange mechanisms and supported use cases as Open API files, Policy Registries, Sample Flows and Certification Agencies etc.
-## Avoid Re-imposing Existing Policies
+### Avoid Re-imposing Existing Policies
Most sector-specific regulatory policies are already enforced by the authorities of a region and do not need to be re-imposed on a network. For example, if selling unauthorised articles online is an existing policy that has been imposed by a region's authorities, it does not need to be re-imposed as a network policy. The fact that a network participant is on an Open Commerce Network does not change the rules and regulations of the region they are operating in. the Network Facilitators should strive to ensure that the relevant policies are available to the network participants easily without searching for them in various websites and possibly missing some of them.
-## Inclusiveness and Optimal Ignorance
+### Inclusiveness and Optimal Ignorance
This should be a prime directive of any Network Policy. Before designing a new policy, the policy designers must ask themselves following questions.
1. Is this needed?
2. Is this needed NOW?
3. Does this policy introduce unnecessary regulatory control over the network participants over and above the already established regulations of the industry?
4. Does this policy unnecessarily restrict NPs from registering on a network?
-## API-fication
+### API-fication
All policy documents must be available and agreeable via an API.
-## Machine Readability
+### Machine Readability
All policy administrators must strive to encode all policies in a machine readable format. This is of course not mandatory but merely a principle for the administrators to adopt as much as possible. In those cases where policies are subjective and cannot be encoded, they should be present as URLs to pdf documents
-## Non-repudiability
+### Non-repudiability
All policies in machine-readable or document format must be accompanied with digital signatures. These signatures must be digitally verifiable by NPs using public keys.
-# Policy Workflow
+## Policy Workflow
Policy administrators and network participants can adopt the below workflow. This merely a reference workflow and is not a standard. Networks are free to design their own workflows to ensure better interoperability.
-# Policy Framework Roles
+## Policy Framework Roles
1. Policy Adopter (BPPs, BAPs, BGs, Registries)
2. Policy Publisher (SRO or equivalent)
3. Policy Auditor (Monitoring and Reporting)
-# Policy Implementation Architecture
+## Policy Implementation Architecture
The below diagram shows a reference policy microservice layered on the transaction layer as a middleware.
-# Policy Agreement and Adoption Protocol
+## Policy Agreement and Adoption Protocol
The below diagram shows a reference dynamic policy adoption workflow via policy API calls
-# Policy Compliance Audits and Checks
+## Policy Compliance Audits and Checks
-## Technical Audits
+### Technical Audits
The NFO can engage a testing agency to test policy compliance via an automated test suite
-## Non-technical Audits
-### Social Audits by External Agency:
+### Non-technical Audits
+#### Social Audits by External Agency:
NFO can engage a social audit agency to test compliance of a Subscriber
-### Social Audits by Users:
+#### Social Audits by Users:
NFO can mandate that all apps must have a one-click report feature by which users can report any compliance issues with the application to an ODR system. These reports can be viewed by an auditor to fetch any policy compliance violations
-# Policy Layer Data Model
+## Policy Layer Data Model
This section describes the minimum schema that must be implemented by any service that enables the above outcomes covering the use cases described above.
-## PolicyCategory
+### PolicyCategory
-### Description
+#### Description
TODO
-### Type
+#### Type
object
-### Properties
+#### Properties
| Property | Type | Description |
|----------|--------|-----------------------------|
| id | string | ID of the policy category |
| name | string | Name of the policy category |
-## SpatialCoverage
-### Description
+### SpatialCoverage
+#### Description
TODO
-### Type
+#### Type
object
-### Properties
+#### Properties
| Property | Type | Description |
|----------|----------|------------------------------------------|
| id | string | ID of the coverage |
| location | Location | Location of coverage |
-| type | string | Enum ( “incl”, “excl” ), Default: “incl” |
+| type | string | Enum ( "incl", "excl" ), Default: "incl" |
-## TemporalCoverage
-### Description
+### TemporalCoverage
+#### Description
TODO
-### Type
+#### Type
object
-### Properties
+#### Properties
| Property | Type | Description |
|----------|--------|------------------------------------------|
| id | string | ID of the coverage |
| time | Time | Time of coverage |
-| type | string | Enum ( “incl”, “excl” ), Default: “incl” |
+| type | string | Enum ( "incl", "excl" ), Default: "incl" |
-## SubscriberCoverage
-### Description
+### SubscriberCoverage
+#### Description
TODO
-### Type
+#### Type
object
-### Properties
+#### Properties
| Property | Type | Description |
|---------------|---------|------------------------------------------|
| id | string | ID of coverage |
| subscriber_id | string | ID of the subscriber |
-| type | string | Enum ( “incl”, “excl” ), Default: “incl” |
+| type | string | Enum ( "incl", "excl" ), Default: "incl" |
-## SchemaOverride
-### Description
+### SchemaOverride
+#### Description
TODO
-### Type
+#### Type
object
-### Properties
+#### Properties
| Property | Type | Description |
|-----------------|--------|---------------------------------------------|
| id | string | ID of row |
| target_schema | Time | Schema to be overriden |
| override_schema | string | Schema that has to override existing schema |
-## Action
-### Description
+### Action
+#### Description
TODO
-### Type
+#### Type
object
-### Properties
+#### Properties
| Property | Type | Description |
|----------|--------|-------------------------|
| id | string | ID of protocol action |
| action | string | Name of protocol action |
-## ProtocolVersion
-### Description
+### ProtocolVersion
+#### Description
The protocol version of the specification
-### Type
+#### Type
string
-### Properties
+#### Properties
-## Policy
-### Description
+### Policy
+#### Description
TODO
-### Type
+#### Type
object
-### Properties
+#### Properties
| Property | Type | Description |
|---------------------|--------------------|-------------------------------------|
| id | string | ID of policy |
@@ -278,50 +299,50 @@ object
| signature | string | Digital Signature of publisher |
| attachment | string | URL of attached document |
-## PolicyManifest
+### PolicyManifest
-### Description
+#### Description
The complete list of policies published by a Network Subscriber
-### Type
+#### Type
object
-### Properties
+#### Properties
| Property | Type | Description |
|-----------|----------------|---------------------|
| id | string | ID of manifest |
| policies | Array (Policy) | Array of policies |
| Meta info | string | Any additional info |
-## PolicyDifference
-### Description
+### PolicyDifference
+#### Description
This is the diff of the policy files
-### Type
+#### Type
string
-## PolicyConflict
-### Description
+### PolicyConflict
+#### Description
TODO
-### Type
+#### Type
object
-### Properties
+#### Properties
| Property | Type | Description |
|-----------|------------------|-----------------------------------------------|
| policy_id | boolean | Indicates if there is a conflict of interest |
| diff | PolicyDifference | A diff between existing and new schema |
| reason | ConflictReason | Reason for the conflict of interest |
-## ConflictReason
-### Description
+### ConflictReason
+#### Description
TODO
-### Type
+#### Type
object
-### Properties
+#### Properties
| Property | Type | Description |
|----------|-------------|-------------|
| code | string enum | Reason code |
@@ -334,6 +355,18 @@ The adopter should return this code if the new policy violates the default netwo
**SELLER_POLICY_VIOLATION**
The adopter should return this code if the new policy violates the default seller policy, then.
+# Examples
+
+[Examples section to be added with concrete policy administration scenarios]
+
+# Recommendations
+
+[Recommendations section to be added with best practices for policy administration]
+# Acknowledgements
+The authors would like to thank the following people for their support and contributions to this document.
+* Pramod Varma (Beckn Foundation)
+* Sujith Nair (Beckn Foundation)
+* Venkataramanan Mahadevan (Humbhionline)
diff --git a/docs/BECKN-005-Error-Codes-Draft-01.md b/docs/BECKN-005-Error-Codes-Draft-01.md
deleted file mode 100644
index a7208710..00000000
--- a/docs/BECKN-005-Error-Codes-Draft-01.md
+++ /dev/null
@@ -1,69 +0,0 @@
-# Error Codes for BPP
-
-## ID:
-BECKN-005
-
-## Draft ID
-Draft-01
-
-## Title:
-Error Codes
-
-## Status:
-Protocol Draft
-
-## Published on:
-January 21, 2022
-
-## Expires on:
-January 20, 2023 or Date of publication of next draft which ever is earlier
-
-## License:
-CC-BY-ND
-
-## Authors:
-1. Ravi Prakash : ravi@becknfoundation.org
-
-## Introduction
- This document outlines the error codes which must be returned by a BPP.
-
- ## Error Codes
- |**Code**|**Message**|**Description**|
- |---|---|---|
- |30000|Invalid request error|Generic invalid request error|
- |30001|Provider not found|When BPP is unable to find the provider id sent by the BAP|
- |30002|Provider location not found|When BPP is unable to find the provider location id sent by the BAP|
- |30003|Provider category not found|When BPP is unable to find the provider category id sent by the BAP|
- |30004|Item not found|When BPP is unable to find the item id sent by the BAP|
- |30005|Category not found|When BPP is unable to find the category id sent by the BAP|
- |30006|Offer not found|When BPP is unable to find the offer id sent by the BAP|
- |30007|Add on not found|When the BPP is unable to find the add on id sent by the BAP|
- |30008|Fulfillment unavailable|When BPP is unable to find the fulfillment id sent by the BAP|
- |30009|Fulfilment provider unavailable|When the BPP is unable to find fulfilment provider id sent by the BAP|
- |30010|Order not found|When the BPP is unable to find the order id sent by the BAP|
- |30011|Invalid cancellation reason|When the BPP is unable to find the cancellation reason in cancellation_reason_id|
- |30012|Invalid update_target|When the BPP is unable to find the update_target in the order object|
- |30013|Update inconsistency|When the BPP finds changes in the order object other than the update_target|
- |30014|Entity to rate not found|When the BPP is unable to find the entity to rate in id|
- |30015|Invalid rating value|When the BPP receives an invalid value as the rating value in value|
- |40000|Business Error|Generic business error|
- |40001|Action not applicable|When an API endpoint is not implemented by the BPP as it is not required for their use cases and a BAP calls one of these endpoints|
- |40002|Item quantity unavailable|When the BPP is unable to select the specified number in order.items[].quantity|
- |40003|Quote unavailable|When the quote sent by the BAP is no longer available from the BPP|
- |40004|Payment not supported|When the payment object sent by the BAP is not supported by the BPP|
- |40005|Tracking not supported|When the BPP does not support tracking for the order in order_id|
- |40006|Fulfilment agent unavailable|When an agent for fulfilment is not available|
- |50000|Policy Error|Generic Policy Error|
- |50001|Cancellation not possible|When the BPP is unable to cancel the order due to it's cancellation policy|
- |50002|Updation not possible|When the BPP is unable to update the order due to it's updation policy|
- |50003|Unsupported rating category|When the BPP receives an entity to rate which is not supported|
- |50004|Support unavailable|When the BPP receives an object if for which it does not provide support|
-
- ## Acknowledgements
- The author would like to thank the following individuals for their contributions in creating the first draft of this document (in alphabetical order):
-
-1. Pramod Varma, Beckn Foundation
-2. Sujith Nair, Beckn Foundation
-3. Supriyo Ghosh, ONDC
-
-*Copyright (c) 2022 Beckn Foundation. All rights reserved.*
diff --git a/docs/BECKN-005-Error-Codes.md b/docs/BECKN-005-Error-Codes.md
new file mode 100644
index 00000000..0b5147be
--- /dev/null
+++ b/docs/BECKN-005-Error-Codes.md
@@ -0,0 +1,117 @@
+# BECKN-005:Error Codes for BPP
+
+## License:
+This document is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/).
+
+
+
+## Category:
+Error Codes
+
+## Published on:
+January 21, 2022
+
+## Last Updated on:
+July 8th, 2024
+
+## History:
+Click on this [link](https://github.com/beckn/protocol-specifications/commits/core-1.2-release/docs/BECKN-005-Error-Codes.md) to view the history of changes to this document
+
+## Issues:
+To view issues related to this document, click on this [link](https://github.com/beckn/protocol-specifications/issues?q=is%3Aissue+label%3ABECKN-005)
+
+## Discussions:
+To view discussions related to this document, click on this [link](https://github.com/beckn/protocol-specifications/discussions?discussions_q=label%3ABECKN-005)
+
+## Authors:
+1. [Ravi Prakash](https://github.com/ravi-prakash-v)
+
+## Reviewers:
+1. [Sujith Nair](https://github.com/sjthnrk)
+2. [Pramod Varma](https://github.com/pramodkvarma)
+3. [Venkatraman Mahadevan](https://github.com/venkatramanm)
+
+# Abstract
+
+This document outlines the standardized error codes which must be returned by a BPP (Beckn Provider Platform) when handling various error scenarios in beckn-enabled networks. These error codes ensure consistent error handling and debugging across all beckn implementations.
+
+# Scope
+
+This document is intended for the following audience:
+
+1. BPP developers implementing error handling
+2. BAP developers handling BPP error responses
+3. Network facilitators defining error handling policies
+4. Quality assurance teams testing beckn implementations
+
+## Prerequisites
+
+Readers of this document must:
+
+1. Have knowledge of the core beckn protocol specification
+2. Have understanding of HTTP status codes and error handling
+3. Have knowledge of beckn API implementations
+
+# Introduction
+
+This document outlines the error codes which must be returned by a BPP.
+
+# Problem
+
+How to ensure consistent and standardized error reporting across all BPP implementations in beckn-enabled networks?
+
+# Solution
+
+Implement a comprehensive set of standardized error codes that cover all possible error scenarios in beckn protocol implementations, categorized by error type and severity.
+
+# Implementation Details
+
+## Error Codes
+|**Code**|**Message**|**Description**|
+|--------|-----------|---------------|
+|30000|Invalid request error|Generic invalid request error|
+|30001|Provider not found|When BPP is unable to find the provider id sent by the BAP|
+|30002|Provider location not found|When BPP is unable to find the provider location id sent by the BAP|
+|30003|Provider category not found|When BPP is unable to find the provider category id sent by the BAP|
+|30004|Item not found|When BPP is unable to find the item id sent by the BAP|
+|30005|Category not found|When BPP is unable to find the category id sent by the BAP|
+|30006|Offer not found|When BPP is unable to find the offer id sent by the BAP|
+|30007|Add on not found|When the BPP is unable to find the add on id sent by the BAP|
+|30008|Fulfillment unavailable|When BPP is unable to find the fulfillment id sent by the BAP|
+|30009|Fulfilment provider unavailable|When the BPP is unable to find fulfilment provider id sent by the BAP|
+|30010|Order not found|When the BPP is unable to find the order id sent by the BAP|
+|30011|Invalid cancellation reason|When the BPP is unable to find the cancellation reason in cancellation_reason_id|
+|30012|Invalid update_target|When the BPP is unable to find the update_target in the order object|
+|30013|Update inconsistency|When the BPP finds changes in the order object other than the update_target|
+|30014|Entity to rate not found|When the BPP is unable to find the entity to rate in id|
+|30015|Invalid rating value|When the BPP receives an invalid value as the rating value in value|
+|40000|Business Error|Generic business error|
+|40001|Action not applicable|When an API endpoint is not implemented by the BPP as it is not required for their use cases and a BAP calls one of these endpoints|
+|40002|Item quantity unavailable|When the BPP is unable to select the specified number in order.items[].quantity|
+|40003|Quote unavailable|When the quote sent by the BAP is no longer available from the BPP|
+|40004|Payment not supported|When the payment object sent by the BAP is not supported by the BPP|
+|40005|Tracking not supported|When the BPP does not support tracking for the order in order_id|
+|40006|Fulfilment agent unavailable|When an agent for fulfilment is not available|
+|50000|Policy Error|Generic Policy Error|
+|50001|Cancellation not possible|When the BPP is unable to cancel the order due to it's cancellation policy|
+|50002|Updation not possible|When the BPP is unable to update the order due to it's updation policy|
+|50003|Unsupported rating category|When the BPP receives an entity to rate which is not supported|
+|50004|Support unavailable|When the BPP receives an object if for which it does not provide support|
+
+# Examples
+
+[Examples section to be added with concrete error handling scenarios]
+
+# Recommendations
+
+[Recommendations section to be added with best practices for error handling]
+
+# Acknowledgements
+
+The author would like to thank the following individuals for their contributions in creating this document (in alphabetical order):
+
+1. Pramod Varma, Beckn Foundation
+2. Sujith Nair, Beckn Foundation
+3. Supriyo Ghosh, ONDC
+
+*Copyright (c) 2022 Beckn Foundation. All rights reserved.*
diff --git a/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP-Draft-01.md b/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP.md
similarity index 88%
rename from docs/BECKN-006-Signing-Beckn-APIs-In-HTTP-Draft-01.md
rename to docs/BECKN-006-Signing-Beckn-APIs-In-HTTP.md
index efe78038..19a95d01 100644
--- a/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP-Draft-01.md
+++ b/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP.md
@@ -1,11 +1,75 @@
-# Signing Beckn APIs in HTTP - Draft 04
+# BECKN-006:Signing Beckn APIs in HTTP
+
+## License:
+This document is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/).
+
+
+
+## Category:
+Authentication
+
+## Published on:
+January 21, 2022
+
+## Last Updated on:
+July 8th, 2024
+
+## History:
+Click on this [link](https://github.com/beckn/protocol-specifications/commits/core-1.2-release/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP.md) to view the history of changes to this document
+
+## Issues:
+To view issues related to this document, click on this [link](https://github.com/beckn/protocol-specifications/issues?q=is%3Aissue+label%3ABECKN-006)
+
+## Discussions:
+To view discussions related to this document, click on this [link](https://github.com/beckn/protocol-specifications/discussions?discussions_q=label%3ABECKN-006)
+
+## Authors:
+1. [Ravi Prakash](https://github.com/ravi-prakash-v)
+
+## Reviewers:
+1. [Sujith Nair](https://github.com/sjthnrk)
+2. [Pramod Varma](https://github.com/pramodkvarma)
+3. [Venkatraman Mahadevan](https://github.com/venkatramanm)
+
+# Abstract
+
+When communicating over HTTP using Beckn APIs, the subscribers need to authenticate themselves to perform transactions with other subscribers. Due to the commercial nature of the transactions, every request/callback pair is considered to be a "contract" between two parties. Therefore, it is imperative that all requests and callbacks are digitally signed by the sender and subsequently verified by the receiver. This document describes a way for network subscribers (BAP/BPPs) and proxy subscribers (BGs) to simultaneously add authentication and message integrity to HTTP messages by using digital signatures.
+
+# Scope
+
+This document is intended for the following audience:
+
+1. Anyone implementing beckn protocol authentication systems
+2. BAP, BPP, and BG developers implementing digital signatures
+3. Security architects designing beckn-enabled networks
+4. Quality assurance teams testing authentication implementations
+
+## Prerequisites
+
+Readers of this document must:
+
+1. Have knowledge of the core beckn protocol specification
+2. Have understanding of digital signatures and cryptography
+3. Have knowledge of HTTP headers and authentication
+4. Have understanding of public key infrastructure (PKI)
+
+# Introduction
-## Context
When communicating over HTTP using Beckn APIs, the subscribers need to authenticate themselves to perform transactions with other subscribers. Due to the commercial nature of the transactions, every request/callback pair is considered to be a "contract" between two parties. Therefore, it is imperative that all requests and callbacks are digitally signed by the sender and subsequently verified by the receiver.
Furthermore, it is also desirable to ensure that the message was not altered or tampered with during transit.
This document describes a way for network subscribers (BAP/BPPs) and proxy subscribers (BGs) to simultaneously add authentication and message integrity to HTTP messages by using digital signatures. How the signatures are generated and the format of those signatures is out of scope of this document and can be found in this IETF document - [Signing HTTP Messages](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12).
This document specifies the algorithms used in generating the keys, how to construct the signing strings being passed in the headers. Also, it specifies clearly the format of the HTTP headers used for authenticating BAP, BPPs and BGs.
+# Problem
+
+How to ensure secure, authenticated, and tamper-proof communication between beckn network participants while maintaining message integrity and non-repudiation?
+
+# Solution
+
+Implement a digital signature-based authentication system using Ed25519 signatures and BLAKE-512 hashing that allows network participants to authenticate themselves and verify message integrity during HTTP communication.
+
+# Implementation Details
+
## Subscriber Authentication
The BAP and BPP subscriber is expected to send an `Authorization` header as defined in [RFC 7235](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12) the "auth-scheme" is "Signature" and the "auth-param" parameters meet the requirements listed in Section 2 of [this](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12) document.
@@ -68,7 +132,7 @@ qK3Uvd39k+SHfSdG5igXsRY2Sh+nvBSNlQkLxzM7NnP4JAHPeqLkyx7NkCluPxTLVBP47Xe+cwRbE5FM
## Signing Algorithm
To digitally sign the signing string, the subscribers should use the "ed25519" signature scheme.
-### Example Flow (BAP <=> BG <=> BPP)
+## Example Flow (BAP <=> BG <=> BPP)
### Step 1 : BAP signs request and calls BG
Let the below be the request body in this example :
@@ -77,7 +141,7 @@ Let the below be the request body in this example :
{"context":{"domain":"nic2004:60212","country":"IND","city":"Kochi","action":"search","core_version":"0.9.1","bap_id":"bap.stayhalo.in","bap_uri":"https://8f9f-49-207-209-131.ngrok.io/protocol/","transaction_id":"e6d9f908-1d26-4ff3-a6d1-3af3d3721054","message_id":"a2fe6d52-9fe4-4d1a-9d0b-dccb8b48522d","timestamp":"2022-01-04T09:17:55.971Z","ttl":"P1M"},"message":{"intent":{"fulfillment":{"start":{"location":{"gps":"10.108768, 76.347517"}},"end":{"location":{"gps":"10.102997, 76.353480"}}}}}}
```
-Let BAP’s keys be :
+Let BAP's keys be :
```
signing_public_key=awGPjRK6i/Vg/lWr+0xObclVxlwZXvTjWYtlu6NeOHk=
@@ -123,11 +187,9 @@ Signature keyId="example-bap.com|ae3ea24b-cfec-495e-81f8-044aaef164ac|ed25519",a
8. Finally the BAP includes the `Authorization` header in the request and calls the BG API
-
**Note:**
The `expires` value should not be more than the expiration time of the key used for signing the request. If the expires value appears to be going beyond the lifespan of the signing key, generate a new key and update it on the registry OR use an existing registered key with an expiry time greater than the `expires` value of the signature.
-
### Step 2 : BG verifies BAP signature
The BG performs the following steps to authenticate the BAP and also ensure message integrity.
@@ -168,9 +230,8 @@ WWW-Authenticate: Signature realm="example-bg.com",headers="(created) (expires)
**NOTE : If the network policy does not allow more than one key-pair per subscriber on the registry, then the `unique_key_id` component is NOT NEEDED in the `keyId` attribure. In such a case, the Authorization header will look like this.
-
### Step 3 : BG signs request before forwarding request to BPP
-Let the BG’s keys be :
+Let the BG's keys be :
```
signing_public_key=7YRZXVeIJ0/Va56vYgzT1Uirg6mnq3FY0MBZY9DJft0=
@@ -216,8 +277,6 @@ Signature keyId="example-bg.com|dfb974ea-9113-4089-9a2d-77552b50624e|ed25519",al
3. The difference between the `created` and the `expires` field should be equal to the TTL of the request.
4. Also, the `expires` value should not be more than the expiration time of the key used for signing the request. If the expires value appears to be going beyond the lifespan of the signing key, generate a new key and update it on the registry via subscribe API OR use an existing registered key with an expiry time greater than the `expires` value of the signature
-
-
### Step 4 : BPP verifies BG signature
The BPP performs the following steps to authenticate the BAP and the BG and also ensure message integrity.
@@ -254,8 +313,6 @@ Proxy-Authenticate: Signature realm="example-bpp.com",headers="(created) (expire
}
```
-
-
### Step 5 : BPP verifies BAP signature
The BPP performs the following steps to authenticate the BAP and also ensure message integrity during transit.
@@ -287,8 +344,6 @@ WWW-Authenticate: Signature realm="example-bpp.com",headers="(created) (expires)
}
```
-
-
### Step 6 : BPP signs callback and calls BG
The BPP performs the following steps to create the Authorization header
@@ -313,8 +368,6 @@ Signature keyId="example-bpp.com|74b43deb-236e-4498-8f5a-ca75d6c67b9d|ed25519",a
9. Finally the BPP includes the Authorization header in the request and calls the BG API.
-
-
### Step 7 : BG verifies BPP signature
The BG performs the following steps to authenticate the BPP and also ensure message integrity.
@@ -346,7 +399,6 @@ WWW-Authenticate: Signature realm="example-bg.com",headers="(created) (expires)
}
```
-
### Step 8 : BG signs callback before calling BAP
Before forwarding the request to the BAP, the BG performs the following steps to create the X-Gateway-Authorization header
@@ -376,7 +428,6 @@ Signature keyId="example-bg.com|dfb974ea-9113-4089-9a2d-77552b50624e|ed25519",al
1. The difference between the `created` and the `expires` field should be equal to the TTL of the request.
2. Also, the `expires` value should not be more than the expiration time of the key used for signing the request. If the expires value appears to be going beyond the lifespan of the signing key, generate a new key and update it on the registry via subscribe API OR use an existing registered key with an expiry time greater than the `expires` value of the signature.
-
### Step 9 : BAP verifies BG signature
The BAP performs the following steps to authenticate the BAP and the BG and also ensure message integrity.
@@ -408,7 +459,6 @@ HTTP/1.1 401 Unauthorized
}
```
-
### Step 10 : BAP verifies BPP signature
The BAP performs the following steps to authenticate the BAP and also ensure message integrity during transit.
@@ -428,7 +478,6 @@ WWW-Authenticate: Signature realm="example-bap.com",headers="(created) (expires)
...
```
-
**Request Body:**
```
@@ -440,3 +489,19 @@ WWW-Authenticate: Signature realm="example-bap.com",headers="(created) (expires)
}
}
```
+
+# Examples
+
+[Examples section to be added with concrete signature implementation scenarios]
+
+# Recommendations
+
+[Recommendations section to be added with best practices for signature implementation]
+
+# Acknowledgements
+
+The authors would like to thank the following people for their support and contributions to this document.
+
+* Pramod Varma (Beckn Foundation)
+* Sujith Nair (Beckn Foundation)
+* Venkataramanan Mahadevan (Humbhionline)
diff --git a/docs/BECKN-007-The-XInput-Schema.md b/docs/BECKN-007-The-XInput-Schema.md
index e0e90127..5db97f32 100644
--- a/docs/BECKN-007-The-XInput-Schema.md
+++ b/docs/BECKN-007-The-XInput-Schema.md
@@ -1,55 +1,72 @@
-# The XInput Schema
-#### CWG Working Draft - November 08, 2022
+# BECKN-007:The XInput Schema
-## Document Details
-### This version
-https://github.com/beckn/protocol-specifications/blob/release-1.x/docs/BECKN-007-The-XInput-Schema.md
+## License:
+This document is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/).
-### Latest published version
-TODO
+
-### Latest editor's draft
-TODO
+## Category:
+XInput
-### Implementation report
-TODO
+## Published on:
+January 21, 2022
-### Editors
-Ravi Prakash (Beckn Foundation)
+## Last Updated on:
+July 8th, 2024
-### Authors
-Ravi Prakash (Beckn Foundation)
+## History:
+Click on this [link](https://github.com/beckn/protocol-specifications/commits/core-1.2-release/docs/BECKN-007-The-XInput-Schema.md) to view the history of changes to this document
+## Issues:
+To view issues related to this document, click on this [link](https://github.com/beckn/protocol-specifications/issues?q=is%3Aissue+label%3ABECKN-007)
-### Feedback
+## Discussions:
+To view discussions related to this document, click on this [link](https://github.com/beckn/protocol-specifications/discussions?discussions_q=label%3ABECKN-007)
-Issues: TODO
-Discussions: TODO
-PRs: TODO
+## Authors:
+1. [Ravi Prakash](https://github.com/ravi-prakash-v)
+## Reviewers:
+1. [Sujith Nair](https://github.com/sjthnrk)
+2. [Pramod Varma](https://github.com/pramodkvarma)
+3. [Venkatraman Mahadevan](https://github.com/venkatramanm)
-### Errata
-No Errata exists as of now
+# Abstract
+Beckn protocol defines a domain-agnostic specification that can be used to represent any customer-provider transaction by implementing a standard set of APIs and schema. Creating a transaction ideally involves the customer discovering products and services offered by various providers, selecting the desired products or services, obtaining the terms of service and payment, and then finally confirming the order. Sometimes, the provider might require additional metadata in order to confirm a transaction. This document defines the XInput schema that allows providers to collect additional information from customers without extending the core transaction protocol.
-## Context
-Beckn protocol defines a domain-agnostic specification that can be used to represent any customer- provider transaction by implementing a standard set of APIs and schema. Creating a transaction ideally involves the customer discovering products and services offered by various providers, selecting the desired products or services, obtaining the terms of service and payment, and then finally confirming the order. But sometimes, the provider might require additional metadata in order to confirm a transaction. This requirement may be due to legal requirements imposed by the regulatory authorities, or business requirements to allow better serviceability.
+# Scope
+
+This document is intended for the following audience:
+
+1. Anyone implementing beckn protocol with custom data collection requirements
+2. BPP developers requiring additional customer information
+3. BAP developers implementing form handling
+4. Network facilitators defining data collection policies
+
+## Prerequisites
+
+Readers of this document must:
-For example, a logistics service provider might require additional information from the logistics customer (like a restaurant) like the dimensions of the package, category of items (food, flammable, fragile etc), approximate weight of the package, the order Number etc,
+1. Have knowledge of the core beckn protocol specification
+2. Have understanding of HTML forms and XForms 2.0
+3. Have knowledge of JSON Schema and Open API 3.0
-to confirm the order. All of this information needs to be transmitted to the person availing the logistics service.
+# Introduction
+
+Beckn protocol defines a domain-agnostic specification that can be used to represent any customer- provider transaction by implementing a standard set of APIs and schema. Creating a transaction ideally involves the customer discovering products and services offered by various providers, selecting the desired products or services, obtaining the terms of service and payment, and then finally confirming the order. But sometimes, the provider might require additional metadata in order to confirm a transaction. This requirement may be due to legal requirements imposed by the regulatory authorities, or business requirements to allow better serviceability.
+
+For example, a logistics service provider might require additional information from the logistics customer (like a restaurant) like the dimensions of the package, category of items (food, flammable, fragile etc), approximate weight of the package, the order Number etc, to confirm the order. All of this information needs to be transmitted to the person availing the logistics service.
Similarly, a healthcare service might want the patient to provide information like, their medical history, a description of their symptoms, details of the insurance, etc, before confirming the order.
The nature of additional information required could vary significantly across sectors. These fields could be varied and many, and adding them as protocol attributes would make the protocol bulky and cluttered.
-
-## Problem
+# Problem
We require an object that captures additional information (over and above what has been published in the catalog) from the customer regarding the item being ordered without extending the core transaction protocol.
-
-## Solution
+# Solution
It is probably not such a good idea to transmit such required data fields as first class citizens of the transaction protocol, rather transmit them in some sort of a custom form object. This form could be a simple HTML form hosted on a url endpoint or transmitted as a whole as per standard form specifications like [XForms 2.0](https://www.w3.org/TR/xforms20/).
@@ -109,7 +126,7 @@ It starts with a schema called `XInput` of type `Form`. The definition of `Form`
properties:
code:
type: string
- description: For full list of error codes, refer to docs/protocol-drafts/BECKN-RFC-005-ERROR-CODES-DRAFT-01.md of this repo
+ description: For full list of error codes, refer to docs/BECKN-005-Error-Codes.md of this repo
path:
type: string
description: Path to json schema generating the error. Used only during json schema validation errors
@@ -121,14 +138,16 @@ It starts with a schema called `XInput` of type `Form`. The definition of `Form`
- path
```
-### Usage
+# Implementation Details
+
+## Usage
The `XInput` object can be found in the following schemas
1. Item
2. Order
3. Feedback
4. CancellationTerm
-#### Usage in the `Item` schema
+### Usage in the `Item` schema
```
Item:
type: object
@@ -138,7 +157,8 @@ Item:
...
```
This usage means that the BAP user is expected to provide additional information over and above the ID of
-#### Usage in the `Order` schema
+
+### Usage in the `Order` schema
```
Order:
type: object
@@ -148,9 +168,7 @@ Order:
...
```
-```
-
-#### Usage in the `CancellationTerm` schema
+### Usage in the `CancellationTerm` schema
```
CancellationTerm:
type: object
@@ -159,20 +177,19 @@ CancellationTerm:
$ref: '#/components/schemas/XInput'
...
```
-### Recommendations for BPPs
-The following recommendations are for BPPs who will create the form to be rendered on BAPs and receive the submissions from it.
+## Recommendations for BPPs
+The following recommendations are for BPPs who will create the form to be rendered on BAPs and receive the submissions from it.
-#### Declaring the form
+### Declaring the form
- BPPs that require additional information pertaining to individual items being ordered to confirm an order, must send the `xinput` object in the `Item` schema with a form object containing a link to the form with item-specific fields. For example, a person buying an airline ticket containing two flights - an onward Journey by Etihad and a return journey by Lufthansa might have to provide his Etihad membership code for his onward journey. For his return journey, Lufthansa might require them to declare their luggage dimensions, and upload a Covid-19 vaccination certificate.
- If BPPs require additional information pertaining to the order as a whole, they must send the xinput object in the Order schema containing a link to the form with order-specific information. For example, a cash on delivery grocery order from a store might require the store owner to declare the amount to be collected, the number of items, package category, and the weight of the package before placing the order.
- If the form is cacheable, then it is recommended for BPPs to send the form link during `on_search` itself.
- If the form is dynamic, then it is recommended for BPPs to send the form link during `on_select`, or `on_init` wherever applicable.
-
-#### Modeling the form
+### Modeling the form
- BPPs can model the form in two ways namely, a) using HTML5 Forms, or b) xForms 2.0 objects
- For creating HTML Forms, please refer to [this](https://www.w3schools.com/html/html_forms.asp) tutorial
@@ -191,15 +208,13 @@ The following recommendations are for BPPs who will create the form to be render
- It is _not recommended_ for BPPs to send `button` tags along with HTML forms as BAPs may render the CTA for form submission according to their UI
- For XForms 2.0 submissions, the BPP can send the <xforms:submission /> tag to specify submission URL, but it will not be rendered at the BAP.
+### Handling form requests
-#### Handling form requests
-
-- The form must be hosted on a trusted url, preferably with the same domain name as the BPP’s subscriber_id to avoid security-related errors thrown by BAPs.
+- The form must be hosted on a trusted url, preferably with the same domain name as the BPP's subscriber_id to avoid security-related errors thrown by BAPs.
- When requested on HTTP, the BPPs must return Content-type: text/html or application/xml in the response body headers.
- It is _recommended_ to send a unique nonce value in UUID format whenever it receives a form request from a BAP and persist it until a submission matches the nonce or the form expires
-
-#### Handling form submissions
+### Handling form submissions
- The form submission method must always be a HTTP/POST when using HTTP as a transport layer. Example: `
+
```
* For xForms 2.0 forms, the submission url will be present in the action attribute of the xform:submissions tag as highlighted in the example below
@@ -257,8 +266,7 @@ The following recommendations are for BAPs who will render the form to its users
* When submitting the form, the BAPs must _digitally sign_ the request body in the request header
* All form submissions must be digitally signed by the BAP
-
-#### Handling form submission responses
+### Handling form submission responses
* Form responses are received in the **FormResponse** object
* The FormResponse object contains status, submission_id and an error array
@@ -271,18 +279,19 @@ The following recommendations are for BAPs who will render the form to its users
throw an exception based on the data inside the error object
```
-#### Post-Form Submission
-After successful submission of the form, the BAP must ideally, send the submission_id received in the previous submission and send it in the corresponding item’s xinput.form.submission_id field, in the confirm API.
+### Post-Form Submission
+After successful submission of the form, the BAP must ideally, send the submission_id received in the previous submission and send it in the corresponding item's xinput.form.submission_id field, in the confirm API.
-### Recommendations for Network Facilitators
+## Recommendations for Network Facilitators
- Network Faciliators should publish a list of supported fields with their datatypes that can be used to create forms. This is to reduce form misuse through over-collection of data, and privacy protection.
- These fields can be the same as supported `Tags` list published by networks
- The IDs of the inputs are the codes
-## Examples
+# Examples
+
The following examples show how XInput can be used by BPPs to collect additional information from the user before confirming the order.
-### Example 1 : A logistics provider wants additional information on the nature of the package just before placing the order
+## Example 1 : A logistics provider wants additional information on the nature of the package just before placing the order
In this example, the Logistics BPP can create a XInput object containing a link the the following form
@@ -313,8 +322,7 @@ The BPP can choose to send this form at an Item level or at an order level. To k
Let us assume, the Logistics BAP has already declared the intent (via search), received the catalogs (via on_search), selected a specific item ( via select), and has received a quote(via on_select).
-
-#### Form identification
+### Form identification
When the BAP calls init, the Logistics BPP sends the following order object
@@ -356,20 +364,16 @@ When the BAP calls init, the Logistics BPP sends the following order object
}
```
-
-
-#### Form Fetching from BPP
+### Form Fetching from BPP
When the Logistics BAP receives this object via on_init, it must pull the form data from the order.xinput.form.url field and render the form on the UI. It is recommended that the Logistics BAP keeps watching for the xinput field at the item and order level.
-
-#### Form Rendering on the BAP
+### Form Rendering on the BAP
Once pulled the BAP can render the form as-is on its UI, but it is not recommended, as doing so would result in a sub-optimal user experience. This is how the form will look if the BAP renders the form as-is using an HTML parser.
-
However, the BAP application can apply any styling framework (like css) on the form and render it as per the style guide of the application.
This form must be rendered just before firing the confirm API. This is typically just before checkout, when the BAP invokes the payment flow.
@@ -395,11 +399,11 @@ The BPP will receive the confirm call with the submission_id as reference. It wi
Now the BPP has all the information required to confirm the order. It can either go ahead with the confirmation or reject the request if applicable.
-### Example 2: A health & wellness service provider wants additional information about the patient's symptoms before confirming a teleconsultation appointment. The provider and customer are on apps that are DHP-enabled (beckn protocol for health and wellness).
+## Example 2: A health & wellness service provider wants additional information about the patient's symptoms before confirming a teleconsultation appointment. The provider and customer are on apps that are DHP-enabled (beckn protocol for health and wellness).
[TODO]
-### Example 3: A recruitment agency wants additional information about the candidate before confirming a job application. The provider and customer are on apps that are DSEP-enabled (beckn protocol for education and skilling).
+## Example 3: A recruitment agency wants additional information about the candidate before confirming a job application. The provider and customer are on apps that are DSEP-enabled (beckn protocol for education and skilling).
```
```
-### Example 4: A flight booking system wants the passenger to declare his Covid vaccination status before confirming the booking.
+## Example 4: A flight booking system wants the passenger to declare his Covid vaccination status before confirming the booking.
```
```
-### Example 5: A mentor can seek additional information about a mentee before accepting the mentee's request for enrollment into the session(1-1 session as well as 1-many sessions). The provider and customer are on apps that are DSEP-enabled (Beckn protocol for education and skilling).
+## Example 5: A mentor can seek additional information about a mentee before accepting the mentee's request for enrollment into the session(1-1 session as well as 1-many sessions). The provider and customer are on apps that are DSEP-enabled (Beckn protocol for education and skilling).
In this case, the on_init BPP passes the form URL to BAP, which is rendered and filled by the mentee on BAP. The BAP then sends the acknowledgment ID received after the submission of the form in the confirm API call to BPP.
@@ -463,7 +467,11 @@ An example of a form can be as below:-
```
-## Acknowledgements
+# Recommendations
+
+[Recommendations section to be added with best practices for XInput implementation]
+
+# Acknowledgements
The authors would like to thank the following people for their support and contributions to this document.
@@ -471,4 +479,4 @@ The authors would like to thank the following people for their support and contr
* Pramod Varma (Beckn Foundation)
* Sujith Nair (Beckn Foundation)
* Akash Shah (Shikshalokam)
-* Sankarshan Mukhopadyay (Dhiway Networks)
\ No newline at end of file
+* Sankarshan Mukhopadyay (Dhiway Networks)
diff --git a/docs/BECKN-008-Rating-and-Reputation-on-Beckn-Protocol.md b/docs/BECKN-008-Rating-and-Reputation-on-Beckn-Protocol.md
index c39c4f7c..e7f74ab7 100644
--- a/docs/BECKN-008-Rating-and-Reputation-on-Beckn-Protocol.md
+++ b/docs/BECKN-008-Rating-and-Reputation-on-Beckn-Protocol.md
@@ -1,73 +1,79 @@
-# Rating and Reputation on Beckn Protocol
+# BECKN-008:Rating and Reputation on Beckn Protocol
-*Draft 01*
+## License:
+This document is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/).
-Author:
-=======
+
-Ravi Prakash (ravi@becknfoundation.org)
+## Category:
+Rating and Reputation
-Scope
-=====
+## Published on:
+January 21, 2022
-This document is intended for anyone wishing to design a Rating and Reputation system for beckn protocol enabled Open Networks. This specification is agnostic of any implementation technology but contains examples of run-time JSON objects for the sake of clarity.
+## Last Updated on:
+July 8th, 2024
-Context
-=======
+## History:
+Click on this [link](https://github.com/beckn/protocol-specifications/commits/core-1.2-release/docs/BECKN-008-Rating-and-Reputation-on-Beckn-Protocol.md) to view the history of changes to this document
-Customers expect quality in any products and services they have bought. To ensure such quality is maintained, providers usually expect their customers to rate their services and products based on how satisfied they are with the product consumed or service rendered. Most e-commerce systems nowadays implement an online rating system that allows their users to rate the products and services bought on that platform.
+## Issues:
+To view issues related to this document, click on this [link](https://github.com/beckn/protocol-specifications/issues?q=is%3Aissue+label%3ABECKN-008)
-Platforms selling physical products usually allow their users to rate the quality of their products and sometimes, the delivery. Business aggregators allow their users to also rate businesses as a whole. Businesses allow their customers to rate the customer support they received. There are many more such entities that can be rated based on the customer's level of satisfaction.
+## Discussions:
+To view discussions related to this document, click on this [link](https://github.com/beckn/protocol-specifications/discussions?discussions_q=label%3ABECKN-008)
-Typically, a rating system allows the consumer to provide a rating value from 1 to 5 where 1 represents lowest quality of service and 5 represents the highest quality of service. In some cases, fractional ratings are also used for further granularity; and in other cases non-numeric values like "Good" or "Bad''; and Ratings from 1 to 10 are also used. The rating value of a particular product or service is typically made visible to the public. A rating system is expected to be fair and transparent to its users, both customers and providers.
+## Authors:
+1. [Ravi Prakash](https://github.com/ravi-prakash-v)
-In the case of beckn protocol, many such platforms connect to each other via beckn and thus present a new challenge of managing rating and reputation on a decentralized network. (Talk about the challenge presented) due to open commerce networks and the purpose of this document.
+## Reviewers:
+1. [Sujith Nair](https://github.com/sjthnrk)
+2. [Pramod Varma](https://github.com/pramodkvarma)
+3. [Venkatraman Mahadevan](https://github.com/venkatramanm)
-For platforms connected to each other in an open commerce network, an interoperable and shared rating and reputation system must be implemented that allows users to rate various entities on the network. The rating system must adhere to the following design principles
+# Abstract
-1. Non-repudiability
+This document defines design specifications to create an interoperable, secure and non-repudiable system for managing Rating and Reputation of various physical and virtual entities on beckn-enabled Open Commerce Networks. It describes the various roles involved in the system and their respective functions. It also describes the format in which rating must be transmitted and stored on the network. There are multiple approaches to design a system, each approach has its advantages and limitations.
-2. Privacy protected
+# Scope
-3. Cross-platform compatibility
+This document is intended for anyone wishing to design a Rating and Reputation system for beckn protocol enabled Open Networks. This specification is agnostic of any implementation technology but contains examples of run-time JSON objects for the sake of clarity.
-Abstract
-========
+## Prerequisites
-This document defines design specifications to create an interoperable, secure and non-repudiable system for managing Rating and Reputation of various physical and virtual entities on beckn-enabled Open Commerce Networks. It describes the various roles involved in the system and their respective functions. It also describes the format in which rating must be transmitted and stored on the network. There are multiple approaches to design a system, each approach has its advantages and limitations.
+Readers of this document must:
-Terminology
-===========
+1. Have knowledge of the core beckn protocol specification
+2. Have understanding of rating and reputation systems
+3. Have knowledge of distributed systems architecture
-1. **Rating Category**: For example: Agent, Fulfillment, Provider
+# Introduction
-2. **Rateable Object**: The runtime object of a Rating Category that can be rated
+Customers expect quality in any products and services they have bought. To ensure such quality is maintained, providers usually expect their customers to rate their services and products based on how satisfied they are with the product consumed or service rendered. Most e-commerce systems nowadays implement an online rating system that allows their users to rate the products and services bought on that platform.
-3. **Rating Sender**: The actor that rates a Rateable Object
+Platforms selling physical products usually allow their users to rate the quality of their products and sometimes, the delivery. Business aggregators allow their users to also rate businesses as a whole. Businesses allow their customers to rate the customer support they received. There are many more such entities that can be rated based on the customer's level of satisfaction.
-4. **Rating Receiver**: The actor that receives the rating for a Rateable Object
+Typically, a rating system allows the consumer to provide a rating value from 1 to 5 where 1 represents lowest quality of service and 5 represents the highest quality of service. In some cases, fractional ratings are also used for further granularity; and in other cases non-numeric values like "Good" or "Bad''; and Ratings from 1 to 10 are also used. The rating value of a particular product or service is typically made visible to the public. A rating system is expected to be fair and transparent to its users, both customers and providers.
-Problem
-=======
+In the case of beckn protocol, many such platforms connect to each other via beckn and thus present a new challenge of managing rating and reputation on a decentralized network. (Talk about the challenge presented) due to open commerce networks and the purpose of this document.
-How to ensure that the customers receive quality services rendered from different providers on an open network?
+For platforms connected to each other in an open commerce network, an interoperable and shared rating and reputation system must be implemented that allows users to rate various entities on the network. The rating system must adhere to the following design principles
-Forces
-======
+1. Non-repudiability
-1. Same Rateable Objects may exist on more than one BPP under different names
+2. Privacy protected
+
+3. Cross-platform compatibility
-Expected Outcomes after reading this document
-=============================================
+# Problem
-After reading this document, the reader should be able to
+How to ensure that the customers receive quality services rendered from different providers on an open network?
-1. Understand how ratings work on Open Commerce Networks enabled by beckn protocol
+## Forces
-2. Understand how to connect their platforms to the Rating and Reputation system on open commerce networks.
+1. Same Rateable Objects may exist on more than one BPP under different names
-Rating using Beckn Protocol
-===========================
+# Solution
In beckn, **rating** is done via the rating action. This action allows any NP to rate a Rateable Object of another NP according to the rating policy of the NP. The rating policy of an NP defines,
@@ -75,10 +81,9 @@ In beckn, **rating** is done via the rating action. This action allows any NP to
2. How to rate
-Communication Protocol for Rating
----------------------------------
+# Implementation Details
-### Rating Policy Handshake
+## Rating Policy Handshake
Before a NP rates another NP's service, an agreement must be reached between both NPs regarding the rating policy. The agreement is done via the Rating Policy agreement handshake. The sequence of messages to be exchanged in this handshake is shown below.
@@ -114,7 +119,7 @@ Before a NP rates another NP's service, an agreement must be reached between bot
The Rating Sender must design their business logic to accept rating from the user only when the Rating Receiver's rating conditions are matched during a transaction.
-### Rating Call
+## Rating Call
Once the rating handshake is complete, the Rating should happen via the following process.
@@ -132,16 +137,13 @@ Once the rating handshake is complete, the Rating should happen via the followin
4. The Rating Receiver must call the on_rating action on the Rating Sender's API. the message must contain any additional information that may be required after the rating is complete. (Requires further elaboration)
-
-### Communication Sequence
-
+## Communication Sequence
-Rating Ledger Architecture
-==========================
+## Rating Ledger Architecture
The Rating Ledger is a table containing records with the following fields. This table can be implemented on a centralized database or a decentralized database like a blockchain.
@@ -169,3 +171,19 @@ To verify the rating of a Rateable Object in the catalog, the Rating Sender must
If this value matches the rating value sent in the catalog, then the rating is accurate. A margin of error may be introduced in the Network Rating Policy specifying the number of significant digits to be used while comparing the average rating with the received rating.
If the rating value does not match or is not within the margin of error, then the Rating Sender should report the error to the Network Facilitator.
+
+# Examples
+
+[Examples section to be added with concrete rating and reputation scenarios]
+
+# Recommendations
+
+[Recommendations section to be added with best practices for rating and reputation implementation]
+
+# Acknowledgements
+
+The authors would like to thank the following people for their support and contributions to this document.
+
+* Pramod Varma (Beckn Foundation)
+* Sujith Nair (Beckn Foundation)
+* Venkataramanan Mahadevan (Humbhionline)
diff --git a/docs/BECKN-009-Tags-the-Edge-of-Beckn.md b/docs/BECKN-009-Tags-the-Edge-of-Beckn.md
index a509ef2b..d3b64138 100644
--- a/docs/BECKN-009-Tags-the-Edge-of-Beckn.md
+++ b/docs/BECKN-009-Tags-the-Edge-of-Beckn.md
@@ -1,55 +1,58 @@
-# Document Details
-## Supported Protocol Version
-
-TODO
-
-
-## This version
-
-TODO
+# BECKN-009:Tags, the Edge of Beckn
+## License:
+This document is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/).
-## Latest published version
+
-TODO
-
-
-## Latest editor's draft
+## Category:
+Tags
-TODO
+## Published on:
+January 21, 2022
-## Stress Test report
+## Last Updated on:
+July 8th, 2024
-TODO
+## History:
+Click on this [link](https://github.com/beckn/protocol-specifications/commits/core-1.2-release/docs/BECKN-009-Tags-the-Edge-of-Beckn.md) to view the history of changes to this document
-## Implementation report
+## Issues:
+To view issues related to this document, click on this [link](https://github.com/beckn/protocol-specifications/issues?q=is%3Aissue+label%3ABECKN-009)
-TODO
+## Discussions:
+To view discussions related to this document, click on this [link](https://github.com/beckn/protocol-specifications/discussions?discussions_q=label%3ABECKN-009)
+## Authors:
+1. [Ravi Prakash](https://github.com/ravi-prakash-v)
-## Editors
-Ravi Prakash (Beckn Foundation)
+## Reviewers:
+1. [Sujith Nair](https://github.com/sjthnrk)
+2. [Pramod Varma](https://github.com/pramodkvarma)
+3. [Venkatraman Mahadevan](https://github.com/venkatramanm)
+# Abstract
-## Authors
-Ravi Prakash (Beckn Foundation)
+Beckn protocol is a generic transaction protocol that allows any producer and consumer to interact and perform digitally signed transactions via a standard set of APIs. The schema of beckn has been abstracted to a level that allows any real-world entity to be represented as a generic object. This document defines two schemas, namely, **TagGroup** and **Tag**, that allow groups of key-value pairs to be transmitted between network participants as metadata without breaking interoperability across implementations.
+# Scope
-## Feedback
+This document is intended for the following audience:
-Issues: TODO
+1. Anyone implementing beckn protocol with extended metadata requirements
+2. BPP developers adding product/service metadata
+3. BAP developers displaying additional information
+4. Network facilitators defining metadata standards
-Discussions : TODO
+## Prerequisites
-PRs : TODO
+Readers of this document must:
+1. Have knowledge of the core beckn protocol specification
+2. Have understanding of metadata and key-value pairs
+3. Have knowledge of JSON Schema and Open API 3.0
-## Errata
-
-No Errata exists as of now
-
-
-# Context
+# Introduction
Beckn protocol is a generic transaction protocol that allows any producer and consumer to interact and perform digitally signed transactions via a standard set of APIs. The schema of beckn has been abstracted to a level that allows any real-world entity to be represented as a generic object.
@@ -61,24 +64,22 @@ A car rental provider might want to send additional information on the make, mod
Similarly, a hospitality service provider may want to transmit additional information related to a room like AC/Non-AC, WiFi availability, Breakfast included, etc to allow the customer to choose the right room for themselves.
-As you can see from the above examples, the above information is not strictly necessary for an order to be created. But rather as metadata for display purposes, grouping, and filtering at the consumer’s end; and for enabling search optimization at the provider’s end.
-
+As you can see from the above examples, the above information is not strictly necessary for an order to be created. But rather as metadata for display purposes, grouping, and filtering at the consumer's end; and for enabling search optimization at the provider's end.
# Problem
-How to transmit extended metadata related to a transaction in beckn protocol without breaking interoperability across implementations.
-
+How to transmit extended metadata related to a transaction in beckn protocol without breaking interoperability across implementations?
# Solution
Beckn protocol defines three schemas, namely, **Tags, TagGroup **and** Tag**, that allow groups of key-value pairs to be transmitted between network participants as metadata. Let us look at them in more detail.
+# Implementation Details
## The **Tags** schema
The Tags schema is an array of TagGroup objects. This contains all the extended metadata about the container object. The schema is represented below
-
```
components:
schemas:
@@ -89,7 +90,6 @@ components:
$ref: "#/components/schemas/TagGroup"
```
-
The Tags schema is explicitly referenced in the following schemas.
* Category.tags
@@ -102,12 +102,11 @@ The Tags schema is explicitly referenced in the following schemas.
* Provider.tags
* Order.tags
-However, this can be added to _any_ schema to carry extended metadata under the reserved keyname “tags”.
-
+However, this can be added to _any_ schema to carry extended metadata under the reserved keyname "tags".
## The **TagGroup** Schema
-The TagGroup schema defines a key-value set that can be listed under a common heading. Examples of key-value sets are Nutritional Information, Technical Specifications, Manufacturer Information, etc. Each of these headings contain a set of key-value pairs that contain additional metadata specific to that heading. For example, the Tag Group named “Nutritional Content” might contain a key-value set containing _kcal = 100, carbohydrates = 11g, protein = 0.2g, fat = 0.11g,_ etc. Similarly, a Tag group named “Technical Specifications” for a mobile phone product may contain a key-value set containing _RAM = 12GB, Display Size = 6.5in, Weight = 128g, Processor = Snapdragon 855,_ and so on.
+The TagGroup schema defines a key-value set that can be listed under a common heading. Examples of key-value sets are Nutritional Information, Technical Specifications, Manufacturer Information, etc. Each of these headings contain a set of key-value pairs that contain additional metadata specific to that heading. For example, the Tag Group named "Nutritional Content" might contain a key-value set containing _kcal = 100, carbohydrates = 11g, protein = 0.2g, fat = 0.11g,_ etc. Similarly, a Tag group named "Technical Specifications" for a mobile phone product may contain a key-value set containing _RAM = 12GB, Display Size = 6.5in, Weight = 128g, Processor = Snapdragon 855,_ and so on.
The TagGroup schema is represented as shown below,
@@ -138,13 +137,11 @@ The TagGroup schema is represented as shown below,
$ref: "#/components/schemas/Tag"
```
-
-As you can see, the TagGroup is of type “object” contains four properties,
-
+As you can see, the TagGroup is of type "object" contains four properties,
1. **code**: This contains a machine-readable name of the group.
-2. **display**: This indicates whether a particular TagGroup is for display purposes. It has been modeled after the CSS “display” property. If it is equal to block, then the respective tag group has to be rendered as a block of key-value pairs. If it is none, then this block should not be rendered and is for internal consumption between platforms only.
-3. **name**: This contains the name of the group like “Product Information”, “Technical Specifications”, etc
+2. **display**: This indicates whether a particular TagGroup is for display purposes. It has been modeled after the CSS "display" property. If it is equal to block, then the respective tag group has to be rendered as a block of key-value pairs. If it is none, then this block should not be rendered and is for internal consumption between platforms only.
+3. **name**: This contains the name of the group like "Product Information", "Technical Specifications", etc
4. **list** : this is an array of Tag objects. (see next section)
## The **Tag** Schema
@@ -153,7 +150,6 @@ The tag schema contains a key-value pair containing the actual extended metadata
The Tag schema is shown below.
-
```
components:
schemas:
@@ -172,93 +168,33 @@ The Tag schema is shown below.
type: string
```
-
As you can see, the Tag schema has the following properties
-
-
1. **key** : The machine-readable name of the tag. This is generally a standard value that must be mutually agreed at a network level.
2. **name**: The display name of the key. This is non-standard and can be set by the creator. For example, there could be two providers who sell mobile phones. One of them
3. **value** : This contains the associated value of the key
-The **Tag** schema is referenced in the **TagGroup** schema in its property - “list”.
-
-
-# Recommendations
-
-This section contains recommendations for entities using the Tag schema.
-
-
-### For BPPs
-
-1. BPPs must group various key-value pairs under a common
-2. BPPs must mandatorily send the tags that have been mandated by the network policy
-3. The value of the “key” field is recommended to be in the snake-case format.
-4. Non-standard tags must be prefixed by a namespace defined by the creator of the tags. To ensure namespace uniqueness, it is recommended that the namespace contain the FQDN of the creator of the tag.
-5. BPPs are recommended index their catalog, carts and order books using these tags to allow better searchability
-
-
-### For BAPs
-
-1. BAPs must render or not render the tags according to the “display” property of its parent tag group.
-2. BAPs must render the tags that have been mandated by the network policy
-3. BAPs can also use these tags to create recommendations or allow comparisons between items basis a specific property
-4. It is recommended that BAPs have a “Report” feature that allows a user to report missing attributes.
-
-
-### For Network Facilitators
-
-1. Certain Tag keys can be mandated to be sent by BPPs to enable compliance to statutory laws
-2. Certain Tag names can also be standardized to enable BAPs to provide consistent customer experience.
-3. Certain Tag groups can be mandated to be hidden or rendered by BAPs
-4. Network facilitators should refer to standard supported tags maintained by domain-specific working groups when creating tag lists.
-5. Tags not found in lists maintained by domain-specific working groups, should be namespaced with a unique network level identifier, usually the FQDN of the network facilitator.
-
-
-### For Domain-specific Working Groups
-
-1. Domain-specific working groups should aggressively create and actively maintain an exhaustive list of standard keywords under various categories and subcategories that can be referenced by network facilitators
-
+The **Tag** schema is referenced in the **TagGroup** schema in its property - "list".
## Reserved Keywords
-Beckn protocol reserves some values for the “key” property of the Tag schema. These values are
+Beckn protocol reserves some values for the "key" property of the Tag schema. These values are
1. **seo** : This indicates the corresponding value is for search optimization. BAPs frequently send this as part of the Intent object
2. **url**: This indicates that that corresponding value is a clickable URL
3. **lang**: Contains a spoken language code
+# Examples
-## Recommendations
-
-### For BPPs
-
-* In the Item.tags array, BPPs must send all the read-only metadata associated with an Item in the tags array.
-* Any network-level category codes must be sent in the tags array
-* BPPs can use network-level standard tags to index their order book
-* BPPs can use network-level standard tags to index their product catalog database
-
-
-### For BAPs
-
-* BAPs can send tags in the Intent object during search to allow BPPs to search through their catalog faster
-* BAPs can use the Item.tags array to display additional information about the item like statutory fields.
-
-
-### For Network Facilitators
-
-* Network Facilitators should publish a list of supported Tags with their namespace, key, and hidden properties that BAPs and BPPs can use
-
-
-# Concrete Examples
+## Concrete Examples
### Example 1: A retail domain-specific working group wants to publish a set of standard tags for various categories of product.
TODO
-### Example 2: A network facilitator with domain as examplenetwork.org wanted to mandate a retail-specific tag called country_of_mfg (Country of manufacture) to be sent as part of the Item. The network facilitator’s domain name is mynetwork.org. The following fields are mandated to be shown whenever packaged goods are being sold.
+### Example 2: A network facilitator with domain as examplenetwork.org wanted to mandate a retail-specific tag called country_of_mfg (Country of manufacture) to be sent as part of the Item. The network facilitator's domain name is mynetwork.org. The following fields are mandated to be shown whenever packaged goods are being sold.
TODO
-It will first check with the tag list maintained by the local retail working group. If it finds the tag listed, it will simply publish that tag with a link to the source tag list. If it doesn’t find the desired tag listed, it will simply namespace and publish it as @examplenetwork/org/country_of_origin
+It will first check with the tag list maintained by the local retail working group. If it finds the tag listed, it will simply publish that tag with a link to the source tag list. If it doesn't find the desired tag listed, it will simply namespace and publish it as @examplenetwork/org/country_of_origin
### Example 3: A packaged food product needs to be sent in response to a search request. The network policy states that product information displayed on a BAP app must be in compliance with the statutory laws of the region.
@@ -268,19 +204,46 @@ It will first check with the tag list maintained by the local retail working gro
* brand_owner
* brand_owner_address
-For example, if the FQDN of a network facilitator is mynetwork.org, and the key name is “fssai_license_number” then the namespace will be equal to “@mynetwork.org/fssai_license_number”.
-
+For example, if the FQDN of a network facilitator is mynetwork.org, and the key name is "fssai_license_number" then the namespace will be equal to "@mynetwork.org/fssai_license_number".
### Example 4: Searching for teleconsulatation services by providing symptoms and language as hindi
TODO
+# Recommendations
-# Acknowledgements
+This section contains recommendations for entities using the Tag schema.
-The author would like to thank the following people for their support and contributions to this document.
+## For BPPs
+
+1. BPPs must group various key-value pairs under a common
+2. BPPs must mandatorily send the tags that have been mandated by the network policy
+3. The value of the "key" field is recommended to be in the snake-case format.
+4. Non-standard tags must be prefixed by a namespace defined by the creator of the tags. To ensure namespace uniqueness, it is recommended that the namespace contain the FQDN of the creator of the tag.
+5. BPPs are recommended index their catalog, carts and order books using these tags to allow better searchability
+
+## For BAPs
+
+1. BAPs must render or not render the tags according to the "display" property of its parent tag group.
+2. BAPs must render the tags that have been mandated by the network policy
+3. BAPs can also use these tags to create recommendations or allow comparisons between items basis a specific property
+4. It is recommended that BAPs have a "Report" feature that allows a user to report missing attributes.
+## For Network Facilitators
+1. Certain Tag keys can be mandated to be sent by BPPs to enable compliance to statutory laws
+2. Certain Tag names can also be standardized to enable BAPs to provide consistent customer experience.
+3. Certain Tag groups can be mandated to be hidden or rendered by BAPs
+4. Network facilitators should refer to standard supported tags maintained by domain-specific working groups when creating tag lists.
+5. Tags not found in lists maintained by domain-specific working groups, should be namespaced with a unique network level identifier, usually the FQDN of the network facilitator.
+
+## For Domain-specific Working Groups
+
+1. Domain-specific working groups should aggressively create and actively maintain an exhaustive list of standard keywords under various categories and subcategories that can be referenced by network facilitators
+
+# Acknowledgements
+
+The author would like to thank the following people for their support and contributions to this document.
1. Venkataramanan Mahadevan
2. Pramod Varma
-3. Sujith Nair
\ No newline at end of file
+3. Sujith Nair
diff --git a/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md b/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md
index fd9d29bf..fae2c3e0 100644
--- a/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md
+++ b/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md
@@ -1,42 +1,70 @@
-# Keyword Definitions for Technical Specifications
+# BECKN-010:Keyword Definitions for Technical Specifications
-#### CWG Working Draft - September 01, 2023
+## License:
+This document is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/).
-## Document Details
-### This version
-https://github.com/beckn/protocol-specifications/blob/release-1.x/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md
+
-### Latest published version
-None
+## Category:
+Keywords for Technical Specification
-### Latest editor's draft
-https://github.com/beckn/protocol-specifications/blob/release-1.x/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md
+## Published on:
+January 21, 2022
-### Implementation report
-TODO
+## Last Updated on:
+July 8th, 2024
-### Editors
-Ravi Prakash (FIDE)
+## History:
+Click on this [link](https://github.com/beckn/protocol-specifications/commits/core-1.2-release/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md) to view the history of changes to this document
-### Authors
-Ravi Prakash (FIDE)
+## Issues:
+To view issues related to this document, click on this [link](https://github.com/beckn/protocol-specifications/issues?q=is%3Aissue+label%3ABECKN-010)
-### Feedback
+## Discussions:
+To view discussions related to this document, click on this [link](https://github.com/beckn/protocol-specifications/discussions?discussions_q=label%3ABECKN-010)
-Issues: TODO
-Discussions: TODO
-PRs: TODO
+## Authors:
+1. [Ravi Prakash](https://github.com/ravi-prakash-v)
-### Errata
-No Errata exists as of now
+## Reviewers:
+1. [Sujith Nair](https://github.com/sjthnrk)
+2. [Pramod Varma](https://github.com/pramodkvarma)
+3. [Venkatraman Mahadevan](https://github.com/venkatramanm)
-## Abstract
+# Abstract
This document outlines the definitions of key words that are commonly used in technical specifications, standards, and protocols. The aim is to provide a uniform interpretation of these terms to avoid ambiguity and misinterpretation.
-## Introduction
+# Scope
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described below. These definitions aim to ensure that the terms are understood precisely and consistently to avoid confusion in the interpretation of standards, specifications, and protocols.
+This document is intended for the following audience:
+
+1. Anyone reading or writing beckn protocol technical specifications
+2. Developers implementing beckn protocol requirements
+3. Quality assurance teams testing beckn implementations
+4. Technical writers creating beckn documentation
+
+## Prerequisites
+
+Readers of this document must:
+
+1. Have knowledge of technical documentation standards
+2. Have understanding of RFC 2119 terminology
+3. Have basic knowledge of beckn protocol concepts
+
+# Introduction
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [rfc 2119](https://datatracker.ietf.org/doc/html/rfc2119). These definitions aim to ensure that the terms are understood precisely and consistently to avoid confusion in the interpretation of standards, specifications, and protocols.
+
+# Problem
+
+How to ensure consistent interpretation of technical requirements and specifications across all beckn protocol implementations and documentation?
+
+# Solution
+
+Implement standardized keyword definitions based on RFC 2119 that provide clear, unambiguous meaning to requirement levels in technical specifications.
+
+# Implementation Details
## Definitions
@@ -80,6 +108,8 @@ The term "MAY" indicates that an item is truly optional.
The term "OPTIONAL" is synonymous with "MAY".
+# Examples
+
## Examples and Correct Usage
In this section, we provide examples that demonstrate the correct usage of the key words defined in this document. The examples are related to a hypothetical Beckn Application Platform (BAP) that interacts with a Beckn Provider Platform (BPP) using beckn protocol APIs.
@@ -94,10 +124,14 @@ In this section, we provide examples that demonstrate the correct usage of the k
### Example 2: Using "RECOMMENDED" and "SHOULD"
- RECOMMENDED. Upon receiving a `search` request, the BPP SHOULD return a `Catalog` that best matches the `Intent`. This can be done by indexing the catalog against the various probable paths in the `Intent` schema relevant to the use case.
-## Conclusion
+# Recommendations
-The definitions provided in this document are intended to clarify the interpretation of key terms used in technical specifications, standards, and protocols. Adherence to these definitions will ensure a consistent understanding and implementation of such documents.
+[Recommendations section to be added with best practices for using technical keywords]
-> Note : This document is subject to change and may be updated to include additional terms or to refine existing definitions.
+# Acknowledgements
+The authors would like to thank the following people for their support and contributions to this document.
+* Pramod Varma (Beckn Foundation)
+* Sujith Nair (Beckn Foundation)
+* Venkataramanan Mahadevan (Humbhionline)
diff --git a/docs/BECKN-011-Search-Provider-Draft-01.md b/docs/BECKN-011-Search-Provider.md
similarity index 58%
rename from docs/BECKN-011-Search-Provider-Draft-01.md
rename to docs/BECKN-011-Search-Provider.md
index 83b685cd..fefdc418 100644
--- a/docs/BECKN-011-Search-Provider-Draft-01.md
+++ b/docs/BECKN-011-Search-Provider.md
@@ -1,19 +1,70 @@
-# Search Provider
+# BECKN-011:Search Provider
+## License:
+This document is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/).
+
+
+
+## Category:
+Search Provider
+
+## Published on:
+July 29th, 2023
+
+## Last Updated on:
+July 8th, 2024
+
+## History:
+Click on this [link](https://github.com/beckn/protocol-specifications/commits/core-1.2-release/docs/BECKN-011-Search-Provider.md) to view the history of changes to this document
+
+## Issues:
+To view issues related to this document, click on this [link](https://github.com/beckn/protocol-specifications/issues?q=is%3Aissue+label%3ABECKN-011)
+
+## Discussions:
+To view discussions related to this document, click on this [link](https://github.com/beckn/protocol-specifications/discussions?discussions_q=label%3ABECKN-011)
+
+## Authors:
+1. [Ravi Prakash](https://github.com/ravi-prakash-v)
+
+## Reviewers:
+1. [Sujith Nair](https://github.com/sjthnrk)
+2. [Pramod Varma](https://github.com/pramodkvarma)
+3. [Venkatraman Mahadevan](https://github.com/venkatramanm)
+
+# Abstract
+
+When BAP fires a `/search` on the gateway, the gateway needs to `lookup` on the registry for all available BPPS that are up and running and cascade the call on to those BPPS. These BPPS in turn do the processing and respond with an `on_search` callback to the BAP. All this takes time and is fairly repetitive. This document defines a new kind of participant on the network called Search Engine (or Search Provider) that can optimize search performance by maintaining current catalog information and serving search requests more efficiently.
+
+# Scope
+
+This document is intended for the following audience:
+
+1. Anyone implementing beckn protocol search optimization systems
+2. Network facilitators designing search infrastructure
+3. BPP developers looking to optimize search performance
+4. BAP developers implementing search functionality
+
+## Prerequisites
+
+Readers of this document must:
+
+1. Have knowledge of the core beckn protocol specification
+2. Have understanding of search systems and indexing
+3. Have knowledge of beckn gateway and registry functionality
+
+# Introduction
-# Context
When BAP fires a `/search` on the gateway, the gateway needs to `lookup` on the registry for all available BPPS that are up and running and cascade the call on to those BPPS. These BPPS in turn do the processing and respond with an `on_search` callback to the BAP. All this takes time and is fairly repetitive. To overcome this problem on the user experience, Buyer apps have arrived at several strategies like :
1. Cache the entire catalogue of the sellers
2. Pull incremental changes to catalogue from sellers based on timestamping.
3. Have BPPS push their catalogue changes to all the BAPS on the network.
+# Problem
+Every new BAP addition will cause all BPPS to start sending catalogues to that BAP also. Every new BPP addition will cause all BAPS to start caching catalogues for that BPP also. This is difficult to maintain and is error prone.
+# Solution
-
-# Problem
-Every new BAP addition will cause all BPPS to start sending catalogues to that BAP also. Every new BPP addition will cause all BAPS to start caching catalogues for that BPP also. This is difficult to maintain and is error prone.
-# Solution
Have a new kind of participant on the network called Search Engine ( or if you will Search Provider). BPPS can onboard onto any search provider of their choice. The search provider spec would ensure that BPPS can push enabled/disabled catalogue items in manageable chunks onto these search providers so that the most current catalogue is always served on the network.
For Eg...
@@ -27,23 +78,23 @@ When BAPS fire `search` on the bg, it is cascaded to `search providers` associat
The Search provider would then compute `on_search` responses for each of its BPP and fire `on_collective_search` to the BAP. The payload for this new api would contain an array of `on_search` payloads corresponding to each BPP on-boarded on the search provider. The message_id , transaction_id etc would be same in all the returned elements.
```
-
[ {"context":".. bpp context", "message" : "on_search response of the bpp_"}]
-
-
```
BAPS can validate the authenticity of the search provider (Based on usual signatures) and simple loop through the payload array and process as if each element was returned by the corresponding bpp on their `on_search`.
-
-** NOTE ** The search provider can make multiple `/on_collective_search` calls to a bap to chunk the payloads by bpps to avoid sending large payloads.
-## Changes to registry spec
+** NOTE ** The search provider can make multiple `/on_collective_search` calls to a bap to chunk the payloads by bpps to avoid sending large payloads.
+
+# Implementation Details
+
+## Changes to registry spec
+
1. Would need to associate a search provider id for a BPP.
2. Search provider as a participant on the network would require a new role "SP", have its own public key and subscriber url like all BPPS.
3. The domain would be the same as the domain of BPPS it can serve on its infrastructure.
+## Gateway Changes
-## Gateway Changes
Current:
1. On receiving /search from a BAP,
@@ -55,28 +106,33 @@ Changed Behavior:
1. On receiving /search from a BAP,
1. BG does a lookup on the registry to get all BPPS and SPS matching the context's domain.
1. Relay the search intent to each identified SP and BPP (not associated with any SP)
-
-## Changes to BPP
+
+## Changes to BPP
+
1. BPPS wishing to leverage a SP for fast responses to BAPS can onboard to one of the empanelled SP of their choice.
1. Make call to SP hooks to keep catalogues current.
-## Changes to BAP
+
+## Changes to BAP
+
1. Implement `on_collective_search` api.
-1. loop through the array in the payload and process each `on_search` request as usual.
+1. loop through the array in the payload and process each `on_search` request as usual.
+
+## Recommendations For Network
-# Recommendations For Network
1. Include SP specification into BG specification so that an additional network hop may be avoided
-1. Cost of SP can be included in gateway fees.
-
-# Concrete Examples
+1. Cost of SP can be included in gateway fees.
+# Examples
Examples to be documented here.
+# Recommendations
-# Acknowledgements
+[Recommendations section to be added with best practices for search provider implementation]
-The author would like to thank the following people for their support and contributions to this document.
+# Acknowledgements
+The author would like to thank the following people for their support and contributions to this document.
1. Ravi Prakash
2. Pramod Varma
diff --git a/docs/README.md b/docs/README.md
index e05935f3..aeca40a9 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,5 +1,5 @@
# Protocol Drafts
-These files contain specifications that have been selected from the proposals submitted to the beckn protocol specifications. The are currently under review by different working groups in the various categories supported beckn protocol governance.
+These files contain specifications that have been selected from the proposals submitted to the beckn protocol specifications. They are currently under review by different working groups in the various categories supported by beckn protocol governance.
After sufficient deliberation, these drafts may be published as a Protocol Standard.
\ No newline at end of file
diff --git a/schema/AddOn.yaml b/schema/AddOn.yaml
index 4ec79b6e..45a6e10a 100644
--- a/schema/AddOn.yaml
+++ b/schema/AddOn.yaml
@@ -8,8 +8,4 @@ properties:
$ref: "./Descriptor.yaml"
price:
$ref: "./Price.yaml"
- quantity:
- description: The Selling quantity of the Item
- allOf:
- - $ref: "./ItemQuantity.yaml"
diff --git a/schema/Cancellation.yaml b/schema/Cancellation.yaml
index b0085380..0c55fbc3 100644
--- a/schema/Cancellation.yaml
+++ b/schema/Cancellation.yaml
@@ -7,6 +7,7 @@ properties:
format: date-time
cancelled_by:
type: string
+ description: Indicated who canceled a specific entity, such as an order or a booking.
enum:
- CONSUMER
- PROVIDER
diff --git a/schema/Catalog.yaml b/schema/Catalog.yaml
index 614386ef..ca5ba91d 100644
--- a/schema/Catalog.yaml
+++ b/schema/Catalog.yaml
@@ -27,4 +27,5 @@ properties:
type: string
format: date-time
ttl:
+ description: Represents the validity of the request.
$ref: "./Duration.yaml"
diff --git a/schema/Contact.yaml b/schema/Contact.yaml
index 214da643..4a0965ef 100644
--- a/schema/Contact.yaml
+++ b/schema/Contact.yaml
@@ -2,8 +2,10 @@ description: Describes the contact information of an entity
type: object
properties:
phone:
+ description: Phone number of an entity.
type: string
email:
+ description: Email of an entity.
type: string
jcard:
type: object
diff --git a/schema/Credential.yaml b/schema/Credential.yaml
index bab203d4..94c4df0f 100644
--- a/schema/Credential.yaml
+++ b/schema/Credential.yaml
@@ -2,9 +2,11 @@ description: Describes a credential of an entity - Person or Organization
type: object
properties:
id:
+ description: A unique identifier for the credential
type: string
type:
type: string
+ description: Type of the credential, i.e. token, SAML, ssh keys etc.
default: "VerifiableCredential"
url:
description: URL of the credential
diff --git a/schema/Document.yaml b/schema/Document.yaml
index 98b6c12a..2f453acc 100644
--- a/schema/Document.yaml
+++ b/schema/Document.yaml
@@ -7,8 +7,6 @@ properties:
url:
type: string
format: uri
- label:
- type: string
mime_type:
description: Describes the contents of the uri field. If the value is text/html, it is recommended for the BAP to render the contents inside a webview. This generally does not render a good user experience on the BAP, hence the payment page developers are recommended to develop their payment pages in a mobile-friendly manner.
type: string
diff --git a/schema/Form.yaml b/schema/Form.yaml
index e3993203..d165585d 100644
--- a/schema/Form.yaml
+++ b/schema/Form.yaml
@@ -2,7 +2,7 @@ description: Describes a form
type: object
properties:
url:
- description: The URL from where the form can be fetched. The content fetched from the url must be processed as per the mime_type specified in this object. Once fetched, the rendering platform can choosed to render the form as-is as an embeddable element; or process it further to blend with the theme of the application. In case the interface is non-visual, the the render can process the form data and reproduce it as per the standard specified in the form.
+ description: The URL from where the form can be fetched. The content fetched from the url must be processed as per the MIME type specified in this object. Once fetched, the rendering platform can choosed to render the form as-is as an embeddable element; or process it further to blend with the theme of the application. In case the interface is non-visual, the the render can process the form data and reproduce it as per the standard specified in the form.
type: string
format: uri
data:
@@ -19,8 +19,10 @@ properties:
- application/html
resubmit:
type: boolean
+ description: Set to true if the resubmission of a form is required. It could be due to a validation error, or session timeout etc.
submission_id:
type: string
+ description: A unique identifier associated with a submission of a form.
format: uuid
auth:
type: object
@@ -28,4 +30,5 @@ properties:
descriptor:
$ref: "./Descriptor.yaml"
value:
- type: string
\ No newline at end of file
+ type: string
+ description: The token that will be used for the authentication. It could be JWT (JSON Web Token), OAuth etc.
\ No newline at end of file
diff --git a/schema/Fulfillment.yaml b/schema/Fulfillment.yaml
index d71201d1..19bccfe0 100644
--- a/schema/Fulfillment.yaml
+++ b/schema/Fulfillment.yaml
@@ -19,7 +19,7 @@ properties:
allOf:
- $ref: "./FulfillmentState.yaml"
documents:
- description: The Documents associated to the fullfilment
+ description: The Documents associated with the fullfilment object. For example in the case of online courses, it could represent a certificate of completion of a course.
type: array
items:
$ref: "./Document.yaml"
diff --git a/schema/MediaFile.yaml b/schema/MediaFile.yaml
index fb6ffcf8..0aaa2b15 100644
--- a/schema/MediaFile.yaml
+++ b/schema/MediaFile.yaml
@@ -1,7 +1,7 @@
description: This object contains a url to a media file.
type: object
properties:
- mimetype:
+ mime_type:
description: indicates the nature and format of the document, file, or assortment of bytes. MIME types are defined and standardized in IETF's RFC 6838
type: string
url:
diff --git a/schema/Price.yaml b/schema/Price.yaml
index 7d29649d..d29e3866 100644
--- a/schema/Price.yaml
+++ b/schema/Price.yaml
@@ -3,17 +3,28 @@ type: object
properties:
currency:
type: string
+ description: Medium of exchange, traditional unit of payment, i.e. INR, USD etc.
value:
type: string
+ description: Monetary cost of an item, a decimal represented as string
estimated_value:
type: string
+ description: Monetary cost of an item, a decimal represented as string
computed_value:
type: string
+ description: Monetary cost of an item, a decimal represented as string
listed_value:
type: string
+ description: Monetary cost of an item, a decimal represented as string
offered_value:
type: string
+ description: Monetary cost of an item, a decimal represented as string
minimum_value:
type: string
+ description: Monetary cost of an item, a decimal represented as string
maximum_value:
- type: string
\ No newline at end of file
+ type: string
+ description: Monetary cost of an item, a decimal represented as string
+ unit:
+ type: string
+ description: A unit of payment that can act as an instrument of exchange, i.e. carbon credit, bitcoin, etc.
\ No newline at end of file
-
-
-
-