Showing preview only (461K chars total). The displayed content is truncated. Use the JSON API for full output.
Extracted by GitExtract (https://gitextract.com)
Repository: beckn/protocol-specifications
Branch: master
Commit: 9be4cebbbf0d
Files: 137
Total size: 427.7 KB
Directory structure:
protocol-specifications/
├── .github/
│ └── ISSUE_TEMPLATE/
│ ├── bug_report.md
│ └── feature_request.md
├── .gitignore
├── CHANGELOG.md
├── CONTRIBUTION.md
├── GOVERNANCE.md
├── LICENSE.md
├── MAINTAINERS.md
├── README.md
├── WORKING-GROUPS.md
├── api/
│ ├── meta/
│ │ ├── README.md
│ │ ├── build/
│ │ │ └── meta.yaml
│ │ └── components/
│ │ ├── index.yaml
│ │ ├── io/
│ │ │ ├── CancellationReasons.yaml
│ │ │ ├── GetCancellationReasons.yaml
│ │ │ ├── GetRatingCategories.yaml
│ │ │ ├── GetReturnReasons.yaml
│ │ │ ├── RatingCategories.yaml
│ │ │ ├── Response.yaml
│ │ │ └── ReturnReasons.yaml
│ │ └── schema/
│ │ └── index.yaml
│ ├── registry/
│ │ ├── README.md
│ │ ├── build/
│ │ │ ├── README.md
│ │ │ └── registry.yaml
│ │ └── components/
│ │ ├── index.yaml
│ │ ├── io/
│ │ │ ├── Lookup.yaml
│ │ │ ├── LookupResponse.yaml
│ │ │ ├── OnSubscribe.yaml
│ │ │ ├── OnSubscribeResponse.yaml
│ │ │ ├── README.md
│ │ │ ├── Register.yaml
│ │ │ ├── Subscribe.yaml
│ │ │ └── SubscriptionResponse.yaml
│ │ └── schema/
│ │ └── index.yaml
│ └── transaction/
│ ├── README.md
│ ├── build/
│ │ └── transaction.yaml
│ └── components/
│ ├── index.yaml
│ ├── io/
│ │ ├── Cancel.yaml
│ │ ├── Confirm.yaml
│ │ ├── Init.yaml
│ │ ├── OnCancel.yaml
│ │ ├── OnConfirm.yaml
│ │ ├── OnInit.yaml
│ │ ├── OnRating.yaml
│ │ ├── OnSearch.yaml
│ │ ├── OnSelect.yaml
│ │ ├── OnStatus.yaml
│ │ ├── OnSupport.yaml
│ │ ├── OnTrack.yaml
│ │ ├── OnUpdate.yaml
│ │ ├── README.md
│ │ ├── Rating.yaml
│ │ ├── Response.yaml
│ │ ├── Search.yaml
│ │ ├── Select.yaml
│ │ ├── Status.yaml
│ │ ├── Support.yaml
│ │ ├── Track.yaml
│ │ └── Update.yaml
│ └── schema/
│ └── index.yaml
├── docs/
│ ├── BECKN-001-Layering-Network-Policy-Draft-01.md
│ ├── BECKN-002-Payments-On-Beckn-Enabled-Networks.md
│ ├── BECKN-003-Beckn-Protocol-Communication-Draft-01.md
│ ├── BECKN-004-Policy-Administration-On-Beckn-Enabled-Networks.md
│ ├── BECKN-005-Error-Codes-Draft-01.md
│ ├── BECKN-006-Signing-Beckn-APIs-In-HTTP-Draft-01.md
│ ├── BECKN-007-The-XInput-Schema.md
│ ├── BECKN-008-Rating-and-Reputation-on-Beckn-Protocol.md
│ ├── BECKN-009-Tags-the-Edge-of-Beckn.md
│ ├── README.md
│ └── RFC-Template.md
├── protocol-specifications.iml
└── schema/
├── Ack.yaml
├── AddOn.yaml
├── Address.yaml
├── Agent.yaml
├── Authorization.yaml
├── Billing.yaml
├── Cancellation.yaml
├── CancellationTerm.yaml
├── Catalog.yaml
├── Category.yaml
├── Circle.yaml
├── City.yaml
├── Contact.yaml
├── Context.yaml
├── Country.yaml
├── Credential.yaml
├── Customer.yaml
├── DecimalValue.yaml
├── Descriptor.yaml
├── Domain.yaml
├── Duration.yaml
├── Error.yaml
├── Fee.yaml
├── Form.yaml
├── FormResponse.yaml
├── Fulfillment.yaml
├── FulfillmentState.yaml
├── Gps.yaml
├── Image.yaml
├── Intent.yaml
├── Item.yaml
├── ItemQuantity.yaml
├── Language.yaml
├── Location.yaml
├── MediaFile.yaml
├── Offer.yaml
├── Option.yaml
├── Order.yaml
├── Organization.yaml
├── Payment.yaml
├── Person.yaml
├── Price.yaml
├── Provider.yaml
├── Quotation.yaml
├── README.md
├── Rating.yaml
├── RefundTerm.yaml
├── Region.yaml
├── ReplacementTerm.yaml
├── ReturnTerm.yaml
├── Scalar.yaml
├── Schedule.yaml
├── Skill.yaml
├── State.yaml
├── Stop.yaml
├── Subscriber.yaml
├── Subscription.yaml
├── Support.yaml
├── Tag.yaml
├── TagGroup.yaml
├── Time.yaml
├── TimeToLive.yaml
├── Tracking.yaml
├── Vehicle.yaml
└── XInput.yaml
================================================
FILE CONTENTS
================================================
================================================
FILE: .github/ISSUE_TEMPLATE/bug_report.md
================================================
---
name: Bug report
about: Create a report to help us improve
title: ''
labels: ''
assignees: ''
---
**Describe the bug**
A clear and concise description of what the bug is.
**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error
**Expected behavior**
A clear and concise description of what you expected to happen.
**Screenshots**
If applicable, add screenshots to help explain your problem.
**Desktop (please complete the following information):**
- OS: [e.g. iOS]
- Browser [e.g. chrome, safari]
- Version [e.g. 22]
**Smartphone (please complete the following information):**
- Device: [e.g. iPhone6]
- OS: [e.g. iOS8.1]
- Browser [e.g. stock browser, safari]
- Version [e.g. 22]
**Additional context**
Add any other context about the problem here.
================================================
FILE: .github/ISSUE_TEMPLATE/feature_request.md
================================================
---
name: Feature request
about: Suggest an idea for this project
title: ''
labels: ''
assignees: ''
---
**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
**Describe the solution you'd like**
A clear and concise description of what you want to happen.
**Describe alternatives you've considered**
A clear and concise description of any alternative solutions or features you've considered.
**Additional context**
Add any other context or screenshots about the feature request here.
================================================
FILE: .gitignore
================================================
.DS_Store
================================================
FILE: CHANGELOG.md
================================================
# Changelog
## Core v1.0 - 31st December 2022
### API Changes
| API Endpoint | 0.9.3 | 1.0 |
|---------|-------|-------|
| rating | Sends a single rating | Allows multiple ratings to be sent |
| support| Returns a ref_id | Returns a **Support** object |
| on_select| Returns a few fields from **Order** object | Returns the complete **Order** object |
| on_init | Returns a few fields from **Order** object | Returns the complete **Order** object |
| on_rating | Returned **RatingAck** object | Returns an **XInput** object |
| on_support | Returned phone, email and url | Returns a **Support** object |
### Schema Changes
| Schema | Added | Removed | Modified |
|--------|--------|---------|----------|
| Ack| tags| - | - | - |
| Address| - | all named fields | Changed to string , entities enclosing Address have address as string and also have named city , state , area_code fields pointing to corresponding object types.|
| Agent| person , contact , organization , rating|all attributes that originally existed|
| Billing | state , city , *country* , *area_code* | created_at , updated_at | address |
| Cancellation|reason , addtional_description|type , ref_id , policies , reasons , selected_reason|
| Catalog| ttl | - | Removed "bpp/" prefix from attrbutes that had them
| Category| ttl | - | tags datatype changed to TagGroup|
| Context|location , version|core_version , city , country|
| Descriptor||symbol , audio , 3d_render|media , additional_desc|
| Domain|name , code , additional_info|-|type changed from String to object
| Error|||type - Enum restriction removed|
| Fulfillment||provider_id , person , customer.person , customer.contact , start , end|rateable , stops(array of FulfillmentStop) , path , tags (TagGroup)|customer type changed to point to (Customer) |
| Image|-|-|Schema changed from string to set of properties|
| Intent|-|-|tags changed from (Tags) to array of (TagGroup)
| ItemQuantity|unitized|-|-|
| Item|parent_item_quantity , manufacturer , quantity , category_ids , fulfillment_ids , location_ids , payment_id , add_ons , cancellation_terms , refund_terms , replacement_terms , return_terms , xinput , ttl|category_id , location_id , fulfillent_id , |tags
| Location|map_url , district , state , area_code , rating|station_code|
| Offer|tags|-|-|
| Order|ref_order_ids , status , type , fulfillments , cancellation , cancellation_terms , refund_terms , replacement_terms , return_terms , payments , xinput , tags|state , documents , fulfillment , payment| items , add_ons , offers
| Organization|descriptor , address , city , state , contact|name , cred|
| Payment|id , collected_by , url , params.bank_code , params.bank_account_number , virtual_payment_address , source_bank_code , source_bank_account_number , source_virtual_payment_address , tags | tl_method , uri , params.transaction_status| type enum changed ON_ORDER to PRE_ORDER|
| Person | id , url , age , creds , languages , skills|cred|tags
| Provider| ttl|locations.rateable | tags
| Quotation| id , breakup[].item| |
| Rating|| feedback_form , feedback_id|
| Scalar||| value , estimated_value , computed_value , range.min , range.max - > number to DecimalValue|
| Tracking| id , location| | |
| Vehicle| wheels_count , cargo_volumne , wheelchair_access , code , emmission_standard|
### New Schemas
|Name|
|-|
|CancellationTerm|
|Credential|
|Customer|
|Fee|
|Form|
|FulfillmentState|
|MediaFile|
|Region|
|ReplacementTerm|
|ReturnTerm|
|Stop|
|Subscription|
|Support |
|Tag|
|TagGroup|
|XInput|
### Removed Schemas
|Schema|
|-|
|Dimensions|
|Document|
|Feedback|
|FeedbackForm|
|FeedbackFormElement|
|FeedbackUrl|
|Language|
|Subscriber|
|Operator|
|Page|
|Policy|
|Rateable|
|RatingAck|
|Tags|
|TrackingData|
## Core v0.9.3
### 13 July, 2021
**Changes in Context schema object**
- Removed ack from action
- Changed feedback to rating in action enum
- Updated description for bap_id, bpp_id, bap_uri, bpp_uri, transaction_id, message_id
- changed ttl as type string and updated description
**Removed context object from acknowledgement responses**
**Changes to Intent schema object**
- removed query_string
- removed purpose
**The following were changed to message.order**
- select request's message.selected
- on_select request's message.selected
- on_init request's message.initialized
**Changes to Fulfillment schema object**
- Added provider_id
- Removed purpose
**Updated description of Provider.id**
**Removed tl_method from Tracking schema object**
**Removed type and ref_id from Quotation schema object**
**Added category_id to the following**
- Provider schema object
- Intent.provider
**Changes to Payment schema object**
- Added property transaction_status
- Added property currency
### 10 August, 2021
**Fixed inconsistencies in the required properties**
Provider was removed from required in the following places :
- Order property in /select
- Order property in /init
- Order schema object
In the following places message was made the only required property :
- /on_search
- /on_select
- /on_init
- /on_confirm
- /on_track
- /on_cancel
- /on_update
- /on_status
- /on_rating
- /on_support
### 12 August, 2021
**Added rating property to the following schema objects**
- Item
- Provider
- Fulfillment
**Fulfillment and Provider have been referenced directly in the Intent schema object**
**Security schemes cleanup**
- Added Gateway Subscriber Auth at top level security definition.
- Removed security from individual paths.
- Removed Signature headers
- Updated the format of the authorization headers
### 19 August, 2021
**Added schedule to Time schema object**
Schedule schema object was added to Time
### 19 August, 2021
**Updated the rating flow**
**Added/Edited the following schema objects :**
- **Rating** - Edited so that the rating_category, rating value and id is present
- **RatingAck** - Newly created to send acknowledgement of receival of rating and feedback
- **FeedbackForm** - Newly created object to represent feedback form
- **FeedbackFormElement** - Newly created object to represent an element in a feedback form
- **FeedbackUrl** - Newly created object to represent feedback URL sent by a BPP
- **Feedback** - Object edited to hold feedback form or feedback URL
**API endpoints edited/created :**
- **/get_rating_categories** : Returns the allowed categories that can be rated
- **/get_feedback_categories** : Returns the allowed categories that can have a feedback
- **/get_feedback_form** : Request the BPP to get a feedback form
- **/feedback_form** : Get a feedback form from the BPP. Callback response of /get_feedback_form
- **/rating** : Uses Rating object as message
- **/on_rating** : Used RatingAck as message
**Made all the meta APIs async. Created the following new meta BAP APIs :**
- POST /cancellation_reasons
- POST /return_reasons
- POST /rating_categories
- POST /feedback_categories
**Added Rateable property**
A new schema object Rateable of type boolean was added.
The same was added to the following :
- Agent
- Fulfillment
- Item
- Provider
- Location array inside Provider
### October 8, 2021
**Added descriptor to Intent schema object**
### October 11, 2021
**Removed enum in rating_category**
### October 12, 2021
**Removed required**
- Removed intent required from /search
- Removed required id and location from provider object in /select
- Removed required quantity from items in /select
- Removed required items from order object in /select
- Removed required id and location from provider object in /init
- Removed required quantity from items in /init
- Removed required items and billing from order object in /init
- Removed cancellation_reason_id from /cancel
- Removed required cred from Agent schema object
- Removed required name and phone from Billing schema object
- Removed required items, billing, quote and payment from Order schema object
- Removed required quantity from items property in Order schema object
- Removed required id and location from provider property in Order schema object
### November 24, 2021
**Added fulfillment_id in Item schema object**
### December 10, 2021
**Added new Gateway Authentication scheme with deprecation notice**
### December 13, 2021
**Changed the order object in select and init call**
### December 14, 2021
**Authorization object in fulfillment start and end**
- New schema object Authorization added
- New property authorization added to Fulfillment schema object and refers to the newly created Authorization object.
### December 22, 2021
**Added document object array in order**
================================================
FILE: CONTRIBUTION.md
================================================
# Contributing to the Specification
## Draft 01
# Authors
1. Ravi Prakash - ravi@becknfoundation.org
# Latest Version
Draft 01
# Previous Versions
None
# Scope
This document intends to establish transparent and open processes and guidelines to contribute to the beckn protocol specification. It contains design principles and guidelines and considerations that should be adopted by anyone wishing to propose changes to the specification.
This document is intended for the following audience.
1. Any person or organization who wants to propose a change in the specification
# Prerequisites
1. Readers must have knowledge and hands-on experience in **git** and **GitHub**.
2. Readers must have knowledge of beckn protocol specification
# Context
Beckn protocol specification exists as a set of public repositories on Github at https://github.com/beckn. Like all version controlled open-source repositories, there are guidelines that must be followed; design principles to be considered in order to propose changes to the files present in these repositories. These pull requests will then be reviewed by the maintainers of the repository and subsequently merged with the main / master branch of that repository. The governing body and repository maintainer of the beckn protocol specification is the **Core Working Group**.
# Abstract
The evolution of beckn protocol specification should be use-case driven. The working group can specify support for hypothetical use cases as they see fit, but specifications should be backed by realistic scenarios. Management of an open-source specification like beckn protocol should be governed by well defined policies and processes. Proposing any change to an open-source repository starts by raising an Issue against a repository. After an Issue is raised, a Pull Request must be created and linked to that issue. These pull requests must be reviewed and merged by the relevant working groups and repository maintainers via a standard governance model.
# Terminology
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
# Expected Outcomes After Reading This Document
After reading this document, the reader should be able to understand how to contribute to the specification.
# Introduction
The current process for evolution of beckn protocol specification is described in the **Contribution Guidelines** section of the document. Development of the next version of the specification is guided by the **Core Working Group (CWG)**. 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 CWG 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.
The beckn protocol governance principles encourage participation from individuals and companies alike.
# Contribution Guidelines
Contributing to the specification involves active participation by the contributor in the beckn open community. The following guidelines ensure a higher chance of a proposal being accepted by the community.
1. Knowledge of the specification
2. Initiating healthy discussions on Github and Slack
3. Helping other community members with Issues
4. Providing sufficient documentation and in-depth analysis
5. Following a code of conduct in the discussion forums
Not all feedback can be accommodated as a change and there may be solid arguments for or against a change being appropriate for the specification.
# Contribution Process
## 1. Review the specification
All contributors are expected to review the specification before submitting a proposal. If there is anything that a contributor does not understand, they are free to pose questions to the beckn open community of developers.
## 2. Join the Beckn Open Community on Discord
Joining the open community on Discord is a simple process. Click [here]( https://bit.ly/bocWebInvite) to join the developer community on Discord. This is useful to have quick real-time interactions with the members of the community.
## 3. Initiate / participate in discussion threads on Github
Before proposing a change to the specification, visit the discussion threads on Github [here](https://github.com/beckn/protocol-specifications/discussions)
## 4. Subscribe to existing Issues or Pull Requests
Check the [issues](https://github.com/beckn/protocol-specifications/issues) and [pull requests](https://github.com/beckn/protocol-specifications/pulls) to see if someone has already documented your idea or feedback on the specification. If you find something relevant to your proposal, subscribe to the discussions around Issues and PRs.
## 5. Raise an Issue (Feature Requests or Enhancements)
Create an issue to describe a new concern. If possible, propose a solution.
## 6. Create a Pull Request
Submit a Pull Request against that Issue.
# Specification Change Criteria
The specification will evolve over time. Changes may be made when any of the following criteria are met:
1. **Clarity**. The current "way" something is done doesn't make sense, is complicated, or not clear.
2. **Consistency**. A portion of the specification is not consistent with the rest, or with the industry standard terminology.
3. **Necessary functionality**. We are missing functionality because of a certain design of the specification.
4. **Forward-looking** **Designs**. As usage of APIs evolves to new protocols, formats, and patterns, we should always consider what the next important functionality should be.
5. **Impact**. A change will provide an impact on a large number of use cases. We should not be forced to accommodate every use case. Maintainers should strive to make the common and important use cases both well supported and common in the definition of the OAI Spec. Evolution cannot be edge-case driven.
# Considerations before Proposing a Change
For each change in the specification we should always consider the following:
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 [Needs Edit]
**Note:** Spec change proposals will be approved by the CWG. Approval will be given via a comment on the issue itself, for example, "_Approved by @cwg-admin_". No change will be approved until there is documentation for it, supplied in an accompanying PR.
# Change Tracking and Management on GitHub
**GitHub** is the medium of record for all spec designs, use cases, and so on.
All the specification related repositories are present on the official beckn protocol Github account [here](https://github.com/beckn).
## Sources of Truth
1. The **protocol-specifications** repository is the source of truth for the core transaction API specification.
2. The **registry** repository is the source of truth for implementing the registry infrastructure
3. The **specification-files** repository is the source of truth for all human readable specification files
## Branch Structure
At any given time, there would be _at most_ 4 working branches. The branches would exist if work has started on them. For example, assume a current version of **0.9.2** in the protocol-specifications repository.
1. **master** - Current stable version. No PRs would be accepted directly to modify the specification. PRs against supporting files can be accepted.
2. **core-0.9.3-draft** - The next PATCH version of the specification. This would include non-breaking changes such as typo fixes, document fixes, wording clarifications.
3. **core-0.10.0-draft** - The next MINOR version of the specification. This would include backward compatible changes to the specification like attributes to existing schema.
4. **core-1.0.0-draft** - The next MAJOR version of the specification.
The master branch shall remain the current, released beckn protocol specification. The will describe and link the working branch(es) on the default README.md on main.
Examples of how something is described _currently_ vs. the proposed solution should accompany any change proposal.
New features should be done in feature branches/forks which, upon approval, will be merged into the proper work branch.
## Raising an Issue in the Specification
Any change to the specification must begin with the creation of a Github Issue. The process for raising an issue on GitHub is detailed [here](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue).
## Creating a Pull Request
All PRs to a specific version of the specification must be made to the **draft** branch of the next upcoming version. For example, All patch changes to version **0.9.2** must be made to the** 0.9.3-draft **branch.
# Adding Features to the Core Schema
Wherever and whenever suitable, new features will be introduced inside the core protocol schema in accordance with the beckn protocol design principles. New features should be _namespaced_ by standard prefixes to indicate their deviation from the standard schema. This namespacing approach enables new features to be designed, documented and then implemented by platforms that are interested in the feature, without putting the burden of implementation on all platforms. If the feature is successfully implemented by a majority of platforms and there is demonstrable value added by the feature, it will become a candidate for inclusion inside the Core Schema in a future release of the specification, at which point all implementations will be expected to support the feature.
## Feature evolution stages
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.

## Namespacing Non-Standard Properties
The name of any new property in the core schema must be namespaced using the below format indicating that it is a **Non-Standard Property **of a schema.
`"./{namespace-id}.{feature-name}.{feature-stage}"`
### Non-standard Property Components
1. **The dot slash ( ./ )** : This symbol in the context of core specification represents a non-standard property in the core schema. If this property is being developed by a network, all platforms must be able to recognize that this attribute is currently not part of the core specification and use / ignore it appropriately.
2. **namespace-id **: This is a unique id linked to a feature being submitted for inclusion in the specification by a unique entity. The format of the ID varies with the proposer of the feature.
1. **For Individuals** : Individuals submitting new features must namespace the property with their **Github username**.For example, if Alice is a developer (_username : @alice-dev_) wants to add a feature called `"direction"` in core schema, she must submit her proposal with the new property **<code>"./@alice-dev.direction.proposed"</code></strong>
2. <strong>For Organizations</strong>: Organizations submitting new features must namespace the property with their <strong>Github orgname</strong>. For example, if Beckn Foundation (username : <em>@beckn-foundation</em>) wants to add a feature called “speed” in core schema, she must submit her proposal with the new property <strong><code>"./@beckn-foundation.speed.proposed"</code></strong>
3. <strong>feature-name </strong>: This is the name of the feature. While creating the feature-name, proposers are <em>recommended</em> to use the following guidelines before submitting the proposal. Please note that these are more like guidelines than rules.
- The English language must be used to propose any new features.
- Standard programming jargon can be used as long as it is widely accepted by the developer community. For example <code>"const"</code> is an acceptable keyword.
- The feature name must be generic and not specific to a limited region or domain
4. <strong>feature-stage</strong> : For a new feature this value will always be “<strong>proposed</strong>”. The other values are <em>draft</em>, <em>recommended</em> and <em>required</em>. These values are reserved for CWG committers and will be described in detail in the Specification Governance document.
## Identifying a new feature in the Schema
New features under discussion should be identified by the prefixed **“./”** in the property of the json schema. If the feature is deemed appropriate for inclusion in the specification, the namespace will be removed and the feature will be moved inside the Core Schema. Implementations that support new features should plan for the future removal of the prefix. When implementations add support for a later version of beckn protocol that includes the final implementation of the feature, they MUST NOT support the use of the prefix for that feature. New features will only be promoted into minor or major releases of the specification and therefore will be transparent to specification description writers and reference implementation providers who choose not to use the feature while in its draft state. This versioning schema does not apply to V0.x features. In 0.x features, even patch versions can contain bug fixes and enhancements rather than just text changes.
## Identifying a new feature in Issues
New features in Github Issues will be **labeled** with the **feature-stage** label and will be initially labelled as **proposed, draft, recommended, required or not-recommended**. When the proposal is considered sufficiently stable for pilot implementation, it will be labeled **recommended**. If during the development of a draft feature, it is determined that the feature needs to change in a way that may break existing draft implementations, the “draft” feature-stage name itself may be versioned with a version suffix. e.g. draft-02. When a draft feature becomes part of a future update to the specification any version suffix will be removed. Draft features that are deemed not appropriate for inclusion MUST be marked with the **not-recommended** label. Draft-features that are considered suitably specified and have had successful pilot implementations will be marked with the **recommended** label. If a draft feature is considered to be a required feature in ALL implementations, it will be marked with a **required** label.
Not all future new features will be introduced in this way. Some new features impact the specification in ways that cannot be encapsulated in this way. However, where a new feature can be introduced in this way, it should be.
# Participation
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/).
================================================
FILE: GOVERNANCE.md
================================================
# Specification Governance
# Version
0.6.0
# Draft Version
Draft 03
# Previous Versions
- 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 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
2. Readers should also know how open-source repositories are managed on Github.
3. Readers must have knowledge and understanding of beckn protocol specification
# Context
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
The evolution of beckn protocol specification is always use-case driven. The Core Working Group can specify support for hypothetical use cases as they see fit, but the specifications should be backed by realistic scenarios. Management of contributions towards an open-source specification like beckn protocol are governed by well defined policies and processes. These processes will evolve just like the specification does, based on use cases. Given beckn is designed to be a global protocol, maintainers and committers must be aware any change committed to the specification has a global impact on implementation. Therefore, the governance model of beckn protocol specification is based on strict and unambiguous design principles described in this document. Anyone reviewing pull requests must apply these principles on each suggested change and decide if a change is deemed worthy of inclusion into the specification. The methodologies, guidelines and processes of conducting working group meetings to review contributions made to the specification is described in this document.
# Terminology
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 of the specification
# Expected Outcomes after reading this document
After reading this document, the reader should be able to
- 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.
## 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
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.
# 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:
## Interoperability:
Any feature added to the specification must ensure that it increases interoperability between implementations.
## 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 that feature may be included in the specification.
## Security
Any feature being included in the specification must be tested for any security vulnerabilities. Free text fields, loosely-typed fields should be avoided.
## 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.
## 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.
## 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 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.
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 ](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 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
### Licensing
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
- 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:
- 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)
Each area will have an Area Director who will be responsible for the functioning and creation of the Working Groups (WG) under it and appointing the WG chair(s). The AD will be a volunteer from the community who will adhere to the design principles while reviewing any proposal submitted by a contributor.
# Working Groups (WG)
A Working Group is a collection of people who collaborate on, and are responsible for managing evolution of the specification.
## Purpose of Specification Working Groups
## Working Group Roles
Each WG has the following roles
1. Administrator
2. Core Committer
3. API Designer
4. System Architect
5. Community Manager
6. Project Manager
7. Subject Matter Expert
8. Implementation Expert
9. Call Moderator
10. Scribe
### Administrator
Each WG will have an Administrator (Admin). The Admin will be responsible for declaring a rough consensus on any decision the group has to make. Having full consensus is preferred but not required. During a decision process if the Admin decides that the issues brought forward have been discussed enough and the group has made an informed decision, the Admin can declare that there is rough consensus to go ahead with the decision. For assets (github repository, document collections, group email id etc) coming under each WG, the Admin will have access to modify it.
There could be more than one person in the group qualified for an Administrator role, but at any time there will only be one person playing that role. The remaining members may be selected via a selection process that is mutually agreed by the members of the working group.
#### Selection Criteria for a WG Admin
1. Architectural expertise
2. Domain expertise across multiple industry sectors
3. Implementation expertise across multiple technologies
4. In-depth understanding of beckn protocol design principles and its applications
5. Open-source experience
6. Experience with Git and Github management
### Core Committers
Each WG will have at least one Core Committer. The objective of a core committer is to
1. Review Proposals
2. Review Protocol Drafts
3. Respond to discussion threads
4. Review and merge PRs to the specification.
#### Selection Criteria for a Core Committer
1. Architectural expertise
2. Domain expertise across multiple industry sectors
3. Implementation expertise across multiple technologies
4. In-depth understanding of beckn protocol and its applications
5. Open-source experience
### Working Group Members
Anyone can send a request to be added to the WG to attend meetings and weigh in with opinions about any decision or through mails. To become part of a WG, one must send an email to the WG Admin. WG members can participate in discussions on Issues and Pull Requests, and respond to comments in the discussion forums. However, the approval of a working group member will not be decisiove in merging PRs to the specification.
# Managing Specification Evolution
The specification will evolve over time. Changes may be made when any of the following criteria are met:
1. **Clarity**. The current "way" something is done doesn't make sense, is complicated, or not clear.
2. **Consistency**. A portion of the specification is not consistent with the rest, or with the industry standard terminology.
3. **Necessary functionality**. We are missing functionality because of a certain design of the specification.
4. **Forward-looking Designs**. As usage of APIs evolves to new protocols, formats, and patterns, we should always consider what the next important functionality should be.
5. **Impact**. A change will have an impact on a large number of use cases. We should not be forced to accommodate every use case. Maintainers should strive to make the common and important use cases both well supported and common in the definition of the OAI Spec. We cannot be edge-case driven.
# Specification Evolution Guidelines
Any change made to specification must happen via a rigourous and comprehensive review mechanism. The review broadly requires the core committers to apply each of the design principles on the proposed change and submit an objective response to the proposer(s).
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?
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 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
All proposals will have the following namespace
```
"./@alice-dev.direction.proposed"
```
## Draft Features
All draft features will have the following namespace structure
```
"./@proposer.feature.draft"
```
## Recommended Standard
All recommended standards will have the following namespace structure
```
"./@proposer.feature.recommended"
```
## Required Standard
All recommended standards will have the following namespace structure on the draft branch. All namespaces from required standards have to be replaced with the feature names before merging them to master.
```
"./@proposer.feature.required"
```
### Not Recommended
```
"./@proposer.direction.not-recommended"
```
# Working Group Weekly Meetings
To review change requests to the specification, Working Groups should review and discuss their inclusion in weekly meetings. The meeting consists of four major agenda items.
1. **Bugs:** This involves discussing all Issues that have been raised as bugs. These will have the highest priority in terms of consideration and will have to be acknowledged and resolved within one week of submission.
2. **Proposed Enhancements:** This involves listing all the new features that have been proposed in the form of Pull Requests to the draft branches. As there are four types of branches, there is an order of priority with which proposals to each branch should be reviewed. The order of priority is recommended as follows
1. Minor Version Draft Branch
2. Patch Version Draft Branch
3. Major Version Draft Branch
As the master branch cannot accept any proposals, any proposal to the master branch must be explicitly rejected by the committers.
3. **Draft features:** This agenda involves all the proposals that have been accepted and have been classified as draft features in the previous working group meeting. In this agenda, the working group will decide whether to classify it as a **Recommended** or a **Not Recommended** standard.
4. **Recommended Standard:** This agenda involves all the draft features that have been accepted as a **Recommended Standard**. The outcome of this agenda is to classify whether a Recommended Standard can be classified as a **Required Standard**.
5. **Final Decision and Commit Approvals**: This is the final agenda of the meeting and contains a list of commits that have to be merged to the various branches.
The duration of the working group meetings can be set by the Working Group Administrator. In case all proposals are not reviewed within the meeting, the WG Admin can propose a second meeting during the week to complete the discussion,
# Change Tracking and Management
**GitHub** is the medium of record for all spec designs, use cases, and so on.
All the specification documents are present on the official beckn protocol Github account [here](https://github.com/beckn).
## Sources of Truth
1. The **protocol-specifications** repository is the source of truth for the core transaction API specification.
2. The **registry** repository is the source of truth for implementing the registry infrastructure
3. The **specification-files** repository is the source of truth for all human readable specification files
## Branch Structure
At any given time, there should be _at most_ 4 working branches. The branches would exist if implementation has started on them. For example, assume a current version of **0.9.2** in the protocol-specifications repository.
1. **master** - Current stable version. No PRs should be accepted directly to modify the specification. PRs against supporting files can be accepted.
2. **core-0.9.3-draft** - The next PATCH version of the specification. This should include non-breaking changes such as typo fixes, document fixes, wording clarifications.
3. **core-0.10.0-draft** - The next MINOR version of the specification. This would include backward compatible changes to the specification like attributes to existing schema.
4. **core-1.0.0-draft** - The next MAJOR version of the specification.
The master branch shall remain the current, released beckn protocol specification. The will describe and link the working branch(es) on the default README.md on main.
Examples of how something is described _currently_ vs. the proposed solution should accompany any change proposal.
Use labels for the workflow of specification changes. Examples of labels are _proposed_, _draft-*_, _recommended_, _required_-, _not-recommended_, _review_ (candidate for upcoming WG meeting), _rejected_, and _needs-approval_. These labels must be assigned by WG members. Style is lowercase with dashes in place of spaces.
An issue will be opened for each feature change. Embedded in the issue, or ideally linked in a file via pull-request (PR), a document about use cases should be supplied with the change.
A PR will be used to describe the _proposed_ solution and linked to the original issue.
Not all committers will contribute to every single proposed change. There may be many open proposals at once, and multiple efforts may happen in parallel.
When the work branch is ready and approved, the branch will be merged to main.
## Reviewing Pull Requests
Any Pull Request must have an associated Issue. If an Issue is not present, the reviewer must post a comment on the PR comment section asking the contributor to Raise an Issue and link the PR to it. If an Issue is not raised within 24 hours, the PR should be considered as rejected and must be closed by the reviewer with the comment _“Closing this due to unlinked Issue”_
## Managing Conflicts
If a Pull Request causes a merge conflict, the reviewer should respond with a comment “Merge conflicts present, kindly resolve and re-submit PR”. If the merge conflict is not resolved within 24 hours, the PR should be considered as rejected and must be closed by the reviewer with the comment “_Closing this due to unresolved merge conflicts_”
# Release Process
A release requires a vote on the release notes by CWG members within the voting period. Major or minor release voting periods will be announced by the CWG admin in the Slack channel and noted on the calendar at least 6 days in advance. During this time, CWG members who have not yet voted must note their approval on the GitHub pull request for the release notes. Patch releases must happen at the first CWG meeting of a calendar month. The CWG admin is responsible for coordinating the actual merge to main with marketing support, if any.
* Patch-level releases require majority approval by WG members. (Max voting period 3 days)
* Minor: requires approval by 66% of WG members. (Max voting period 7 days)
* Major: requires approval by 66% of WG members. (Max voting period 14 days)
The above policies apply to the Core Working Group. However, a WG Admin may override the majority and voting period depending on the area and size of the group.
# Transparency
The process should be as transparent as possible. Sometimes there will be discussions that use customer names, sensitive use cases, and so on. These must be anonymized, discussed in a private repository, or conducted offline. General discussions should happen on the GitHub issues for this project.
# Participation
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.
================================================
FILE: LICENSE.md
================================================
## creative commons
# 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.
### Using Creative Commons Public Licenses
Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses.
* __Considerations for licensors:__ Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. [More considerations for licensors](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensors).
* __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-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-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. __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. __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. __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. __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. __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. __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. __Licensed Material__ means the artistic or literary work, database, or other material to which the Licensor applied this Public License.
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.
h. __Licensor__ means the individual(s) or entity(ies) granting rights under this Public License.
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.
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.
l. __You__ means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning.
### Section 2 – Scope.
a. ___License grant.___
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:
A. reproduce and Share the Licensed Material, in whole or in part, for NonCommercial purposes only; and
B. produce, reproduce, and Share Adapted Material for NonCommercial purposes only.
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).
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.__
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.
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.
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.
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.___
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.
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 (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);
ii. a copyright notice;
iii. a notice that refers to this Public License;
iv. a notice that refers to the disclaimer of warranties;
v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable;
B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and
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.
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.
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.
b. ___ShareAlike.___
In addition to the conditions in Section 3(a), if You Share Adapted Material You produce, the following conditions also apply.
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 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, 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.
For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights.
### Section 5 – Disclaimer of Warranties and Limitation of Liability.
a. __Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.__
b. __To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.__
c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.
### Section 6 – Term and Termination.
a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically.
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
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.
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.
d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License.
### Section 7 – Other Terms and Conditions.
a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed.
b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License.
### Section 8 – Interpretation.
a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License.
b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions.
c. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor.
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](http://creativecommons.org/).
```
================================================
FILE: MAINTAINERS.md
================================================
# Ravi Prakash
* __Github__ : [ravi-prakash-v](https://github.com/ravi-prakash-v)
# Pramod Varma
* __Github__ : [pramodkvarma](https://github.com/pramodkvarma)
# Venkataraman Mahadevan
* __Github__ : [venkatramanm](https://github.com/venkatramanm)
================================================
FILE: README.md
================================================
---
title: "Beckn Protocol - Core"
metaTitle: "Beckn Protocol Transaction API Core"
metaDescription: "Domain agnostic transaction specification for e-commerce"
---
## Specification Evolution
| Domain | Version | Release Date |
|-----------------------|-----------|-----------------------|
| Core | 1.0.0 | 31 December 2022 |
| Core | 0.9.3 | 22 December 2021 |
| Core | 0.9.2 | 27 July, 2021 |
| Core | 0.9.1 | 09 November, 2020 |
| [Final Mile Delivery](https://github.com/beckn/protocol-specifications/tree/fd154368c4670218ce6ad0fc8ee4ada5c401b485/final-mile-delivery/v0) | 0.8.3 | 10 October, 2020 |
| [Final Mile Delivery](https://github.com/beckn/protocol-specifications/tree/ba54b53aa341d6d0bc0f65633b0a33ff75b628ab/final-mile-delivery/v0) | 0.8.2 | 21 August, 2020 |
| [Final Mile Delivery](https://github.com/beckn/protocol-specifications/tree/029496c7e969fc322f654e19ee4ae7299c25fdb5/final-mile-delivery/v0) | 0.8.1 | 19 August, 2020 |
| [Final Mile Delivery](https://github.com/beckn/protocol-specifications/tree/83006c82ae1f7069f6b609211245e651d21d90ab/final-mile-delivery/v0) | 0.8.0 | 10 August, 2020 |
| [Core](https://github.com/beckn/protocol-specifications/tree/83006c82ae1f7069f6b609211245e651d21d90ab/final-mile-delivery/v0) | 0.8.2 | 10 August, 2020 |
| [Final Mile Delivery](https://github.com/beckn/protocol-specifications/tree/83006c82ae1f7069f6b609211245e651d21d90ab/final-mile-delivery/archives/schema/0.7.0) | 0.7.0 | 06 July, 2020 |
| [Mobility](https://github.com/beckn/protocol-specifications/tree/master/mobility/schema/0.8.0) | 0.8.0 | 02 July, 2020 |
| Final Mile Delivery | 0.6.0 (depr) | 02 June, 2020 |
| [Food and Beverage](https://github.com/beckn/protocol-specifications/tree/master/food-and-beverage/schema/0.4.0) | 0.4.0 | 02 June, 2020 |
| Final Mile Delivery | 0.5.1 (depr) | 21 May, 2020 |
| [Core](https://github.com/beckn/protocol-specifications/tree/master/core/schema/0.8.0) | 0.8.0 | 21 May, 2020 |
| [Healthcare](https://developers.beckn.org/Healthcare) | 0.5.0 | 02 May, 2020 |
| Food and Beverage | 0.3.1 (depr) | 22 April, 2020 |
| Core (depr) | 0.7.1 | 17 April, 2020 |
| Mobility (depr) | 0.7.1 | 09 December, 2019 |
| Mobility (depr) | 0.7.0 | 31 October, 2019 |
# Introduction
**Beckn** is an open protocol that allows local businesses across any industry to be discovered and engaged by any beckn-enabled application. Beckn protocol helps businesses co-create solutions for the masses seamlessly, by combining services of any form or provider.
**Beckn protocol** is a collection of open specifications consisting of protocol APIs, message formats, network design and reference architectures to allow any two entities to execute commercial transactions without being on the same platform.
This server-to-server communication protocol allows any consumer facing online platform to discover and transact with any business with minimal implementation overhead. The server-to-server nature of the protocol allows rich user experiences to be built by bundling services from multiple independent platforms.
Beckn protocol decouples the demand side digital infrastructure in the form of apps and other channels from the supply side service provisioning infrastructure. It does this by making integratedservices available not just on a single platform but potentially on any online consumer interface, (online maps, messaging, wallets, voice assistant apps and devices) that have mainstream adoption in a city.
Beckn is a protocol, not a platform. It adopts a decentralized architecture that obviates the need for creating a centralised platform in order to integrate services from multiple providers simultaneously ensuring privacy and security by design by enabling secure, encrypted iteractions.
## Beckn Protocol - Core Specification
Beckn protocol - core specification defines a generic, abstracted API that when implemented allows domain-agnostic interoperable e-commerce transactions between a buyer and seller irrespective of which platform they are on. An analogy similar to this would be the case of SMTP specification that allows email communication between any two platforms that have implemented the same specification.
The core specification defines APIs for the following events in e-commerce
1. Discovery - This involves activities like platform discovery, catalog browsing, filtering and item viewing
2. Ordering - This involves activities like cart building, quote calculation, checkout & payment terms agreement, and ultimately order confirmation
3. Fulfillment - This involves all post-order-creation activities like tracking, order update, cancellation and status updates
4. Post-fulfillment - The involves all post-fulfillment activities like rating, feedback, support, returns and replacements
## Packet Structure
All communication using beckn protocol have the following packet structure
| Field | Description |
|---------------|-----------------------------------------------------------------------------------------------|
| `context` | Contains header information that is used for packet switching, key lookup, and encryption |
| `message` | Contains transaction information that is visible only to the participants of a transaction |
## Transport Protocol
While beckn protocol it designed to be transport agnostic, it is conventional to use HTTP as the default transport protocol. Additional layers like security and trust can be layered on top of this protocol using exisiting standards like HTTPS and SSL. It is recommended that any platform implementing beckn protocol use HTTPS to secure its communication.
## Communication
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.
A beckn enabled network has multiple entities communicating with each other via standard protocol APIs. The following types of communication are possible. The communication can be between,
- BAP and BG
- BAP and BPP
- BG and BPP
- BAP and Registry
- BPP and Registry
- 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 acknowledgment or ACK which basically means, “Hey, I have received your request and it looks okay during validation of the input. Let me call you back when I have the details you need”. The actual response is sent later in the form of a standard callback API which the sender is required to implement.
## Communication Protocol Between 2 Entities
The sequence diagram of a typical beckn protocol API is shown in Figure 1. For example, let’s say X is the sender and Y is the receiver, and the API being called is search.
In most cases, the sender will call the API first and the receiver will respond immediately with an ACK and close the session. After an arbitrary period of time (which is dependent on the processing of the message), the receiver will respond with an API callback to the sender. The name of the callback API is the name of the sender API with an “on_” prefix. For example, if the request API is called “search” then the associated callback API will be “on_search”.
## Communication Protocol Via Beckn Gateway
Most communication in a beckn enabled network involves two entities - the BAP and the BPP. But sometimes during the discovery stage, an intermediate entity like a Beckn Gateway (BG) is involved. In those cases, the recommended flow of communication is as follows.
If the address of the BPP is _not_ specified in the `context` field of the request body, only then should the BAP should call the `search` request to the BG. The BG may then broadcast this request to multiple BPPs that match the `context` of the request.
Sometimes the BG may query a Registry via the `lookup` API to get the BPP addresses that _match_ the `context` and then broadcast the message to those BPPs.
The BPPs immediately respond with ACKs. Soon after, the BPPs call the `on_search` API which is sent back to the BG. The BG then forwards those requests back to the BAPs.
To protect the privacy and confidentiality of the end user, it is recommended not to send _Personally Identifiable Information_ (PII) or _transactional information_ in the `message` object when transmitting via a BG. The BG should be able to only use the `context` header to perform BPP discovery and routing.
# Acknowledgments
The author would like to thank the following individuals for their contributions in creating the this document. (in alphabetical order):
Pramod Varma, Beckn Foundation
Sujith Nair, Beckn Foundation
================================================
FILE: WORKING-GROUPS.md
================================================
# Core Working Group
* [Ravi Prakash](#TODO)
* [Pramod Varma](#TODO)
* [Sujith Nair](#TODO)
* [Nirmal Rajeevan](#TODO)
* [Venkataraman Mahadevan](#TODO)
* [Paul Kapustin](#TODO)
# Mobility Working Group
* [Sujith Nair](#TODO)
* [Ravi Prakash](#TODO)
* [Srikanth Chunduri](#TODO)
* [Nirmal Rajeevan](#TODO)
* [Nikith Shetty](#TODO)
* [Paul Kapustin](#TODO)
* [Oleg Romashin](#TODO)
# Retail Working Group
* [Venkatraman Mahadevan](#TODO)
* [Thejesh GN](#TODO)
* [Ashok Ayengar](#TODO)
* [Akshay Mathur](#TODO)
# Logistics Working Group
* [Oleg Romashin](#TODO)
* [Paul Kapustin](#TODO)
* [Nikith Shetty](#TODO)
# Infrastructure Working Group
* [Dhiraj Patorkar](#TODO)
* [Devendra Rane](#TODO)
* [Sujeet Suryavanshi](#TODO)
* [Nikith Shetty](#TODO)
* [Dharmesh Bajpai](#TODO)
# Network Security Working Group
* [Sasi Kumar Ganesan](#TODO)
* [Venkataraman Mahadevan](#TODO)
* [Ravi Prakash](#TODO)
================================================
FILE: api/meta/README.md
================================================
================================================
FILE: api/meta/build/meta.yaml
================================================
openapi: 3.1.0
info:
title: Beckn Protocol Meta API
description: This document contains all the meta API endpoints that are implemented by the network participants. The information returned from these endpoints typically contain cacheable information.
version: 1.1.1
security:
- SubscriberAuth: []
paths:
/get_cancellation_reasons:
post:
tags:
- Beckn Provider Platform (BPP)
description: BAP fetches the list of cancellation reasons from BPP
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- get_cancellation_reasons
required:
- action
required:
- context
responses:
default:
$ref: '#/paths/~1return_reasons/post/responses/default'
/cancellation_reasons:
post:
tags:
- Beckn Application Platform (BPP)
description: BPP sends cancellation reasons to BAP
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- cancellation_reasons
required:
- action
message:
type: object
properties:
cancellation_reasons:
type: array
items:
$ref: '#/components/schemas/Option'
required:
- cancellation_reasons
required:
- context
- message
responses:
default:
$ref: '#/paths/~1return_reasons/post/responses/default'
/get_return_reasons:
post:
tags:
- Beckn Provider Platform (BPP)
description: BAP requests BPP to provide the list of return reasons
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- get_return_reasons
required:
- action
required:
- context
responses:
default:
$ref: '#/paths/~1return_reasons/post/responses/default'
/return_reasons:
post:
tags:
- Beckn Application Platform (BPP)
description: BPP provides the list of return reasons to the BAP
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- return_reasons
required:
- action
message:
type: object
properties:
return_reasons:
type: array
items:
$ref: '#/components/schemas/Option'
required:
- return_reasons
required:
- context
- message
responses:
default:
description: Acknowledgement of message received after successful validation of schema and signature
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
ack:
allOf:
- description: 'Describes the acknowledgement sent in response to an API call. If the implementation uses HTTP/S, then Ack must be returned in the same session. Every API call to a BPP must be responded to with an Ack whether the BPP intends to respond with a callback or not. This has one property called `status` that indicates the status of the Acknowledgement.'
type: object
properties:
status:
type: string
description: 'The status of the acknowledgement. If the request passes the validation criteria of the BPP, then this is set to ACK. If a BPP responds with status = `ACK` to a request, it is required to respond with a callback. If the request fails the validation criteria, then this is set to NACK. Additionally, if a BPP does not intend to respond with a callback even after the request meets the validation criteria, it should set this value to `NACK`.'
enum:
- ACK
- NACK
tags:
description: A list of tags containing any additional information sent along with the Acknowledgement.
type: array
items:
description: 'A collection of tag objects with group level attributes. For detailed documentation on the Tags and Tag Groups schema go to https://github.com/beckn/protocol-specifications/discussions/316'
type: object
properties:
display:
description: 'Indicates the display properties of the tag group. If display is set to false, then the group will not be displayed. If it is set to true, it should be displayed. However, group-level display properties can be overriden by individual tag-level display property. As this schema is purely for catalog display purposes, it is not recommended to send this value during search.'
type: boolean
default: true
code:
description: 'The machine-readable name of the tag group. The allowed values of this property can be published at three levels namely, a) Core specification, b) industry sector-specific adaptations, and c) Network-specific adaptations. Except core, each adaptation (sector or network) should prefix a unique namespace with the allowed value. Values outside the allowed values may or may not be ignored by the rendering platform. As this schema is purely for catalog display purposes, it is not recommended to send this value during search.'
type: string
name:
description: 'A human-readable string describing the heading under which the tags are to be displayed. Sometimes, the network policy may reserve some names for this property. Values outside the reserved values can be set by the BPP. However,the BAP may choose to rename or even ignore this value and render the output purely using code property, but it is recommended for BAPs to keep the name same to avoid confusion and provide consistency. As this schema is purely for catalog display purposes, it is not recommended to send this value during `search`.'
type: string
list:
description: 'An array of Tag objects listed under this group. This property can be set by BAPs during search to narrow the `search` and achieve more relevant results. When received during `on_search`, BAPs must render this list under the heading described by the `name` property of this schema.'
type: array
items:
description: 'Describes a tag. This is a simple key-value store which is used to contain extended metadata. This object can be added as a property to any schema to describe extended attributes. For BAPs, tags can be sent during search to optimize and filter search results. BPPs can use tags to index their catalog to allow better search functionality. Tags are sent by the BPP as part of the catalog response in the `on_search` callback. Tags are also meant for display purposes. Upon receiving a tag, BAPs are meant to render them as name-value pairs. This is particularly useful when rendering tabular information about a product or service.'
type: object
properties:
code:
description: 'The machine-readable name of the tag. The allowed values of this property can be published at three levels namely, a) Core specification, b) industry sector-specific adaptations, and c) Network-specific adaptations. Except core, each adaptation (sector or network) should prefix a unique namespace with the allowed value.'
type: string
name:
description: 'The human-readable name of the tag. This set by the BPP and rendered as-is by the BAP. Sometimes, the network policy may reserve some names for this property. Values outside the reserved values can be set by the BPP. However,the BAP may choose to rename or even ignore this value and render the output purely using the `code` property, but it is recommended for BAPs to keep the name same to avoid confusion and provide consistency.'
type: string
value:
description: The value of the tag. This set by the BPP and rendered as-is by the BAP.
type: string
display:
description: 'This value indicates if the tag is intended for display purposes. If set to `true`, then this tag must be displayed. If it is set to `false`, it should not be displayed. This value can override the group display value.'
type: boolean
- properties:
status:
enum:
- ACK
- NACK
required:
- ack
error:
description: 'Describes an error object that is returned by a BAP, BPP or BG as a response or callback to an action by another network participant. This object is sent when any request received by a network participant is unacceptable. This object can be sent either during Ack or with the callback.'
type: object
properties:
code:
type: string
description: 'Standard error code. For full list of error codes, refer to docs/protocol-drafts/BECKN-005-ERROR-CODES-DRAFT-01.md of this repo"'
paths:
type: string
description: Path to json schema generating the error. Used only during json schema validation errors
message:
type: string
description: Human readable message describing the error. Used mainly for logging. Not recommended to be shown to the user.
required:
- message
/get_rating_categories:
post:
tags:
- Beckn Provider Platform (BPP)
description: BAP requests BPP to provide the list of entities that can be rated on its system
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- get_rating_categories
required:
- action
required:
- context
responses:
default:
$ref: '#/paths/~1return_reasons/post/responses/default'
/rating_categories:
post:
tags:
- Beckn Application Platform (BPP)
description: BPP provides the list of entities that can be rated in its system to the BAP
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- rating_categories
required:
- action
message:
type: object
properties:
rating_categories:
type: array
items:
$ref: '#/components/schemas/Rating/properties/rating_category'
required:
- return_reasons
required:
- context
- message
responses:
default:
$ref: '#/paths/~1return_reasons/post/responses/default'
components:
securitySchemes:
SubscriberAuth:
type: apiKey
in: header
name: Authorization
description: 'Signature of message body using signing public key of the caller. <br/><br/>Format:<br/><br/><code>Authorization : Signature keyId="{subscriber_id}|{key_id}|{algorithm}",algorithm="ed25519",created="1606970629",expires="1607030629",headers="(created) (expires) digest",signature="Base64(signing string)"</code>'
schemas:
Context:
description: 'Every API call in beckn protocol has a context. It provides a high-level overview to the receiver about the nature of the intended transaction. Typically, it is the BAP that sets the transaction context based on the consumer''s location and action on their UI. But sometimes, during unsolicited callbacks, the BPP also sets the transaction context but it is usually the same as the context of a previous full-cycle, request-callback interaction between the BAP and the BPP. The context object contains four types of fields. <ol><li>Demographic information about the transaction using fields like `domain`, `country`, and `region`.</li><li>Addressing details like the sending and receiving platform''s ID and API URL.</li><li>Interoperability information like the protocol version that implemented by the sender and,</li><li>Transaction details like the method being called at the receiver''s endpoint, the transaction_id that represents an end-to-end user session at the BAP, a message ID to pair requests with callbacks, a timestamp to capture sending times, a ttl to specifiy the validity of the request, and a key to encrypt information if necessary.</li></ol> This object must be passed in every interaction between a BAP and a BPP. In HTTP/S implementations, it is not necessary to send the context during the synchronous response. However, in asynchronous protocols, the context must be sent during all interactions,'
type: object
properties:
domain:
description: Domain code that is relevant to this transaction context
allOf:
- description: 'Standard code representing the domain. The standard is usually published as part of the network policy. Furthermore, the network facilitator should also provide a mechanism to provide the supported domains of a network.'
location:
description: The location where the transaction is intended to be fulfilled.
allOf:
- description: The physical location of something
type: object
properties:
id:
type: string
descriptor:
$ref: '#/components/schemas/Option/properties/descriptor'
map_url:
description: The url to the map of the location. This can be a globally recognized map url or the one specified by the network policy.
type: string
format: uri
gps:
description: The GPS co-ordinates of this location.
allOf:
- description: Describes a GPS coordinate
type: string
pattern: '^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)$'
address:
description: The address of this location.
allOf:
- description: Describes a postal address.
type: string
city:
description: 'The city this location is, or is located within'
allOf:
- description: Describes a city
type: object
properties:
name:
description: Name of the city
type: string
code:
description: City code
type: string
district:
description: 'The state this location is, or is located within'
type: string
state:
description: 'The state this location is, or is located within'
allOf:
- description: A bounded geopolitical region of governance inside a country.
type: object
properties:
name:
type: string
description: Name of the state
code:
type: string
description: State code as per country or international standards
country:
description: 'The country this location is, or is located within'
allOf:
- description: Describes a country
type: object
properties:
name:
type: string
description: Name of the country
code:
type: string
description: Country code as per ISO 3166-1 and ISO 3166-2 format
area_code:
type: string
circle:
description: Describes a circular region of a specified radius centered at a specified GPS coordinate.
type: object
properties:
gps:
$ref: '#/paths/~1return_reasons/post/requestBody/content/application~1json/schema/properties/context/allOf/0/properties/location/allOf/0/properties/gps/allOf/0'
radius:
description: Describes a scalar
type: object
properties:
type:
type: string
enum:
- CONSTANT
- VARIABLE
value:
description: Describes a numerical value in decimal form
type: string
pattern: '[+-]?([0-9]*[.])?[0-9]+'
estimated_value:
$ref: '#/paths/~1return_reasons/post/requestBody/content/application~1json/schema/properties/context/allOf/0/properties/location/allOf/0/properties/circle/properties/radius/properties/value'
computed_value:
$ref: '#/paths/~1return_reasons/post/requestBody/content/application~1json/schema/properties/context/allOf/0/properties/location/allOf/0/properties/circle/properties/radius/properties/value'
range:
type: object
properties:
min:
$ref: '#/paths/~1return_reasons/post/requestBody/content/application~1json/schema/properties/context/allOf/0/properties/location/allOf/0/properties/circle/properties/radius/properties/value'
max:
$ref: '#/paths/~1return_reasons/post/requestBody/content/application~1json/schema/properties/context/allOf/0/properties/location/allOf/0/properties/circle/properties/radius/properties/value'
unit:
type: string
polygon:
description: The boundary polygon of this location
type: string
3dspace:
description: The three dimensional region describing this location
type: string
rating:
description: The rating of this location
allOf:
- $ref: '#/components/schemas/Rating/properties/value'
action:
description: The Beckn protocol method being called by the sender and executed at the receiver.
type: string
version:
type: string
description: Version of transaction protocol being used by the sender.
bap_id:
description: Subscriber ID of the BAP
allOf:
- description: 'A globally unique identifier of the platform, Typically it is the fully qualified domain name (FQDN) of the platform.'
type: string
bap_uri:
description: Subscriber URL of the BAP for accepting callbacks from BPPs.
allOf:
- description: The callback URL of the Subscriber. This should necessarily contain the same domain name as set in `subscriber_id``.
type: string
format: uri
bpp_id:
description: Subscriber ID of the BPP
allOf:
- $ref: '#/components/schemas/Context/properties/bap_id/allOf/0'
bpp_uri:
description: Subscriber URL of the BPP for accepting calls from BAPs.
allOf:
- $ref: '#/components/schemas/Context/properties/bap_uri/allOf/0'
transaction_id:
description: 'This is a unique value which persists across all API calls from `search` through `confirm`. This is done to indicate an active user session across multiple requests. The BPPs can use this value to push personalized recommendations, and dynamic offerings related to an ongoing transaction despite being unaware of the user active on the BAP.'
type: string
format: uuid
message_id:
description: 'This is a unique value which persists during a request / callback cycle. Since beckn protocol APIs are asynchronous, BAPs need a common value to match an incoming callback from a BPP to an earlier call. This value can also be used to ignore duplicate messages coming from the BPP. It is recommended to generate a fresh message_id for every new interaction. When sending unsolicited callbacks, BPPs must generate a new message_id.'
type: string
format: uuid
timestamp:
description: Time of request generation in RFC3339 format
type: string
format: date-time
key:
description: The encryption public key of the sender
type: string
ttl:
description: The duration in ISO8601 format after timestamp for which this message holds valid
type: string
Option:
description: Describes a selectable option
type: object
properties:
id:
type: string
descriptor:
description: Physical description of something.
type: object
properties:
name:
type: string
code:
type: string
short_desc:
type: string
long_desc:
type: string
additional_desc:
type: object
properties:
url:
type: string
content_type:
type: string
enum:
- text/plain
- text/html
- application/json
media:
type: array
items:
description: This object contains a url to a media file.
type: object
properties:
mimetype:
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:
description: The URL of the file
type: string
format: uri
signature:
description: The digital signature of the file signed by the sender
type: string
dsa:
description: The signing algorithm used by the sender
type: string
images:
type: array
items:
description: Describes an image
type: object
properties:
url:
description: URL to the image. This can be a data url or an remote url
type: string
format: uri
size_type:
description: The size of the image. The network policy can define the default dimensions of each type
type: string
enum:
- xs
- sm
- md
- lg
- xl
- custom
width:
description: Width of the image in pixels
type: string
height:
description: Height of the image in pixels
type: string
Rating:
description: Describes the rating of an entity
type: object
properties:
rating_category:
description: Category of the entity being rated
type: string
enum:
- Item
- Order
- Fulfillment
- Provider
- Agent
- Support
id:
description: Id of the object being rated
type: string
value:
description: 'Rating value given to the object. This can be a single value or can also contain an inequality operator like gt, gte, lt, lte. This can also contain an inequality expression containing logical operators like && and ||.'
type: string
================================================
FILE: api/meta/components/index.yaml
================================================
openapi: 3.1.0
info:
title: Beckn Protocol Meta API
description: This document contains all the meta API endpoints that are implemented by the network participants. The information returned from these endpoints typically contain cacheable information.
version: "1.1.1"
security:
- SubscriberAuth: []
paths:
/get_cancellation_reasons:
post:
tags:
- Beckn Provider Platform (BPP)
description: BAP fetches the list of cancellation reasons from BPP
requestBody:
content:
application/json:
schema:
$ref: "./io/GetCancellationReasons.yaml"
responses:
default:
$ref: "./io/Response.yaml"
/cancellation_reasons:
post:
tags:
- Beckn Application Platform (BPP)
description: BPP sends cancellation reasons to BAP
requestBody:
content:
application/json:
schema:
$ref: "./io/CancellationReasons.yaml"
responses:
default:
$ref: "./io/Response.yaml"
/get_return_reasons:
post:
tags:
- Beckn Provider Platform (BPP)
description: BAP requests BPP to provide the list of return reasons
requestBody:
content:
application/json:
schema:
$ref: "./io/GetReturnReasons.yaml"
responses:
default:
$ref: "./io/Response.yaml"
/return_reasons:
post:
tags:
- Beckn Application Platform (BPP)
description: BPP provides the list of return reasons to the BAP
requestBody:
content:
application/json:
schema:
$ref: "./io/ReturnReasons.yaml"
responses:
default:
$ref: "./io/Response.yaml"
/get_rating_categories:
post:
tags:
- Beckn Provider Platform (BPP)
description: BAP requests BPP to provide the list of entities that can be rated on its system
requestBody:
content:
application/json:
schema:
$ref: "./io/GetRatingCategories.yaml"
responses:
default:
$ref: "./io/Response.yaml"
/rating_categories:
post:
tags:
- Beckn Application Platform (BPP)
description: BPP provides the list of entities that can be rated in its system to the BAP
requestBody:
content:
application/json:
schema:
$ref: "./io/RatingCategories.yaml"
responses:
default:
$ref: "./io/Response.yaml"
components:
securitySchemes:
SubscriberAuth:
type: apiKey
in: header
name: Authorization
description: 'Signature of message body using signing public key of the caller. <br/><br/>Format:<br/><br/><code>Authorization : Signature keyId="{subscriber_id}|{key_id}|{algorithm}",algorithm="ed25519",created="1606970629",expires="1607030629",headers="(created) (expires) digest",signature="Base64(signing string)"</code>'
schemas:
$ref: "./schema/index.yaml"
================================================
FILE: api/meta/components/io/CancellationReasons.yaml
================================================
type: object
properties:
context:
allOf:
- $ref: "../../../../schema/Context.yaml"
- properties:
action:
enum:
- cancellation_reasons
required:
- action
message:
type: object
properties:
cancellation_reasons:
type: array
items:
$ref: '../../../../schema/Option.yaml'
required:
- cancellation_reasons
required:
- context
- message
================================================
FILE: api/meta/components/io/GetCancellationReasons.yaml
================================================
type: object
properties:
context:
allOf:
- $ref: "../../../../schema/Context.yaml"
- properties:
action:
enum:
- get_cancellation_reasons
required:
- action
required:
- context
================================================
FILE: api/meta/components/io/GetRatingCategories.yaml
================================================
type: object
properties:
context:
allOf:
- $ref: "../../../../schema/Context.yaml"
- properties:
action:
enum:
- get_rating_categories
required:
- action
required:
- context
================================================
FILE: api/meta/components/io/GetReturnReasons.yaml
================================================
type: object
properties:
context:
allOf:
- $ref: "../../../../schema/Context.yaml"
- properties:
action:
enum:
- get_return_reasons
required:
- action
required:
- context
================================================
FILE: api/meta/components/io/RatingCategories.yaml
================================================
type: object
properties:
context:
allOf:
- $ref: "../../../../schema/Context.yaml"
- properties:
action:
enum:
- rating_categories
required:
- action
message:
type: object
properties:
rating_categories:
type: array
items:
$ref: '../../../../schema/Rating.yaml#/properties/rating_category'
required:
- return_reasons
required:
- context
- message
================================================
FILE: api/meta/components/io/Response.yaml
================================================
description: Acknowledgement of message received after successful validation of schema and signature
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
ack:
allOf:
- $ref: "../../../../schema/Ack.yaml"
- properties:
status:
enum:
- ACK
- NACK
required:
- ack
error:
$ref: "../../../../schema/Error.yaml"
required:
- message
================================================
FILE: api/meta/components/io/ReturnReasons.yaml
================================================
type: object
properties:
context:
allOf:
- $ref: "../../../../schema/Context.yaml"
- properties:
action:
enum:
- return_reasons
required:
- action
message:
type: object
properties:
return_reasons:
type: array
items:
$ref: '../../../../schema/Option.yaml'
required:
- return_reasons
required:
- context
- message
================================================
FILE: api/meta/components/schema/index.yaml
================================================
Context:
$ref: "../../../../schema/Context.yaml"
Option:
$ref: "../../../../schema/Option.yaml"
Rating:
$ref: "../../../../schema/Rating.yaml"
================================================
FILE: api/registry/README.md
================================================
# How to build the specification
The full specification can be found at `api/registry/build/registry.yaml`
This is an autogenerated file created by compiling two sets of components namely,
1. APIs : found at `api/registry/components/io`
2. Schema : found at `api/registry/components/schemas`
The compilation flow is illustrated below
# Compilation steps
## Step 1 : Create the schema index file
- Go to the ```api/registry/components/schemas/``` folder
- Create a file ```index.yaml```. If already present, open it in a text editor
- It will contain a list of schema with $refs pointing to specific schema files in the current folder as shown below
```
Gps:
$ref: "../../../../schema/Gps.yaml"
Location:
$ref: "../../../../schema/Location.yaml"
...
```
- Ensure that each file in the ```schemas``` folder has an entry in this file. If it is not present, it will not be compiled
## Step 2 : Create the unresolved OpenAPI file
- Go to the `api/registry/components/` folder
- In this folder, create a file - `index.yaml`. If it is already present, open it in a text editor.
- In the file, you will see the following
```
openapi: 3.0.0
info:
title: Beckn Protocol Core
description: Beckn Core API specification
version: "1.0.0"
security:
- SubscriberAuth: []
- GatewaySubscriberAuth: []
/lookup:
description: Look up platforms listed on the network registry. This is a protected endpoint only accessible to network participants that have subscribed to the network (i.e Subscribers). Any subscriber can query the Registry by sending a `Lookup` object. The Registry will respond with all the platforms that match the lookup parameters.
post:
tags:
- Registry
requestBody:
content:
application/json:
schema:
$ref : "./io/Lookup.yaml"
...
```
- As you can see, the ```index.yaml``` contains the unresolved Open API definitions with references to the APIs found in ```api/registry/components/io/```
- Ensure each API definition in the ```api/registry/components/io/``` folder is referenced in this file. If it is not present, it will not be compiled.
- Once all API referencing is done, save this file and close it.
## Install swagger CLI
- Install the swagger command line tool using ```npm```
- Note: you may need to use root privileges if installing it globally
```
sudo npm install -g swagger-cli
```
## Generate the resolved OpenAPI definition file
- Go to the root directory of this project i.e ```protocol-specifications/```
- Run the following command
```
swagger-cli bundle api/registry/components/index.yaml --outfile api/registry/build/registry.yaml --type yaml
```
- If the command runs successfully, you should see an output like this,
```
Created api/registry/build/registry.yaml from api/registry/components/index.yaml
```
- Commit the changes and push the updated code
================================================
FILE: api/registry/build/README.md
================================================
================================================
FILE: api/registry/build/registry.yaml
================================================
openapi: 3.1.0
info:
title: Beckn Protocol Registry Infrastructure API
description: 'This document contains the API specification for the Registry infrastructure of a beckn-enabled network. The Registry API forms the trust layer of beckn protocol. When implemented, they enable creation of an infrastructure that allow trusted transactions between network participants to take place by means of digital signature authentication. The core infrastructure is called the Network Registry or simply, Registry. Any network participant that is listed on the registry can be assumed to have successfully passed the certfication and compliance process of the network, and hence be trusted to transact with.'
version: 1.1.1
security:
- SubscriberAuth: []
paths:
/lookup:
description: Look up platforms listed on the network registry. This is a protected endpoint only accessible to network participants that have subscribed to the network (i.e Subscribers). Any subscriber can query the Registry by sending a `Lookup` object. The Registry will respond with all the platforms that match the lookup parameters.
post:
tags:
- Registry
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
responses:
default:
description: Array of subscribers matching the lookup request attributes
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Subscription'
/subscribe:
description: 'Subscribe to a network. This endpoint allows registered network participants (a.k.a Subscribers), to update their subscription details like `domain`, `location`, `signing_public_key`, `encr_public_key` on the registry. The fields that can be updated can vary from network to network. Every network policy must contain the fields that can be updated for each type of subscriber. For example, the network policy may allow BAPs and BPPs to update all fields, but BGs may not be allowed to update any field except the public keys.'
post:
tags:
- Registry
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- subscribe
required:
- action
message:
allOf:
- $ref: '#/components/schemas/Subscription'
- properties:
nonce:
description: A randomly generated uuid nonce value
type: string
format: uuid
responses:
default:
description: The Registry returns the status of the subscription request.
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- UNDER_SUBSCRIPTION
/on_subscribe:
description: 'This endpoint is implemented by all platforms that have successfully passed the certification and compliance requirements on a network. In this endpoint, the Subscriber receives an encrypted challenge string generated by the Registry to verify the subscription details of the Network Participant sent during the `subscribe` call. During this call, Registry also validates the SSL certificate of Subscriber. If the SSL certificate is invalid, the Registry will update the subscriber’s status = INVALID_SSL and call the Subscriber''s `on_subscribe` endpoint again. Anytime the state of the Subscriber changes in the registry, the Registry can make an unsolicited call to the subscriber''s `on_subscribe` endpoint. This request must be digitally signed by the Registry. The Registry''s public key must be published at a publicly accessible trusted location so that the Subscribers can save it on their systems.'
post:
tags:
- 'Subscriber (BAP, BPP, BG)'
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- subscribe
required:
- action
message:
type: object
properties:
status:
description: The current status of the Registrant
type: string
enum:
- INITIATED
- UNDER_SUBSCRIPTION
- SUBSCRIBED
- INVALID_SSL
- UNSUBSCRIBED
challenge:
type: string
description: A random string generated by the registry encrypted with the subscriber's encryption public key
required:
- challenge
responses:
default:
description: Network Participant decrypts the challenge string using its private key and returns the decrypted value.
content:
application/json:
schema:
type: object
properties:
answer:
description: Decrypted challenge string
type: string
required:
- answer
components:
securitySchemes:
SubscriberAuth:
type: apiKey
in: header
name: Authorization
description: 'Signature of message body using signing public key of the caller. <br/><br/>Format:<br/><br/><code>Authorization : Signature keyId="{subscriber_id}|{key_id}|{algorithm}",algorithm="ed25519",created="1606970629",expires="1607030629",headers="(created) (expires) digest",signature="Base64(signing string)"</code>'
schemas:
Context:
description: 'Every API call in beckn protocol has a context. It provides a high-level overview to the receiver about the nature of the intended transaction. Typically, it is the BAP that sets the transaction context based on the consumer''s location and action on their UI. But sometimes, during unsolicited callbacks, the BPP also sets the transaction context but it is usually the same as the context of a previous full-cycle, request-callback interaction between the BAP and the BPP. The context object contains four types of fields. <ol><li>Demographic information about the transaction using fields like `domain`, `country`, and `region`.</li><li>Addressing details like the sending and receiving platform''s ID and API URL.</li><li>Interoperability information like the protocol version that implemented by the sender and,</li><li>Transaction details like the method being called at the receiver''s endpoint, the transaction_id that represents an end-to-end user session at the BAP, a message ID to pair requests with callbacks, a timestamp to capture sending times, a ttl to specifiy the validity of the request, and a key to encrypt information if necessary.</li></ol> This object must be passed in every interaction between a BAP and a BPP. In HTTP/S implementations, it is not necessary to send the context during the synchronous response. However, in asynchronous protocols, the context must be sent during all interactions,'
type: object
properties:
domain:
description: Domain code that is relevant to this transaction context
allOf:
- description: 'Standard code representing the domain. The standard is usually published as part of the network policy. Furthermore, the network facilitator should also provide a mechanism to provide the supported domains of a network.'
location:
description: The location where the transaction is intended to be fulfilled.
allOf:
- $ref: '#/components/schemas/Location'
action:
description: The Beckn protocol method being called by the sender and executed at the receiver.
type: string
version:
type: string
description: Version of transaction protocol being used by the sender.
bap_id:
description: Subscriber ID of the BAP
allOf:
- $ref: '#/components/schemas/Subscriber/properties/subscriber_id'
bap_uri:
description: Subscriber URL of the BAP for accepting callbacks from BPPs.
allOf:
- $ref: '#/components/schemas/Subscriber/properties/url'
bpp_id:
description: Subscriber ID of the BPP
allOf:
- $ref: '#/components/schemas/Subscriber/properties/subscriber_id'
bpp_uri:
description: Subscriber URL of the BPP for accepting calls from BAPs.
allOf:
- $ref: '#/components/schemas/Subscriber/properties/url'
transaction_id:
description: 'This is a unique value which persists across all API calls from `search` through `confirm`. This is done to indicate an active user session across multiple requests. The BPPs can use this value to push personalized recommendations, and dynamic offerings related to an ongoing transaction despite being unaware of the user active on the BAP.'
type: string
format: uuid
message_id:
description: 'This is a unique value which persists during a request / callback cycle. Since beckn protocol APIs are asynchronous, BAPs need a common value to match an incoming callback from a BPP to an earlier call. This value can also be used to ignore duplicate messages coming from the BPP. It is recommended to generate a fresh message_id for every new interaction. When sending unsolicited callbacks, BPPs must generate a new message_id.'
type: string
format: uuid
timestamp:
description: Time of request generation in RFC3339 format
type: string
format: date-time
key:
description: The encryption public key of the sender
type: string
ttl:
description: The duration in ISO8601 format after timestamp for which this message holds valid
type: string
Gps:
description: Describes a GPS coordinate
type: string
pattern: '^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)$'
Location:
description: The physical location of something
type: object
properties:
id:
type: string
descriptor:
description: Physical description of something.
type: object
properties:
name:
type: string
code:
type: string
short_desc:
type: string
long_desc:
type: string
additional_desc:
type: object
properties:
url:
type: string
content_type:
type: string
enum:
- text/plain
- text/html
- application/json
media:
type: array
items:
description: This object contains a url to a media file.
type: object
properties:
mimetype:
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:
description: The URL of the file
type: string
format: uri
signature:
description: The digital signature of the file signed by the sender
type: string
dsa:
description: The signing algorithm used by the sender
type: string
images:
type: array
items:
description: Describes an image
type: object
properties:
url:
description: URL to the image. This can be a data url or an remote url
type: string
format: uri
size_type:
description: The size of the image. The network policy can define the default dimensions of each type
type: string
enum:
- xs
- sm
- md
- lg
- xl
- custom
width:
description: Width of the image in pixels
type: string
height:
description: Height of the image in pixels
type: string
map_url:
description: The url to the map of the location. This can be a globally recognized map url or the one specified by the network policy.
type: string
format: uri
gps:
description: The GPS co-ordinates of this location.
allOf:
- $ref: '#/components/schemas/Gps'
address:
description: The address of this location.
allOf:
- description: Describes a postal address.
type: string
city:
description: 'The city this location is, or is located within'
allOf:
- description: Describes a city
type: object
properties:
name:
description: Name of the city
type: string
code:
description: City code
type: string
district:
description: 'The state this location is, or is located within'
type: string
state:
description: 'The state this location is, or is located within'
allOf:
- description: A bounded geopolitical region of governance inside a country.
type: object
properties:
name:
type: string
description: Name of the state
code:
type: string
description: State code as per country or international standards
country:
description: 'The country this location is, or is located within'
allOf:
- description: Describes a country
type: object
properties:
name:
type: string
description: Name of the country
code:
type: string
description: Country code as per ISO 3166-1 and ISO 3166-2 format
area_code:
type: string
circle:
description: Describes a circular region of a specified radius centered at a specified GPS coordinate.
type: object
properties:
gps:
$ref: '#/components/schemas/Gps'
radius:
$ref: '#/components/schemas/Scalar'
polygon:
description: The boundary polygon of this location
type: string
3dspace:
description: The three dimensional region describing this location
type: string
rating:
description: The rating of this location
allOf:
- description: 'Rating value given to the object. This can be a single value or can also contain an inequality operator like gt, gte, lt, lte. This can also contain an inequality expression containing logical operators like && and ||.'
type: string
Scalar:
description: Describes a scalar
type: object
properties:
type:
type: string
enum:
- CONSTANT
- VARIABLE
value:
description: Describes a numerical value in decimal form
type: string
pattern: '[+-]?([0-9]*[.])?[0-9]+'
estimated_value:
$ref: '#/components/schemas/Scalar/properties/value'
computed_value:
$ref: '#/components/schemas/Scalar/properties/value'
range:
type: object
properties:
min:
$ref: '#/components/schemas/Scalar/properties/value'
max:
$ref: '#/components/schemas/Scalar/properties/value'
unit:
type: string
Subscriber:
description: A unique operational configuration of a trusted platform on a network.
type: object
properties:
subscriber_id:
description: 'A globally unique identifier of the platform, Typically it is the fully qualified domain name (FQDN) of the platform.'
type: string
url:
description: The callback URL of the Subscriber. This should necessarily contain the same domain name as set in `subscriber_id``.
type: string
format: uri
type:
description: The role of subscriber on the network
type: string
enum:
- BAP
- BPP
- BG
domain:
description: Operating industry domain that this subscriber offers its products or services in. A single subscriber can operate in multiple domains. Each operating domain must have a unique subscriber object entry in the req
allOf:
- $ref: '#/components/schemas/Context/properties/domain/allOf/0'
location:
description: The region of operation of this subscriber
allOf:
- $ref: '#/components/schemas/Location'
Subscription:
description: Subscription details of a Network Participant.
allOf:
- $ref: '#/components/schemas/Subscriber'
- properties:
key_id:
description: A unique ID of the subscription entry in a registry.
type: string
format: uuid
signing_public_key:
description: The signing public key of the subscriber
type: string
encr_public_key:
description: The encryption public key of the subscriber
type: string
valid_from:
description: Date-time which the signing and encryption keys are valid from
type: string
format: date-time
valid_until:
description: Time till which the signing and encryption keys are valid
type: string
format: date-time
status:
description: Status of the subscription
type: string
enum:
- INITIATED
- UNDER_SUBSCRIPTION
- SUBSCRIBED
- EXPIRED
- UNSUBSCRIBED
- INVALID_SSL
created:
type: string
format: date-time
updated:
type: string
format: date-time
================================================
FILE: api/registry/components/index.yaml
================================================
openapi: 3.1.0
info:
title: Beckn Protocol Registry Infrastructure API
description: This document contains the API specification for the Registry infrastructure of a beckn-enabled network. The Registry API forms the trust layer of beckn protocol. When implemented, they enable creation of an infrastructure that allow trusted transactions between network participants to take place by means of digital signature authentication. The core infrastructure is called the Network Registry or simply, Registry. Any network participant that is listed on the registry can be assumed to have successfully passed the certfication and compliance process of the network, and hence be trusted to transact with.
version: "1.1.1"
security:
- SubscriberAuth: []
paths:
/lookup:
description: Look up platforms listed on the network registry. This is a protected endpoint only accessible to network participants that have subscribed to the network (i.e Subscribers). Any subscriber can query the Registry by sending a `Lookup` object. The Registry will respond with all the platforms that match the lookup parameters.
post:
tags:
- Registry
requestBody:
content:
application/json:
schema:
$ref : "./io/Lookup.yaml"
responses:
default:
$ref: "./io/LookupResponse.yaml"
/subscribe:
description: Subscribe to a network. This endpoint allows registered network participants (a.k.a Subscribers), to update their subscription details like `domain`, `location`, `signing_public_key`, `encr_public_key` on the registry. The fields that can be updated can vary from network to network. Every network policy must contain the fields that can be updated for each type of subscriber. For example, the network policy may allow BAPs and BPPs to update all fields, but BGs may not be allowed to update any field except the public keys.
post:
tags:
- Registry
requestBody:
content:
application/json:
schema:
$ref: "./io/Subscribe.yaml"
responses:
default:
$ref: "./io/SubscriptionResponse.yaml"
/on_subscribe:
description: This endpoint is implemented by all platforms that have successfully passed the certification and compliance requirements on a network. In this endpoint, the Subscriber receives an encrypted challenge string generated by the Registry to verify the subscription details of the Network Participant sent during the `subscribe` call. During this call, Registry also validates the SSL certificate of Subscriber. If the SSL certificate is invalid, the Registry will update the subscriber’s status = INVALID_SSL and call the Subscriber's `on_subscribe` endpoint again. Anytime the state of the Subscriber changes in the registry, the Registry can make an unsolicited call to the subscriber's `on_subscribe` endpoint. This request must be digitally signed by the Registry. The Registry's public key must be published at a publicly accessible trusted location so that the Subscribers can save it on their systems.
post:
tags:
- Subscriber (BAP, BPP, BG)
requestBody:
content:
application/json:
schema:
$ref: "./io/OnSubscribe.yaml"
responses:
default:
$ref: "./io/OnSubscribeResponse.yaml"
components:
securitySchemes:
SubscriberAuth:
type: apiKey
in: header
name: Authorization
description: 'Signature of message body using signing public key of the caller. <br/><br/>Format:<br/><br/><code>Authorization : Signature keyId="{subscriber_id}|{key_id}|{algorithm}",algorithm="ed25519",created="1606970629",expires="1607030629",headers="(created) (expires) digest",signature="Base64(signing string)"</code>'
schemas:
$ref: "./schema/index.yaml"
================================================
FILE: api/registry/components/io/Lookup.yaml
================================================
$ref: "../../../../schema/Subscription.yaml"
================================================
FILE: api/registry/components/io/LookupResponse.yaml
================================================
description: Array of subscribers matching the lookup request attributes
content:
application/json:
schema:
type: array
items:
$ref: '../../../../schema/Subscription.yaml'
================================================
FILE: api/registry/components/io/OnSubscribe.yaml
================================================
type: object
properties:
context:
allOf:
- $ref: "../../../../schema/Context.yaml"
- properties:
action:
enum:
- subscribe
required:
- action
message:
type: object
properties:
status:
description: The current status of the Registrant
type: string
enum:
- INITIATED
- UNDER_SUBSCRIPTION
- SUBSCRIBED
- INVALID_SSL
- UNSUBSCRIBED
challenge:
type: string
description: A random string generated by the registry encrypted with the subscriber's encryption public key
required:
- challenge
================================================
FILE: api/registry/components/io/OnSubscribeResponse.yaml
================================================
description: Network Participant decrypts the challenge string using its private key and returns the decrypted value.
content:
application/json:
schema:
type: object
properties:
answer:
description: Decrypted challenge string
type: string
required:
- answer
================================================
FILE: api/registry/components/io/README.md
================================================
================================================
FILE: api/registry/components/io/Register.yaml
================================================
allOf:
- $ref: "../../../../schema/Subscriber.yaml"
- properties:
nonce:
type: string
xinput_response:
$ref: "../../../../schema/XInputResponse.yaml"
================================================
FILE: api/registry/components/io/Subscribe.yaml
================================================
type: object
properties:
context:
allOf:
- $ref: "../../../../schema/Context.yaml"
- properties:
action:
enum:
- subscribe
required:
- action
message:
allOf:
- $ref: "../../../../schema/Subscription.yaml"
- properties:
nonce:
description: A randomly generated uuid nonce value
type: string
format: uuid
================================================
FILE: api/registry/components/io/SubscriptionResponse.yaml
================================================
description: The Registry returns the status of the subscription request.
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- UNDER_SUBSCRIPTION
================================================
FILE: api/registry/components/schema/index.yaml
================================================
Context:
$ref: "../../../../schema/Context.yaml"
Gps:
$ref: "../../../../schema/Gps.yaml"
Location:
$ref: "../../../../schema/Location.yaml"
Scalar:
$ref: "../../../../schema/Scalar.yaml"
Subscriber:
$ref: "../../../../schema/Subscriber.yaml"
Subscription:
$ref: "../../../../schema/Subscription.yaml"
================================================
FILE: api/transaction/README.md
================================================
# How to build the specification
**Note:** All folders mentioned here are relative to the root folder ```protocol-specifications```
The full specification can be found at `api/transaction/build/transaction.yaml`
This is an autogenerated file created by compiling two sets of components namely,
1. APIs : found at `api/components/io/`
2. Schema : found at `api/components/schemas/`
The compilation flow is illustrated below
# Compilation steps
## Step 1 : Create the schema index file
- Go to the ```core/v0/api/components/schemas/``` folder
- Create a file ```index.yaml```. If already present, open it in a text editor
- It will contain a list of schema with $refs pointing to specific schema files in the ```schema/``` folder as shown below
```
Ack:
$ref: "../../../../Ack.yaml"
AddOn:
$ref: "../../../../AddOn.yaml"
...
```
- Ensure that each file in the ```schemas``` folder has an entry in this file. If it is not present, it will not be compiled
## Step 2 : Create the unresolved OpenAPI file
- Go to the `api/transaction/components/` folder
- In this folder, create a file - `index.yaml`. If it is already present, open it in a text editor.
- In the file, you will see the following
```
openapi: 3.1.0
info:
title: Beckn Protocol Core
description: Beckn Core API specification
version: "1.1.1"
security:
- SubscriberAuth: []
paths:
/search:
post:
tags:
- Beckn Provider Platform (BPP)
- Beckn Gateway (BG)
description: BAP declares the customer's intent to buy/avail products or services
requestBody:
content:
application/json:
schema:
$ref : "./io/Search.yaml"
responses:
default:
$ref: "./io/Response.yaml"
...
```
- As you can see, the ```api/transaction/components/index.yaml``` contains the unresolved Open API definitions with references to the schemas found in ```core/v0/api/components/io/```
- Ensure each API definition in the ```api/transaction/components/io/``` folder is referenced in this file. If it is not present, it will not be compiled.
- Once all API referencing is done, save this file and close it.
## Install swagger CLI
- Install the swagger command line tool using ```npm``` (Note: you may need to use root privileges if installing it globally)
```
sudo npm install -g swagger-cli
```
## Generate the resolved OpenAPI definition file
- Go to the root directory of this project
- Run the following command
```
swagger-cli bundle api/transaction/components/index.yaml --outfile api/transaction/build/transaction.yaml --type yaml
```
- If the command runs successfully, you should see an output like this,
```
Created api/transaction/build/transaction.yaml from api/transaction/components/index.yaml
```
- Commit the changes and push the updated code
================================================
FILE: api/transaction/build/transaction.yaml
================================================
openapi: 3.1.0
info:
title: Beckn Protocol Core
description: Beckn Core Transaction API specification
version: 1.1.1
security:
- SubscriberAuth: []
paths:
/search:
post:
tags:
- Beckn Provider Platform (BPP)
- Beckn Gateway (BG)
description: BAP declares the customer's intent to buy/avail products or services
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- search
message:
type: object
properties:
intent:
$ref: '#/components/schemas/Intent'
required:
- context
- message
responses:
default:
$ref: '#/paths/~1init/post/responses/default'
/select:
post:
tags:
- Beckn Provider Platform (BPP)
description: BAP declares the customer's cart (or equivalent) created by selecting objects from the catalog
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- select
required:
- action
message:
type: object
properties:
order:
$ref: '#/components/schemas/Order'
required:
- order
required:
- context
- message
responses:
default:
$ref: '#/paths/~1init/post/responses/default'
/init:
post:
tags:
- Beckn Provider Platform (BPP)
description: Initialize an order by providing billing and/or shipping details
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- init
required:
- action
message:
type: object
properties:
order:
$ref: '#/components/schemas/Order'
required:
- order
required:
- context
- message
responses:
default:
description: Acknowledgement of message received after successful validation of schema and signature
content:
application/json:
schema:
type: object
properties:
message:
type: object
properties:
ack:
allOf:
- $ref: '#/components/schemas/Ack'
- properties:
status:
enum:
- ACK
- NACK
required:
- ack
error:
$ref: '#/components/schemas/Error'
required:
- message
/confirm:
post:
tags:
- Beckn Provider Platform (BPP)
description: Initialize an order by providing billing and/or shipping details
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- confirm
required:
- action
message:
type: object
properties:
order:
$ref: '#/components/schemas/Order'
required:
- order
required:
- context
- message
responses:
default:
$ref: '#/paths/~1init/post/responses/default'
/status:
post:
tags:
- Beckn Provider Platform (BPP)
description: Fetch the latest order object
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- status
required:
- action
message:
type: object
properties:
order_id:
$ref: '#/components/schemas/Order/properties/id'
required:
- order_id
required:
- context
- message
responses:
default:
$ref: '#/paths/~1init/post/responses/default'
/track:
post:
tags:
- Beckn Provider Platform (BPP)
description: Track an active order
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- track
required:
- action
message:
type: object
properties:
order_id:
$ref: '#/components/schemas/Order/properties/id'
callback_url:
type: string
format: uri
required:
- order_id
required:
- context
- message
responses:
default:
$ref: '#/paths/~1init/post/responses/default'
/cancel:
post:
tags:
- Beckn Provider Platform (BPP)
description: Cancel an order
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- cancel
required:
- action
message:
type: object
properties:
order_id:
$ref: '#/components/schemas/Order/properties/id'
cancellation_reason_id:
$ref: '#/components/schemas/Option/properties/id'
descriptor:
$ref: '#/components/schemas/Descriptor'
required:
- order_id
required:
- context
- message
responses:
default:
$ref: '#/paths/~1init/post/responses/default'
/update:
post:
tags:
- Beckn Provider Platform (BPP)
description: Remove object
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- update
required:
- action
message:
type: object
properties:
update_target:
description: 'Comma separated values of order objects being updated. For example: ```"update_target":"item,billing,fulfillment"```'
type: string
order:
description: Updated order object
allOf:
- $ref: '#/components/schemas/Order'
required:
- update_target
- order
required:
- context
- message
responses:
default:
$ref: '#/paths/~1init/post/responses/default'
/rating:
post:
tags:
- Beckn Provider Platform (BPP)
description: Provide feedback on a service
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- rating
required:
- action
message:
type: object
properties:
ratings:
type: array
items:
$ref: '#/components/schemas/Rating'
required:
- context
- message
responses:
default:
$ref: '#/paths/~1init/post/responses/default'
/support:
post:
tags:
- Beckn Provider Platform (BPP)
description: Contact support
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- support
required:
- action
message:
type: object
properties:
support:
$ref: '#/components/schemas/Support'
required:
- context
- message
responses:
default:
$ref: '#/paths/~1init/post/responses/default'
/on_search:
post:
tags:
- Beckn Application Platform (BAP)
- Beckn Gateway (BG)
description: BPP sends its catalog in response to a search request.
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- on_search
required:
- action
message:
type: object
properties:
catalog:
$ref: '#/components/schemas/Catalog'
required:
- catalog
error:
$ref: '#/components/schemas/Error'
required:
- context
responses:
default:
$ref: '#/paths/~1init/post/responses/default'
/on_select:
post:
tags:
- Beckn Application Platform (BAP)
description: Send draft order object with quoted price for selected items
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- on_select
required:
- action
message:
type: object
properties:
order:
$ref: '#/components/schemas/Order'
error:
$ref: '#/components/schemas/Error'
required:
- context
responses:
default:
$ref: '#/paths/~1init/post/responses/default'
/on_init:
post:
tags:
- Beckn Application Platform (BAP)
description: Send order object with payment details updated
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- on_init
required:
- action
message:
type: object
properties:
order:
$ref: '#/components/schemas/Order'
required:
- order
error:
$ref: '#/components/schemas/Error'
required:
- context
responses:
default:
$ref: '#/paths/~1init/post/responses/default'
/on_confirm:
post:
tags:
- Beckn Application Platform (BAP)
description: Send active order object
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- on_confirm
required:
- action
message:
type: object
properties:
order:
$ref: '#/components/schemas/Order'
required:
- order
error:
$ref: '#/components/schemas/Error'
required:
- context
responses:
default:
$ref: '#/paths/~1init/post/responses/default'
/on_track:
post:
tags:
- Beckn Application Platform (BAP)
description: Send tracking details of an active order
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- on_track
required:
- action
message:
type: object
properties:
tracking:
$ref: '#/components/schemas/Tracking'
required:
- tracking
error:
$ref: '#/components/schemas/Error'
required:
- context
responses:
default:
$ref: '#/paths/~1init/post/responses/default'
/on_cancel:
post:
tags:
- Beckn Application Platform (BAP)
description: Send cancellation request_id with reasons list in case of cancellation request. Else send cancelled order object
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- on_cancel
required:
- action
message:
type: object
properties:
order:
$ref: '#/components/schemas/Order'
required:
- order
error:
$ref: '#/components/schemas/Error'
required:
- context
responses:
default:
$ref: '#/paths/~1init/post/responses/default'
/on_update:
post:
tags:
- Beckn Application Platform (BAP)
description: Returns updated service with updated runtime object
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- on_update
required:
- action
message:
type: object
properties:
order:
$ref: '#/components/schemas/Order'
required:
- order
error:
$ref: '#/components/schemas/Error'
required:
- context
responses:
default:
$ref: '#/paths/~1init/post/responses/default'
/on_status:
post:
tags:
- Beckn Application Platform (BAP)
description: Fetch the status of a Service
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- on_status
required:
- action
message:
type: object
properties:
order:
$ref: '#/components/schemas/Order'
required:
- order
error:
$ref: '#/components/schemas/Error'
required:
- context
responses:
default:
$ref: '#/paths/~1init/post/responses/default'
/on_rating:
post:
tags:
- Beckn Application Platform (BAP)
description: Provide feedback on a service
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- on_rating
required:
- action
message:
type: object
properties:
feedback_form:
description: A feedback form to allow the user to provide additional information on the rating provided
allOf:
- $ref: '#/components/schemas/XInput'
error:
$ref: '#/components/schemas/Error'
required:
- context
- message
responses:
default:
$ref: '#/paths/~1init/post/responses/default'
/on_support:
post:
tags:
- Beckn Application Platform (BAP)
description: Contact Support
requestBody:
content:
application/json:
schema:
type: object
properties:
context:
allOf:
- $ref: '#/components/schemas/Context'
- properties:
action:
enum:
- on_support
required:
- action
message:
type: object
properties:
support:
$ref: '#/components/schemas/Support'
error:
$ref: '#/components/schemas/Error'
required:
- context
responses:
default:
$ref: '#/paths/~1init/post/responses/default'
components:
securitySchemes:
SubscriberAuth:
type: apiKey
in: header
name: Authorization
description: 'Signature of message body using BAP or BPP subscriber''s signing public key. <br/><br/>Format:<br/><br/><code>Authorization : Signature keyId="{subscriber_id}|{unique_key_id}|{algorithm}",algorithm="ed25519",created="1606970629",expires="1607030629",headers="(created) (expires) digest",signature="Base64(signing string)"</code>'
schemas:
Ack:
description: 'Describes the acknowledgement sent in response to an API call. If the implementation uses HTTP/S, then Ack must be returned in the same session. Every API call to a BPP must be responded to with an Ack whether the BPP intends to respond with a callback or not. This has one property called `status` that indicates the status of the Acknowledgement.'
type: object
properties:
status:
type: string
description: 'The status of the acknowledgement. If the request passes the validation criteria of the BPP, then this is set to ACK. If a BPP responds with status = `ACK` to a request, it is required to respond with a callback. If the request fails the validation criteria, then this is set to NACK. Additionally, if a BPP does not intend to respond with a callback even after the request meets the validation criteria, it should set this value to `NACK`.'
enum:
- ACK
- NACK
tags:
description: A list of tags containing any additional information sent along with the Acknowledgement.
type: array
items:
$ref: '#/components/schemas/TagGroup'
AddOn:
description: Describes an additional item offered as a value-addition to a product or service. This does not exist independently in a catalog and is always associated with an item.
type: object
properties:
id:
description: Provider-defined ID of the add-on
type: string
descriptor:
$ref: '#/components/schemas/Descriptor'
price:
$ref: '#/components/schemas/Price'
Address:
description: Describes a postal address.
type: string
Agent:
description: 'Describes the direct performer, driver or executor that fulfills an order. It is usually a person. But in some rare cases, it could be a non-living entity like a drone, or a bot. Some examples of agents are Doctor in the healthcare sector, a driver in the mobility sector, or a delivery person in the logistics sector. This object can be set at any stage of the order lifecycle. This can be set at the discovery stage when the BPP wants to provide details on the agent fulfilling the order, like in healthcare, where the doctor''s name appears during search. This object can also used to search for a particular person that the customer wants fulfilling an order. Sometimes, this object gets instantiated after the order is confirmed, like in the case of on-demand taxis, where the driver is assigned after the user confirms the ride.'
properties:
person:
$ref: '#/components/schemas/Person'
contact:
$ref: '#/components/schemas/Contact'
organization:
$ref: '#/components/schemas/Organization'
rating:
$ref: '#/components/schemas/Rating/properties/value'
Authorization:
description: 'Describes an authorization mechanism used to start or end the fulfillment of an order. For example, in the mobility sector, the driver may require a one-time password to initiate the ride. In the healthcare sector, a patient may need to provide a password to open a video conference link during a teleconsultation.'
type: object
properties:
type:
description: Type of authorization mechanism used. The allowed values for this field can be published as part of the network policy.
type: string
token:
description: 'Token used for authorization. This is typically generated at the BPP. The BAP can send this value to the user via any channel that it uses to authenticate the user like SMS, Email, Push notification, or in-app rendering.'
type: string
valid_from:
description: Timestamp in RFC3339 format from which token is valid
type: string
format: date-time
valid_to:
description: Timestamp in RFC3339 format until which token is valid
type: string
format: date-time
status:
description: Status of the token
type: string
Billing:
description: 'Describes the billing details of an entity.<br>This has properties like name,organization,address,email,phone,time,tax_number, created_at,updated_at'
type: object
properties:
name:
description: Name of the billable entity
type: string
organization:
description: Details of the organization being billed.
allOf:
- $ref: '#/components/schemas/Organization'
address:
description: The address of the billable entity
allOf:
- $ref: '#/components/schemas/Address'
state:
description: The state where the billable entity resides. This is important for state-level tax calculation
allOf:
- $ref: '#/components/schemas/State'
city:
description: The city where the billable entity resides.
allOf:
- $ref: '#/components/schemas/City'
email:
description: Email address where the bill is sent to
type: string
format: email
phone:
description: Phone number of the billable entity
type: string
time:
description: Details regarding the billing period
allOf:
- $ref: '#/components/schemas/Time'
tax_id:
description: ID of the billable entity as recognized by the taxation authority
type: string
Cancellation:
description: Describes a cancellation event
type: object
properties:
time:
description: Date-time when the order was cancelled by the buyer
type: string
format: date-time
cancelled_by:
type: string
enum:
- CONSUMER
- PROVIDER
reason:
description: The reason for cancellation
allOf:
- $ref: '#/components/schemas/Option'
additional_description:
description: Any additional information regarding the nature of cancellation
allOf:
- $ref: '#/components/schemas/Descriptor'
CancellationTerm:
description: Describes the cancellation terms of an item or an order. This can be referenced at an item or order level. Item-level cancellation terms can override the terms at the order level.
type: object
properties:
fulfillment_state:
description: The state of fulfillment during which this term is applicable.
allOf:
- $ref: '#/components/schemas/FulfillmentState'
reason_required:
description: Indicates whether a reason is required to cancel the order
type: boolean
cancel_by:
description: Information related to the time of cancellation.
allOf:
- $ref: '#/components/schemas/Time'
cancellation_fee:
$ref: '#/components/schemas/Fee'
xinput:
$ref: '#/components/schemas/XInput'
external_ref:
$ref: '#/components/schemas/MediaFile'
Catalog:
description: 'Describes the products or services offered by a BPP. This is typically sent as the response to a search intent from a BAP. The payment terms, offers and terms of fulfillment supported by the BPP can also be included here. The BPP can show hierarchical nature of products/services in its catalog using the parent_category_id in categories. The BPP can also send a ttl (time to live) in the context which is the duration for which a BAP can cache the catalog and use the cached catalog. <br>This has properties like bbp/descriptor,bbp/categories,bbp/fulfillments,bbp/payments,bbp/offers,bbp/providers and exp<br>This is used in the following situations.<br><ul><li>This is typically used in the discovery stage when the BPP sends the details of the products and services it offers as response to a search intent from the BAP. </li></ul>'
type: object
properties:
descriptor:
$ref: '#/components/schemas/Descriptor'
fulfillments:
description: Fulfillment modes offered at the BPP level. This is used when a BPP itself offers fulfillments on behalf of the providers it has onboarded.
type: array
items:
$ref: '#/components/schemas/Fulfillment'
payments:
description: Payment terms offered by the BPP for all transactions. This can be overriden at the provider level.
type: array
items:
$ref: '#/components/schemas/Payment'
offers:
description: Offers at the BPP-level. This is common across all providers onboarded by the BPP.
type: array
items:
$ref: '#/components/schemas/Offer'
providers:
type: array
items:
$ref: '#/components/schemas/Provider'
exp:
description: Timestamp after which catalog will expire
type: string
format: date-time
ttl:
description: Duration in seconds after which this catalog will expire
type: string
Category:
description: A label under which a collection of items can be grouped.
type: object
properties:
id:
description: ID of the category
type: string
parent_category_id:
$ref: '#/components/schemas/Category/properties/id'
descriptor:
$ref: '#/components/schemas/Descriptor'
time:
$ref: '#/components/schemas/Time'
ttl:
description: Time to live for an instance of this schema
tags:
type: array
items:
$ref: '#/components/schemas/TagGroup'
Circle:
description: Describes a circular region of a specified radius centered at a specified GPS coordinate.
type: object
properties:
gps:
$ref: '#/components/schemas/Gps'
radius:
$ref: '#/components/schemas/Scalar'
City:
description: Describes a city
type: object
properties:
name:
description: Name of the city
type: string
code:
description: City code
type: string
Contact:
description: Describes the contact information of an entity
type: object
properties:
phone:
type: string
email:
type: string
jcard:
type: object
description: A Jcard object as per draft-ietf-jcardcal-jcard-03 specification
Context:
description: 'Every API call in beckn protocol has a context. It provides a high-level overview to the receiver about the nature of the intended transaction. Typically, it is the BAP that sets the transaction context based on the consumer''s location and action on their UI. But sometimes, during unsolicited callbacks, the BPP also sets the transaction context but it is usually the same as the context of a previous full-cycle, request-callback interaction between the BAP and the BPP. The context object contains four types of fields. <ol><li>Demographic information about the transaction using fields like `domain`, `country`, and `region`.</li><li>Addressing details like the sending and receiving platform''s ID and API URL.</li><li>Interoperability information like the protocol version that implemented by the sender and,</li><li>Transaction details like the method being called at the receiver''s endpoint, the transaction_id that represents an end-to-end user session at the BAP, a message ID to pair requests with callbacks, a timestamp to capture sending times, a ttl to specifiy the validity of the request, and a key to encrypt information if necessary.</li></ol> This object must be passed in every interaction between a BAP and a BPP. In HTTP/S implementations, it is not necessary to send the context during the synchronous response. However, in asynchronous protocols, the context must be sent during all interactions,'
type: object
properties:
domain:
description: Domain code that is relevant to this transaction context
allOf:
- $ref: '#/components/schemas/Domain/properties/code'
location:
description: The location where the transaction is intended to be fulfilled.
allOf:
- $ref: '#/components/schemas/Location'
action:
description: The Beckn protocol method being called by the sender and executed at the receiver.
type: string
version:
type: string
description: Version of transaction protocol being used by the sender.
bap_id:
description: Subscriber ID of the BAP
allOf:
- description: 'A globally unique identifier of the platform, Typically it is the fully qualified domain name (FQDN) of the platform.'
type: string
bap_uri:
description: Subscriber URL of the BAP for accepting callbacks from BPPs.
allOf:
- description: The callback URL of the Subscriber. This should necessarily contain the same domain name as set in `subscriber_id``.
type: string
format: uri
bpp_id:
description: Subscriber ID of the BPP
allOf:
- $ref: '#/components/schemas/Context/properties/bap_id/allOf/0'
bpp_uri:
description: Subscriber URL of the BPP for accepting calls from BAPs.
allOf:
- $ref: '#/components/schemas/Context/properties/bap_uri/allOf/0'
transaction_id:
description: 'This is a unique value which persists across all API calls from `search` through `confirm`. This is done to indicate an active user session across multiple requests. The BPPs can use this value to push personalized recommendations, and dynamic offerings related to an ongoing transaction despite being unaware of the user active on the BAP.'
type: string
format: uuid
message_id:
description: 'This is a unique value which persists during a request / callback cycle. Since beckn protocol APIs are asynchronous, BAPs need a common value to match an incoming callback from a BPP to an earlier call. This value can also be used to ignore duplicate messages coming from the BPP. It is recommended to generate a fresh message_id for every new interaction. When sending unsolicited callbacks, BPPs must generate a new message_id.'
type: string
format: uuid
timestamp:
description: Time of request generation in RFC3339 format
type: string
format: date-time
key:
description: The encryption public key of the sender
type: string
ttl:
description: The duration in ISO8601 format after timestamp for which this message holds valid
type: string
Country:
description: Describes a country
type: object
properties:
name:
type: string
description: Name of the country
code:
type: string
description: Country code as per ISO 3166-1 and ISO 3166-2 format
Credential:
description: Describes a credential of an entity - Person or Organization
type: object
properties:
id:
type: string
type:
type: string
default: VerifiableCredential
url:
description: URL of the credential
type: string
format: uri
Customer:
description: Describes a customer buying/availing a product or a service
type: object
properties:
person:
$ref: '#/components/schemas/Person'
contact:
$ref: '#/components/schemas/Contact'
DecimalValue:
description: Describes a numerical value in decimal form
type: string
pattern: '[+-]?([0-9]*[.])?[0-9]+'
Descriptor:
description: Physical description of something.
type: object
properties:
name:
type: string
code:
type: string
short_desc:
type: string
long_desc:
type: string
additional_desc:
type: object
properties:
url:
type: string
content_type:
type: string
enum:
- text/plain
- text/html
- application/json
media:
type: array
items:
$ref: '#/components/schemas/MediaFile'
images:
type: array
items:
$ref: '#/components/schemas/Image'
Domain:
description: 'Described the industry sector or sub-sector. The network policy should contain codes for all the industry sectors supported by the network. Domains can be created in varying levels of granularity. The granularity of a domain can be decided by the participants of the network. Too broad domains will result in irrelevant search broadcast calls to BPPs that don''t have services supporting the domain. Too narrow domains will result in a large number of registry entries for each BPP. It is recommended that network facilitators actively collaborate with various working groups and network participants to carefully choose domain codes keeping in mind relevance, performance, and opportunity cost. It is recommended that networks choose broad domains like mobility, logistics, healthcare etc, and progressively granularize them as and when the number of network participants for each domain grows large.'
type: object
properties:
name:
description: Name of the domain
type: string
code:
description: 'Standard code representing the domain. The standard is usually published as part of the network policy. Furthermore, the network facilitator should also provide a mechanism to p
protocol-specifications/
├── .github/
│ └── ISSUE_TEMPLATE/
│ ├── bug_report.md
│ └── feature_request.md
├── .gitignore
├── CHANGELOG.md
├── CONTRIBUTION.md
├── GOVERNANCE.md
├── LICENSE.md
├── MAINTAINERS.md
├── README.md
├── WORKING-GROUPS.md
├── api/
│ ├── meta/
│ │ ├── README.md
│ │ ├── build/
│ │ │ └── meta.yaml
│ │ └── components/
│ │ ├── index.yaml
│ │ ├── io/
│ │ │ ├── CancellationReasons.yaml
│ │ │ ├── GetCancellationReasons.yaml
│ │ │ ├── GetRatingCategories.yaml
│ │ │ ├── GetReturnReasons.yaml
│ │ │ ├── RatingCategories.yaml
│ │ │ ├── Response.yaml
│ │ │ └── ReturnReasons.yaml
│ │ └── schema/
│ │ └── index.yaml
│ ├── registry/
│ │ ├── README.md
│ │ ├── build/
│ │ │ ├── README.md
│ │ │ └── registry.yaml
│ │ └── components/
│ │ ├── index.yaml
│ │ ├── io/
│ │ │ ├── Lookup.yaml
│ │ │ ├── LookupResponse.yaml
│ │ │ ├── OnSubscribe.yaml
│ │ │ ├── OnSubscribeResponse.yaml
│ │ │ ├── README.md
│ │ │ ├── Register.yaml
│ │ │ ├── Subscribe.yaml
│ │ │ └── SubscriptionResponse.yaml
│ │ └── schema/
│ │ └── index.yaml
│ └── transaction/
│ ├── README.md
│ ├── build/
│ │ └── transaction.yaml
│ └── components/
│ ├── index.yaml
│ ├── io/
│ │ ├── Cancel.yaml
│ │ ├── Confirm.yaml
│ │ ├── Init.yaml
│ │ ├── OnCancel.yaml
│ │ ├── OnConfirm.yaml
│ │ ├── OnInit.yaml
│ │ ├── OnRating.yaml
│ │ ├── OnSearch.yaml
│ │ ├── OnSelect.yaml
│ │ ├── OnStatus.yaml
│ │ ├── OnSupport.yaml
│ │ ├── OnTrack.yaml
│ │ ├── OnUpdate.yaml
│ │ ├── README.md
│ │ ├── Rating.yaml
│ │ ├── Response.yaml
│ │ ├── Search.yaml
│ │ ├── Select.yaml
│ │ ├── Status.yaml
│ │ ├── Support.yaml
│ │ ├── Track.yaml
│ │ └── Update.yaml
│ └── schema/
│ └── index.yaml
├── docs/
│ ├── BECKN-001-Layering-Network-Policy-Draft-01.md
│ ├── BECKN-002-Payments-On-Beckn-Enabled-Networks.md
│ ├── BECKN-003-Beckn-Protocol-Communication-Draft-01.md
│ ├── BECKN-004-Policy-Administration-On-Beckn-Enabled-Networks.md
│ ├── BECKN-005-Error-Codes-Draft-01.md
│ ├── BECKN-006-Signing-Beckn-APIs-In-HTTP-Draft-01.md
│ ├── BECKN-007-The-XInput-Schema.md
│ ├── BECKN-008-Rating-and-Reputation-on-Beckn-Protocol.md
│ ├── BECKN-009-Tags-the-Edge-of-Beckn.md
│ ├── README.md
│ └── RFC-Template.md
├── protocol-specifications.iml
└── schema/
├── Ack.yaml
├── AddOn.yaml
├── Address.yaml
├── Agent.yaml
├── Authorization.yaml
├── Billing.yaml
├── Cancellation.yaml
├── CancellationTerm.yaml
├── Catalog.yaml
├── Category.yaml
├── Circle.yaml
├── City.yaml
├── Contact.yaml
├── Context.yaml
├── Country.yaml
├── Credential.yaml
├── Customer.yaml
├── DecimalValue.yaml
├── Descriptor.yaml
├── Domain.yaml
├── Duration.yaml
├── Error.yaml
├── Fee.yaml
├── Form.yaml
├── FormResponse.yaml
├── Fulfillment.yaml
├── FulfillmentState.yaml
├── Gps.yaml
├── Image.yaml
├── Intent.yaml
├── Item.yaml
├── ItemQuantity.yaml
├── Language.yaml
├── Location.yaml
├── MediaFile.yaml
├── Offer.yaml
├── Option.yaml
├── Order.yaml
├── Organization.yaml
├── Payment.yaml
├── Person.yaml
├── Price.yaml
├── Provider.yaml
├── Quotation.yaml
├── README.md
├── Rating.yaml
├── RefundTerm.yaml
├── Region.yaml
├── ReplacementTerm.yaml
├── ReturnTerm.yaml
├── Scalar.yaml
├── Schedule.yaml
├── Skill.yaml
├── State.yaml
├── Stop.yaml
├── Subscriber.yaml
├── Subscription.yaml
├── Support.yaml
├── Tag.yaml
├── TagGroup.yaml
├── Time.yaml
├── TimeToLive.yaml
├── Tracking.yaml
├── Vehicle.yaml
└── XInput.yaml
Condensed preview — 137 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (458K chars).
[
{
"path": ".github/ISSUE_TEMPLATE/bug_report.md",
"chars": 834,
"preview": "---\nname: Bug report\nabout: Create a report to help us improve\ntitle: ''\nlabels: ''\nassignees: ''\n\n---\n\n**Describe the b..."
},
{
"path": ".github/ISSUE_TEMPLATE/feature_request.md",
"chars": 595,
"preview": "---\nname: Feature request\nabout: Suggest an idea for this project\ntitle: ''\nlabels: ''\nassignees: ''\n\n---\n\n**Is your fea..."
},
{
"path": ".gitignore",
"chars": 10,
"preview": ".DS_Store\n"
},
{
"path": "CHANGELOG.md",
"chars": 8695,
"preview": "# Changelog\n\n## Core v1.0 - 31st December 2022\n### API Changes\n\n| API Endpoint | 0.9.3 | 1.0 |\n|---------|-------|-----..."
},
{
"path": "CONTRIBUTION.md",
"chars": 16800,
"preview": "# Contributing to the Specification\n\n\n## Draft 01\n\n\n# Authors\n\n1. Ravi Prakash - ravi@becknfoundation.org\n\n\n# Latest Ver..."
},
{
"path": "GOVERNANCE.md",
"chars": 27342,
"preview": "# Specification Governance\n\n# Version\n0.6.0\n\n# Draft Version \nDraft 03\n\n# Previous Versions\n\n- Draft 02\n- Draft 01\n\n# Sc..."
},
{
"path": "LICENSE.md",
"chars": 19082,
"preview": "## creative commons\n\n# Attribution-NonCommercial-ShareAlike 4.0 International\n\nCreative Commons Corporation (“Creative C..."
},
{
"path": "MAINTAINERS.md",
"chars": 253,
"preview": "# Ravi Prakash \n* __Github__ : [ravi-prakash-v](https://github.com/ravi-prakash-v)\n\n# Pramod Varma \n* __Github__ : [pra..."
},
{
"path": "README.md",
"chars": 9934,
"preview": "---\ntitle: \"Beckn Protocol - Core\"\nmetaTitle: \"Beckn Protocol Transaction API Core\"\nmetaDescription: \"Domain agnostic tr..."
},
{
"path": "WORKING-GROUPS.md",
"chars": 901,
"preview": "# Core Working Group\n* [Ravi Prakash](#TODO)\n* [Pramod Varma](#TODO)\n* [Sujith Nair](#TODO)\n* [Nirmal Rajeevan](#TODO)\n*..."
},
{
"path": "api/meta/README.md",
"chars": 0,
"preview": ""
},
{
"path": "api/meta/build/meta.yaml",
"chars": 28096,
"preview": "openapi: 3.1.0\ninfo:\n title: Beckn Protocol Meta API\n description: This document contains all the meta API endpoints t..."
},
{
"path": "api/meta/components/index.yaml",
"chars": 3034,
"preview": "openapi: 3.1.0\ninfo:\n title: Beckn Protocol Meta API\n description: This document contains all the meta API endpoints t..."
},
{
"path": "api/meta/components/io/CancellationReasons.yaml",
"chars": 460,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/meta/components/io/GetCancellationReasons.yaml",
"chars": 251,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/meta/components/io/GetRatingCategories.yaml",
"chars": 248,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/meta/components/io/GetReturnReasons.yaml",
"chars": 245,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/meta/components/io/RatingCategories.yaml",
"chars": 476,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/meta/components/io/Response.yaml",
"chars": 614,
"preview": "description: Acknowledgement of message received after successful validation of schema and signature\ncontent:\n applicat..."
},
{
"path": "api/meta/components/io/ReturnReasons.yaml",
"chars": 442,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/meta/components/schema/index.yaml",
"chars": 150,
"preview": "Context:\n $ref: \"../../../../schema/Context.yaml\"\n\nOption:\n $ref: \"../../../../schema/Option.yaml\"\n\nRating:\n $ref: \"...."
},
{
"path": "api/registry/README.md",
"chars": 2894,
"preview": "# How to build the specification\n\nThe full specification can be found at `api/registry/build/registry.yaml`\n\nThis is an..."
},
{
"path": "api/registry/build/README.md",
"chars": 0,
"preview": ""
},
{
"path": "api/registry/build/registry.yaml",
"chars": 19765,
"preview": "openapi: 3.1.0\ninfo:\n title: Beckn Protocol Registry Infrastructure API\n description: 'This document contains the API..."
},
{
"path": "api/registry/components/index.yaml",
"chars": 3863,
"preview": "openapi: 3.1.0\ninfo:\n title: Beckn Protocol Registry Infrastructure API\n description: This document contains the API s..."
},
{
"path": "api/registry/components/io/Lookup.yaml",
"chars": 45,
"preview": "$ref: \"../../../../schema/Subscription.yaml\"\n"
},
{
"path": "api/registry/components/io/LookupResponse.yaml",
"chars": 197,
"preview": "description: Array of subscribers matching the lookup request attributes\ncontent:\n application/json:\n schema:..."
},
{
"path": "api/registry/components/io/OnSubscribe.yaml",
"chars": 676,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/registry/components/io/OnSubscribeResponse.yaml",
"chars": 317,
"preview": "description: Network Participant decrypts the challenge string using its private key and returns the decrypted value.\nco..."
},
{
"path": "api/registry/components/io/README.md",
"chars": 0,
"preview": ""
},
{
"path": "api/registry/components/io/Register.yaml",
"chars": 182,
"preview": "allOf:\n - $ref: \"../../../../schema/Subscriber.yaml\"\n - properties:\n nonce:\n type: string\n xinput_res..."
},
{
"path": "api/registry/components/io/Subscribe.yaml",
"chars": 438,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/registry/components/io/SubscriptionResponse.yaml",
"chars": 239,
"preview": "description: The Registry returns the status of the subscription request.\ncontent:\n application/json:\n schema:..."
},
{
"path": "api/registry/components/schema/index.yaml",
"chars": 320,
"preview": "Context:\n $ref: \"../../../../schema/Context.yaml\"\n\nGps:\n $ref: \"../../../../schema/Gps.yaml\"\n\nLocation:\n $ref: \"../....."
},
{
"path": "api/transaction/README.md",
"chars": 2831,
"preview": "# How to build the specification\n\n**Note:** All folders mentioned here are relative to the root folder ```protocol-speci..."
},
{
"path": "api/transaction/build/transaction.yaml",
"chars": 88400,
"preview": "openapi: 3.1.0\ninfo:\n title: Beckn Protocol Core\n description: Beckn Core Transaction API specification\n version: 1.1..."
},
{
"path": "api/transaction/components/index.yaml",
"chars": 7444,
"preview": "openapi: 3.1.0\ninfo:\n title: Beckn Protocol Core\n description: Beckn Core Transaction API specification\n version: \"1...."
},
{
"path": "api/transaction/components/io/Cancel.yaml",
"chars": 558,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/transaction/components/io/Confirm.yaml",
"chars": 377,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/transaction/components/io/Init.yaml",
"chars": 373,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/transaction/components/io/OnCancel.yaml",
"chars": 418,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/transaction/components/io/OnConfirm.yaml",
"chars": 419,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/transaction/components/io/OnInit.yaml",
"chars": 416,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/transaction/components/io/OnRating.yaml",
"chars": 542,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/transaction/components/io/OnSearch.yaml",
"chars": 424,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/transaction/components/io/OnSelect.yaml",
"chars": 390,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/transaction/components/io/OnStatus.yaml",
"chars": 418,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/transaction/components/io/OnSupport.yaml",
"chars": 395,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/transaction/components/io/OnTrack.yaml",
"chars": 426,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/transaction/components/io/OnUpdate.yaml",
"chars": 418,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/transaction/components/io/README.md",
"chars": 1005,
"preview": "# Transaction API Endpoints\n\nThis folder contains API specification for Transaction API endpoints\n\nThe transaction APIs..."
},
{
"path": "api/transaction/components/io/Rating.yaml",
"chars": 388,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/transaction/components/io/Response.yaml",
"chars": 614,
"preview": "description: Acknowledgement of message received after successful validation of schema and signature\ncontent:\n applicat..."
},
{
"path": "api/transaction/components/io/Search.yaml",
"chars": 322,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/transaction/components/io/Select.yaml",
"chars": 375,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/transaction/components/io/Status.yaml",
"chars": 397,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/transaction/components/io/Support.yaml",
"chars": 353,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/transaction/components/io/Track.yaml",
"chars": 457,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/transaction/components/io/Update.yaml",
"chars": 641,
"preview": "type: object\nproperties:\n context:\n allOf:\n - $ref: \"../../../../schema/Context.yaml\"\n - properties:..."
},
{
"path": "api/transaction/components/schema/index.yaml",
"chars": 3007,
"preview": "Ack:\n $ref: \"../../../../schema/Ack.yaml\"\n \nAddOn:\n $ref: \"../../../../schema/AddOn.yaml\"\n\nAddress:\n $ref: \"../../....."
},
{
"path": "docs/BECKN-001-Layering-Network-Policy-Draft-01.md",
"chars": 16959,
"preview": "# Layering Network Policy on the Specification\n\n## ID: \nBECKN-RFC-001\n\n## Draft ID\nDraft-01\n\n## Title:\nLayering Network..."
},
{
"path": "docs/BECKN-002-Payments-On-Beckn-Enabled-Networks.md",
"chars": 10071,
"preview": "# Payments on Beckn-Enabled Networks\n\n\n## ID: \nBECKN-RFC-002\n\n## Draft ID\nDraft-01\n\n## Title:\nPayments on Beckn-Enabled..."
},
{
"path": "docs/BECKN-003-Beckn-Protocol-Communication-Draft-01.md",
"chars": 5489,
"preview": "# Beckn Protocol Communication\n\n## ID \nBECKN-RFC-003\n\n## Draft ID\nDraft-01\n\n## Title\nBeckn Protocol Communication\n\n## Ca..."
},
{
"path": "docs/BECKN-004-Policy-Administration-On-Beckn-Enabled-Networks.md",
"chars": 14588,
"preview": "# Policy Administration on Beckn-Enabled Networks\n\n## ID: \nBECKN-RFC-004\n\n## Draft ID\nDraft-01\n\n## Title:\nPolicy Adminis..."
},
{
"path": "docs/BECKN-005-Error-Codes-Draft-01.md",
"chars": 3492,
"preview": "# Error Codes for BPP\n\n## ID: \nBECKN-005\n\n## Draft ID\nDraft-01\n\n## Title:\nError Codes\n\n## Status:\nProtocol Draft\n\n## Pub..."
},
{
"path": "docs/BECKN-006-Signing-Beckn-APIs-In-HTTP-Draft-01.md",
"chars": 24961,
"preview": "# Signing Beckn APIs in HTTP - Draft 04\n\n## Context\nWhen communicating over HTTP using Beckn APIs, the subscribers need..."
},
{
"path": "docs/BECKN-007-The-XInput-Schema.md",
"chars": 23457,
"preview": "# The XInput Schema\n#### CWG Working Draft - November 08, 2022\n\n## Document Details\n### This version\nhttps://github.com/..."
},
{
"path": "docs/BECKN-008-Rating-and-Reputation-on-Beckn-Protocol.md",
"chars": 9291,
"preview": "# Rating and Reputation on Beckn Protocol\n\n*Draft 01*\n\nAuthor:\n=======\n\nRavi Prakash (ravi@becknfoundation.org)\n\nScope\n=..."
},
{
"path": "docs/BECKN-009-Tags-the-Edge-of-Beckn.md",
"chars": 12081,
"preview": "# Document Details\n## Supported Protocol Version\n\nTODO\n\n\n## This version\n\nTODO\n\n\n## Latest published version\n\nTODO\n\n\n##..."
},
{
"path": "docs/README.md",
"chars": 352,
"preview": "# Protocol Drafts\n\nThese files contain specifications that have been selected from the proposals submitted to the beckn..."
},
{
"path": "docs/RFC-Template.md",
"chars": 674,
"preview": "# Context\n\nExplain the context of your proposal without detailing the nature of the problem (that comes later...). Best..."
},
{
"path": "protocol-specifications.iml",
"chars": 335,
"preview": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<module type=\"WEB_MODULE\" version=\"4\">\n <component name=\"NewModuleRootManager\" i..."
},
{
"path": "schema/Ack.yaml",
"chars": 1080,
"preview": "description: Describes the acknowledgement sent in response to an API call. If the implementation uses HTTP/S, then Ack..."
},
{
"path": "schema/AddOn.yaml",
"chars": 358,
"preview": "description: Describes an additional item offered as a value-addition to a product or service. This does not exist indep..."
},
{
"path": "schema/Address.yaml",
"chars": 53,
"preview": "description: Describes a postal address.\ntype: string"
},
{
"path": "schema/Agent.yaml",
"chars": 1036,
"preview": "description: Describes the direct performer, driver or executor that fulfills an order. It is usually a person. But in s..."
},
{
"path": "schema/Authorization.yaml",
"chars": 1094,
"preview": "description: Describes an authorization mechanism used to start or end the fulfillment of an order. For example, in the..."
},
{
"path": "schema/Billing.yaml",
"chars": 1140,
"preview": "description: Describes the billing details of an entity.<br>This has properties like name,organization,address,email,pho..."
},
{
"path": "schema/Cancellation.yaml",
"chars": 511,
"preview": "description: Describes a cancellation event\ntype: object\nproperties:\n time:\n description: Date-time when the order w..."
},
{
"path": "schema/CancellationTerm.yaml",
"chars": 731,
"preview": "description: Describes the cancellation terms of an item or an order. This can be referenced at an item or order level...."
},
{
"path": "schema/Catalog.yaml",
"chars": 1777,
"preview": "description: Describes the products or services offered by a BPP. This is typically sent as the response to a search int..."
},
{
"path": "schema/Category.yaml",
"chars": 415,
"preview": "description: A label under which a collection of items can be grouped.\ntype: object\nproperties:\n id:\n description: I..."
},
{
"path": "schema/Circle.yaml",
"chars": 195,
"preview": "description: Describes a circular region of a specified radius centered at a specified GPS coordinate.\ntype: object\nprop..."
},
{
"path": "schema/City.yaml",
"chars": 165,
"preview": "description: Describes a city\ntype: object\nproperties:\n name:\n description: Name of the city\n type: string\n code..."
},
{
"path": "schema/Contact.yaml",
"chars": 246,
"preview": "description: Describes the contact information of an entity\ntype: object\nproperties:\n phone:\n type: string\n email:..."
},
{
"path": "schema/Context.yaml",
"chars": 3736,
"preview": "description: Every API call in beckn protocol has a context. It provides a high-level overview to the receiver about the..."
},
{
"path": "schema/Country.yaml",
"chars": 215,
"preview": "description: Describes a country\ntype: object\nproperties:\n name:\n type: string\n description: Name of the country..."
},
{
"path": "schema/Credential.yaml",
"chars": 263,
"preview": "description: Describes a credential of an entity - Person or Organization\ntype: object\nproperties:\n id:\n type: strin..."
},
{
"path": "schema/Customer.yaml",
"chars": 172,
"preview": "description: Describes a customer buying/availing a product or a service\ntype: object\nproperties:\n person:\n $ref: \"...."
},
{
"path": "schema/DecimalValue.yaml",
"chars": 106,
"preview": "description: Describes a numerical value in decimal form\ntype: string\npattern: \"[+-]?([0-9]*[.])?[0-9]+\"\n\n"
},
{
"path": "schema/Descriptor.yaml",
"chars": 529,
"preview": "description: Physical description of something.\ntype: object\nproperties:\n name:\n type: string\n code:\n type: stri..."
},
{
"path": "schema/Domain.yaml",
"chars": 1388,
"preview": "description: Described the industry sector or sub-sector. The network policy should contain codes for all the industry s..."
},
{
"path": "schema/Duration.yaml",
"chars": 68,
"preview": "description: Describes duration as per ISO8601 format\ntype: string\n\n"
},
{
"path": "schema/Error.yaml",
"chars": 784,
"preview": "description: Describes an error object that is returned by a BAP, BPP or BG as a response or callback to an action by an..."
},
{
"path": "schema/Fee.yaml",
"chars": 257,
"preview": "description: A fee applied on a particular entity\ntype: object\nproperties:\n percentage:\n description: Percentage of..."
},
{
"path": "schema/Form.yaml",
"chars": 965,
"preview": "description: Describes a form\ntype: object\nproperties:\n url:\n description: The URL from where the form can be fetche..."
},
{
"path": "schema/FormResponse.yaml",
"chars": 388,
"preview": "description: Describes the response to a form submission\ntype: object\nproperties:\n status:\n description: Contains th..."
},
{
"path": "schema/Fulfillment.yaml",
"chars": 1948,
"preview": "description: Describes how a an order will be rendered/fulfilled to the end-customer\ntype: object\nproperties:\n id:..."
},
{
"path": "schema/FulfillmentState.yaml",
"chars": 256,
"preview": "description: Describes the state of fulfillment\ntype: object\nproperties:\n descriptor:\n $ref: \"./Descriptor.yaml\"\n u..."
},
{
"path": "schema/Gps.yaml",
"chars": 154,
"preview": "description: Describes a GPS coordinate\ntype: string\npattern: '^[-+]?([1-8]?\\d(\\.\\d+)?|90(\\.0+)?),\\s*[-+]?(180(\\.0+)?|((..."
},
{
"path": "schema/Image.yaml",
"chars": 536,
"preview": "description: Describes an image\ntype: object\nproperties:\n url:\n description: URL to the image. This can be a data ur..."
},
{
"path": "schema/Intent.yaml",
"chars": 3639,
"preview": "description: The intent to buy or avail a product or a service. The BAP can declare the intent of the consumer containin..."
},
{
"path": "schema/Item.yaml",
"chars": 3422,
"preview": "description: Describes a product or a service offered to the end consumer by the provider. In the mobility sector, it ca..."
},
{
"path": "schema/ItemQuantity.yaml",
"chars": 1525,
"preview": "description: Describes the count or amount of an item\ntype: object\nproperties:\n allocated:\n description: This repres..."
},
{
"path": "schema/Language.yaml",
"chars": 131,
"preview": "description: Describes a language known to the person.\ntype: object\nproperties:\n code:\n type: string\n name:\n typ..."
},
{
"path": "schema/Location.yaml",
"chars": 1331,
"preview": "description: The physical location of something\ntype: object\nproperties:\n id:\n type: string\n descriptor:\n $ref:..."
},
{
"path": "schema/MediaFile.yaml",
"chars": 529,
"preview": "description: This object contains a url to a media file. \ntype: object\nproperties:\n mimetype:\n description: indicate..."
},
{
"path": "schema/Offer.yaml",
"chars": 577,
"preview": "description: An offer associated with a catalog. This is typically used to promote a particular product and enable more..."
},
{
"path": "schema/Option.yaml",
"chars": 136,
"preview": "description: Describes a selectable option\ntype: object\nproperties:\n id:\n type: string\n descriptor:\n $ref: \"./De..."
},
{
"path": "schema/Order.yaml",
"chars": 3209,
"preview": "description: Describes a legal purchase order. It contains the complete details of the legal contract created between th..."
},
{
"path": "schema/Organization.yaml",
"chars": 527,
"preview": "description: An organization. Usually a recognized business entity. \ntype: object\nproperties:\n descriptor:\n $ref: \"...."
},
{
"path": "schema/Payment.yaml",
"chars": 2601,
"preview": "description: Describes the terms of settlement between the BAP and the BPP for a single transaction. When instantiated,..."
},
{
"path": "schema/Person.yaml",
"chars": 1099,
"preview": "description: Describes a person as any individual\ntype: object\nproperties:\n id:\n type: string\n description: Descr..."
},
{
"path": "schema/Price.yaml",
"chars": 449,
"preview": "description: Describes the price of a product or service\ntype: object\nproperties:\n currency:\n type: string\n value:..."
},
{
"path": "schema/Provider.yaml",
"chars": 1243,
"preview": "description: Describes the catalog of a business. \ntype: object\nproperties:\n id:\n type: string\n description: Id o..."
},
{
"path": "schema/Quotation.yaml",
"chars": 627,
"preview": "description: Describes a quote. It is the estimated price of products or services from the BPP.<br>This has properties l..."
},
{
"path": "schema/README.md",
"chars": 0,
"preview": ""
},
{
"path": "schema/Rating.yaml",
"chars": 597,
"preview": "description: Describes the rating of an entity\ntype: object\nproperties:\n rating_category:\n description: Category of..."
},
{
"path": "schema/RefundTerm.yaml",
"chars": 506,
"preview": "description: Refund term of an item or an order\ntype: object\nproperties:\n fulfillment_state:\n description: The state..."
},
{
"path": "schema/Region.yaml",
"chars": 1711,
"preview": "description: Describes an arbitrary region of space. The network policy should contain a published list of supported reg..."
},
{
"path": "schema/ReplacementTerm.yaml",
"chars": 511,
"preview": "description: The replacement policy of an item or an order\ntype: object\nproperties:\n fulfillment_state:\n description..."
},
{
"path": "schema/ReturnTerm.yaml",
"chars": 871,
"preview": "description: Describes the return policy of an item or an order\ntype: object\nproperties:\n fulfillment_state:\n descri..."
},
{
"path": "schema/Scalar.yaml",
"chars": 429,
"preview": "description: Describes a scalar\ntype: object\nproperties:\n type:\n type: string\n enum:\n - CONSTANT\n - VAR..."
},
{
"path": "schema/Schedule.yaml",
"chars": 734,
"preview": "description: Describes schedule as a repeating time period used to describe a regularly recurring event. At a minimum a..."
},
{
"path": "schema/Skill.yaml",
"chars": 122,
"preview": "description: Describes a skill of the person.\ntype: object\nproperties:\n code:\n type: string\n name:\n type: string..."
},
{
"path": "schema/State.yaml",
"chars": 257,
"preview": "description: A bounded geopolitical region of governance inside a country. \ntype: object\nproperties:\n name:\n type: s..."
},
{
"path": "schema/Stop.yaml",
"chars": 877,
"preview": "description: A logical point in space and time during the fulfillment of an order. \ntype: object\nproperties:\n id:\n t..."
},
{
"path": "schema/Subscriber.yaml",
"chars": 993,
"preview": "description: A unique operational configuration of a trusted platform on a network. \ntype: object\nproperties: \n subscr..."
},
{
"path": "schema/Subscription.yaml",
"chars": 1124,
"preview": "description: Subscription details of a Network Participant. \nallOf:\n - $ref: \"./Subscriber.yaml\"\n - properties:..."
},
{
"path": "schema/Support.yaml",
"chars": 273,
"preview": "description: Details of customer support\ntype: object\nproperties:\n ref_id:\n type: string\n callback_phone:\n type:..."
},
{
"path": "schema/Tag.yaml",
"chars": 1160,
"preview": "description: Describes a tag. This is used to contain extended metadata. This object can be added as a property to any s..."
},
{
"path": "schema/TagGroup.yaml",
"chars": 1172,
"preview": "description: A collection of tag objects with group level attributes. For detailed documentation on the Tags and Tag Gro..."
},
{
"path": "schema/Time.yaml",
"chars": 650,
"preview": "description: Describes time in its various forms. It can be a single point in time; duration; or a structured timetable..."
},
{
"path": "schema/TimeToLive.yaml",
"chars": 209,
"preview": " description: The time-to-live in seconds, for this object. This can be overriden at deeper levels. A value of -1 ind..."
},
{
"path": "schema/Tracking.yaml",
"chars": 1266,
"preview": "description: Contains tracking information that can be used by the BAP to track the fulfillment of an order in real-time..."
},
{
"path": "schema/Vehicle.yaml",
"chars": 693,
"preview": "description: Describes a vehicle is a device that is designed or used to transport people or cargo over land, water, air..."
},
{
"path": "schema/XInput.yaml",
"chars": 1262,
"preview": "\ndescription: Contains any additional or extended inputs required to confirm an order. This is typically a Form Input. S..."
}
]
About this extraction
This page contains the full source code of the beckn/protocol-specifications GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 137 files (427.7 KB), approximately 96.4k tokens. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.