Beckn Protocol Specifications

The Beckn Protocol is governed through several specialized 'areas', each managed by Working Groups (WG). These areas ensure the protocol remains interoperable, scalable, and well-documented. The identified areas are:

• Design Principles: Ensures all updates adhere to atomic, unambiguous, and future-proof principles.
• Licensing: Manages the Creative Commons licensing and its practical implementation implications.
• API: Defines supported methods and documentation (e.g., OpenAPI, AsyncAPI).
• Schema: Defines standard schemas (e.g., JSON Schema) and mapping methodologies.
• Communication: Defines exchange mechanisms via UML sequence diagrams and links them to schemas/APIs.
• Architecture: Specifies the reference architecture, including actors like BAP, BPP, BG, and the Network Registry.

The Beckn Transaction APIs are organized into three distinct functional groups based on the role of the entity interacting with the protocol:

1. BPP API (Beckn Provider Platform): Endpoints used by the provider to respond to requests or initiate actions.
2. BAP API (Beckn Agent Platform): Endpoints used by the consumer/agent to receive responses or callbacks (typically prefixed with on_).
3. BG API (Beckn Gateway): Endpoints used for communication through a gateway intermediary.

Changes to the specification are evaluated based on five primary criteria:

1. Clarity: Resolving complicated or unclear existing implementations.
2. Consistency: Aligning with industry standards or the rest of the specification.
3. Necessary functionality: Addressing missing capabilities caused by current designs.
4. Forward-looking Designs: Anticipating evolving API protocols and patterns.
5. Impact: Prioritizing common and important use cases over edge cases.

The Beckn protocol uses a specific branch structure to manage stable releases and upcoming versions. At any time, there are at most 4 working branches:

• master: The current stable, released version. No PRs are accepted directly to master for modifying the specification (only for supporting files).
• core-[PATCH]-draft: For the next PATCH version (e.g., core-0.9.3-draft). Used for non-breaking changes like typo fixes or wording clarifications.
• core-[MINOR]-draft: For the next MINOR version (e.g., core-0.10.0-draft). Used for backward-compatible changes like adding attributes to existing schemas.
• core-[MAJOR]-draft: For the next MAJOR version (e.g., core-1.0.0-draft).

Important: All PRs for a specific version must be made to the corresponding draft branch. For example, patch changes for version 0.9.2 must be submitted to the core-0.9.3-draft branch.

In Beckn-enabled networks, the protocol does not handle the actual movement of money (e.g., charging a card or bank transfers). Instead, it facilitates a Payment Contract Agreement.

This agreement consists of the exchange of payment terms and the proof of payment between the BAP (Buyer App Provider) and the BPP (Seller App Provider). The actual settlement is performed asynchronously by integrating with existing regional payment infrastructures like banking APIs, payment gateways, or open payment protocols.

Key roles in this agreement:

• Payer (belongs to BAP): The entity paying for the order.
• Payee (belongs to BPP): The entity receiving the payment.

A Network Policy is a set of specific rules applied to the core Beckn protocol specification to instantiate a specific network (e.g., a logistics network vs. an education network).

Because the core Beckn specification is sector-agnostic and non-derivative, it cannot be modified directly without breaking global interoperability. Instead, architects layer network-specific policies on top of the core specification. These policies govern the allowed values for schema properties without changing the underlying schema itself.

Key use cases for Network Policies include:

• Adding enumerations to core schema properties (e.g., limiting fulfillment types to HOME-DELIVERY or STORE-PICKUP).
• Adding qualifiers like min, max, or default values.
• Applying sector-specific or region-specific standards using regex patterns.

The Beckn protocol specification evolves based on specific criteria. A change is considered appropriate if it addresses:

• Clarity: Resolving complicated or unclear implementation paths.
• Consistency: Aligning the specification with itself or industry standard terminology.
• Necessary functionality: Adding missing capabilities due to current design limitations.
• Forward-looking Designs: Anticipating future protocol, format, or pattern evolutions.
• Impact: Providing value to a large number of use cases. Evolution should not be driven by edge cases; the CWG prioritizes common and important use cases.

Before submitting a change proposal, evaluate the following impact areas:

• Migration Impact: How difficult is it for existing implementations to migrate to this change, and how large is the affected cohort?
• Tooling: Does the change support code generation, software interfaces, and spec generation? Document any limitations regarding specific frameworks or languages.
• Visualization: Can the change be graphically represented in a UI or other interface?

The XInput Schema is a domain-agnostic mechanism within the Beckn protocol designed to capture additional metadata required by a provider to confirm a transaction.

Instead of cluttering the core transaction protocol with sector-specific attributes (which would make the protocol bulky and difficult to maintain), XInput allows for the transmission of arbitrary, context-specific information that is not part of the initial product catalog.

Use cases include:

• Logistics: Transmitting package dimensions, weight, item category (e.g., flammable, fragile), or order numbers.
• Healthcare: Transmitting medical history, symptom descriptions, or insurance details.

Developers should use XInput when a provider requires specific customer-provided data to fulfill or confirm an order that cannot be pre-defined in a standard catalog.

When implementing a Beckn API, you must follow the request/callback pattern. The receiver responds immediately with an ACK and closes the session. The actual response is sent later using a callback API.

Naming Convention: The callback API name is derived from the request API name by adding an on_ prefix.

Example flow:

1. Sender calls search.
2. Receiver returns an immediate ACK.
3. Receiver asynchronously calls on_search to provide the results.