From 2f95c7e728a28476d57d14dd74173318282479c8 Mon Sep 17 00:00:00 2001 From: Rajaneesh Date: Thu, 4 Jul 2024 14:27:36 +0530 Subject: [PATCH 01/11] Making the following changes: - Add: Price.unit - Add: Description in objects where it is missing - Change: mime_type to mimetype - Remove: Document.label - Remove: addon.quantity - Remove: draft keyword from all the documents under doc/ - Resturture the content of all the documents under doc/ - Remove: ID, title, expires on, status fields - Addded: last update date - Changed: licence version - Changed abstract of BECKN-003 --- api/transaction/build/transaction.yaml | 14 ++--- ...d => BECKN-001-Layering-Network-Policy.md} | 2 - ...-002-Payments-On-Beckn-Enabled-Networks.md | 28 +++------ ...BECKN-003-Beckn-Protocol-Communication.md} | 37 +++++------- ...dministration-On-Beckn-Enabled-Networks.md | 29 +++------ ...s-Draft-01.md => BECKN-005-Error-Codes.md} | 31 ++++------ ...> BECKN-006-Signing-Beckn-APIs-In-HTTP.md} | 21 ++++++- docs/BECKN-007-The-XInput-Schema.md | 43 +++++--------- ...Rating-and-Reputation-on-Beckn-Protocol.md | 23 ++++++-- docs/BECKN-009-Tags-the-Edge-of-Beckn.md | 59 +++++-------------- ...efinitions-for-Technical-Specifications.md | 38 +++++------- ...aft-01.md => BECKN-011-Search-Provider.md} | 26 ++++++-- docs/README.md | 2 +- schema/AddOn.yaml | 4 -- schema/Cancellation.yaml | 1 + schema/Catalog.yaml | 1 + schema/Contact.yaml | 2 + schema/Credential.yaml | 2 + schema/Document.yaml | 4 +- schema/Form.yaml | 9 ++- schema/Fulfillment.yaml | 2 +- schema/Price.yaml | 2 + 22 files changed, 169 insertions(+), 211 deletions(-) rename docs/{BECKN-001-Layering-Network-Policy-Draft-01.md => BECKN-001-Layering-Network-Policy.md} (99%) rename docs/{BECKN-003-Beckn-Protocol-Communication-Draft-01.md => BECKN-003-Beckn-Protocol-Communication.md} (67%) rename docs/{BECKN-005-Error-Codes-Draft-01.md => BECKN-005-Error-Codes.md} (84%) rename docs/{BECKN-006-Signing-Beckn-APIs-In-HTTP-Draft-01.md => BECKN-006-Signing-Beckn-APIs-In-HTTP.md} (97%) rename docs/{BECKN-011-Search-Provider-Draft-01.md => BECKN-011-Search-Provider.md} (90%) diff --git a/api/transaction/build/transaction.yaml b/api/transaction/build/transaction.yaml index 11472c94..f7528cde 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 @@ -1069,9 +1065,7 @@ components: url: type: string format: uri - label: - type: string - mime_type: + mimetype: 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 enum: @@ -1122,7 +1116,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 mimetype 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: @@ -1130,7 +1124,7 @@ components: type: object additionalProperties: type: string - mime_type: + mimetype: description: This field indicates the nature and format of the form received by querying the url. MIME types are defined and standardized in IETF's RFC 6838. type: string enum: @@ -1832,6 +1826,8 @@ components: type: string maximum_value: type: string + unit: + type: string Provider: description: Describes the catalog of a business. type: object diff --git a/docs/BECKN-001-Layering-Network-Policy-Draft-01.md b/docs/BECKN-001-Layering-Network-Policy.md similarity index 99% rename from docs/BECKN-001-Layering-Network-Policy-Draft-01.md rename to docs/BECKN-001-Layering-Network-Policy.md index fbd15eb1..525ba743 100644 --- a/docs/BECKN-001-Layering-Network-Policy-Draft-01.md +++ b/docs/BECKN-001-Layering-Network-Policy.md @@ -22,8 +22,6 @@ This document is licensed under a [Creative Commons Attribution-NonCommercial-Sh 2. Pramod Varma : pramod@ekstep.org 3. Venkatraman Mahadevan : venkatramanm@gmail.com -replace email with github ids. - # 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. diff --git a/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md b/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md index 2c6984cd..24009ec7 100644 --- a/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md +++ b/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md @@ -1,36 +1,26 @@ -# Payments on Beckn-Enabled Networks - - -## ID: -BECKN-RFC-002 - -## Draft ID -Draft-01 - -## Title: -Payments on Beckn-Enabled Networks +# BECKN-002:Payments on Beckn-Enabled Networks ## Category: Payments -## Status: -Protocol Draft - ## Published on: December 10, 2021 -## Expires on: -April 05, 2022 or Date of publication of next draft which ever is earlier +## Last Updated on: +July 4th, 2024 ## License: -CC-BY-ND +This document is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/). + +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) ## Authors: -1. Ravi Prakash : ravi@becknfoundation.org +1. Ravi Prakash : ravi@becknprotocol.io ## Reviewers: -1. Sujith Nair : sujith@becknfoundation.org +1. Sujith Nair : sujith@becknprotocol.io 2. Pramod Varma : pramod@ekstep.org +3. Venkatraman Mahadevan : venkatramanm@gmail.com # 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. diff --git a/docs/BECKN-003-Beckn-Protocol-Communication-Draft-01.md b/docs/BECKN-003-Beckn-Protocol-Communication.md similarity index 67% rename from docs/BECKN-003-Beckn-Protocol-Communication-Draft-01.md rename to docs/BECKN-003-Beckn-Protocol-Communication.md index 23a08ea7..d37c350e 100644 --- a/docs/BECKN-003-Beckn-Protocol-Communication-Draft-01.md +++ b/docs/BECKN-003-Beckn-Protocol-Communication.md @@ -1,38 +1,31 @@ -# Beckn Protocol Communication - -## ID -BECKN-RFC-003 - -## Draft ID -Draft-01 - -## Title -Beckn Protocol Communication +# BECKN-003: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 +## Last Updated on: +July 4th, 2024 + +## 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/). -## License -CC-BY-ND +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) -## Authors -1. Ravi Prakash : ravi@becknfoundation.org +## Authors: +1. Ravi Prakash : ravi@becknprotocol.io -## Reviewers -1. Sujith Nair : sujith@becknfoundation.org +## Reviewers: +1. Sujith Nair : sujith@becknprotocol.io 2. Pramod Varma : pramod@ekstep.org +3. Venkatraman Mahadevan : venkatramanm@gmail.com # 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. +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. # Introduction A beckn enabled network has multiple entities communicating with each other via standard protocol APIs. The following types of communication are possible. 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..5d959bc6 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,26 @@ -# Policy Administration on Beckn-Enabled Networks - -## ID: -BECKN-RFC-004 - -## Draft ID -Draft-01 - -## Title: -Policy Administration on Beckn-Enabled Networks +# BECKN-004: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 4th, 2024 ## License: -CC-BY-ND +This document is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/). + +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) ## Authors: -1. Ravi Prakash : ravi@becknfoundation.org -2. Sujith Nair : sujith@becknfoundation.org +1. Ravi Prakash : ravi@becknprotocol.io ## Reviewers: -1. Sujith Nair : sujith@becknfoundation.org +1. Sujith Nair : sujith@becknprotocol.io 2. Pramod Varma : pramod@ekstep.org - +3. Venkatraman Mahadevan : venkatramanm@gmail.com # Introduction diff --git a/docs/BECKN-005-Error-Codes-Draft-01.md b/docs/BECKN-005-Error-Codes.md similarity index 84% rename from docs/BECKN-005-Error-Codes-Draft-01.md rename to docs/BECKN-005-Error-Codes.md index a7208710..0db9ec44 100644 --- a/docs/BECKN-005-Error-Codes-Draft-01.md +++ b/docs/BECKN-005-Error-Codes.md @@ -1,28 +1,23 @@ -# Error Codes for BPP - -## ID: -BECKN-005 - -## Draft ID -Draft-01 - -## Title: -Error Codes - -## Status: -Protocol Draft +# BECKN-005:Error Codes for BPP ## Published on: January 21, 2022 -## Expires on: -January 20, 2023 or Date of publication of next draft which ever is earlier +## Last Updated on: +July 4th, 2024 ## License: -CC-BY-ND +This document is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/). + +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) ## Authors: -1. Ravi Prakash : ravi@becknfoundation.org +1. Ravi Prakash : ravi@becknprotocol.io + +## Reviewers: +1. Sujith Nair : sujith@becknprotocol.io +2. Pramod Varma : pramod@ekstep.org +3. Venkatraman Mahadevan : venkatramanm@gmail.com ## Introduction This document outlines the error codes which must be returned by a BPP. @@ -60,7 +55,7 @@ CC-BY-ND |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): + 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 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 97% 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..d54828de 100644 --- a/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP-Draft-01.md +++ b/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP.md @@ -1,4 +1,23 @@ -# Signing Beckn APIs in HTTP - Draft 04 +# BECKN-006:Signing Beckn APIs in HTTP + +## Published on: +January 21, 2022 + +## Last Updated on: +July 4th, 2024 + +## 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/). + +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) + +## Authors: +1. Ravi Prakash : ravi@becknprotocol.io + +## Reviewers: +1. Sujith Nair : sujith@becknprotocol.io +2. Pramod Varma : pramod@ekstep.org +3. Venkatraman Mahadevan : venkatramanm@gmail.com ## 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. diff --git a/docs/BECKN-007-The-XInput-Schema.md b/docs/BECKN-007-The-XInput-Schema.md index e0e90127..00bb7147 100644 --- a/docs/BECKN-007-The-XInput-Schema.md +++ b/docs/BECKN-007-The-XInput-Schema.md @@ -1,36 +1,23 @@ -# 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 +## Published on: +January 21, 2022 -### Latest published version -TODO +## Last Updated on: +July 4th, 2024 -### Latest editor's draft -TODO +## 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/). -### Implementation report -TODO +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) -### Editors -Ravi Prakash (Beckn Foundation) - -### Authors -Ravi Prakash (Beckn Foundation) - - -### Feedback - -Issues: TODO -Discussions: TODO -PRs: TODO - - -### Errata -No Errata exists as of now +## Authors: +1. Ravi Prakash : ravi@becknprotocol.io +## Reviewers: +1. Sujith Nair : sujith@becknprotocol.io +2. Pramod Varma : pramod@ekstep.org +3. Venkatraman Mahadevan : venkatramanm@gmail.com ## 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. @@ -109,7 +96,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 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..c7630562 100644 --- a/docs/BECKN-008-Rating-and-Reputation-on-Beckn-Protocol.md +++ b/docs/BECKN-008-Rating-and-Reputation-on-Beckn-Protocol.md @@ -1,11 +1,24 @@ -# Rating and Reputation on Beckn Protocol +# BECKN-008:Rating and Reputation on Beckn Protocol -*Draft 01* +## Published on: +January 21, 2022 -Author: -======= +## Last Updated on: +July 4th, 2024 + +## 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/). + +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) + +## Authors: +1. Ravi Prakash : ravi@becknprotocol.io + +## Reviewers: +1. Sujith Nair : sujith@becknprotocol.io +2. Pramod Varma : pramod@ekstep.org +3. Venkatraman Mahadevan : venkatramanm@gmail.com -Ravi Prakash (ravi@becknfoundation.org) Scope ===== diff --git a/docs/BECKN-009-Tags-the-Edge-of-Beckn.md b/docs/BECKN-009-Tags-the-Edge-of-Beckn.md index a509ef2b..1e4b214d 100644 --- a/docs/BECKN-009-Tags-the-Edge-of-Beckn.md +++ b/docs/BECKN-009-Tags-the-Edge-of-Beckn.md @@ -1,52 +1,23 @@ -# Document Details -## Supported Protocol Version +# BECKN-009:Tags, the Edge of Beckn -TODO - - -## This version - -TODO - - -## Latest published version - -TODO - - -## Latest editor's draft - -TODO - -## Stress Test report - -TODO - -## Implementation report - -TODO - - -## Editors -Ravi Prakash (Beckn Foundation) +## Published on: +January 21, 2022 +## Last Updated on: +July 4th, 2024 -## Authors -Ravi Prakash (Beckn Foundation) +## 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/). +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) -## Feedback +## Authors: +1. Ravi Prakash : ravi@becknprotocol.io -Issues: TODO - -Discussions : TODO - -PRs : TODO - - -## Errata - -No Errata exists as of now +## Reviewers: +1. Sujith Nair : sujith@becknprotocol.io +2. Pramod Varma : pramod@ekstep.org +3. Venkatraman Mahadevan : venkatramanm@gmail.com # Context @@ -279,8 +250,6 @@ TODO 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 diff --git a/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md b/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md index fd9d29bf..34a472c7 100644 --- a/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md +++ b/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md @@ -1,34 +1,24 @@ -# Keyword Definitions for Technical Specifications +# BECKN-010:Keyword Definitions for Technical Specifications -#### CWG Working Draft - September 01, 2023 +## Published on: +January 21, 2022 -## Document Details -### This version -https://github.com/beckn/protocol-specifications/blob/release-1.x/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md +## Last Updated on: +July 4th, 2024 -### Latest published version -None +## 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 editor's draft -https://github.com/beckn/protocol-specifications/blob/release-1.x/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) -### Implementation report -TODO +## Authors: +1. Ravi Prakash : ravi@becknprotocol.io -### Editors -Ravi Prakash (FIDE) +## Reviewers: +1. Sujith Nair : sujith@becknprotocol.io +2. Pramod Varma : pramod@ekstep.org +3. Venkatraman Mahadevan : venkatramanm@gmail.com -### Authors -Ravi Prakash (FIDE) - -### Feedback - -Issues: TODO -Discussions: TODO -PRs: TODO - -### Errata -No Errata exists as of now ## Abstract diff --git a/docs/BECKN-011-Search-Provider-Draft-01.md b/docs/BECKN-011-Search-Provider.md similarity index 90% rename from docs/BECKN-011-Search-Provider-Draft-01.md rename to docs/BECKN-011-Search-Provider.md index 83b685cd..59ff4267 100644 --- a/docs/BECKN-011-Search-Provider-Draft-01.md +++ b/docs/BECKN-011-Search-Provider.md @@ -1,16 +1,31 @@ -# Search Provider +# BECKN-011:Search Provider +## Published on: +July 29th, 2023 -# Context +## Last Updated on: +July 4th, 2024 + +## 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/). + +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) + +## Authors: +1. Ravi Prakash : ravi@becknprotocol.io + +## Reviewers: +1. Sujith Nair : sujith@becknprotocol.io +2. Pramod Varma : pramod@ekstep.org +3. Venkatraman Mahadevan : venkatramanm@gmail.com + +# 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 @@ -77,7 +92,6 @@ Examples to be documented here. The author would like to thank the following people for their support and contributions to this document. - 1. Ravi Prakash 2. Pramod Varma 3. Sujith Nair 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..c9dcffa6 100644 --- a/schema/Document.yaml +++ b/schema/Document.yaml @@ -7,9 +7,7 @@ properties: url: type: string format: uri - label: - type: string - mime_type: + mimetype: 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 enum: diff --git a/schema/Form.yaml b/schema/Form.yaml index e3993203..182d99b0 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 mimetype 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: @@ -10,7 +10,7 @@ properties: type: object additionalProperties: type: string - mime_type: + mimetype: description: This field indicates the nature and format of the form received by querying the url. MIME types are defined and standardized in IETF's RFC 6838. type: string enum: @@ -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/Price.yaml b/schema/Price.yaml index 7d29649d..9bac5ffc 100644 --- a/schema/Price.yaml +++ b/schema/Price.yaml @@ -16,4 +16,6 @@ properties: minimum_value: type: string maximum_value: + type: string + unit: type: string \ No newline at end of file From e29ea4764cf2f00642e0c2970ad2f939949e82e0 Mon Sep 17 00:00:00 2001 From: Rajaneesh Date: Thu, 4 Jul 2024 15:02:27 +0530 Subject: [PATCH 02/11] compiled a new transaction.yaml out of the updated components --- api/transaction/build/transaction.yaml | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/api/transaction/build/transaction.yaml b/api/transaction/build/transaction.yaml index f7528cde..4ee77561 100644 --- a/api/transaction/build/transaction.yaml +++ b/api/transaction/build/transaction.yaml @@ -820,6 +820,7 @@ components: format: date-time cancelled_by: type: string + description: 'Indicated who canceled a specific entity, such as an order or a booking.' enum: - CONSUMER - PROVIDER @@ -882,6 +883,7 @@ components: type: string format: date-time ttl: + description: Represents the validity of the request. $ref: '#/components/schemas/Duration' Category: description: A label under which a collection of items can be grouped. @@ -925,8 +927,10 @@ components: type: object properties: phone: + description: Phone number of an entity. type: string email: + description: Email of an entity. type: string jcard: type: object @@ -1000,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 @@ -1133,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.' submission_id: type: string + description: A unique identifier associated with a submission of a form. format: uuid auth: type: object @@ -1143,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 @@ -1165,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' From de078f1025a1cbeba7b2cc2bc27ca558770d89b8 Mon Sep 17 00:00:00 2001 From: Rajaneesh Date: Thu, 4 Jul 2024 15:37:11 +0530 Subject: [PATCH 03/11] adding description in the Price object fields --- api/transaction/build/transaction.yaml | 9 +++++++++ schema/Price.yaml | 11 ++++++++++- 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/api/transaction/build/transaction.yaml b/api/transaction/build/transaction.yaml index 4ee77561..53dd780b 100644 --- a/api/transaction/build/transaction.yaml +++ b/api/transaction/build/transaction.yaml @@ -1821,22 +1821,31 @@ components: 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 + 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/schema/Price.yaml b/schema/Price.yaml index 9bac5ffc..126808f6 100644 --- a/schema/Price.yaml +++ b/schema/Price.yaml @@ -3,19 +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 + description: Monetary cost of an item, a decimal represented as string unit: - type: string \ No newline at end of file + type: string + description: A custom unit of payment, i.e. carbon credit, bitcoin, etc. \ No newline at end of file From 386c30218c37fbf2969d6b9d0a294e4be1e8b181 Mon Sep 17 00:00:00 2001 From: Rajaneesh Date: Thu, 4 Jul 2024 16:37:44 +0530 Subject: [PATCH 04/11] Change mimetype to mime_type --- api/transaction/build/transaction.yaml | 8 ++++---- schema/Document.yaml | 2 +- schema/Form.yaml | 4 ++-- schema/MediaFile.yaml | 2 +- schema/Price.yaml | 2 +- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/api/transaction/build/transaction.yaml b/api/transaction/build/transaction.yaml index 53dd780b..58825134 100644 --- a/api/transaction/build/transaction.yaml +++ b/api/transaction/build/transaction.yaml @@ -1071,7 +1071,7 @@ components: url: type: string format: uri - mimetype: + 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 enum: @@ -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 mimetype 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: @@ -1130,7 +1130,7 @@ components: type: object additionalProperties: type: string - mimetype: + mime_type: description: This field indicates the nature and format of the form received by querying the url. MIME types are defined and standardized in IETF's RFC 6838. type: string enum: @@ -1527,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: diff --git a/schema/Document.yaml b/schema/Document.yaml index c9dcffa6..2f453acc 100644 --- a/schema/Document.yaml +++ b/schema/Document.yaml @@ -7,7 +7,7 @@ properties: url: type: string format: uri - mimetype: + 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 enum: diff --git a/schema/Form.yaml b/schema/Form.yaml index 182d99b0..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 mimetype 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: @@ -10,7 +10,7 @@ properties: type: object additionalProperties: type: string - mimetype: + mime_type: description: This field indicates the nature and format of the form received by querying the url. MIME types are defined and standardized in IETF's RFC 6838. type: string enum: 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 126808f6..d29e3866 100644 --- a/schema/Price.yaml +++ b/schema/Price.yaml @@ -27,4 +27,4 @@ properties: 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. \ No newline at end of file + 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 From c150b604f8df0fbc59b58ca4bc16a819faa423a7 Mon Sep 17 00:00:00 2001 From: Rajaneesh Date: Thu, 4 Jul 2024 16:37:44 +0530 Subject: [PATCH 05/11] Change mimetype to mime_type - changed the structure of the docs under doc/ folder. - added doc history links --- api/registry/README.md | 4 +-- docs/BECKN-001-Layering-Network-Policy.md | 23 +++++++++++----- ...-002-Payments-On-Beckn-Enabled-Networks.md | 23 +++++++++++----- .../BECKN-003-Beckn-Protocol-Communication.md | 23 +++++++++++----- ...dministration-On-Beckn-Enabled-Networks.md | 23 +++++++++++----- docs/BECKN-005-Error-Codes.md | 26 ++++++++++++++----- docs/BECKN-006-Signing-Beckn-APIs-In-HTTP.md | 26 ++++++++++++++----- docs/BECKN-007-The-XInput-Schema.md | 26 ++++++++++++++----- ...Rating-and-Reputation-on-Beckn-Protocol.md | 26 ++++++++++++++----- docs/BECKN-009-Tags-the-Edge-of-Beckn.md | 26 ++++++++++++++----- ...efinitions-for-Technical-Specifications.md | 26 ++++++++++++++----- docs/BECKN-011-Search-Provider.md | 26 ++++++++++++++----- 12 files changed, 199 insertions(+), 79 deletions(-) diff --git a/api/registry/README.md b/api/registry/README.md index 0e6977c5..ac1ae548 100644 --- a/api/registry/README.md +++ b/api/registry/README.md @@ -37,11 +37,11 @@ AddOn: - In the file, you will see the following ``` -openapi: 3.0.0 +openapi: 3.1.0 info: title: Beckn Protocol Core description: Beckn Core API specification - version: "1.0.0" + version: "1.1.1" security: - SubscriberAuth: [] diff --git a/docs/BECKN-001-Layering-Network-Policy.md b/docs/BECKN-001-Layering-Network-Policy.md index 525ba743..f0e5f939 100644 --- a/docs/BECKN-001-Layering-Network-Policy.md +++ b/docs/BECKN-001-Layering-Network-Policy.md @@ -1,5 +1,10 @@ # 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/). + +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) + ## Category: Network Policy @@ -9,18 +14,22 @@ December 10, 2021 ## Last Updated on: July 2nd, 2024 -## 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 -![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) +## 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) # 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. diff --git a/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md b/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md index 24009ec7..056167ff 100644 --- a/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md +++ b/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md @@ -1,5 +1,10 @@ # 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/). + +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) + ## Category: Payments @@ -9,18 +14,22 @@ December 10, 2021 ## Last Updated on: July 4th, 2024 -## 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-002-Payments-On-Beckn-Enabled-Networks.md) to view the history of changes to this document -![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) +## 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@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) # 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. diff --git a/docs/BECKN-003-Beckn-Protocol-Communication.md b/docs/BECKN-003-Beckn-Protocol-Communication.md index d37c350e..fddcdcef 100644 --- a/docs/BECKN-003-Beckn-Protocol-Communication.md +++ b/docs/BECKN-003-Beckn-Protocol-Communication.md @@ -1,5 +1,10 @@ # 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/). + +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) + ## Category Communication @@ -9,18 +14,22 @@ December 10, 2021 ## Last Updated on: July 4th, 2024 -## 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-003-Beckn-Protocol-Communication.md) to view the history of changes to this document -![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) +## 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 : 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 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. 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 5d959bc6..2508eab4 100644 --- a/docs/BECKN-004-Policy-Administration-On-Beckn-Enabled-Networks.md +++ b/docs/BECKN-004-Policy-Administration-On-Beckn-Enabled-Networks.md @@ -1,5 +1,10 @@ # BECKN-004:Policy Administration 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/). + +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) + ## Category: Policy @@ -9,18 +14,22 @@ December 10, 2021 ## Last Updated on: July 4th, 2024 -## 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-004-Policy-Administration-On-Beckn-Enabled-Networks.md) to view the history of changes to this document -![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) +## 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@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) # Introduction diff --git a/docs/BECKN-005-Error-Codes.md b/docs/BECKN-005-Error-Codes.md index 0db9ec44..778a8393 100644 --- a/docs/BECKN-005-Error-Codes.md +++ b/docs/BECKN-005-Error-Codes.md @@ -1,23 +1,35 @@ # 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/). + +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) + +## Category: +Error Codes + ## Published on: January 21, 2022 ## Last Updated on: July 4th, 2024 -## 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-005-Error-Codes.md) to view the history of changes to this document -![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) +## 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 : 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) ## Introduction This document outlines the error codes which must be returned by a BPP. diff --git a/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP.md b/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP.md index d54828de..985ba1ad 100644 --- a/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP.md +++ b/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP.md @@ -1,23 +1,35 @@ # 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/). + +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) + +## Category: +Authentication + ## Published on: January 21, 2022 ## Last Updated on: July 4th, 2024 -## 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-006-Signing-Beckn-APIs-In-HTTP.md) to view the history of changes to this document -![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) +## 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 : 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) ## 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. diff --git a/docs/BECKN-007-The-XInput-Schema.md b/docs/BECKN-007-The-XInput-Schema.md index 00bb7147..bfb86104 100644 --- a/docs/BECKN-007-The-XInput-Schema.md +++ b/docs/BECKN-007-The-XInput-Schema.md @@ -1,23 +1,35 @@ # BECKN-007:The XInput Schema +## 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/). + +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) + +## Category: +XInput + ## Published on: January 21, 2022 ## Last Updated on: July 4th, 2024 -## 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-007-The-XInput-Schema.md) to view the history of changes to this document -![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) +## 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) + +## Discussions: +To view discussions related to this document, click on this [link](https://github.com/beckn/protocol-specifications/discussions?discussions_q=label%3ABECKN-007) ## 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) ## 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. 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 c7630562..32e99369 100644 --- a/docs/BECKN-008-Rating-and-Reputation-on-Beckn-Protocol.md +++ b/docs/BECKN-008-Rating-and-Reputation-on-Beckn-Protocol.md @@ -1,23 +1,35 @@ # BECKN-008:Rating and Reputation on Beckn Protocol +## 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/). + +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) + +## Category: +Rating and Reputation + ## Published on: January 21, 2022 ## Last Updated on: July 4th, 2024 -## 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-008-Rating-and-Reputation-on-Beckn-Protocol.md) to view the history of changes to this document -![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) +## 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) + +## Discussions: +To view discussions related to this document, click on this [link](https://github.com/beckn/protocol-specifications/discussions?discussions_q=label%3ABECKN-008) ## 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) Scope diff --git a/docs/BECKN-009-Tags-the-Edge-of-Beckn.md b/docs/BECKN-009-Tags-the-Edge-of-Beckn.md index 1e4b214d..5d6b3656 100644 --- a/docs/BECKN-009-Tags-the-Edge-of-Beckn.md +++ b/docs/BECKN-009-Tags-the-Edge-of-Beckn.md @@ -1,23 +1,35 @@ # 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/). + +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) + +## Category: +Tags + ## Published on: January 21, 2022 ## Last Updated on: July 4th, 2024 -## 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-009-Tags-the-Edge-of-Beckn.md) to view the history of changes to this document -![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) +## 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) + +## 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 : 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) # Context diff --git a/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md b/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md index 34a472c7..3fe5fc70 100644 --- a/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md +++ b/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md @@ -1,23 +1,35 @@ # BECKN-010:Keyword Definitions for Technical Specifications +## 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/). + +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) + +## Category: +Keywords for Technical Specification + ## Published on: January 21, 2022 ## Last Updated on: July 4th, 2024 -## 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-010-Keyword-Definitions-for-Technical-Specifications.md) to view the history of changes to this document -![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) +## 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) + +## Discussions: +To view discussions related to this document, click on this [link](https://github.com/beckn/protocol-specifications/discussions?discussions_q=label%3ABECKN-010) ## 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 diff --git a/docs/BECKN-011-Search-Provider.md b/docs/BECKN-011-Search-Provider.md index 59ff4267..9d73d792 100644 --- a/docs/BECKN-011-Search-Provider.md +++ b/docs/BECKN-011-Search-Provider.md @@ -1,23 +1,35 @@ # 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/). + +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) + +## Category: +Search Provider + ## Published on: July 29th, 2023 ## Last Updated on: July 4th, 2024 -## 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-011-Search-Provider.md) to view the history of changes to this document -![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) +## 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 : 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) # 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 : From 36994b8c9f9a64909835292f8f6b3d910dd877e2 Mon Sep 17 00:00:00 2001 From: Rajaneesh Date: Mon, 8 Jul 2024 10:51:04 +0530 Subject: [PATCH 06/11] minor change in grammer --- docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md b/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md index 056167ff..86b7b892 100644 --- a/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md +++ b/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md @@ -6,7 +6,7 @@ This document is licensed under a [Creative Commons Attribution-NonCommercial-Sh ![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) ## Category: -Payments +Payment ## Published on: December 10, 2021 From 35a6e2f857db123e3b0d1e9a27e2a62b25cda198 Mon Sep 17 00:00:00 2001 From: Rajaneesh Date: Tue, 13 Aug 2024 10:59:34 +0530 Subject: [PATCH 07/11] fixing incorrect version --- api/registry/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/registry/README.md b/api/registry/README.md index ac1ae548..d45347b1 100644 --- a/api/registry/README.md +++ b/api/registry/README.md @@ -37,11 +37,11 @@ AddOn: - In the file, you will see the following ``` -openapi: 3.1.0 +openapi: 3.0.0 info: title: Beckn Protocol Core description: Beckn Core API specification - version: "1.1.1" + version: "1.2.0" security: - SubscriberAuth: [] From 8b23c3afc76f30b29f57d135296a445d9b020bcd Mon Sep 17 00:00:00 2001 From: Rajaneesh Date: Tue, 13 Aug 2024 15:07:41 +0530 Subject: [PATCH 08/11] minor changes in desc of some components --- api/transaction/build/transaction.yaml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/api/transaction/build/transaction.yaml b/api/transaction/build/transaction.yaml index 58825134..26e578b2 100644 --- a/api/transaction/build/transaction.yaml +++ b/api/transaction/build/transaction.yaml @@ -820,7 +820,7 @@ components: format: date-time cancelled_by: type: string - description: 'Indicated who canceled a specific entity, such as an order or a booking.' + description: 'Represents the entity which initiated a cancellation' enum: - CONSUMER - PROVIDER @@ -883,7 +883,7 @@ components: type: string format: date-time ttl: - description: Represents the validity of the request. + 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. @@ -930,7 +930,7 @@ components: description: Phone number of an entity. type: string email: - description: Email of an entity. + description: Email address of an entity. type: string jcard: type: object @@ -1139,7 +1139,7 @@ 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.' + 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. @@ -1821,7 +1821,7 @@ components: properties: currency: type: string - description: 'Medium of exchange, traditional unit of payment, i.e. INR, USD etc.' + description: 'Medium of exchange i.e. INR, USD etc.' value: type: string description: 'Monetary cost of an item, a decimal represented as string' From 85a92818da255d455d58dac88b9e8042d991ab01 Mon Sep 17 00:00:00 2001 From: Rajaneesh Date: Tue, 9 Sep 2025 16:09:42 +0530 Subject: [PATCH 09/11] doc: making all the docs consistent --- docs/BECKN-001-Layering-Network-Policy.md | 13 ++++- ...-002-Payments-On-Beckn-Enabled-Networks.md | 10 +++- .../BECKN-003-Beckn-Protocol-Communication.md | 14 ++++- ...dministration-On-Beckn-Enabled-Networks.md | 10 +++- docs/BECKN-005-Error-Codes.md | 15 +++-- docs/BECKN-006-Signing-Beckn-APIs-In-HTTP.md | 16 +++-- docs/BECKN-007-The-XInput-Schema.md | 6 +- ...Rating-and-Reputation-on-Beckn-Protocol.md | 38 ++++++------ docs/BECKN-009-Tags-the-Edge-of-Beckn.md | 12 ++-- ...efinitions-for-Technical-Specifications.md | 58 ++++--------------- docs/BECKN-011-Search-Provider.md | 12 ++-- 11 files changed, 106 insertions(+), 98 deletions(-) diff --git a/docs/BECKN-001-Layering-Network-Policy.md b/docs/BECKN-001-Layering-Network-Policy.md index 5b8bbdf6..9830eeb0 100644 --- a/docs/BECKN-001-Layering-Network-Policy.md +++ b/docs/BECKN-001-Layering-Network-Policy.md @@ -7,10 +7,12 @@ This document is licensed under a [Creative Commons Attribution-NonCommercial-Sh ## Category: Network Policy + +## Published on: December 10, 2021 ## Last Updated on: -July 2nd, 2024 +Sept 9th, 2025 ## 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 @@ -380,3 +382,12 @@ Rating: $ref: '#/components/schemas/FeedbackUrl/properties/params/properties/feedback_id' required: false ``` + +## 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 86b7b892..c4cfc007 100644 --- a/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md +++ b/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md @@ -12,7 +12,7 @@ Payment December 10, 2021 ## Last Updated on: -July 4th, 2024 +July 8th, 2024 ## 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 @@ -202,6 +202,14 @@ Payment Collection by a BAP and settled at the end of the month using UPI before } ``` +## 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.md b/docs/BECKN-003-Beckn-Protocol-Communication.md index fddcdcef..ce2bbc31 100644 --- a/docs/BECKN-003-Beckn-Protocol-Communication.md +++ b/docs/BECKN-003-Beckn-Protocol-Communication.md @@ -5,14 +5,14 @@ This document is licensed under a [Creative Commons Attribution-NonCommercial-Sh ![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) -## Category +## Category: Communication -## Published on +## Published on: December 10, 2021 ## Last Updated on: -July 4th, 2024 +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 @@ -87,3 +87,11 @@ During the status and on_status calls, the BAP first initiates the transaction b
Figure 4
+ +## 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 2508eab4..509f2abb 100644 --- a/docs/BECKN-004-Policy-Administration-On-Beckn-Enabled-Networks.md +++ b/docs/BECKN-004-Policy-Administration-On-Beckn-Enabled-Networks.md @@ -12,7 +12,7 @@ Policy December 10, 2021 ## Last Updated on: -July 4th, 2024 +July 8th, 2024 ## 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 @@ -332,6 +332,14 @@ 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. +## 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.md b/docs/BECKN-005-Error-Codes.md index 778a8393..4de78e32 100644 --- a/docs/BECKN-005-Error-Codes.md +++ b/docs/BECKN-005-Error-Codes.md @@ -12,7 +12,7 @@ Error Codes January 21, 2022 ## Last Updated on: -July 4th, 2024 +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 @@ -31,7 +31,7 @@ To view discussions related to this document, click on this [link](https://githu 2. [Pramod Varma](https://github.com/pramodkvarma) 3. [Venkatraman Mahadevan](https://github.com/venkatramanm) -## Introduction +# Introduction This document outlines the error codes which must be returned by a BPP. ## Error Codes @@ -66,11 +66,10 @@ To view discussions related to this document, click on this [link](https://githu |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 this document (in alphabetical order): +## Acknowledgements -1. Pramod Varma, Beckn Foundation -2. Sujith Nair, Beckn Foundation -3. Supriyo Ghosh, ONDC +The authors would like to thank the following people for their support and contributions to this document. -*Copyright (c) 2022 Beckn Foundation. All rights reserved.* +* Pramod Varma (Beckn Foundation) +* Sujith Nair (Beckn Foundation) +* Venkataramanan Mahadevan (Humbhionline) diff --git a/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP.md b/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP.md index 985ba1ad..f625b1bd 100644 --- a/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP.md +++ b/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP.md @@ -12,7 +12,7 @@ Authentication January 21, 2022 ## Last Updated on: -July 4th, 2024 +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 @@ -31,13 +31,13 @@ To view discussions related to this document, click on this [link](https://githu 2. [Pramod Varma](https://github.com/pramodkvarma) 3. [Venkatraman Mahadevan](https://github.com/venkatramanm) -## Context +# 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. -## Subscriber Authentication +# 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. @@ -55,7 +55,7 @@ The BG will send its signature in the `X-Gateway-Authorization` header in the ex X-Gateway-Authorization:Signature keyId="{subscriber_id}|{unique_key_id}|{algorithm}", algorithm="ed25519", created="1606970629", expires="1607030629", headers="(created) (expires) digest", signature="Base64(ed25519_sign(signing string))" ``` -### Signature Attributes +## Signature Attributes #### keyID: The KeyID is a string that uniquely identifies a subscriber's key(s) on the network. It has three components. @@ -471,3 +471,11 @@ WWW-Authenticate: Signature realm="example-bap.com",headers="(created) (expires) } } ``` + +## 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 bfb86104..fab1a4d2 100644 --- a/docs/BECKN-007-The-XInput-Schema.md +++ b/docs/BECKN-007-The-XInput-Schema.md @@ -12,7 +12,7 @@ XInput January 21, 2022 ## Last Updated on: -July 4th, 2024 +July 8th, 2024 ## 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 @@ -31,7 +31,7 @@ To view discussions related to this document, click on this [link](https://githu 2. [Pramod Varma](https://github.com/pramodkvarma) 3. [Venkatraman Mahadevan](https://github.com/venkatramanm) -## Context +# 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. 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, @@ -466,8 +466,8 @@ An example of a form can be as below:- The authors would like to thank the following people for their support and contributions to this document. -* Venkataramanan Mahadevan (Humbhionline) * Pramod Varma (Beckn Foundation) * Sujith Nair (Beckn Foundation) +* Venkataramanan Mahadevan (Humbhionline) * Akash Shah (Shikshalokam) * Sankarshan Mukhopadyay (Dhiway Networks) \ No newline at end of file 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 32e99369..1d830e2f 100644 --- a/docs/BECKN-008-Rating-and-Reputation-on-Beckn-Protocol.md +++ b/docs/BECKN-008-Rating-and-Reputation-on-Beckn-Protocol.md @@ -12,7 +12,7 @@ Rating and Reputation January 21, 2022 ## Last Updated on: -July 4th, 2024 +July 8th, 2024 ## 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 @@ -32,13 +32,11 @@ To view discussions related to this document, click on this [link](https://githu 3. [Venkatraman Mahadevan](https://github.com/venkatramanm) -Scope -===== +# Scope 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. -Context -======= +# Context 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. @@ -56,13 +54,11 @@ For platforms connected to each other in an open commerce network, an interopera 3. Cross-platform compatibility -Abstract -======== +# Abstract 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. -Terminology -=========== +# Terminology 1. **Rating Category**: For example: Agent, Fulfillment, Provider @@ -72,18 +68,15 @@ Terminology 4. **Rating Receiver**: The actor that receives the rating for a Rateable Object -Problem -======= +# Problem How to ensure that the customers receive quality services rendered from different providers on an open network? -Forces -====== +# Forces 1. Same Rateable Objects may exist on more than one BPP under different names -Expected Outcomes after reading this document -============================================= +# Expected Outcomes after reading this document After reading this document, the reader should be able to @@ -91,8 +84,8 @@ After reading this document, the reader should be able to 2. Understand how to connect their platforms to the Rating and Reputation system on open commerce networks. -Rating using Beckn Protocol -=========================== +# Rating using Beckn Protocol + 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, @@ -165,8 +158,7 @@ Once the rating handshake is complete, the Rating should happen via the followin -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. @@ -194,3 +186,11 @@ 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. + +## 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 5d6b3656..83a5852a 100644 --- a/docs/BECKN-009-Tags-the-Edge-of-Beckn.md +++ b/docs/BECKN-009-Tags-the-Edge-of-Beckn.md @@ -12,7 +12,7 @@ Tags January 21, 2022 ## Last Updated on: -July 4th, 2024 +July 8th, 2024 ## 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 @@ -258,10 +258,10 @@ For example, if the FQDN of a network facilitator is mynetwork.org, and the key TODO -# Acknowledgements +## Acknowledgements -The author would like to thank the following people for their support and contributions to this document. +The authors 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 +* Pramod Varma (Beckn Foundation) +* Sujith Nair (Beckn Foundation) +* Venkataramanan Mahadevan (Humbhionline) \ No newline at end of file diff --git a/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md b/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md index 3fe5fc70..8f3df926 100644 --- a/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md +++ b/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md @@ -12,7 +12,7 @@ Keywords for Technical Specification January 21, 2022 ## Last Updated on: -July 4th, 2024 +July 8th, 2024 ## 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 @@ -32,55 +32,13 @@ To view discussions related to this document, click on this [link](https://githu 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 +# 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 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. - -## Definitions - -### MUST - -The term "MUST" implies an absolute requirement. - -### MUST NOT - -The term "MUST NOT" indicates an absolute prohibition. - -### REQUIRED - -The term "REQUIRED" is synonymous with "MUST". - -### SHALL - -The term "SHALL" is equivalent to "MUST". - -### SHALL NOT - -The term "SHALL NOT" is equivalent to "MUST NOT". - -### SHOULD - -The term "SHOULD" indicates a strong recommendation. - -### SHOULD NOT - -The term "SHOULD NOT" indicates a strong recommendation against. - -### RECOMMENDED - -The term "RECOMMENDED" is synonymous with "SHOULD". - -### MAY - -The term "MAY" indicates that an item is truly optional. - -### OPTIONAL - -The term "OPTIONAL" is synonymous with "MAY". +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. ## Examples and Correct Usage @@ -100,6 +58,14 @@ In this section, we provide examples that demonstrate the correct usage of the k 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. +## 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) + > Note : This document is subject to change and may be updated to include additional terms or to refine existing definitions. diff --git a/docs/BECKN-011-Search-Provider.md b/docs/BECKN-011-Search-Provider.md index 9d73d792..e94dea1d 100644 --- a/docs/BECKN-011-Search-Provider.md +++ b/docs/BECKN-011-Search-Provider.md @@ -12,7 +12,7 @@ Search Provider July 29th, 2023 ## Last Updated on: -July 4th, 2024 +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 @@ -100,10 +100,10 @@ Changed Behavior: Examples to be documented here. -# Acknowledgements +## Acknowledgements -The author would like to thank the following people for their support and contributions to this document. +The authors would like to thank the following people for their support and contributions to this document. -1. Ravi Prakash -2. Pramod Varma -3. Sujith Nair +* Pramod Varma (Beckn Foundation) +* Sujith Nair (Beckn Foundation) +* Venkataramanan Mahadevan (Humbhionline) From f48d43bc81af0184920ef4b843f333d1c158baf0 Mon Sep 17 00:00:00 2001 From: Rajaneesh Date: Tue, 16 Sep 2025 12:50:51 +0530 Subject: [PATCH 10/11] docs: layer2 configuration and payment docs: added recommendations section in RFC 001 and 002 docs: created RFC000 for Terminology docs: modified last updated file time --- docs/BECKN-000-Terminology.md | 98 +++++++++++++ docs/BECKN-001-Layering-Network-Policy.md | 136 +++++++++--------- ...-002-Payments-On-Beckn-Enabled-Networks.md | 126 +++++++++++----- 3 files changed, 261 insertions(+), 99 deletions(-) create mode 100644 docs/BECKN-000-Terminology.md 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/). + +![Creative Commons License](https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png) + +## 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.md b/docs/BECKN-001-Layering-Network-Policy.md index 9830eeb0..6553b184 100644 --- a/docs/BECKN-001-Layering-Network-Policy.md +++ b/docs/BECKN-001-Layering-Network-Policy.md @@ -12,7 +12,7 @@ Network Policy December 10, 2021 ## Last Updated on: -Sept 9th, 2025 +Sept 16th, 2025 ## 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 @@ -31,83 +31,66 @@ To view discussions related to this document, click on this [link](https://githu 2. [Pramod Varma](https://github.com/pramodkvarma) 3. [Venkatraman Mahadevan](https://github.com/venkatramanm) +# Abstract + +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: -# Prerequisites +1. Anyone who is using beckn protocol specifications to design open commerce networks for a specific set of use cases + +## 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 @@ -138,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. @@ -158,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 @@ -175,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: @@ -233,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: @@ -312,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. @@ -329,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: @@ -343,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. @@ -383,11 +347,55 @@ Rating: required: false ``` -## Acknowledgements +# 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 c4cfc007..4aa33368 100644 --- a/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md +++ b/docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md @@ -12,7 +12,7 @@ Payment December 10, 2021 ## Last Updated on: -July 8th, 2024 +Sept 16th, 2025 ## 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 @@ -31,38 +31,68 @@ To view discussions related to this document, click on this [link](https://githu 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 + +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. -# Payment Infrastructure on a Beckn-enabled Network +# Implementation Details + +## Payment Infrastructure on a Beckn-enabled Network ![alt text](https://github.com/beckn/protocol-specifications/blob/master/docs/images/Payment-Contract-Infrastructure.png) -# 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 @@ -72,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 ![alt text](https://github.com/beckn/protocol-specifications/blob/master/docs/images/Payment-API-Sequence.png) -# 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 @@ -85,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 ![alt text](https://github.com/beckn/protocol-specifications/blob/master/docs/images/Payment-Settlement-Flow-1.png) -## 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 @@ -107,25 +137,27 @@ From the buyer to the seller, money may flow through different payment intermedi ![alt text](https://github.com/beckn/protocol-specifications/blob/master/docs/images/Payment-Settlement-Flow-2.png) -# 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 | + +# Examples -# Runtime Payment Object Examples +## Runtime Payment Object Examples -## Example 1 +### Example 1 Payment Collection by a BAP and settled at the end of the month to a bank account before 30th of November 2021 ``` @@ -148,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 ``` @@ -164,7 +196,7 @@ Immediate payment on order placement to a UPI Endpoint } ``` -## Example 3 +### Example 3 Transfer to a Payment Gateway Endpoint ``` @@ -180,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 ``` @@ -202,15 +234,39 @@ Payment Collection by a BAP and settled at the end of the month using UPI before } ``` -## Acknowledgements +# Recommendations -The authors would like to thank the following people for their support and contributions to this document. +- 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 -* Pramod Varma (Beckn Foundation) -* Sujith Nair (Beckn Foundation) -* Venkataramanan Mahadevan (Humbhionline) +- 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) From 51dadc0558e91f1940186aedd44e5e7827b0c92b Mon Sep 17 00:00:00 2001 From: Rajaneesh Date: Wed, 1 Oct 2025 11:48:12 +0530 Subject: [PATCH 11/11] docs: Enhancing the documentations List of docs updated - Payment on Beckn network - Communication - Policy - Error codes - Signing APIs - Xinput - Rating and Reputation - tags - Keyword definition - Search Provider --- .../BECKN-003-Beckn-Protocol-Communication.md | 53 +++- ...dministration-On-Beckn-Enabled-Networks.md | 229 ++++++++++-------- docs/BECKN-005-Error-Codes.md | 124 ++++++---- docs/BECKN-006-Signing-Beckn-APIs-In-HTTP.md | 70 ++++-- docs/BECKN-007-The-XInput-Schema.md | 133 +++++----- ...Rating-and-Reputation-on-Beckn-Protocol.md | 65 +++-- docs/BECKN-009-Tags-the-Edge-of-Beckn.md | 160 ++++++------ ...efinitions-for-Technical-Specifications.md | 82 ++++++- docs/BECKN-011-Search-Provider.md | 78 ++++-- 9 files changed, 603 insertions(+), 391 deletions(-) diff --git a/docs/BECKN-003-Beckn-Protocol-Communication.md b/docs/BECKN-003-Beckn-Protocol-Communication.md index ce2bbc31..cdff3984 100644 --- a/docs/BECKN-003-Beckn-Protocol-Communication.md +++ b/docs/BECKN-003-Beckn-Protocol-Communication.md @@ -32,11 +32,30 @@ To view discussions related to this document, click on this [link](https://githu 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 @@ -46,20 +65,30 @@ A beckn enabled network has multiple entities communicating with each other via 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. +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 -# Communication Protocol Between 2 Entities +How to enable reliable, scalable, and interoperable communication between distributed entities in beckn-enabled networks while maintaining real-world transaction behavior patterns? -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.** +# Solution -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**”. +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 +## 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. @@ -71,7 +100,7 @@ The BPPs synchronously respond with ACKs. The BPPs then asynchronously call the
Figure 2:
-# Communication Protocol for Search Via Beckn Gateway with Registry Lookup +## 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.
@@ -79,7 +108,7 @@ Sometimes the BG may query a Registry via the **lookup** API to get the BPP addr
Figure 3:Search with Registry Lookup
-# Communication Protocol during status updates +## 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. @@ -88,7 +117,15 @@ During the status and on_status calls, the BAP first initiates the transaction b
Figure 4
-## Acknowledgements +# 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. 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 509f2abb..f52cc0ca 100644 --- a/docs/BECKN-004-Policy-Administration-On-Beckn-Enabled-Networks.md +++ b/docs/BECKN-004-Policy-Administration-On-Beckn-Enabled-Networks.md @@ -31,6 +31,27 @@ To view discussions related to this document, click on this [link](https://githu 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 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. @@ -43,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 @@ -77,188 +120,168 @@ Policies can be of various categories as shown below 6. Data Transmission 7. Communication -# Problem Definition +## Network Policy Design Principles -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 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 Workflow](https://github.com/beckn/protocol-specifications/blob/master/docs/images/Policy-Workflow-New.png) -# 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 Workflow](https://github.com/beckn/protocol-specifications/blob/master/docs/images/Policy-Agreement-Implementation-Architecture.png) -# 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 Workflow](https://github.com/beckn/protocol-specifications/blob/master/docs/images/Policy-Agreement-and-Adoption-Protocol.png) -# 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 | @@ -276,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 | @@ -332,14 +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. -## Acknowledgements +# Examples -The authors would like to thank the following people for their support and contributions to this document. +[Examples section to be added with concrete policy administration scenarios] -* Pramod Varma (Beckn Foundation) -* Sujith Nair (Beckn Foundation) -* Venkataramanan Mahadevan (Humbhionline) +# 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.md b/docs/BECKN-005-Error-Codes.md index 4de78e32..0b5147be 100644 --- a/docs/BECKN-005-Error-Codes.md +++ b/docs/BECKN-005-Error-Codes.md @@ -31,45 +31,87 @@ To view discussions related to this document, click on this [link](https://githu 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. - - ## 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 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) + +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.md b/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP.md index f625b1bd..19a95d01 100644 --- a/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP.md +++ b/docs/BECKN-006-Signing-Beckn-APIs-In-HTTP.md @@ -31,13 +31,46 @@ To view discussions related to this document, click on this [link](https://githu 2. [Pramod Varma](https://github.com/pramodkvarma) 3. [Venkatraman Mahadevan](https://github.com/venkatramanm) -# Context +# 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 + 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. -# Subscriber Authentication +# 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. @@ -55,7 +88,7 @@ The BG will send its signature in the `X-Gateway-Authorization` header in the ex X-Gateway-Authorization:Signature keyId="{subscriber_id}|{unique_key_id}|{algorithm}", algorithm="ed25519", created="1606970629", expires="1607030629", headers="(created) (expires) digest", signature="Base64(ed25519_sign(signing string))" ``` -## Signature Attributes +### Signature Attributes #### keyID: The KeyID is a string that uniquely identifies a subscriber's key(s) on the network. It has three components. @@ -99,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 : @@ -108,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= @@ -154,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. @@ -199,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= @@ -247,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. @@ -285,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. @@ -318,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 @@ -344,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. @@ -377,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 @@ -407,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. @@ -439,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. @@ -459,7 +478,6 @@ WWW-Authenticate: Signature realm="example-bap.com",headers="(created) (expires) ... ``` - **Request Body:** ``` @@ -472,7 +490,15 @@ WWW-Authenticate: Signature realm="example-bap.com",headers="(created) (expires) } ``` -## Acknowledgements +# 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. diff --git a/docs/BECKN-007-The-XInput-Schema.md b/docs/BECKN-007-The-XInput-Schema.md index fab1a4d2..5db97f32 100644 --- a/docs/BECKN-007-The-XInput-Schema.md +++ b/docs/BECKN-007-The-XInput-Schema.md @@ -31,24 +31,42 @@ To view discussions related to this document, click on this [link](https://githu 2. [Pramod Varma](https://github.com/pramodkvarma) 3. [Venkatraman Mahadevan](https://github.com/venkatramanm) -# 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. +# 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. + +# 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 -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, +## Prerequisites + +Readers of this document must: + +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 + +# 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. -to confirm the order. All of this information needs to be transmitted to the person availing the logistics service. +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/). @@ -120,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 @@ -137,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 @@ -147,9 +168,7 @@ Order: ... ``` -``` - -#### Usage in the `CancellationTerm` schema +### Usage in the `CancellationTerm` schema ``` CancellationTerm: type: object @@ -158,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 @@ -190,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: `
` - The form submission API must also be on the same domain name as the BPP subscriber_id to avoid security-related errors thrown by BAPs @@ -211,40 +227,34 @@ The following recommendations are for BPPs who will create the form to be render * Generate a **FormResponse** object and return it as an `application/json` response - BPPs must persist this UUID at their ends so that they can match each submission with the corresponding confirm API call - -#### Linking form submission to existing transactions +### Linking form submission to existing transactions * After successful form submissions, the BPP should ideally receive a confirm API call containing references to the submissions. * The form submission references can be found in Order.items[ ].xinput_required.form.submission_id, and Order.xinput_required.form.submission_id fields. - -#### Discarding Form Submissions +### Discarding Form Submissions * The BPP can choose to discard the form submissions if the confirm API call does not arrive within a specified time window after the form has been submitted - -### Recommendations for BAPs +## Recommendations for BAPs The following recommendations are for BAPs who will render the form to its users and send the submissions to the BPPs. - -#### Identifying form declarations +### Identifying form declarations * BAPs can identify required item-specific form inputs by parsing the Item schema received in on_search callbacks. * BAPs must also check for required order-specific form inputs by parsing the Order schema received in on_select, and on_init callbacks. * The BAP may choose to cache the form by calling the `{Item}.xinput.form.url` endpoint from its API endpoint. * It should expect either an HTML or an Xforms 2.0 object as a response. If the response body header has Content-type: text/html, then it should expect an HTML form object. If it is application/xml, it should expect an xForms 2.0 model object. - -#### Rendering the form +### Rendering the form * BAPs should render their forms typically any time before confirming the order * For item-specific inputs, BAPs should typically render the form when the user selects the item for ordering * For order-specific inputs, BAPs should typically render the form * BAPs should remove any script, style, and button tags when rendering the form inside their own UI - -#### Submitting the form +### Submitting the form * BAPs should submit the form data on the submission url specified in the form object via a HTTP/POST request. * For HTML forms the submission url will be present in the action attribute of the form tag as highlighted in the example below ``` - …
+
…
``` * 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 @@ -256,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 @@ -270,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 @@ -312,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 @@ -355,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. ![](https://user-images.githubusercontent.com/52468749/188610013-a97b6332-be73-4331-8edf-1cee807cf304.png) - 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. @@ -394,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). ```
@@ -423,14 +428,14 @@ Now the BPP has all the information required to confirm the order. It can either
``` -### 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. ```
-  -  -  + + + @@ -439,7 +444,7 @@ Now the BPP has all the information required to confirm the order. It can either
``` -### 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. @@ -462,12 +467,16 @@ 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. +* Venkataramanan Mahadevan (Humbhionline) * Pramod Varma (Beckn Foundation) * Sujith Nair (Beckn Foundation) -* Venkataramanan Mahadevan (Humbhionline) * 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 1d830e2f..e7f74ab7 100644 --- a/docs/BECKN-008-Rating-and-Reputation-on-Beckn-Protocol.md +++ b/docs/BECKN-008-Rating-and-Reputation-on-Beckn-Protocol.md @@ -31,12 +31,23 @@ To view discussions related to this document, click on this [link](https://githu 2. [Pramod Varma](https://github.com/pramodkvarma) 3. [Venkatraman Mahadevan](https://github.com/venkatramanm) +# Abstract + +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. # Scope -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. +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. + +## Prerequisites -# Context +Readers of this document must: + +1. Have knowledge of the core beckn protocol specification +2. Have understanding of rating and reputation systems +3. Have knowledge of distributed systems architecture + +# Introduction 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. @@ -54,38 +65,15 @@ For platforms connected to each other in an open commerce network, an interopera 3. Cross-platform compatibility -# Abstract - -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. - -# Terminology - -1. **Rating Category**: For example: Agent, Fulfillment, Provider - -2. **Rateable Object**: The runtime object of a Rating Category that can be rated - -3. **Rating Sender**: The actor that rates a Rateable Object - -4. **Rating Receiver**: The actor that receives the rating for a Rateable Object - # Problem How to ensure that the customers receive quality services rendered from different providers on an open network? -# Forces +## Forces 1. Same Rateable Objects may exist on more than one BPP under different names -# Expected Outcomes after reading this document - -After reading this document, the reader should be able to - -1. Understand how ratings work on Open Commerce Networks enabled by beckn protocol - -2. Understand how to connect their platforms to the Rating and Reputation system on open commerce networks. - -# 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, @@ -93,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. @@ -132,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. @@ -150,15 +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. @@ -187,7 +172,15 @@ If this value matches the rating value sent in the catalog, then the rating is a 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. -## Acknowledgements +# 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. diff --git a/docs/BECKN-009-Tags-the-Edge-of-Beckn.md b/docs/BECKN-009-Tags-the-Edge-of-Beckn.md index 83a5852a..d3b64138 100644 --- a/docs/BECKN-009-Tags-the-Edge-of-Beckn.md +++ b/docs/BECKN-009-Tags-the-Edge-of-Beckn.md @@ -31,8 +31,28 @@ To view discussions related to this document, click on this [link](https://githu 2. [Pramod Varma](https://github.com/pramodkvarma) 3. [Venkatraman Mahadevan](https://github.com/venkatramanm) +# Abstract -# Context +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 + +This document is intended for the following audience: + +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 + +## Prerequisites + +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 + +# 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. @@ -44,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: @@ -72,7 +90,6 @@ components: $ref: "#/components/schemas/TagGroup" ``` - The Tags schema is explicitly referenced in the following schemas. * Category.tags @@ -85,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, @@ -121,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 @@ -136,7 +150,6 @@ The tag schema contains a key-value pair containing the actual extended metadata The Tag schema is shown below. - ``` components: schemas: @@ -155,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. @@ -251,17 +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 + +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 -## Acknowledgements +# Acknowledgements -The authors would like to thank the following people for their support and contributions to this document. +The author 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) \ No newline at end of file +1. Venkataramanan Mahadevan +2. Pramod Varma +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 8f3df926..fae2c3e0 100644 --- a/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md +++ b/docs/BECKN-010-Keyword-Definitions-for-Technical-Specifications.md @@ -31,15 +31,85 @@ To view discussions related to this document, click on this [link](https://githu 2. [Pramod Varma](https://github.com/pramodkvarma) 3. [Venkatraman Mahadevan](https://github.com/venkatramanm) - # 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. +# Scope + +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 + +### MUST + +The term "MUST" implies an absolute requirement. + +### MUST NOT + +The term "MUST NOT" indicates an absolute prohibition. + +### REQUIRED + +The term "REQUIRED" is synonymous with "MUST". + +### SHALL + +The term "SHALL" is equivalent to "MUST". + +### SHALL NOT + +The term "SHALL NOT" is equivalent to "MUST NOT". + +### SHOULD + +The term "SHOULD" indicates a strong recommendation. + +### SHOULD NOT + +The term "SHOULD NOT" indicates a strong recommendation against. + +### RECOMMENDED + +The term "RECOMMENDED" is synonymous with "SHOULD". + +### MAY + +The term "MAY" indicates that an item is truly optional. + +### 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. @@ -54,18 +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] -## Acknowledgements +# 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) - -> Note : This document is subject to change and may be updated to include additional terms or to refine existing definitions. - - diff --git a/docs/BECKN-011-Search-Provider.md b/docs/BECKN-011-Search-Provider.md index e94dea1d..fefdc418 100644 --- a/docs/BECKN-011-Search-Provider.md +++ b/docs/BECKN-011-Search-Provider.md @@ -31,16 +31,40 @@ To view discussions related to this document, click on this [link](https://githu 2. [Pramod Varma](https://github.com/pramodkvarma) 3. [Venkatraman Mahadevan](https://github.com/venkatramanm) -# Context +# 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 + 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... @@ -54,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, @@ -82,28 +106,34 @@ 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 + +[Recommendations section to be added with best practices for search provider implementation] -## Acknowledgements +# Acknowledgements -The authors would like to thank the following people for their support and contributions to this document. +The author 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) +1. Ravi Prakash +2. Pramod Varma +3. Sujith Nair