From bdd02cc700e8e46056c2e5885128da3f6cab7d8b Mon Sep 17 00:00:00 2001 From: Venky Date: Sat, 22 Jan 2022 00:51:36 +0530 Subject: [PATCH 01/11] Pub sub Proposal --- ...FC-005-Creating-Pub-Sub-Enabled-Network.md | 116 ++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 docs/proposals/BECKN-RFC-005-Creating-Pub-Sub-Enabled-Network.md diff --git a/docs/proposals/BECKN-RFC-005-Creating-Pub-Sub-Enabled-Network.md b/docs/proposals/BECKN-RFC-005-Creating-Pub-Sub-Enabled-Network.md new file mode 100644 index 00000000..e13c7865 --- /dev/null +++ b/docs/proposals/BECKN-RFC-005-Creating-Pub-Sub-Enabled-Network.md @@ -0,0 +1,116 @@ +# Creating-Pub-Sub-Enabled Network + + +## ID: +BECKN-RFC-005 + +## Draft ID +Draft-01 + +## Title: +Creating a Pub-sub enabled network. + +## Category: +Network + +## Status: +Protocol Draft + +## Published on: +January 21, 2022 + +## Expires on: +April 05, 2022 or Date of publication of next draft which ever is earlier + +## License: +CC-BY-ND + +## Authors: +1. Venkatraman Mahadevan : venky@humbhionline.in + +## Reviewers: +1. Sujith Nair : sujith@becknfoundation.org +2. Pramod Varma : pramod@ekstep.org +3. Ravi Prakash : ravi@becknfoundation.org +4. + +# Introduction +Pub Subscribe is a popular industry standard where events are published by _publishers_ to a message queue on specific topics. _Subscribers_ listening to specific topics/topic wildcards, on the queue are notified of the event. _Subscribers_ typically take actions on these events asyncronously and go back to listening for more events of interest. + +The Beckn protocol as on Jan 21 2021 has been documented according to openapi spec version 3.0.0. Open Api spec, which is primary for synchronous communication over http. As Beckn is architected fundamentally to be for async communication, It was felt that a pub-sub mechanism and probably documenting through Async Api Spec would be better suited. + +# The experiment. +In [Beckn-One](https://github.com/venkatramanm/beckn-portal) (which is a reference network for Beckn applications), the following experiment was conducted. + +1. A system wide open message broker (nats.io and hivemq were tried out) was be made available for BAP and BPP registered on the network +2. TOPIC via which communication was enabled were designed according to the following pattern + + ROOT/[Country]/[City]/[domain]/[action]/[intended_subscriber_id]/[transaction_id]/[message_id] (in hive mq) + + ** Note + * topic level separators, single level wild cards and multilevel wild cards are different by brokers + * For Search requests the intended_subscriber_id field was always "all" in BAP and BPP. + * Special characters like "/" in the fields would need to be escaped so that they are not confused with level separator. For uniformity, we replaced all broker specific special characters by strings "_separator_", "_single_level_wild_card_" and "_multi_level_wild_card_" respectively + +3. Sandbox BAP in beckn-one published a **Cloud event** to the complete topic with no wild card. +4. Humbhionline BPP subscribed to specific topic or wild card topic and received the **Cloud event*. + + Extract from Humbhionline logs. + ================================ + Subscribed to topic ROOT.*.*.nic2004:52110.confirm.mandi_separator_succinct_separator_in.> + Subscribed to topic ROOT.*.*.nic2004:52110.cancel.mandi_separator_succinct_separator_in.> + Subscribed to topic ROOT.*.*.nic2004:52110.init.mandi_separator_succinct_separator_in.> + Subscribed to topic ROOT.*.*.nic2004:52110.search.all.> + Subscribed to topic ROOT.*.*.nic2004:52110.select.mandi_separator_succinct_separator_in.> + Subscribed to topic ROOT.*.*.nic2004:52110.update.mandi_separator_succinct_separator_in.> + Subscribed to topic ROOT.*.*.nic2004:52110.track.mandi_separator_succinct_separator_in.> + Subscribed to topic ROOT.*.*.nic2004:52110.status.mandi_separator_succinct_separator_in.> + +5. On firing a test search api on beckn-one the bap, simply put the payload to the topic. +5. Humbhionline's BPP picked up the search request. Processed it asyncronously and pushed the response payload to the on_search queue being listened to by the beckn-one bap. +6. Beckn One bAP was subscribed to the following topics + + Extract from Beckn-One Logs + ============================ + Subscribed to topic ROOT.*.*.nic2004:52110.on_search.beckn-one_separator_succinct_separator_in_separator_nic2004:52110_separator_BAP.> + Subscribed to topic ROOT.*.*.nic2004:52110.on_select.beckn-one_separator_succinct_separator_in_separator_nic2004:52110_separator_BAP.> + Subscribed to topic ROOT.*.*.nic2004:52110.on_init.beckn-one_separator_succinct_separator_in_separator_nic2004:52110_separator_BAP.> + Subscribed to topic ROOT.*.*.nic2004:52110.on_confirm.beckn-one_separator_succinct_separator_in_separator_nic2004:52110_separator_BAP.> + Subscribed to topic ROOT.*.*.nic2004:52110.on_track.beckn-one_separator_succinct_separator_in_separator_nic2004:52110_separator_BAP.> + Subscribed to topic ROOT.*.*.nic2004:52110.on_cancel.beckn-one_separator_succinct_separator_in_separator_nic2004:52110_separator_BAP.> + Subscribed to topic ROOT.*.*.nic2004:52110.on_update.beckn-one_separator_succinct_separator_in_separator_nic2004:52110_separator_BAP.> + Subscribed to topic ROOT.*.*.nic2004:52110.on_status.beckn-one_separator_succinct_separator_in_separator_nic2004:52110_separator_BAP.> + Subscribed to topic ROOT.*.*.nic2004:52110.on_rating.beckn-one_separator_succinct_separator_in_separator_nic2004:52110_separator_BAP.> + Subscribed to topic ROOT.*.*.nic2004:52110.on_support.beckn-one_separator_succinct_separator_in_separator_nic2004:52110_separator_BAP.> + +1. Data in the **Cloud Event** contained the regular beckn json payload as bytes. and the http headers (Authorization etc) were passed as Extension attributes on the Event) +2. +# Observations +1. There was no ACK or NACK. Just the message was pushed successfully into the queue with message broker api. + 1. Ack and Nack in http implementation was for signature validations. Now this feedback is not being provided. no response could mean many things, + 1. Validation Failures, + 2. Processing Errors + 3. Nothing to return. +2. Response times were a bit fast than http as there was no need for connections to be created each time. The queue was always connected. +3. Cloud event serialization and deserialization needed to be done with content_type of "application/octet-stream" (When we tried as application/json, the jackson library used by cloud events would unescape and escaped forward slash. Meaning "\/" became "/" ). This caused payload tampering and signature verification failed. However once content_type was marked as octet-stream, jackson didnot get an oppurtunity to apply over intelligence and corrupt the payload!! + + + +# Conclusions, +1. Pub sub is workable. We can start working on the Async Api Specification.. +2. Network will need to decide what broker to use and how permissioning may be done. + +# Further investigations +2. Need to figure out how we need to control the permissions of the topic. it is possible to do using some user/password or other schemes but need to find what makes sense and is easy to implement at network level. + + +# How Can some one try out the pub sub gateway of beckn-one. +1. You can mark the apitest on Beckn-One as 'via queue'. and the BAP would put in queue. +2. Your BPP/BAP need to listen on appropriate queues to get the messages. +3. You would need to support the queue based subscription as another mechanism to receive messages other than the http connection so that existing functionality is also supported. + + + + + + From d0946f4f4c97d2e6f7bd5fa2e251d00bebe6f970 Mon Sep 17 00:00:00 2001 From: Venky Date: Thu, 27 Jan 2022 21:18:26 +0530 Subject: [PATCH 02/11] Fixed some grammar and spelling mistakes --- ...FC-005-Creating-Pub-Sub-Enabled-Network.md | 29 +++++++++++-------- 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/docs/proposals/BECKN-RFC-005-Creating-Pub-Sub-Enabled-Network.md b/docs/proposals/BECKN-RFC-005-Creating-Pub-Sub-Enabled-Network.md index e13c7865..d6baf35e 100644 --- a/docs/proposals/BECKN-RFC-005-Creating-Pub-Sub-Enabled-Network.md +++ b/docs/proposals/BECKN-RFC-005-Creating-Pub-Sub-Enabled-Network.md @@ -32,7 +32,7 @@ CC-BY-ND 1. Sujith Nair : sujith@becknfoundation.org 2. Pramod Varma : pramod@ekstep.org 3. Ravi Prakash : ravi@becknfoundation.org -4. + # Introduction Pub Subscribe is a popular industry standard where events are published by _publishers_ to a message queue on specific topics. _Subscribers_ listening to specific topics/topic wildcards, on the queue are notified of the event. _Subscribers_ typically take actions on these events asyncronously and go back to listening for more events of interest. @@ -42,18 +42,21 @@ The Beckn protocol as on Jan 21 2021 has been documented according to openapi sp # The experiment. In [Beckn-One](https://github.com/venkatramanm/beckn-portal) (which is a reference network for Beckn applications), the following experiment was conducted. -1. A system wide open message broker (nats.io and hivemq were tried out) was be made available for BAP and BPP registered on the network -2. TOPIC via which communication was enabled were designed according to the following pattern +1. A system wide open message broker was made available for BAPs and BPPs registered on the network. (nats.io and hivemq were tried out) +2. Topics via which communication was enabled were designed according to the following pattern ROOT/[Country]/[City]/[domain]/[action]/[intended_subscriber_id]/[transaction_id]/[message_id] (in hive mq) + AND + ROOT.[Country].[City].[domain].[action].[intended_subscriber_id].[transaction_id].[message_id] (in nats.io) + + *Note* - ** Note - * topic level separators, single level wild cards and multilevel wild cards are different by brokers - * For Search requests the intended_subscriber_id field was always "all" in BAP and BPP. - * Special characters like "/" in the fields would need to be escaped so that they are not confused with level separator. For uniformity, we replaced all broker specific special characters by strings "_separator_", "_single_level_wild_card_" and "_multi_level_wild_card_" respectively + 1. Topic level separators, single level wild cards and multilevel wild cards are different by brokers + 2. For Search requests the intended_subscriber_id field was always "all" in BAP and BPP. + 3. Special characters like "/" in the fields would need to be escaped so that they are not confused with level separator. For uniformity, we replaced all broker specific special characters by strings "_separator_", "_single_level_wild_card_" and "_multi_level_wild_card_" respectively -3. Sandbox BAP in beckn-one published a **Cloud event** to the complete topic with no wild card. -4. Humbhionline BPP subscribed to specific topic or wild card topic and received the **Cloud event*. +1. Sandbox BAP in beckn-one published a **Cloud event** to the complete topic with no wild card. +2. Humbhionline BPP was listening to multiple topics. Some of which were complete topic and some were wild cards. Extract from Humbhionline logs. ================================ @@ -66,8 +69,10 @@ In [Beckn-One](https://github.com/venkatramanm/beckn-portal) (which is a referen Subscribed to topic ROOT.*.*.nic2004:52110.track.mandi_separator_succinct_separator_in.> Subscribed to topic ROOT.*.*.nic2004:52110.status.mandi_separator_succinct_separator_in.> -5. On firing a test search api on beckn-one the bap, simply put the payload to the topic. -5. Humbhionline's BPP picked up the search request. Processed it asyncronously and pushed the response payload to the on_search queue being listened to by the beckn-one bap. +5. On firing a test search api from the beckn-one bap, a payload was pushed to the topic ROOT.IND.std080.nic2004:52110.search.all.[a_txn_id].[a_message_id] + +5. Humbhionline's BPP picked up the search request from the wild card topic subscription (ROOT.*.*.nic2004:52110.search.all.>). Processed it asyncronously and pushed the response payload to the on_search queue being listened to by the beckn-one bap. + 6. Beckn One bAP was subscribed to the following topics Extract from Beckn-One Logs @@ -105,7 +110,7 @@ In [Beckn-One](https://github.com/venkatramanm/beckn-portal) (which is a referen # How Can some one try out the pub sub gateway of beckn-one. -1. You can mark the apitest on Beckn-One as 'via queue'. and the BAP would put in queue. +1. You can mark the apitest on Beckn-One as 'via queue'. and the Sandbox tool would put the payload in an appropriate queue. 2. Your BPP/BAP need to listen on appropriate queues to get the messages. 3. You would need to support the queue based subscription as another mechanism to receive messages other than the http connection so that existing functionality is also supported. From 0965bfefdf34abc6acc54a4ba4440e3b23874cf4 Mon Sep 17 00:00:00 2001 From: Venky Date: Thu, 27 Jan 2022 21:27:40 +0530 Subject: [PATCH 03/11] wildcard messed up in markdown --- .../BECKN-RFC-005-Creating-Pub-Sub-Enabled-Network.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/proposals/BECKN-RFC-005-Creating-Pub-Sub-Enabled-Network.md b/docs/proposals/BECKN-RFC-005-Creating-Pub-Sub-Enabled-Network.md index d6baf35e..236aeb13 100644 --- a/docs/proposals/BECKN-RFC-005-Creating-Pub-Sub-Enabled-Network.md +++ b/docs/proposals/BECKN-RFC-005-Creating-Pub-Sub-Enabled-Network.md @@ -71,7 +71,7 @@ In [Beckn-One](https://github.com/venkatramanm/beckn-portal) (which is a referen 5. On firing a test search api from the beckn-one bap, a payload was pushed to the topic ROOT.IND.std080.nic2004:52110.search.all.[a_txn_id].[a_message_id] -5. Humbhionline's BPP picked up the search request from the wild card topic subscription (ROOT.*.*.nic2004:52110.search.all.>). Processed it asyncronously and pushed the response payload to the on_search queue being listened to by the beckn-one bap. +5. Humbhionline's BPP picked up the search request from the wild card topic subscription (ROOT.\*.*.nic2004:52110.search.all.>). Processed it asyncronously and pushed the response payload to the on_search queue being listened to by the beckn-one bap. 6. Beckn One bAP was subscribed to the following topics @@ -111,7 +111,7 @@ In [Beckn-One](https://github.com/venkatramanm/beckn-portal) (which is a referen # How Can some one try out the pub sub gateway of beckn-one. 1. You can mark the apitest on Beckn-One as 'via queue'. and the Sandbox tool would put the payload in an appropriate queue. -2. Your BPP/BAP need to listen on appropriate queues to get the messages. +2. Your BPP/BAP need to listen on appropriate queues to get the messages. 3. You would need to support the queue based subscription as another mechanism to receive messages other than the http connection so that existing functionality is also supported. From 9ab9e321d4f0730c8f3a0793150d3147a78cf8bb Mon Sep 17 00:00:00 2001 From: Ravi Prakash Date: Thu, 31 Mar 2022 17:48:08 +0530 Subject: [PATCH 04/11] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 68dbea10..9b6d4e22 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,7 @@ The BPPs immediately respond with ACKs. Soon after, the BPPs call the `on_search Sometimes the BG may query a Registry via the `lookup` API to get the BPP addresses and then broadcast the message to the BPPs. -The transaction via the BG is encrypted and the BG has no visibility into the transaction information contained in the `message` field and only uses the `context` header to perform BPP discovery and routing. +It is possible to encrypt the `message` information transmitted via a BG. In that case,BG will have no visibility into the transaction information contained in the `message` field and only uses the `context` header to perform BPP discovery and routing. If the `message` data is not encrypted, then it is **not recommended** to send PII data during `search` as it is typically not required to discover products and services. # Acknowledgments From 3edf62e4a9fc249ec877827aba6497623b559e81 Mon Sep 17 00:00:00 2001 From: Ravi Prakash Date: Thu, 31 Mar 2022 19:57:20 +0530 Subject: [PATCH 05/11] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9b6d4e22..352c3652 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,7 @@ The BPPs immediately respond with ACKs. Soon after, the BPPs call the `on_search Sometimes the BG may query a Registry via the `lookup` API to get the BPP addresses and then broadcast the message to the BPPs. -It is possible to encrypt the `message` information transmitted via a BG. In that case,BG will have no visibility into the transaction information contained in the `message` field and only uses the `context` header to perform BPP discovery and routing. If the `message` data is not encrypted, then it is **not recommended** to send PII data during `search` as it is typically not required to discover products and services. +To protect the privacy and confidentiality of the user, it is possible to encrypt the `message` information transmitted via a BG. In that case,BG will have no visibility into the transaction information contained in the `message` field and only uses the `context` header to perform BPP discovery and routing. # Acknowledgments From 2da5d9070fa607838c6b8fd1b1a7b1b54527f719 Mon Sep 17 00:00:00 2001 From: techframewirk <65583767+techframewirk@users.noreply.github.com> Date: Tue, 5 Apr 2022 15:53:33 +0530 Subject: [PATCH 06/11] Added link to community guidelines Added link to community guidelines in CONTRIBUTION.md --- CONTRIBUTION.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTION.md b/CONTRIBUTION.md index 80043e45..b4bab842 100644 --- a/CONTRIBUTION.md +++ b/CONTRIBUTION.md @@ -241,3 +241,4 @@ Not all future new features will be introduced in this way. Some new features im While governance of the specification is the role of the CWG, the evolution of the specification happens through the participation of members of the developer community at large. Any person willing to contribute to the effort is welcome, and contributions may include filing or participating in issues, creating pull requests, or helping others with such activities. +However, during any interaction with the community or its members, there is a code of conduct and a set of community guidelines that everyone is expected to adhere to. Please find the details [here](https://becknprotocol.io/community-guidelines/). \ No newline at end of file From e9035f2f3a4631cb904703b219e0946ee633936e Mon Sep 17 00:00:00 2001 From: Ravi Prakash Date: Mon, 14 Feb 2022 14:59:46 +0530 Subject: [PATCH 07/11] Initial commit for Governance Model Draft 03 --- GOVERNANCE.md | 143 +++++++++++++++++++++++++++++++------------------- 1 file changed, 88 insertions(+), 55 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index c42a95a8..2036bf80 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -1,27 +1,27 @@ # Specification Governance -## Draft 02 +## Version 0.5.0, Draft 01 # Authors 1. Ravi Prakash : ravi@becknfoundation.org -# Latest Version +# Draft Version -Draft 02 +Draft 03 # Previous Versions -Draft 01 | Deprecated +- Draft 02 +- Draft 01 # Scope -This document intends to establish processes and guidelines which build a transparent, open mechanism for deciding how to manage contributions to the beckn protocol specification. The Core Working Group will initially follow these processes when merging changes from external contributors or from the CWG itself. This guideline document will be adjusted as practicality dictates. +This document intends to establish processes and guidelines which build a transparent, open mechanism for deciding how to manage contributions to the beckn protocol specification. The Core Working Group will initially follow these processes when merging changes from contributors. This guideline document will be adjusted as practicality dictates. This document is intended for the following audience. 1. Anyone who wants to understand how contributions are reviewed and merged by the Core Working Group - # Prerequisites 1. Readers must have a working knowledge of git @@ -30,8 +30,7 @@ This document is intended for the following audience. # Context -Beckn protocol exists as a set of public repositories on Github at https://github.com/beckn. These repositories contain specification documents, reference implementations, tools and utilities. Like all version controlled open-source repositories, there are processes that must be adopted to manage changes to the files present in these repositories. The most common way a change is proposed to the specification is via an Issue linked to that repository which ultimately gets converted to a Pull Request linked to that Issue. These pull requests must then be reviewed by the maintainers of the repository and subsequently merged with the main / master branch of that repository. - +Beckn protocol exists as a set of specifications documented within public repositories on Github at https://github.com/beckn. These repositories contain specification documents, reference implementations, tools and utilities. Like all version controlled open-source repositories, there are processes that must be adopted to manage changes to the files present in these repositories. The most common way a change is proposed to the specification is via an Issue linked to that repository which ultimately gets converted to a Pull Request linked to that Issue. These pull requests must then be reviewed by the maintainers of the repository and subsequently merged with the main / master branch of that repository. # Abstract @@ -43,65 +42,53 @@ The evolution of beckn protocol specification is always use-case driven. The Cor 1. **Git:** A decentralized version control software 2. **Github:** An online platform for managing shared repositories via git 3. **Pull Request:** A request to merge a change to an existing version of the repository -4. **Core Working Group:** Current maintainer and governing authority of the specification +4. **Core Working Group:** Current maintainer of the specification # Expected Outcomes after reading this document After reading this document, the reader should be able to -1. Understand how to review and merge changes to the specification - -# Introduction - -The Beckn protocol is maintained via an open community-driven governance model. The community comprises multiple businesses and organizations that actively contribute to the specification to fuel their digital acceleration. This collaboration across domains, technologies and expertises will bring in new ideas which need to be part of the protocol. Hence there is a need for a standardised process for making relevant changes to the specification as well and for a retrospective understanding of the specification. The governance model for beckn protocol has been created using some of the best practices of globally recognized governance models. - -Evolution of beckn protocol specification is guided by the **Core Working Group**. This working group contains members that bring their API expertise, industry knowledge, incorporate feedback from the community, and expand the group of committers as and when appropriate. All development activity on the future specification will be performed as features on a draft branch and merged into this branch. Upon release of the future specification, this branch will be merged to master. - -The Core Working Group holds weekly web conferences to review open pull requests and discuss open issues related to the evolving specification. Participation in weekly calls and scheduled working sessions is open to the community. - -This governance model is inspired from the [OpenAPI specification governance model](https://www.openapis.org/participate/how-to-contribute/governance). - +- TODO +- TODO # The Beckn Credo - -The Beckn community is an open community. So, no registrations. No memberships. No partnerships. Just a minimal footprint of an open and equally accessible Beckn Protocol that anyone can use. Multiple businesses and organizations have started using beckn protocol to fuel their digital acceleration. The credo of being an open protocol creates a level-playing field for any market player, small or large. - +The beckn community is an open community. So, no registrations. No memberships. No partnerships. Just a minimal footprint of an open and equally accessible Beckn Protocol that anyone can use. Multiple businesses and organizations have started using beckn protocol to fuel their digital acceleration. The credo of being an open protocol creates a level-playing field for any market player, small or large. ## Motivation - To make the internet small-business friendly. be a force multiplier with minimal footprint. ## Guiding Lights - Open specs, equal access. retain agency of small businesses. non-rivalrous, non-exclusive networks ## Community Driven - Increase value for all participants. be a network weaver in your own way. be a contributor of specs and best practices -The Beckn Protocol is an open commerce protocol with an abstract core, which is enabling market players to reimagine building seamless digital experiences and networks. This is very similar to how HTTP, while being a simple and open protocol has fueled seamless interaction between multiple systems and led to an explosive growth in internet adoption. +Beckn protocol is an open protocol with an abstract core, that is enabling market players to re-imagine building seamless digital experiences and networks. This is very similar to how HTTP, while being a simple and open protocol has fueled seamless interaction between multiple systems and led to an explosive growth in internet adoption. ## Open Community Contributions +Beckn protocol has been accepting community contributions to the specification since May 2020. -The Beckn Protocol has been accepting community contributions to the specification since May 2020. - -# Design Principles +# Design Principles for Specification Evolution +To allow contributions from the beckn open community, the following design principles need to be applied while reviewing or proposing changes to the specification. They are: -To allow open contributions from the community, a governance model is required to apply some basic design principles while reviewing or proposing changes to the specification. They are: +## Interoperability: +Any feature added to the specification must ensure that it increases interoperability between implementations. -## Interoperability via Abstraction: +## Abstraction Any feature included in the specification must be abstracted so as to allow it to be consumed across a global range of use cases. That means no feature should be linked to a specific domain, region or use case. ## Optimal ignorance: -Before including any feature in the specification, reviewers should ask the following questions: a) _Do we need it?_ And, b) _Do we need it now? If the answer to both these questions is “Yes” then this criteria will have been met. +Before including any feature in the specification, reviewers should ask the following questions: a) _Do we need it?_ And, b) _Do we need it now?_ If the answer to both these questions is “Yes” then that feature may be included in the specification. -## Privacy and Security -Any feature being included in the specification must be tested for any security or privacy vulnerabilities. Free text fields, loosely-typed fields and any fields that may be used to implicitly capture Personally Identifiable Information should not be accepted. +## Security +Any feature being included in the specification must be tested for any security vulnerabilities. Free text fields, loosely-typed fields should be avoided. -## Scalability +## Privacy and Consent +Any feature that may be used to explicitly capture Personally Identifiable Information should not be accepted. Features especially like age, gender, contact information must be avoided and must only be shared via a consent mechanism. -Any feature being included in the specification must be tested for scalability. String fields with unlimited size; arrays with unlimited size etc, must be discouraged. Any feature that is included must work at scale. +## Scalability +Any feature being included in the specification must be tested for scalability. Any feature that is included must be agnostic of scale. Contributors should keep in mind that the implementors may not always have the capability to scale their platform and hence contributors should be aware of this limitation while proposing changes to the spec. ## Reusability Any new feature must be checked if it can reuse components from the existing schema before inclusion into the specification. @@ -109,26 +96,69 @@ Any new feature must be checked if it can reuse components from the existing sch ## Unification over Standardization Not all features across the globe can be standardized. Standard values vary with domain, region and adoption. In case multiple standards are being adopted for a single feature, it is recommended that both the standards are included in the feature instead of proposing a new standard. For example, if a Location schema is defined using gps and address, then the feature should include both gps and address instead of choosing one over the other. Standardization should occur as a natural consequence of market adoption rather than a forced adoption. -There will be exceptions to the above principles. The objective of the Core Working Group is to address such exceptions and define the most logical way forward to include such exceptions. +There will be exceptions to the above principles. The objective of the Core Working Group is to address such exceptions and define the most logical way to include such exceptions in the specification and clearly document those deviations. + +# Introduction +Beckn protocol is maintained via an open community-driven governance model. The community comprises multiple businesses and organizations that actively contribute to the specification to fuel their digital acceleration. This collaboration across domains, technologies and expertises will bring in new ideas which need to be part of the protocol. Hence there is a need for a standardised process for making relevant changes to the specification as well and for a retrospective understanding of the specification. The governance model for beckn protocol has been created using some of the best practices of globally recognized governance models. + +Evolution of beckn protocol is managed by committers of the **Core Working Group**. This working group consists of members from the **Beckn Open Community** that bring their architectural expertise, open-source knowledge, and industry experience to continuously review proposals to update the specification, and to also manage its releases. They constantly interact with the community members and incorporate their feedback, and also expand the group of committers as and when appropriate. -# Need for Governance +The Core Working Group holds weekly web conferences to review open pull requests and discuss open issues related to the evolving specification. Participation in weekly calls and scheduled working sessions is open to the community. -Since the core specification is essentially abstracted, the implementers of the specification must use instances of the core specification for various domains, regions and scope. Moreover, the Beckn Protocol specification is built by applying policies on the core specification. Hence, there is a need for a strong and inclusive governance model that adheres to the basic design principles while simultaneously being inclusive in its approach to evolution as opposed to a foundation-controlled evolution. +This governance model is inspired from the [OpenAPI ](https://www.openapis.org/participate/how-to-contribute/governance) Specification and IETF governance models. +## Need for Governance +Since the core specification is essentially abstracted, the implementors of the specification must use instances of the core specification for various domains, regions and scope. Moreover, the beckn protocol specification is implemented by applying policies on the core specification. Hence, there is a need for a strong and inclusive governance model that adheres to the basic design principles while simultaneously being inclusive in its approach to evolution as opposed to a foundation-controlled evolution. -# Areas That Require Specification Governance +## Areas That Require Specification Governance There are many independently governable specification elements in the Beckn Protocol. These elements are called areas. Each area will have multiple working groups under it. The following are the areas currently identified : +### Design Principles +Beckn protocol specification adopts a set of design principles that must be adhered to at all times while updating the specification. These principles, like all other principles, are not applicable for all time. Hence, the design principles must also allow themselves to evolve over time. Only then will the protocol be future-proof. The Core Working Group must: + +- Document the design principles in its purest and most unambiguous form +- Identify any overlaps between design principles, and find a way to make each principle atomic in its definition +- Define a methodology to apply each principle on various decision points related to the specification +- Create sufficient examples for each principle to allow contributors to self-apply the principles before proposing changes to the specification +- Periodically stress-test the design principles on the various components of the specification +- Record any violation of said design principles and report it to the violator with suggested changes + +### API +Beckn protocol defines a set of actions that may be implemented as APIs. The Core Working Group must: -* **API** : Core API and schema definitions -* **Taxonomy** : Domain-specific repositories for organization of taxonomies and taxonomy element definitions -* **Certification** : Certification and compliance rules and specifications -* **Architecture** : High level architecture definition and definitions of the various components in the network -* **Network Security** : Network security protocols and best practices -* **Policy** : Governance structures, licences and copyrights -* **Missions** : Specific implementation related working groups +- Clearly define the methods supported by the API +- Document the API in standard machine-readable formats like Open API, Async API or likewise +- Define methodologies to test the API against various use cases +- Extend the API to support more use cases +### Schema +Beckn protocol defines a standard schema that can be composed and instantiated as run-time objects. The Core Working Group must: + +- Clearly define the schema in an unambiguous manner +- Document the schema in standard formats like JSON Schema +- Define methodologies to test the schema against various use cases +- Extend the schema set to support more use cases via addition or extension +- Define methodologies to map any sector-specific knowledge model to the core schema + +### Communication +Beckn protocol defines a standard communication protocol for each API endpoint. The Core Working Group must: + +- Clearly define the exchange mechanism for each action via UML sequence diagrams +- Link the schema and API definition in each sequence +- Explain each interaction in simple terms +- Define methodologies to map real-world consumer-provider interactions to beckn protocol interactions + +### Architecture +Beckn protocol specifies a standard reference architecture of an open network. The network actors it currently includes are BAP, BPP, BG and a Network Registry. The Core Working Group must: + +- Document the ecosystem architecture in an unambiguous, machine-readable way. Using UML wherever possible +- Clearly define each layer of the architecture +- Clearly define the actors in each layer of the architecture +- To clearly define the purpose of each Network Actor +- To maintain an up-to-date, technology-agnostic, high-level reference implementation architecture document for each network actor +- To define processes to add new Network Actors to the specification +- Define processes to periodically evolve the architecture based on community contributions # Area Director (AD) @@ -170,21 +200,24 @@ The specification will evolve over time. Changes may be made when any of the fol # Specification Review Guidelines -While reviewing each change in the specification committers should always consider the following: +While reviewing each change in the Core Working Group should always consider the following: + +1. **Relevance**: Beckn protocol has defined clear boundaries on what is in-scope of beckn protocol and what is not. CWG members should ask themselves some basic questions like. Is it network-specific? Is it technology-specific? Is it implementation-specific? -1. **Migration Impact**: Is this a construct that has a smooth implementation path from the latest specification? If so, how complicated is it to migrate implementations to the proposed change? Secondly, how large of a cohort is affected due to this change -2. **Tooling**: Contributors should strive to support code generation, software interfaces, spec generation techniques, as well as other utilities. Some features may be impossible to support in different frameworks/languages. These should be documented and considered during the change approval process. -3. **Visualization**: Can the specification change be graphically visualized somehow in a UI or other interface +2. **Migration Impact**: Is this a construct that has a smooth implementation path from the latest specification? If so, how complicated is it to migrate implementations to the proposed change? Secondly, how large of a cohort is affected due to this change +3. **Tooling**: Contributors should strive to support code generation, software interfaces, spec generation techniques, as well as other utilities. Some features may be impossible to support in different frameworks/languages. These should be documented and considered during the change approval process. +4. **Visualization**: Can the specification change be graphically visualized somehow in a UI or other interface Spec changes should be approved by a majority of the committers. Approval can be given by commenting on the issue itself, for example, "Approved by @cwgadmin" however at least one formal GitHub-based flow approval must be given. After the voting criteria is met, the WG Admin can merge or assign a member to merge the PR. No change should be approved until there is documentation for it, supplied in an accompanying PR. # Feature Evolution -All new features have a life cycle starting from a proposal to a required standard. All new features to the specification must start with a status as “proposed”. Upon review, the CWG will decide to move forward with a discussion on the change and then move it to a “draft” status. If the feature is considered to become part of the specification, it will be moved to the “recommended” status. And if the feature is widely accepted and adopted by the ecosystem, then it will be moved to a “required” status after which it will become part of the core specification. - +All new features have a lifecycle starting from a proposal to a protocol standard. All new features to the specification must start with a status as “proposed”. Upon review, the CWG will decide to move forward with a discussion on the change and then move it to a “draft” status. If the feature is considered to become part of the specification, it will be moved to the “recommended” status. And if the feature is widely accepted and adopted by the ecosystem, then it will be moved to a “required” status after which it will become part of the core specification. All proposals to the specification are submitted as namespaced properties as mentioned in CONTRIBUTIONS.md. The working group has the responsibility of reviewing these proposals and classify them accordingly as draft, recommended, required or not-recommended features. Once classified, the WGs must rename the namespace with the appropriate feature stage component after review. +All development activity on the future specification will be performed as features on a draft branch and merged into this branch. Upon release of the future specification, this branch will be merged to master. + ## Proposal From 776e2a4658acbcb3674d856b8862a003a38e250e Mon Sep 17 00:00:00 2001 From: Ravi Prakash Date: Tue, 17 May 2022 18:49:04 +0530 Subject: [PATCH 08/11] Adding licensing as an area that requires governance --- GOVERNANCE.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 2036bf80..359dfa31 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -124,6 +124,15 @@ Beckn protocol specification adopts a set of design principles that must be adhe - Periodically stress-test the design principles on the various components of the specification - Record any violation of said design principles and report it to the violator with suggested changes + +### Licensing +Beckn protocol is currently covered under a CC-BY-ND License. Just like the design principles, the licensing also may change basis the extent of adoption by the community. At the beginning, to ensure common adoption across the ecosystem, it is recommended to have a strict "Non-Derivative" license and gradually move to a slightly more lenient license as adoption becomes more standardized. The Core Working Group must: + +- Clearly define what is allowed and not allowed as per the licensing rules in practical implementation scenarios +- Gather feedback from the ecosystem around issues faced by implementors due to the licensing +- Provide solutions to overcome problems around licensing +- If all of the above fail to achieve outomes, also consider changing the license to make the protocol more flexible without loss of interoperability + ### API Beckn protocol defines a set of actions that may be implemented as APIs. The Core Working Group must: From 2ecffaf4f7d7ef5d9320f23697c327dc9b59c4ca Mon Sep 17 00:00:00 2001 From: Ravi Prakash Date: Thu, 19 May 2022 18:00:51 +0530 Subject: [PATCH 09/11] simplified licensing --- GOVERNANCE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 359dfa31..e0a188cb 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -126,7 +126,7 @@ Beckn protocol specification adopts a set of design principles that must be adhe ### Licensing -Beckn protocol is currently covered under a CC-BY-ND License. Just like the design principles, the licensing also may change basis the extent of adoption by the community. At the beginning, to ensure common adoption across the ecosystem, it is recommended to have a strict "Non-Derivative" license and gradually move to a slightly more lenient license as adoption becomes more standardized. The Core Working Group must: +Beckn protocol is currently covered under a Creative Commons License. Just like the design principles, the licensing also may change basis the extent of adoption by the community. The Core Working Group must: - Clearly define what is allowed and not allowed as per the licensing rules in practical implementation scenarios - Gather feedback from the ecosystem around issues faced by implementors due to the licensing From 01385a7ed1b9a20c3062864caf9d63cc3fa1d33d Mon Sep 17 00:00:00 2001 From: Ravi Prakash Date: Tue, 24 May 2022 21:39:55 +0530 Subject: [PATCH 10/11] Adding CC-BY-NC-SA License --- LICENSE.md | 116 +++++++++++++++++++++++++++++++---------------------- 1 file changed, 68 insertions(+), 48 deletions(-) diff --git a/LICENSE.md b/LICENSE.md index 92d34970..6b81a4b5 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,6 +1,6 @@ ## creative commons -# Attribution-NoDerivatives 4.0 International +# Attribution-NonCommercial-ShareAlike 4.0 International Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible. @@ -12,101 +12,119 @@ Creative Commons public licenses provide a standard set of terms and conditions * __Considerations for the public:__ By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to respect those requests where reasonable. [More considerations for the public](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensees). -## Creative Commons Attribution-NoDerivatives 4.0 International Public License +## Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License -By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-NoDerivatives 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions. +By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions. ### Section 1 – Definitions. a. __Adapted Material__ means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image. -b. __Copyright and Similar Rights__ means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights. +b. __Adapter's License__ means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License. -c. __Effective Technological Measures__ means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements. +c. __BY-NC-SA Compatible License__ means a license listed at [creativecommons.org/compatiblelicenses](http://creativecommons.org/compatiblelicenses), approved by Creative Commons as essentially the equivalent of this Public License. -d. __Exceptions and Limitations__ means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material. +d. __Copyright and Similar Rights__ means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights. -e. __Licensed Material__ means the artistic or literary work, database, or other material to which the Licensor applied this Public License. +e. __Effective Technological Measures__ means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements. -f. __Licensed Rights__ means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license. +f. __Exceptions and Limitations__ means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material. -g. __Licensor__ means the individual(s) or entity(ies) granting rights under this Public License. +g. __License Elements__ means the license attributes listed in the name of a Creative Commons Public License. The License Elements of this Public License are Attribution, NonCommercial, and ShareAlike. -h. __Share__ means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them. +h. __Licensed Material__ means the artistic or literary work, database, or other material to which the Licensor applied this Public License. -i. __Sui Generis Database Rights__ means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world. +i. __Licensed Rights__ means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license. -j. __You__ means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning. +h. __Licensor__ means the individual(s) or entity(ies) granting rights under this Public License. -### Section 2 – Scope. +i. __NonCommercial__ means not primarily intended for or directed towards commercial advantage or monetary compensation. For purposes of this Public License, the exchange of the Licensed Material for other material subject to Copyright and Similar Rights by digital file-sharing or similar means is NonCommercial provided there is no payment of monetary compensation in connection with the exchange. -a. ___License grant.___ +j. __Share__ means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them. + +k. __Sui Generis Database Rights__ means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world. - 1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to: +l. __You__ means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning. - A. reproduce and Share the Licensed Material, in whole or in part; and +### Section 2 – Scope. - B. produce and reproduce, but not Share, Adapted Material. +a. ___License grant.___ - 2. __Exceptions and Limitations.__ For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions. + 1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to: - 3. __Term.__ The term of this Public License is specified in Section 6(a). + A. reproduce and Share the Licensed Material, in whole or in part, for NonCommercial purposes only; and - 4. __Media and formats; technical modifications allowed.__ The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material. + B. produce, reproduce, and Share Adapted Material for NonCommercial purposes only. - 5. __Downstream recipients.__ + 2. __Exceptions and Limitations.__ For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions. + + 3. __Term.__ The term of this Public License is specified in Section 6(a). - A. __Offer from the Licensor – Licensed Material.__ Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License. + 4. __Media and formats; technical modifications allowed.__ The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material. + + 5. __Downstream recipients.__ - B. __No downstream restrictions.__ You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material. + A. __Offer from the Licensor – Licensed Material.__ Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License. - 6. __No endorsement.__ Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i). + B. __Additional offer from the Licensor – Adapted Material.__ Every recipient of Adapted Material from You automatically receives an offer from the Licensor to exercise the Licensed Rights in the Adapted Material under the conditions of the Adapter’s License You apply. -b. ___Other rights.___ + C. __No downstream restrictions.__ You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material. - 1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise. + 6. __No endorsement.__ Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i). + +b. ___Other rights.___ - 2. Patent and trademark rights are not licensed under this Public License. + 1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise. - 3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties. + 2. Patent and trademark rights are not licensed under this Public License. + 3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties, including when the Licensed Material is used other than for NonCommercial purposes. + ### Section 3 – License Conditions. Your exercise of the Licensed Rights is expressly made subject to the following conditions. a. ___Attribution.___ - 1. If You Share the Licensed Material, You must: + 1. If You Share the Licensed Material (including in modified form), You must: + + A. retain the following if it is supplied by the Licensor with the Licensed Material: + + i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated); - A. retain the following if it is supplied by the Licensor with the Licensed Material: + ii. a copyright notice; - i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated); + iii. a notice that refers to this Public License; - ii. a copyright notice; + iv. a notice that refers to the disclaimer of warranties; - iii. a notice that refers to this Public License; + v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable; - iv. a notice that refers to the disclaimer of warranties; + B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and - v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable; + C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License. - B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and + 2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information. - C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License. + 3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable. - For the avoidance of doubt, You do not have permission under this Public License to Share Adapted Material. +b. ___ShareAlike.___ - 2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information. +In addition to the conditions in Section 3(a), if You Share Adapted Material You produce, the following conditions also apply. - 3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable. + 1. The Adapter’s License You apply must be a Creative Commons license with the same License Elements, this version or later, or a BY-NC-SA Compatible License. + + 2. You must include the text of, or the URI or hyperlink to, the Adapter's License You apply. You may satisfy this condition in any reasonable manner based on the medium, means, and context in which You Share Adapted Material. + + 3. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, Adapted Material that restrict exercise of the rights granted under the Adapter's License You apply. ### Section 4 – Sui Generis Database Rights. Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material: -a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database, provided You do not Share Adapted Material; +a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database for NonCommercial purposes only; -b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material; and +b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material, including for purposes of Section 3(b); and c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database. @@ -126,11 +144,11 @@ a. This Public License applies for the term of the Copyright and Similar Rights b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates: - 1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or + 1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or - 2. upon express reinstatement by the Licensor. + 2. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or - For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License. + For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License. c. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License. @@ -152,6 +170,8 @@ c. No term or condition of this Public License will be waived and no failure to d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority. -> Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at [creativecommons.org/policies](http://creativecommons.org/policies), Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses. -> -> Creative Commons may be contacted at creativecommons.org +``` +Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at [creativecommons.org/policies](http://creativecommons.org/policies), Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses. + +Creative Commons may be contacted at [creativecommons.org](http://creativecommons.org/). +``` \ No newline at end of file From 52967925b96789106d4d512f64a62e51ab61bffd Mon Sep 17 00:00:00 2001 From: Ravi Prakash Date: Tue, 24 May 2022 21:46:09 +0530 Subject: [PATCH 11/11] Delete BECKN-RFC-005-Creating-Pub-Sub-Enabled-Network.md --- ...FC-005-Creating-Pub-Sub-Enabled-Network.md | 121 ------------------ 1 file changed, 121 deletions(-) delete mode 100644 docs/proposals/BECKN-RFC-005-Creating-Pub-Sub-Enabled-Network.md diff --git a/docs/proposals/BECKN-RFC-005-Creating-Pub-Sub-Enabled-Network.md b/docs/proposals/BECKN-RFC-005-Creating-Pub-Sub-Enabled-Network.md deleted file mode 100644 index 236aeb13..00000000 --- a/docs/proposals/BECKN-RFC-005-Creating-Pub-Sub-Enabled-Network.md +++ /dev/null @@ -1,121 +0,0 @@ -# Creating-Pub-Sub-Enabled Network - - -## ID: -BECKN-RFC-005 - -## Draft ID -Draft-01 - -## Title: -Creating a Pub-sub enabled network. - -## Category: -Network - -## Status: -Protocol Draft - -## Published on: -January 21, 2022 - -## Expires on: -April 05, 2022 or Date of publication of next draft which ever is earlier - -## License: -CC-BY-ND - -## Authors: -1. Venkatraman Mahadevan : venky@humbhionline.in - -## Reviewers: -1. Sujith Nair : sujith@becknfoundation.org -2. Pramod Varma : pramod@ekstep.org -3. Ravi Prakash : ravi@becknfoundation.org - - -# Introduction -Pub Subscribe is a popular industry standard where events are published by _publishers_ to a message queue on specific topics. _Subscribers_ listening to specific topics/topic wildcards, on the queue are notified of the event. _Subscribers_ typically take actions on these events asyncronously and go back to listening for more events of interest. - -The Beckn protocol as on Jan 21 2021 has been documented according to openapi spec version 3.0.0. Open Api spec, which is primary for synchronous communication over http. As Beckn is architected fundamentally to be for async communication, It was felt that a pub-sub mechanism and probably documenting through Async Api Spec would be better suited. - -# The experiment. -In [Beckn-One](https://github.com/venkatramanm/beckn-portal) (which is a reference network for Beckn applications), the following experiment was conducted. - -1. A system wide open message broker was made available for BAPs and BPPs registered on the network. (nats.io and hivemq were tried out) -2. Topics via which communication was enabled were designed according to the following pattern - - ROOT/[Country]/[City]/[domain]/[action]/[intended_subscriber_id]/[transaction_id]/[message_id] (in hive mq) - AND - ROOT.[Country].[City].[domain].[action].[intended_subscriber_id].[transaction_id].[message_id] (in nats.io) - - *Note* - - 1. Topic level separators, single level wild cards and multilevel wild cards are different by brokers - 2. For Search requests the intended_subscriber_id field was always "all" in BAP and BPP. - 3. Special characters like "/" in the fields would need to be escaped so that they are not confused with level separator. For uniformity, we replaced all broker specific special characters by strings "_separator_", "_single_level_wild_card_" and "_multi_level_wild_card_" respectively - -1. Sandbox BAP in beckn-one published a **Cloud event** to the complete topic with no wild card. -2. Humbhionline BPP was listening to multiple topics. Some of which were complete topic and some were wild cards. - - Extract from Humbhionline logs. - ================================ - Subscribed to topic ROOT.*.*.nic2004:52110.confirm.mandi_separator_succinct_separator_in.> - Subscribed to topic ROOT.*.*.nic2004:52110.cancel.mandi_separator_succinct_separator_in.> - Subscribed to topic ROOT.*.*.nic2004:52110.init.mandi_separator_succinct_separator_in.> - Subscribed to topic ROOT.*.*.nic2004:52110.search.all.> - Subscribed to topic ROOT.*.*.nic2004:52110.select.mandi_separator_succinct_separator_in.> - Subscribed to topic ROOT.*.*.nic2004:52110.update.mandi_separator_succinct_separator_in.> - Subscribed to topic ROOT.*.*.nic2004:52110.track.mandi_separator_succinct_separator_in.> - Subscribed to topic ROOT.*.*.nic2004:52110.status.mandi_separator_succinct_separator_in.> - -5. On firing a test search api from the beckn-one bap, a payload was pushed to the topic ROOT.IND.std080.nic2004:52110.search.all.[a_txn_id].[a_message_id] - -5. Humbhionline's BPP picked up the search request from the wild card topic subscription (ROOT.\*.*.nic2004:52110.search.all.>). Processed it asyncronously and pushed the response payload to the on_search queue being listened to by the beckn-one bap. - -6. Beckn One bAP was subscribed to the following topics - - Extract from Beckn-One Logs - ============================ - Subscribed to topic ROOT.*.*.nic2004:52110.on_search.beckn-one_separator_succinct_separator_in_separator_nic2004:52110_separator_BAP.> - Subscribed to topic ROOT.*.*.nic2004:52110.on_select.beckn-one_separator_succinct_separator_in_separator_nic2004:52110_separator_BAP.> - Subscribed to topic ROOT.*.*.nic2004:52110.on_init.beckn-one_separator_succinct_separator_in_separator_nic2004:52110_separator_BAP.> - Subscribed to topic ROOT.*.*.nic2004:52110.on_confirm.beckn-one_separator_succinct_separator_in_separator_nic2004:52110_separator_BAP.> - Subscribed to topic ROOT.*.*.nic2004:52110.on_track.beckn-one_separator_succinct_separator_in_separator_nic2004:52110_separator_BAP.> - Subscribed to topic ROOT.*.*.nic2004:52110.on_cancel.beckn-one_separator_succinct_separator_in_separator_nic2004:52110_separator_BAP.> - Subscribed to topic ROOT.*.*.nic2004:52110.on_update.beckn-one_separator_succinct_separator_in_separator_nic2004:52110_separator_BAP.> - Subscribed to topic ROOT.*.*.nic2004:52110.on_status.beckn-one_separator_succinct_separator_in_separator_nic2004:52110_separator_BAP.> - Subscribed to topic ROOT.*.*.nic2004:52110.on_rating.beckn-one_separator_succinct_separator_in_separator_nic2004:52110_separator_BAP.> - Subscribed to topic ROOT.*.*.nic2004:52110.on_support.beckn-one_separator_succinct_separator_in_separator_nic2004:52110_separator_BAP.> - -1. Data in the **Cloud Event** contained the regular beckn json payload as bytes. and the http headers (Authorization etc) were passed as Extension attributes on the Event) -2. -# Observations -1. There was no ACK or NACK. Just the message was pushed successfully into the queue with message broker api. - 1. Ack and Nack in http implementation was for signature validations. Now this feedback is not being provided. no response could mean many things, - 1. Validation Failures, - 2. Processing Errors - 3. Nothing to return. -2. Response times were a bit fast than http as there was no need for connections to be created each time. The queue was always connected. -3. Cloud event serialization and deserialization needed to be done with content_type of "application/octet-stream" (When we tried as application/json, the jackson library used by cloud events would unescape and escaped forward slash. Meaning "\/" became "/" ). This caused payload tampering and signature verification failed. However once content_type was marked as octet-stream, jackson didnot get an oppurtunity to apply over intelligence and corrupt the payload!! - - - -# Conclusions, -1. Pub sub is workable. We can start working on the Async Api Specification.. -2. Network will need to decide what broker to use and how permissioning may be done. - -# Further investigations -2. Need to figure out how we need to control the permissions of the topic. it is possible to do using some user/password or other schemes but need to find what makes sense and is easy to implement at network level. - - -# How Can some one try out the pub sub gateway of beckn-one. -1. You can mark the apitest on Beckn-One as 'via queue'. and the Sandbox tool would put the payload in an appropriate queue. -2. Your BPP/BAP need to listen on appropriate queues to get the messages. -3. You would need to support the queue based subscription as another mechanism to receive messages other than the http connection so that existing functionality is also supported. - - - - - -